Talk to Your Graph

Note

This feature is currently still experimental.

Talk to Your Graph is a chatbot that lets you converse with your data and extract factual information using natural language. The chatbot is an example of Graph Retrieval-Augmented Generation (Graph RAG), as it retrieves relevant information from a GraphDB knowledge graph in the form of triples and uses that information to generate informed responses.

Talk to Your Graph provides the accuracy and depth of graph queries without requiring comprehensive understanding of SPARQL or other retrieval methods. It works with datasets of different sizes and can be tailored to different user-specific needs. The chatbot also stores information on the server side, allowing you to manage conversations between multiple interactions.

The chatbot uses OpenAI’s GPT models and builds on the concept of agents — individual assistants based on OpenAI’s Assistants API. Each agent corresponds to a single repository and can be configured to use different models, retrieval methods, and other settings. You can express additional configurations as written text to offer further context or instructions to the agent. (More information about creating and configuring Talk to Your Graph agents is available in the Talk to your graph agent configuration parameters section below.)

The chatbot uses several extraction methods — including SPARQL queries, similarity search, simple full-text search, and the ChatGPT Retrieval Connector — to request information from your knowledge graph, based on your query.

Once you’ve set up your agents, you can then use natural language to retrieve information from your knowledge graphs using the retrieval methods you have specified. Talk to Your Graph can also show you what specific methods and queries were used for each individual response, and it can perform regular actions found in most GPT interfaces such as regeneration of the response or copying it to the clipboard.

Tip

You can start by following the Star Wars example or Acme employees and products example below.

Note

An older version of Talk to Your Graph existed prior to GraphDB 10.8 which used only the ChatGPT Retrieval Connector. For all practical purposes, that previous implementation is completely different from the current version of Talk to Your Graph.

Talk to Your Graph query methods

When creating a Talk to Your Graph agent, you can choose any combination of the four available query methods to retrieve information from the dataset. Each method is specialized to answer different types of questions and work with different types of datasets. Each agent must have one or more of the query methods enabled.

Query method	Requirements	Description
SPARQL query	One of the following: The named graph that contains the data’s class and property definitions stored as an ontology or schema. A SPARQL query that fetches ontology or schema information from the repository.	Answers questions by performing a SPARQL query. Performs well on close-ended questions, including aggregations. Suitable for datasets with well-defined schemas or ontologies.
Full-text search	Full-text search must be enabled at repository configuration level.	Answers questions by using full-text search in literals and IRIs. Performs well on open-ended questions and in datasets rich in text data, but underperforms when providing aggregations.
Semantic similarity search	Similarity index must be created.	Answers questions by using Similarity search. Performs well on open-ended questions, but underperforms when providing aggregations.
ChatGPT Retrieval connector	ChatGPT retrieval connector must be created.	Answers questions by using vector search in text chunks created from RDF. Performs well on open-ended questions, but underperforms when providing aggregations.

Tip

An agent that combines SPARQL query with either Full-text search or Semantic similarity search is suitable for most use cases, as it will be able to adequately answer both close-ended and open-ended questions and switch between methods based on the type of question the user asks.

In addition to the methods listed above, you can also enable Full-text search in labels for IRI discovery as a supplement to the main query methods. This method helps the model discover the IRIs for a particular incomplete query when it cannot answer general questions about the dataset on its own.

A hidden query method called the Now function is always enabled and provides the current date and time as its output. The result is in the time zone of the user browser that initiated the chat request that led to the model calling this tool. It has no settings. This tool helps the model answer questions that involve relative time such as “how many new employees were hired this year” or “is it OK to call John at this time?” (presuming the model can find out John’s time zone and what are appropriate hours to call him), or even things as simple as “what time is it?”

Prerequisites and configuration

In order to use Talk to Your Graph, you must have an API key for OpenAI’s API. To provide your OpenAI key to GraphDB, set the configuration property to the value of your API key.

Note

Use of the OpenAI API requires API credits, which can be purchased on the OpenAI website. Free accounts are available and may include API credits depending on the promotions currently available from OpenAI. Free credits may expire if they go unused.

Create and configure a Talk to Your Graph agent

Note

• Only users with a repository manager role can create agents. However, any user that has access to a repository also has access to the agents created for that repository.

• Talk to Your Graph does not support support Ontop and FedX repositories.

OpenAI’s Assistants API allows the creation of AI assistants within external applications. Each Talk to Your Graph agent corresponds to exactly one assistant on the OpenAI side and can retrieve information from a single GraphDB repository.

To create your first agent, select Lab ‣ Talk to Your Graph on the GraphDB main menu, click on Create your first agent, and provide the necessary configuration parameters. (If you already have one or more agents, click on the Create a new agent icon on the top right of the Talk to Your Graph interface.)

Talk to Your Graph agent configuration parameters

The Talk to Your Graph agents take several configuration parameters:

• Agent name: The name of your agent.

• Repository ID: The repository for which you are creating the agent.

• Query methods: Allows you to enable or disable each of the four query methods individually. When enabled, each method also takes additional configuration parameters:

  • SPARQL: When querying with SPARQL, you will need an ontology. You can set this to fetch the ontology from a specific named graph stored with the repository named in Repository ID. Instead of fetching the ontology from a named graph, you can also use a CONSTRUCT query to identify the triples in that repository that serve as an ontology. When using a SPARQL query method, you can use the Auto-add missing namespaces checkbox to tell Talk to Your Graph to automatically insert namespace prefix declarations when a query uses prefixes without declaring them if Talk to Your Graph can find those declarations in the repository.

    See also

    Loading data using the Workbench has a section on the import settings; this outlines how to load data such as an ontology into a named graph within a repository.

    If you do select Fetch ontology from a named graph, instead of naming a specific named graph you can use one of several special IRIs that are hints to insert a message in the instructions that tell the model what ontology to use. The following shows the supported values and what ontology schemas they tell the model to use in SPARQL queries:

    • onto:use:schema.org the schema.org ontology

    • onto:use:foaf the FOAF ontology

    • onto:use:wikidata the Wikidata ontology (note that GraphDB cannot handle Wikidata SPARQL extensions)

    • onto:custom/<some text here> <some text here>

  • Full-text search: You can set the maximum number of results per call. If left unchanged, the maximum number of triples will be automatically determined.

    Note

    To use this method, you must enable the full-text search index on the corresponding repository.

  • Similarity search: Requires the name of the Similarity index. Also takes the maximum number of results per call. If the latter is left unchanged, the maximum number of triples will be automatically determined.

    Note

    To use this method, you must create a similarity search index.

  • ChatGPT Retrieval Connector: Requires the ChatGPT retrieval connector ID. You can edit the query template and set a maximum number of results (chunks) per call. If the latter is left unchanged, the maximum number will be automatically determined.

    Note

    To use this method, you must create a ChatGPT retrieval connector.

• Full-text search in labels for IRI discovery: Described under Talk to Your Graph Query Methods.

• Temperature: Sets the sampling temperature of the agent. Lower values result in more consistent, repetitive responses generated by the agent and higher values result in a wider variety of responses. This takes a value between 0 and 2, but values higher than 1 may result in unreliable and unpredictable answers and are not recommended.

• Top P: Sets the nucleus sampling of the agent. Upon retrieving a set of candidate values, this controls how many of those values to consider using. Takes a value between 0 and 1.

• Additional instructions: Provides additional instructions and context, such as general information about the dataset, to the agent as written text.

Advanced settings:

• Base instructions

  Warning

  Base instructions for the agent. Changing this is is not recommended and may hurt performance.

After configuring your new agent, click the Create Agent button in the lower right. Next, select your agent from the drop-down list at the top and you can start entering natural language queries for that agent in the Ask field at the bottom of your screen. For example, if you graph has information about employees, you could enter “Which employee was hired the most recently?”

See also

• The Talk to Your Graph configuration properties in GraphDB

Manage Talk to Your Graph agents

Once you have created one or more agents, you can expand or hide the Manage agents panel by clicking on the Manage agents icon on the top right of the Talk to Your Graph interface. Once expanded, the panel will display a list of all available agents. You can then filter agents by repository by choosing a repository from the drop-down menu on the top of the agents list.

Manage agent settings

1. Click the Manage agents icon and scroll to the name of the agent whose settings you want to edit.

2. Click on the options icon next to an agent’s name.

3. Click on Settings.

4. Edit the settings of the agent.

Note

You can also change the repository from which the agent retrieves information. Doing so will not affect previous messages in existing conversations with the agent, but if you continue such an existing conversation, the agent will answer any new queries using the newly selected repository.

Clone agent

1. Click the Manage agents icon and scroll to the name of the agent that you want to clone.

2. Click on the options icon next to the agent’s name.

3. Click on Clone.

4. Edit the settings of the new agent.

Delete agent

1. Click the Manage agents icon and scroll to the name of the agent that you want to delete.

2. Click on the options icon next to the agent’s name.

3. Click on Delete.

Note

This will not remove your chat history with that agent. However, you will be unable to continue the conversation unless you select a new agent.

Using the Talk to Your Graph chat interface

The chat is the main interface for asking questions and receiving responses from Talk to Your Graph. There are two ways to start a conversation:

• If there aren’t any conversations available yet, select an agent if there isn’t one selected already, enter a natural language query in the Ask field (for example, “What kind of data do you have?”) and click its button. The chat will be automatically created and will appear in the chat list on the left.

• Click the Start a new chat icon at the top of the chat list. This creates a new entry on the list and puts your cursor in the Ask field. The most recently used agent from a previous chat session may be automatically selected; if not, select one from the drop-down list at the top of the Talk to Your Graph screen.

If you leave and return to the Talk to Your Graph page in your browser, the most recently used agent and chat will be already selected.

Tip

Talk to Your Graph chats correspond to Threads at the OpenAI level.

Explaining agent responses

You can ask the agent to explain how it obtained the information for any of its responses. Clicking on the Explain response icon under any response will prompt the model to respond with the query methods used. It may display a suggested prompt (like “How did you derive this answer?” below) that you can then click on to execute.

When it displays a SPARQL query, the Open in SPARQL editor icon in the upper right of the SPARQL window copies the query to Workbench’s SPARQL screen where you can explore variations on the query and execute them. The Copy SPARQL query icon to the right of that copies the query into your clipboard.

Managing chats

Talk to Your Graph remembers each user’s chats and can display a list of them grouped by date on the left of the Talk to Your Graph screen, where you can manage them. Each chat can use multiple repositories and multiple agents. When you select a chat from the list, Talk to Your Graph loads it so that you can resume that chat using the agent that was most recently used with it.

In the following the chat list has three chats under “Today”. The mouse pointer is hovering to the right of the third one, displaying a menu for actions you can take on that chat.

The Hide/Show chat list and Start a new chat icons above the list are self-explanatory. Entering a question in the Ask field at the bottom will also create a new chat if none currently exists.

A chat’s name on the list will be the beginning of the first response from the agent in that chat. As shown above, the Rename choice of the pop-up menu with each chat name will let you rename it; double-clicking a name on the list will also let you do this.

The Delete choice on that menu removes that chat, and the Export choice downloads the chat in JSON format.

Star Wars example

This example uses data describing Star Wars movies, characters, planets and vehicles, and an agent configured to use SPARQL for querying the database and answering questions.

Creating a repository and importing the data

Before you start with Talk to Your Graph, you need to create a repository and import the dataset:

1. First, create a repository with a name of your choice (for example, starwars).

2. Then, download the starwars.trig dataset and import it into your new repository.

Talking to your graph

At this point you’re set to use the Talk to Your Graph feature. On the Workbench go to Lab ‣ Talk to Your Graph.

First, you need to create an agent:

1. Click on the Create your first agent button. If you already have one or more agents, click on the Create a new agent icon on the top right of the Talk to Your Graph interface. The create agent dialog will open.

2. Enter a name for the agent, for example, “Star Wars demo”.

3. Choose the repository you just created (if not already selected).

4. Enable the SPARQL query method.

5. Click on Fetch ontology from a named graph and enter https://swapi.co/ontology/ in the named graph field, because that is the ontology named graph in the starwars.trig file you downloaded that has the ontology.

6. If needed, scroll down to the Additional instructions and enter “The data uses the SWAPI dataset and describes characters, space vessels and planets from the Star Wars universe.”

7. Click on the Create Agent button.

Once the agent has been created, you will see the chat interface. Locate the dropdown field at the top of the screen where it says Select an agent and choose the agent you just created. If you already have other agents and chats, the interface will continue showing the last chat and you need to click the Start a new chat icon at the top of the chat list. This will initiate a new chat, and then you need to select the agent you created from the dropdown.

Try asking questions about characters in the Star Wars universe:

If you are curious how a particular question was answered, you can click the Explain response icon under any response.

Acme employees and products example

Another dataset and corresponding agent configuration lets you explore the Talk to Your Graph feature with more business-oriented data. It contains data about the employees and products of Acme, an IT company that makes software for the animation industry.

Unlike the Star Wars example, this one will use both SPARQL and full-text search for querying the database.

Creating a repository and importing the data

Before you start with Talk to Your Graph, you need to create a repository and import the dataset:

1. First, create a repository with a name of your choice (for example, acme). Unlike the previous example, you need to enable the Simple full-text search index for this repository by clicking the Enable full-text search (FTS) index checkbox in the repository creation form.

   

2. Then, download the acme.trig dataset and import it into your new repository.

Talking to your graph

At this point you’re set to use the Talk to Your Graph feature. On the Workbench go to Lab ‣ Talk to Your Graph.

First, you need to create an agent:

1. Click on the Create your first agent button. If you already have one or more agents, click on the Create a new agent icon on the top right of the Talk to Your Graph interface. The create agent dialog will open.

2. Enter a name for the agent, for example, “Acme demo”.

3. Choose the repository you just created if it’s not already selected.

4. Enable the SPARQL query method.

5. Click on Fetch ontology from a named graph and enter http://example.com/acme in the named graph field because that is the named graph in the acme.trig file you downloaded that has the ontology.

6. Enable the Full-text search query method, because we will execute a query that takes advantage of that.

7. If needed, scroll down to the Additional instructions and enter “The data describes employees, roles, job titles and products of Acme, a company that makes software for the animation industry.”

8. Click on the Create Agent button.

Once the agent has been created, you will see the chat interface. Locate the dropdown field at the top of the screen where it says Select an agent and choose the agent you just created. If you already have other agents and chats, the interface will continue showing the last chat and you need to click the Start a new chat icon at the top of the chat list. This will initiate a new chat, and then you need to select the agent you created from the dropdown.

Try asking questions about employees, departments and products of Acme:

The model answered these questions by using the ontology and writing SPARQL queries. Let’s try a more open-ended question:

If you click the Explain response icon under that response you will see the model used the Full-text search query method to answer that question.

Note

Whether the model uses SPARQL or another enabled query method like Full-text search is not strictly predictable. In fact, the question about employees liking hiking and photography could be answered by a SPARQL query that searches the employees’ biographies for keywords.