a ; ; "2026-06-16T20:33:57.327Z"^^; ; "CSV imports and mapping to RDF using SPARQL CONSTRUCT"; "CSV imports"; ; . "Generating RDF from Tabular Data on the Web" . a ; "
\n

CSV imports and mapping to RDF using SPARQL CONSTRUCT

\n

CSV is a plain-text format for\n tabular data.

\n

A CSV import is a combination of multiple resources:

\n
\n
File
\n
The CSV file to be mapped to RDF and imported
\n
Mapping query
\n
A user-defined CONSTRUCT query that produces RDF
\n
\n

CSV import in LinkedDataHub consists of 2 steps:

\n
    \n
  1. \n generic conversion creates an intermediary, generic CSV/RDF representation for each CSV row\n
    2. \n
  2. \n vocabulary conversion maps the CSV/RDF to the final RDF representation using the mapping query\n
    3. \n
\n

The import process runs in the background, i.e. the import item is created before the process completes.\n Currently the only way to determine when it completes is to refresh the import item and check the import\n status (completed/failed). Upon successful report, metadata such as the number of imported RDF triples is attached\n to the import.

\n

The mapping is done one row at a time, with each row resulting in a new created document, which should attach to the document hierarchy. The documents have to be URI resources. The server will automatically assign URIs for the documents constructed in the default graph. Alternatively, it is possible to explicitly specify the document graph using a GRAPH block in the CONSTRUCT template (which is a\n Jena-specific extension of SPARQL 1.1).

\n

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

\n

We provide an running example of CSV data that will be shown as RDF conversion in the following\n sections:

\n 
countryCode,latitude,longitude,name\nAD,42.5,1.6,Andorra\nAE,23.4,53.8,\"United Arab Emirates\"\nAF,33.9,67.7,Afghanistan
\n
\n

Generic conversion

\n

The data table is converted to a graph by treating rows as resources, columns as predicates, and\n cells as xsd:string literals. The approach is the same as CSV on the Web\n minimal mode.

\n 
@base <https://localhost:4443/> .\n\n_:8228a149-8efe-448d-b15f-8abf92e7bd17\n<#countryCode> \"AD\" ;\n<#latitude> \"42.5\" ;\n<#longitude> \"1.6\" ;\n<#name> \"Andorra\" .\n\n_:ec59dcfc-872a-4144-822b-9ad5e2c6149c\n<#countryCode> \"AE\" ;\n<#latitude> \"23.4\" ;\n<#longitude> \"53.8\" ;\n<#name> \"United Arab Emirates\" .\n\n_:e8f2e8e9-3d02-4bf5-b4f1-4794ba5b52c9\n<#countryCode> \"AF\" ;\n<#latitude> \"33.9\" ;\n<#longitude> \"67.7\" ;\n<#name> \"Afghanistan\" .
\n
\n
\n

Vocabulary conversion

\n

This step provides a semantic \"lift\" for the generic RDF output of the previous step by mapping it\n to classes and properties from specific vocabularies. It also connects instances in the imported data to the documents in LinkedDataHub's dataset.

\n

These are the rules that hold for mapping queries:

\n
    \n
  • BASE value is automatically set to the imported file's URI. Do not add an explicit BASE to the query.
    • \n
  • $base binding is set to the value of the application's baseURI
    • \n
  • useOPTIONAL for optional cell values
    • \n
  • use BIND() to introduce new values and/or cast literals to the appropriate result datatype or URI
    • \n
  • when building document URIs, use natural IDs from the input data (or UUIDs if there are no IDs) and remember to URI-encode them using encode_for_uri
    • \n
  • use a GRAPH block in the constructor template to construct triples for a specific document
    • \n
  • 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.
    • \n
  • if you're constructing non-information resource (e.g. thing, concept) descriptions, assign them URIs with fragment identified (e.g. #this) and pair them with item documents using the foaf:primaryTopic property
    • \n
\n

We are planning to provide a UI-based mapping tool in the future.

\n
\n

Example

\n

In this example we produce a SKOS concept paired with its item (document) for each country:

\n 
PREFIX  geo:  <http://www.w3.org/2003/01/geo/wgs84_pos#>\nPREFIX  dh:   <https://www.w3.org/ns/ldt/document-hierarchy#>\nPREFIX  dct:  <http://purl.org/dc/terms/>\nPREFIX  rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#>\nPREFIX  xsd:  <http://www.w3.org/2001/XMLSchema#>\nPREFIX  foaf: <http://xmlns.com/foaf/0.1/>\nPREFIX  sioc: <http://rdfs.org/sioc/ns#>\n\nCONSTRUCT\n  {\n    ?item a dh:Item ;\n        sioc:has_container ?container ;\n        dct:title ?name ;\n        dh:slug ?countryCode ;\n        foaf:primaryTopic ?country .\n    ?country a <http://dbpedia.org/ontology/Country> ;\n        dct:identifier ?countryCode ;\n        geo:lat ?lat ;\n        geo:long ?long ;\n        dct:title ?name .\n  }\nWHERE\n  { \n    BIND(bnode() AS ?item)\n    BIND (uri(concat(str($base), \"countries/\")) AS ?container)\n\n    ?country  <#countryCode>  ?countryCode ;\n              <#latitude>     ?latString ;\n              <#longitude>    ?longString ;\n              <#name>         ?name .\n\n    BIND(xsd:float(?latString) AS ?lat)\n    BIND(xsd:float(?longString) AS ?long)\n  }
\n

When the import is complete, you should be able to see the imported documents as children of the ${base}countries/ container.

\n

The result of our mapping:

\n 
PREFIX  geo:  <http://www.w3.org/2003/01/geo/wgs84_pos#>\nPREFIX  dh:   <https://www.w3.org/ns/ldt/document-hierarchy#>\nPREFIX  dct:  <http://purl.org/dc/terms/>\nPREFIX  rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#>\nPREFIX  xsd:  <http://www.w3.org/2001/XMLSchema#>\nPREFIX  foaf: <http://xmlns.com/foaf/0.1/>\nPREFIX  sioc: <http://rdfs.org/sioc/ns#>\n\n<https://localhost:4443/countries/AD/> a dh:Item ;\n    sioc:has_container <https://localhost:4443/countries/> ;\n    dct:title \"Andorra\" ;\n    dh:slug \"AD\" ;\n    foaf:primaryTopic <https://localhost:4443/countries/AD/#id459bdd90-a309-49f9-92b2-1b9b5d110471> .\n\n<https://localhost:4443/countries/AD/#id459bdd90-a309-49f9-92b2-1b9b5d110471> a <http://dbpedia.org/ontology/Country> ;\n    dct:identifier \"AD\" ;\n    geo:lat 42.5 ;\n    geo:long 1.6 ;\n    dct:title \"Andorra\" .\n\n<https://localhost:4443/countries/AE/> a dh:Item ;\n    sioc:has_container <https://localhost:4443/countries/> ;\n    dct:title \"United Arab Emirates\" ;\n    dh:slug \"AE\" ;\n    foaf:primaryTopic <https://localhost:4443/countries/AE/#id7ad9b80b-8fbf-4696-92fa-61facf6c2066> .\n\n<https://localhost:4443/countries/AE/#id7ad9b80b-8fbf-4696-92fa-61facf6c2066> a <http://dbpedia.org/ontology/Country> ;\n    dct:identifier \"AE\" ;\n    geo:lat 23.4 ;\n    geo:long 53.8 ;\n    dct:title \"United Arab Emirates\" .\n\n<https://localhost:4443/countries/AF/> a dh:Item ;\n    sioc:has_container <https://localhost:4443/countries/> ;\n    dct:title \"Afghanistan\" ;\n    dh:slug \"AF\" ;\n    foaf:primaryTopic <https://localhost:4443/countries/AF/#id5de2fd91-158a-47d8-a302-d1af205fe59f> .\n\n<https://localhost:4443/countries/AF/#id5de2fd91-158a-47d8-a302-d1af205fe59f> a <http://dbpedia.org/ontology/Country> ;\n    dct:identifier \"AF\" ;\n    geo:lat 33.9 ;\n    geo:long 67.7 ;\n    dct:title \"Afghanistan\" .
\n
\n
\n

If you are ready to import some CSV, see our step-by-step tutorial on creating an CSV import.

\n
"^^; , . "SPARQL 1.1 Query Language: CONSTRUCT" .