Load Turtle from disk

One function reads a .ttl or .nt file from the database server's filesystem into a graph and returns the number of triples loaded.

What it does

pgrdf.load_turtle(path TEXT, graph_id BIGINT, base_iri TEXT DEFAULT NULL, bulk_load BOOLEAN DEFAULT FALSE) → BIGINT

Reads the file at path, parses it, turns every term into a dictionary id, and writes the triples into the graph.

The path is on the database server, not on your machine. The server process must be able to read it. If the file is on the client, read it in your application and pass the text to parse_turtle.
It reads with the server's file permissions and does not require superuser: any role allowed to call it can load any RDF file the server process can read. Revoke EXECUTE on the load_turtle* functions from roles that shouldn't do that.
base_iri resolves relative IRIs such as <alice>. Leave it NULL when the file uses only absolute IRIs or sets its own @base.
Loading appends. Loading the same file twice stores its triples twice. To reload a graph, clear it first.
Errors refuse the whole load. A syntax error names the line and column and nothing is written. A missing file refuses with load_turtle: failed to open "/tmp/nope.ttl": No such file or directory (os error 2).
A locked graph refuses with 55P03; see Locking a graph.

Which loader runs

Turtle (prefixes, multi-line statements) always goes through the standard parser. A NOTICE says so:

NOTICE:  pgrdf.load_turtle: input is Turtle (prefixed/multi-line); using the full parser.
         For the faster staged loader, supply N-Triples (one bare-term statement per line)
         with pgrdf preloaded

N-Triples, on a server with pgRDF in shared_preload_libraries and no base_iri given, is handed to the staged loader. The staged loader only takes a database into which nothing has been loaded yet; otherwise the standard parser loads the file. On a small 4-core machine, a 300,000-line N-Triples file took about 3 seconds through the staged route and about 41 seconds through the standard parser.
load_turtle_verbose loads through the standard parser (or the bulk path with bulk_load => true) and names the path it used in its report.

For very large loads, call the staged loader directly: its report confirms the load and its timings.

`bulk_load => true`

The trailing flag opts into the parallel bulk path: N-Triples only, for a first load into an empty database. See Bulk ingest.

Leave bulk_load off for Turtle

On a Turtle file with prefixes or multi-line statements, bulk_load => true loads zero triples without an error: every line is skipped as unreadable. Use it only on N-Triples, and check parse_skipped in the verbose report when you do.

Why you'd use it

Project managers — no custom ETL for RDF. Standard ontologies load with one SQL statement, and a billion-scale N-Triples dump goes through the same front door.
Data scientists — load production graphs into a real PostgreSQL instance without leaving SQL.
Ontologists — ingest the published Turtle files of W3C and other vocabularies without per-vocabulary tooling.

Example

Put a file where the server can read it. With the Docker container from Install:

cat > people.ttl <<'EOF'
@prefix ex:   <http://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:alice a foaf:Person ;
    foaf:name "Alice" ;
    foaf:knows ex:bob .

ex:bob a foaf:Person ;
    foaf:name "Bob" .
EOF
docker cp people.ttl pgrdf:/tmp/people.ttl

Then load it:

sql

SELECT pgrdf.add_graph('http://example.org/people');
SELECT pgrdf.load_turtle('/tmp/people.ttl', pgrdf.graph_id('http://example.org/people'));
-- NOTICE:  pgrdf.load_turtle: input is Turtle (prefixed/multi-line); using the full parser. …
--  → 5

A file with relative IRIs (<alice> <knows> <bob> .) needs a base:

sql

SELECT pgrdf.load_turtle('/tmp/relative.ttl',
                         pgrdf.graph_id('http://example.org/people'),
                         'http://example.org/');
--  → 1   (stored as http://example.org/alice, …)

Without the base it refuses with a parse error (No scheme found in an absolute IRI).

Load Turtle from disk ​

What it does ​

Which loader runs ​

bulk_load => true ​

Why you'd use it ​

Example ​

See also ​