Mapping queries

Both import types use a user-defined SPARQL CONSTRUCT query to map the incoming data to the final RDF representation and to connect it to the documents in LinkedDataHub's dataset. These are the rules that hold for mapping queries:

• The BASE value is automatically set to the imported file's URI. Do not add an explicit BASE to the query.
• The $base binding is bound to the dataspace's base URI
• use OPTIONAL for optional values (such as optional cell values in CSV)
• use BIND() to introduce new values and/or cast literals to the appropriate result datatype or URI
• when building document URIs, use natural IDs from the input data (or UUIDs if there are no IDs) and URI-encode them with encode_for_uri
• use a GRAPH block in the constructor template to construct triples for a specific document
• construct dh:Container instances to create new container documents or dh:Item instances to create new item documents. dct:title values are mandatory for documents.
• if you are constructing descriptions of non-information resources (a thing, a concept), assign them URIs with fragment identifiers (e.g. #this) and pair them with item documents using the foaf:primaryTopic property

All of the rules in one skeleton, shaped like the Northwind category mapping:

PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>
PREFIX schema: <https://schema.org/>

CONSTRUCT
{
    GRAPH ?graph                                   # one GRAPH block per constructed document
    {
        ?graph dct:title ?categoryName ;           # dct:title is mandatory for documents
            foaf:primaryTopic ?category .

        ?category a schema:ProductGroup ;          # the document's topic…
            schema:name ?categoryName ;
            schema:description ?description .
    }
}
WHERE
{
    ?row <#categoryID> ?categoryID ;               # input values bind as <#column> predicates
        <#categoryName> ?categoryName .            # (no explicit BASE — it is set to the file's URI)

    OPTIONAL { ?row <#description> ?description }  # OPTIONAL for optional values

    # $base is bound to the dataspace's base URI
    BIND(uri(concat(str($base), "categories/")) AS ?container)
    # URI-encode natural IDs when minting document URIs
    BIND(uri(concat(str(?container), encode_for_uri(?categoryID), "/")) AS ?graph)
    # …a non-information resource, as a fragment of its document
    BIND(uri(concat(str(?graph), "#this")) AS ?category)
}

The complete version: categories/categories.rq in the Northwind Traders demo

Import execution

Imports run asynchronously in the background: the import item is created before the process completes. To check the status (completed or failed), refresh the import item. On successful completion, metadata such as the number of imported RDF triples is attached to the import.

The resulting RDF data is validated against constraints during the import. Constraint violations, if any, are attached to the import item.