Docs portal

Mapping a concept to a data set

Once you have a Grafo document that is connected to a data source—and contains some concepts, relationships, and attributes—you are ready to add your first mapping from your dataset to your document.

A video tutorial is available: Add a simple table-based mapping

Define a mapping

Mappings are small SQL queries that connect elements in your model to a data source.

Click on an element in your model and then click the Create a new mapping link.

dataworld_data_14.png

The Mappings popup window will appear, in which you can configure all of the properties of the mapping.

For Mapping Type, you can specify Table or View mappings, and enter a Display Name. Choose the Data Source, Schema, Table Name, and Primary key column.

integration_18.png

In most cases, it is best to automatically generate an IRI template, which will generate a unique identifier that corresponds to the unique keys in the chosen Primary key column.

In some advanced cases, it may be necessary to insert a custom IRI Template to use in your mapping export.

To test the mapping, click Test. The results will appear in the RDF field.

Click the Create button to add the mapping to the document.

integration_19.png

The new mapping is now available by clicking Manage Mappings in the left panel.

Note

You can DELETE a mapping by clicking on the mapping in Manage Mappings and scrolling to the bottom to the delete section.

integration_20.png

Add a view-based mapping

To add a view-based mapping, you need to have at least one accessible view.

A video tutorial is available: Add a view-based mapping

Follow these steps to add a view -based mapping:

1. If necessary, add a view that you will use in the mapping.

2. Click on the element containing the attribute to which you want to add a mapping. Then click Create a new mapping.

3. A popup window will appear in which you configure the mapping.

view_based_mapping_1.png

4. For Mapping Type, choose View, and enter a Display Name. Choose the Data Source, Schema, and View name.

5. In most cases, it is best to automatically generate an IRI template, which will generate a unique identifier that corresponds to the primary key in the view. The Concept template will fill in automatically. 

5. To test the mapping, click Test. The results will appear in the RDF field.

6. Click the Create button to add the mapping to the document.

Add a mapping to an attribute

A video tutorial is available: Attribute mappings

Follow these steps to add a mapping to an attribute:

1. Click on the element containing the attribute to which you want to add a mapping. Then click Create a new mapping.

attribute_mapping_1.png

2. A popup window will appear, in which you configure the mapping.

attribute_mapping_2.png

3. For Mapping Type, you can specify Table or View mappings, and enter a Display Name. Choose the Data Source, Schema, Table Name, and Column.

4. In most cases, it is best to automatically generate an IRI template, which will generate a unique identifier that corresponds to the unique keys in the chosen Column. Choose a Concept Template from the drop-down.

5. To test the IRI template, click Test. The results will appear in the RDF field.

6. Click the Create button to add the mapping to the document.

attribute_mapping_3.png

Add a mapping to a relationship

Follow these steps to add a mapping to an relationship:

1. Click on the element containing the attribute to which you want to add a mapping. Then click Create a new mapping.

attribute_mapping_6.png

2. A popup window will appear, in which you configure the mapping.

attribute_mapping_4.png

3. For Mapping Type, you can specify Table or View mappings, and enter a Display Name. Choose the Data Source, Schema, Table Name, and Column.

4. In most cases, it is best to automatically generate an IRI template, which will generate a unique identifier that corresponds to the unique keys in the chosen Column. Because this is a relationship, you'll need to choose a Concept Template (from) and Concept Template (to) in the drop-downs. 

5. To test the IRI templates, click Test. The results will appear in the RDF field.

6. Click the Create button to add the mapping to the document.

attribute_mapping_5.png

Export a mapping file to data.world

After creating a mapping, you can link a Grafo document to a data.world dataset by exporting the mapping to data.world.

Follow these steps to export a mapping file:

1. In the menus at the top, click Data sources > Export to data.world.

export_mapping_1.png

2. A popup window will appear that indicates the destination for the mapping file. You could click the Choose Another button to choose another location. We'll keep it simple here and go with the default location. Click the Export button.

export_mapping_2.png

3. In the next popup window, confirm that the username is correct and click Continue.

export_mapping_3.png

4. A success message will appear.

export_mapping_4.png

5. To confirm that the export has been successful, switch over to data.world. Locate the data set and scroll to the bottom of the main page to see the mapping file.

export_mapping_5.png

Writing SPARQL Queries against your semantic model

After you export a mapping file to data.world, you can write SPARQL queries against the data source that is accessible through the mapping file.

A video tutorial is available: Writing SPARQL Queries against your semantic model

NOTE: You can open the mapping file in a tool such as dw Editor.

sparql_1.png

SPAQRL is a query language for interacting with RDF and Turtle files. It is not yet possible to use conventional SQL against RDF and Turtle files.

Let's walkthough the creation of a simple SPARQL query.

1. Access your dataset in data.world, then click Explore this dataset, and then click the +Add button in the upper-left corner. Choose SPARQL Query from the drop-down menu.

sparql_2.png

2. A PREFIX statement will appear at the top of the new query, which is the namespace for the data.world dataset. Add another namespace for the the Grafo model by copying all but the last part of the IRI.

sparql_3.png

3. Paste the IRI path into the model namespace in the SPARQL query. Begin structuring the query with select *...where. Also, enter a service: mapped statement to indicate that you want the query to employ the data.world mapping service.

sparql_4.png

4. Write a query, for example, to retrieve the full name of the student. The syntax is ?x model:full_name ?StudentFullName. Click the Run query button in the upper-right corner to verify that the query works as you intend.

sparql_5.png