Quickstart

In this quickstart we will learn how to use Ontopic AI-assisted mapping generator to automatically propose class and property mapping entries.

Pre-requisites

• The destination-tutorial-db database is up
• The LLM provider has been configured as a secret for Ontopic

9 Steps to get you going

1. Import the ontology
2. Create a data source
3. Create an empty mapping
4. Enable AI-assisted mapping generator
5. Create lenses from the database tables
6. Map data to classes and properties
7. Query the Knowledge Graph using SPARQL
8. Materialize data into a graph database
9. Query the Knowledge Graph using SQL

Import the ontology

1. Download the quickstart destination ontology
2. In metaphactory, go to Assets > Ontologies, click on the Import menu and select Import from local file
3. Upload the downloaded quickstart destination ontology

Create a data source

1. Go Assets > Datasources and click on Create datasource
2. Fill in the connection information as shown below. The password is postgres2.

3. Click on Select schemas
4. Select the schemas source1, source2 and source3 and click on Create

Create an empty mapping

1. On Assets > Datasources, find the datasource Destination tutorial in the list and click on its Create mapping button

2. Name the mapping as below, select the quickstart destination ontology, unselect Generate AI mapping and click on Create

   

3. On the mapping page, wait for the button Map in Ontopic to appear and click on it

Enable AI and label rendering

1. In Ontopic, go to Settings > AI Configuration
2. Click on Enable AI and select the preferred LLM model from the drop-down menu

4. Go to Settings > Advanced settings
5. Enable Use labels

List of database tables

You can see the list of tables by selecting the Data Lenses tab on the left-side navigation menu

What we want to build

Our goal is to build a Knowledge Graph giving us information about all the lodging businesses in South Tyrol, Italy.

For our tutorial, we will be using the following two tables for the sake of simplicity:

1. source1.municipalities
2. source1.hospitality

Creating lenses

1. Select Data Lenses from the left-side navigation menu to get a list of all tables

2. Select the two tables source1.hospitality and source1.municipalities, by checking the checkboxes and clicking Generate mirror lenses at the bottom of the page.

   

Mapping data from the database to a Knowledge Graph

Start populating your Graph (Mapping a lens to a class)

Map municipalities to a class

1. Select Mapping from the left-side navigation menu and select the lens lenses.source1.municipalities.

   

2. Click on the C* button.

   

3. The AI service analyses the table and returns a ranked list of candidate classes:

   The score is a confidence value between 0 and 1 - use it as a guide, but always review the candidates and accept the one that best fits the intended semantics.

   

4. Select Municipality by clicking on the green tick.

The template data:source1-municipalities/{r_id} is now an instance of Municipality.

Map hospitalities to a class

1. Select the lens lenses.source1.hospitality from the Mapping menu.

   

2. Click on the C* button.

3. The AI service analyses the table and returns a ranked list of candidate classes:

   

4. Select LodgingBusiness by clicking on the green tick.

The template data:source1-hospitality/{h_id} is now an instance of LodgingBusiness.

Adding properties to the class instances (Mapping lens municipalities to data and object properties)

With a class assigned to both lenses, click on the AI button on the right of the template data:source1-hospitality/{h_id} once. The AI service processes the lens and streams proposals to the UI.

Connecting municipalities to lodging businesses (Mapping a lens to an object property)

The following mapping entry (opens new window) involves two different identifiers, one about lodging businesses and one about municipalities. We have to connect these two to get the answer to our specific question. The AI service detects that h_id is a foreign key pointing to municipalities and proposes an object property mapping entry between the two identifiers.

Select containedIn by clicking on the green tick.

Adding data properties to the class instances (Mapping a lens to data properties)

The AI service then proposes data property mapping entries on the remaining columns:

For the purpose of this quickstart reject the proposals on columns name_it and name_de by clicking on the red cross. Accept the others by clicking on Accept all at the bottom.

Important: the mapping generator is AI-based and can make mistakes. Always review every proposal before accepting - scores indicate confidence, not correctness. Results may differ from this quickstart.

Query the Knowledge Graph using SPARQL

We can now extract key facts by testing the Knowledge Graph with SPARQL queries.

1. Select Query > SPARQL from the left-side navigation menu.

   

2. Write the query for finding the lodging businesses and click on the play button.

   1. First we query the first 10 lodging businesses by typing:

      PREFIX dest: <http://quickstart.example.org/>
      SELECT * WHERE {
          ?sub a dest:LodgingBusiness;
              dest:name ?name.
      }
      LIMIT 10
      

   The first 10 lodging businesses

   

   2. We can get information about the municipality identifier in which such lodging business are contained in by typing:

      PREFIX dest: <http://quickstart.example.org/>
      SELECT * WHERE {
          ?sub a dest:LodgingBusiness;
              dest:name ?name ;
              dest:containedIn ?place .
      }
      LIMIT 10
      

   The first 10 lodging businesses with their location

   

Materialize data into a graph database

Materialize in RDF files and load into a triplestore (starting from 2024.1).

Materialization to RDF is disabled by default (except for the Desktop version, where files are stored locally). See how to enable materialization with S3.

1. Click on Materialize to materialize the knowledge graph into an RDF file.

   

2. Then select the RDF format

   

3. Then select the Compression format

   

4. You can materialize your KG into one file in compress or uncompress format. For simplicity, we keep the default option and materialize with zip compression.

5. Click on Materialize, you will have all the content of KG copied to the file materialized-triples.ttl.

   

6. Now you can load this file in the triplestore of your choice, in this case, use GraphDB (opens new window). This graph database offers several ways to load files (opens new window). Here, since the file is only 200 MB, we go for the simplest option and load it directly from the UI.

7. We can now see the list of materialized files by clicking on List files.

   

8. This will show a list of all materialized files. Each materialized file has three associated actions: "Export materialized file" or "Open directory", "Copy file location to clipboard", and "Delete materialized file".

   

Query the Knowledge Graph using semantic SQL

We can additionally extract information from the Knowledge Graph using the semantic SQL endpoint. To more easily explore the data, we will use DBeaver (opens new window), a standard open-source SQL tool.

1. Connect to the Semantic SQL endpoint using DBeaver

   1. Select Query > Semantic SQL from the left-side navigation menu.

      

   2. Generate a Personal Access Token by clicking the Generate button. Copy it and save it somewhere safe, as you will not be able to see it again.

      

   3. Start the Semantic SQL endpoint by clicking the Start button in the top right.

   4. On the left, you can see the connection details to connect to the Semantic SQL endpoint. You will need these details in DBeaver.

      

   5. In DBeaver, go to the Database menu, select New Database Connection and choose PostgreSQL as your database type.

   6. Fill in the connection details from Ontopic Suite, using the Personal Access Token as password. Click on Finish to save the connection.

      

2. Explore the data using the DBeaver UI

   1. From the left side panel, expand the connection created until you see the LodgingBusiness table and click on it to see the data.

      

      

   2. Alternatively, if you move from the Data tab to the Diagram tab, you can visualize the Entity-Relationship diagram for the data.

      

3. Query the data directly using SQL

   1. In DBeaver, right-click on the connection name and select SQL Editor > New SQL Script. A new tab will open where you can type your SQL queries.

   2. To run the same query defined in the SPARQL section and retrieve the first 10 lodging businesses in South Tyrol, enter the following SQL query and click on the play button.

      SELECT *
      FROM "classes"."LodgingBusiness"
      LIMIT 10;
      

      The first 10 lodging businesses in in South Tyrol.