RDF imports

27 October 2026 13:17

Backlinks

RDF imports and transforming RDF using SPARQL CONSTRUCT

Read the shared mapping query rules first — they apply to CSV and RDF imports alike.

An RDF import is a combination of multiple resources:

File: The RDF file to be imported (ldh:file)
Transformation query (optional): A user-defined CONSTRUCT query that transforms the input RDF into a different RDF representation (spin:query)
Graph (optional): The target graph (document) to which converted items are appended with POST (sd:name)

Specify either the transformation query or the target graph, not both.

If the graph is specified, the resulting RDF data is appended to a single document.

If the transformation query is specified, the resulting data should contain document instances in order to attach to the document hierarchy. The documents have to be URI resources. The document graphs have to be explicitly specified using a GRAPH block in the CONSTRUCT template (a Jena-specific extension of SPARQL 1.1); otherwise the import result ends up in the default graph of the dataspace's RDF dataset, which LinkedDataHub does not serve.

Imports run in the background — see import execution.

The resulting RDF is split into documents (named graphs), which are then created one by one and validated against constraints as they are created. Constraint violations, if any, are attached to the import item.

Running example¶

The running example connects the Northwind Traders dataspace to the UNESCO Thesaurus dataspace: each Northwind product category is mapped to the thesaurus concept it corresponds to, using the SKOS mapping relations. The mapping file also types the categories as skos:Concept, which makes the relations applicable (and lets the taxonomy editor package render the categories as concepts):

@prefix skos:   <http://www.w3.org/2004/02/skos/core#> .

# 1 Beverages -> Beverages
<https://northwind-traders.demo.linkeddatahub.com/categories/1/#this> a skos:Concept ;
    skos:closeMatch <https://unesco-thesaurus.demo.linkeddatahub.com/concepts/concept3683/#this> .

# 2 Condiments -> Food (no finer concept in the thesaurus)
<https://northwind-traders.demo.linkeddatahub.com/categories/2/#this> a skos:Concept ;
    skos:broadMatch <https://unesco-thesaurus.demo.linkeddatahub.com/concepts/concept1812/#this> .

# 3 Confections -> Sugar
<https://northwind-traders.demo.linkeddatahub.com/categories/3/#this> a skos:Concept ;
    skos:relatedMatch <https://unesco-thesaurus.demo.linkeddatahub.com/concepts/concept3495/#this> .

# … one mapping per category, 8 in total

Source: categories/unesco-mappings.ttl

Imported with the graph variant, the whole file is appended to one target document — a single graph of mappings that describe the two dataspaces' resources:

<#mappings-import> a ldh:RDFImport ;
    dct:title "UNESCO category mappings" ;
    ldh:file <https://localhost:4443/uploads/751b60d9516f4630a6d39bc304ce649ec3a740e9> ;
    sd:name <https://localhost:4443/categories/mappings/> .

Transformation¶

This step is used to transform the RDF data that is being imported, if necessary (to a different vocabulary, for example). It also connects instances in the imported data to the documents in LinkedDataHub's dataset.

The mapping is a user-defined SPARQL CONSTRUCT that follows the shared mapping query rules.

Example¶

Imported with the transformation variant instead, each mapping is routed into its own category's document. The mapping file describes the demo's categories, so the transformation also rebases their URIs onto this dataspace — an ETL step that makes the same file installable against any base URI:

PREFIX skos:  <http://www.w3.org/2004/02/skos/core#>

CONSTRUCT
{
    GRAPH ?graph
    {
        ?category a skos:Concept ;
            ?mapping ?concept .
    }
}
WHERE
{
    ?remote a skos:Concept ;
        ?mapping ?concept .
    FILTER(?mapping IN (skos:closeMatch, skos:broadMatch, skos:relatedMatch))

    # rebase the demo's category URIs onto this dataspace's $base
    BIND(strafter(str(?remote), "northwind-traders.demo.linkeddatahub.com/") AS ?path)
    BIND(uri(concat(str($base), strbefore(?path, "#"))) AS ?graph)
    BIND(uri(concat(str($base), ?path)) AS ?category)
}

When the import is complete, each category document carries its mapping. The Beverages document gains:

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

<https://localhost:4443/categories/1/#this> a skos:Concept ;
    skos:closeMatch <https://unesco-thesaurus.demo.linkeddatahub.com/concepts/concept3683/#this> .

The mapped concept URIs stay remote on purpose: following one leads into the UNESCO Thesaurus dataspace through the Linked Data proxy, and queries can join the two dataspaces over their federated SPARQL endpoints.

Management¶

RDF import actions and their CLI commands
Action	CLI command
Create RDF import from an uploaded file (`--file`, with `--query` or `--graph`)	`ldh add rdf-import`
Import a local RDF file end-to-end (`--rdf-file`, `--content-type`, with `--query-file` or `--graph`)	`ldh import rdf`

If you are ready to import some RDF, follow the user guide on creating an RDF import.