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 works with most large language models (LLMs) that are compatible with the Chat Completions API.

The chatbot builds on the concept of agents — individual assistants that 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 on 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.

See also

The two Talk to Your Graph examples showcase how to create and query a Talk to Your Graph agent using a simple dataset (Star Wars example) or a more complex, business-oriented dataset (Acme employees and products example).

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.

Prerequisites and configuration

Before using Talk to Your Graph you must configure an LLM API type, an API key, and a default model:

• graphdb.llm.api: The address for the LLM API type that will determine the available LLM models.

• graphdb.llm.api-key: The authentication token for the LLM API.

• graphdb.llm.model: The model which Talk to Your Graph agents will use by default, if not changed during the creation process.

If an LLM API type is not provided with graphdb.llm.api, Talk to Your Graph will default to OpenAI’s Completions API. If the graphdb.llm.api property is set, graphdb.llm.model is required.

See also

The full list of relevant configuration properties, as well as detailed explanation of which properties are required, is available in the Talk to Your Graph properties documentation.

Model Requirements

Talk to Your Graph uses large language models to process natural language questions and fetch relevant data from GraphDB using the provided extraction method. The response from GraphDB is then once again processed by the LLM, and returned as a natural language response to the user. Thus Talk to Your Graph should work with most LLM APIs which are compatible with the Chat Completions standard, and meet the following requirements:

• Must support function calling (tool calls)

• Must support multi-turn conversations

• Must be capable of generating code (specifically SPARQL queries)

• Should have a large context window to process the ontology and the memory

Note

The LLM needs the ontology of the knowledge graph to succeed in generating a truthful response. Different models may be suitable for different ontologies. We strongly recommend experimenting with different models (if possible) to see which one yields the best results for your specific ontology.

Warning

Small local models often do not perform well in SPARQL query generation. However, a bigger model does not necessarily translate to better results, and must be tested first.

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	The tool can now use either: A similarity index A connector for similarity search (Elasticsearch or OpenSearch) that has declared at least one field with datatype "vector" or "native:semantic_text" (if using Elasticsearch)	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.

Note

When using full-text search, it is a good idea to limit the number of results to prevent results from filling the context window. This is especially advisable when using Talk to Your Graph with models with smaller context windows.

You can also set the full-text search query itself using the configuration property graphdb.ttyg.fts.query.template. Check the Talk to Your Graph properties documentation for more information.

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.

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?”

IRI discovery query methods

You can also enable additional query methods — Autocomplete for IRI discovery and Full-text search in labels for IRI discovery — as a supplement to the main query methods listed above. These methods help the model discover the IRIs for a particular incomplete query when it cannot answer general questions about the dataset on its own.

We recommend you try Autocomplete for IRI discovery first. It requires autocomplete for the repository to be enabled and comes with default values for max number of results (IRIs) per call which can be individually configured.

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 Ontop and FedX repositories.

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 or connector index. Takes the maximum number of results per call. If the latter is left unchanged, the maximum number of triples will be automatically determined.

    This method takes several additional configuration parameters of its own:

    Parameter	Type	Description	Default value
    similarityIndex	string	Name of the similarity index (for Similarity plugin index) or connector instance for similarity search (for Elasticsearch/OpenSearch connectors)
    resultThreshold	double	Minimum similarity score for results to be included	0.4
    limit	int	Maximum number of triples to return per call (0 is unlimited)	0
    connectorType	string	Determines which backend is used: "similarity", "elasticsearch", or "opensearch"
    connectorFields	array of string	(For connectors only) Specifies which vector field (one) to use in the search query

    The agent uses only text-based similarity search, and does not support the use of predicate-based similarity indexing or other methods.

    Note

    To use this method, you must create a connector with a vector field (Elasticsearch or OpenSearch) or 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.

• IRI discovery query methods: Described under Talk to Your Graph Query Methods.

• Model: Sets the LLM model of the agent. If this is left unchanged, the agent will use the default model, as described in Prerequisites and configuration.

  Tip

  If you are unsure what models are available for your deployment, your administrator should be able to provide you with a list.

• 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.

  Note

  When creating or updating an agent, the Temperature can be omitted. Some providers do not allow for both Top P and temperature to be passed to some of the models.

• Context window size: Sets the maximum size of the context sent to the model with each request, measured in tokens. When the context window exceeds the maximum size, the mechanism will start removing old messages to fit the maximum size.

  The default size is 1,000,000 and is controlled by the graphdb.ttyg.model.context.window.size property.

  Warning

  The maximum context window size must not be bigger than what the model supports. If the maximum size exceeds that, it will eventually result in errors when using the agent. Consult with the documentation of the model you are using to check what the model supports.

• 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.

  Note

  When creating or updating an agent, the Top P parameter can be omitted. Some providers do not allow for both Top P and temperature to be passed to some of the models.

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

Advanced settings:

• Base instructions: The instructions that provide the agent with a personality, as well as general context on answering questions about data stored in GraphDB.

  Warning

  Changing the base instructions 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.

Warning

You can also cancel a running question — for example, when an agent takes too long to respond. However, be aware that this does not guarantee no tokens are consumed. Tokens may still be spent during processing, and the exact amount used cannot be predicted in advance. Use caution when canceling queries, particularly those involving large or complex datasets.

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.