Quickstart with AI assistance

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

Early release

The AI-assisted mapping generator is available starting from 2026.2.0-beta-1.

8 Steps to get you going

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

Create a new project

1. The first step is to create a new project by clicking on the + icon or the text Get started by creating your first project.

   

2. Give your project a name and add a description relevant to the project. Choose Sample DB as project type, so your new project connects to the existing sample database and click on Save.

   

After saving, you will automatically land on the dashboard of the newly created project.

Import the ontology

1. Save the following ontology in a .ttl file.
2. Click on Import ontology from the home page to import the already saved ontology. As you can notice, the Turtle ontology format is automatically recognized.

Enable AI

1. Go to Settings > AI Configuration.
2. Click on the button near Enable AI to enable the AI-assisted mapping generator.

3. Select your preferred LLM model from the drop-down menu.

List of database tables

Having chosen a Sample DB as project type, the database connection is already set up, and 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.

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 lens on the bottom of the page.
   Note: If you are using the Windows Desktop version select DESTINATION-DB.source1.hospitality and DESTINATION-DB.source1.municipalities .

   

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 AI 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 voc:Municipality by clicking on the green tick.

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

Map hospitalities to a class

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

   

2. Click on the AI button.

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

   

4. Select voc:LodgingBusiness by clicking on the green tick.

The template data:source1-hospitality/{h_id} is now an instance of voc: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 voc: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 voc: <http://vocabulary.example.org/>
      SELECT * WHERE {
          ?sub a voc:LodgingBusiness;
              voc: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 voc: <http://vocabulary.example.org/>
      SELECT * WHERE {
          ?sub a voc:LodgingBusiness;
              voc:name ?name ;
              voc: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.