Connect Graph DB

This guide describes how to register an externally hosted graph database in AI Knowledge Fabric, so GraphRAG Topics can store their knowledge graph there.

1. What is a graph database for?

A GraphRAG Topic reads your documents and finds the important things in them: people, products, places, terms. These are called entities. It also records how the entities are connected. All of this together is the knowledge graph. The graph database is where the knowledge graph is stored.

In the chat, a GraphRAG Topic uses this graph to answer questions that need connections between facts, not only single text passages.

A graph database is required for every GraphRAG Topic. There is no built-in store to fall back to. A registered graph database is the only way to give a GraphRAG Topic a place for its graph. A GraphRAG Topic also needs a registered vector database — see Connect Vector DB:

Vector store Graph store

Built-in option

No

No

Registered database

Required — see Connect Vector DB

Required

The platform does not start a graph database for you. The database must already be running, and you register a connection to it here. You register it once and can then use it in as many GraphRAG Topics as you like.

2. Supported types

Type Protocol Default port Default authentication Notes

CYROCK_DB

gRPC

9090

API Key (fixed)

Also needs a Project ID (a UUID) and a Graph Name — see CYROCK.DB

NEO4J

Bolt

7687

Username / Password

MEMGRAPH

Bolt

7687

None

GENERIC_CYPHER

Bolt

7687

Username / Password

For other graph servers that speak the Bolt protocol and the Cypher query language

The port and authentication values above are pre-filled when you pick a type for a new entry. Use TLS starts switched off. Change the values if your server differs.

When you edit an existing entry and change its type, the port and authentication are not changed for you. Only CYROCK_DB still fixes the authentication to API Key.

The dialog names the protocol in the Port label once a type is picked: Port (gRPC) for CYROCK_DB, Port (Bolt) for the others. The Endpoint column of the list shows the same as a scheme (grpc://, grpcs://, bolt://, bolt+s://). So a wrong port or a wrong TLS setting is visible without opening the entry.

CYROCK.DB: fixed port, fixed authentication

CYROCK.DB is reached over gRPC on port 9090. The same port serves encrypted and unencrypted connections. Ticking Use TLS encrypts the connection and leaves the port as it is.

Three more fields are not free choices for this type:

  • Authentication is always API Key. CYROCK.DB has no other way to log in. The picker is fixed and shows CyrockDB only accepts an API key, so this cannot be changed. The key is required.

  • The Project ID is a UUID, not a project name. Use the project’s id, for example 123e4567-e89b-12d3-a456-426614174000. A name is rejected on Save. Otherwise it would only fail much later, when a GraphRAG Topic first connects.

  • The Graph Name is required. It is the start of the graph’s name, not the full name. See Graph Name and Database Name.

The same CYROCK.DB server can also be registered under Admin → Vector Databases, as the vector store of a Topic or GraphRAG Topic. The port, the API-key rule and the Project ID rule are the same there.

Bolt types: TLS comes from the scheme

NEO4J, MEMGRAPH and GENERIC_CYPHER are reached with a direct Bolt connection. The address is built from Host and Port:

  • Use TLS off → bolt://<host>:<port> (not encrypted)

  • Use TLS on → bolt+s://<host>:<port> (encrypted)

Turn Use TLS on when the server only accepts encrypted connections. With TLS on, the server’s certificate must be trusted. A self-signed certificate cannot be verified, and the connection test says so.

The port does not change when you tick Use TLS. If your server uses a different port for encrypted connections, enter it yourself.

Not supported yet: Neo4j Aura and other Neo4j clusters with several servers. They need a different kind of address (neo4j+s://…) that cannot be entered here. Only a single server, reached directly, works.

3. Register the database

Navigate to Admin → Graph Databases and click Add Graph Database.

Viewing this screen requires the SERVER_VIEW permission. Add Graph Database, Edit and Delete require SERVER_MANAGE. If the buttons are missing, ask an administrator to check your role.

The list shows one row per registered database:

Column Shows

Name

The name you gave the entry

Type

CYROCK_DB, NEO4J, MEMGRAPH or GENERIC_CYPHER

Endpoint

Protocol, host and port the platform connects to, for example bolt+s://graph.example.com:7687

Authentication

NONE, API_KEY or USERNAME_PASSWORD

Actions

Edit and Delete

The Search…​ field above the list filters by name and endpoint.

Fill in the dialog

Field Required Notes

Name

Yes

A name that tells you which database this is, for example Neo4j Production. It is shown in the GraphRAG wizard

Type

Yes

One of the four types above. For a new entry, picking a type fills in the port and authentication

Host

Yes

Server name or IP address only — no bolt://, no https://, no port. See Choosing the Host value

Port / Port (Bolt) / Port (gRPC)

Yes

Pre-filled per type: 7687 for the Bolt types, 9090 for CYROCK_DB

Authentication

Yes

None, API Key or Username / Password. The fields below appear to match. Fixed to API Key for CYROCK_DB

API Key

If API Key

Required for CYROCK_DB. For the Bolt types, the key is sent as a login token. Use this only if your server is set up for token login

Username / Password

If Username / Password

The database user the GraphRAG Topics log in with

Graph Name (CYROCK_DB) / Database Name (other types)

CYROCK_DB: Yes. Others: No

Means something different per type — see Graph Name and Database Name

Project ID

CYROCK_DB only

The CYROCK.DB project where the graphs are created, as a UUID. Shown only for this type

Use TLS

No

Off by default. Turn it on when the server only accepts encrypted connections. The port stays the same

Description

No

A free note for your own documentation

Click Save. The message Graph database saved confirms it.

The dialog does not close when you click outside it or press Esc. Leave it with Cancel or Save, so a pasted password or key is not lost by accident.

Graph Name and Database Name

The same field has a different label and a different meaning per type.

CYROCK_DB — Graph Name (required). This is only the start of the graph’s name. Each GraphRAG Topic adds its own ID to it, for example <name>_<topic id>. The topic creates its graph on its first start. So several topics can share one connection, and each topic keeps its own graph.

NEO4J, MEMGRAPH, GENERIC_CYPHER — Database Name (optional). This is the database on the server that the topic writes its graph to. It is used exactly as you type it.

  • It must already exist. The platform does not create it.

  • Leave it empty to use the server’s default database. Neo4j Community Edition has only this one.

  • All topics that use this connection write into the same database, and their graphs mix. A topic may then find entities from another topic’s documents. To keep topics apart, register one connection per topic, each with its own database. Or give each topic its own server.

Choosing the Host value

The host must be reachable from inside the GraphRAG Topic containers, not from your browser. The value is passed on to the containers as you type it.

Where the database runs Host value

On the Docker host, Docker Desktop (Windows/macOS)

host.docker.internal

On the Docker host, plain Linux Docker

172.17.0.1

As another container on the same Docker network

That container’s service name

On another server or in the cloud

Its hostname or IP, for example graph.internal.example.com

In Kubernetes, in the same cluster

The Service DNS name, for example neo4j.default.svc.cluster.local

localhost almost never works. Inside a GraphRAG Topic container, localhost means that container itself, not your machine.

Enter only the bare host. Unlike the vector database dialog, this field does not take a pasted URL apart for you. A value like bolt://graph.example.com would be put into a second bolt:// address and could never connect. Remove the scheme and use Port and Use TLS instead.

4. Test the connection

The dialog has a Test Connection button. Use it before saving. It tests the values currently in the dialog, even if they are not saved yet. While it runs, the button reads Testing…. Each attempt waits up to 5 seconds.

Pick a Type first. Otherwise the test stops with Select a type before testing the connection.

How deep the test goes depends on the type:

Type What is tested

NEO4J, MEMGRAPH, GENERIC_CYPHER

A real Bolt connection with login, built from the same address, TLS setting and credentials the GraphRAG Topics use. Checks host, port, TLS and the credentials

CYROCK_DB

A plain network connection to host and port only. The API key, Project ID and Graph Name are first checked when a GraphRAG Topic starts

For the Bolt types, the test also opens the Database Name, if you entered one. So a misspelt or missing database shows up here, not only when a GraphRAG Topic starts. With an empty Database Name, the server’s default database is used and not checked separately.

Message Meaning

Connected to bolt://<host>:<port> over Bolt — credentials accepted.

The server answered and accepted the login. This configuration works

… Database "<name>" exists. (at the end of the message above)

The Database Name was found on the server

Connected, but database "<name>" does not exist on this server.

Login works, but there is no database with this name. Check the spelling, or create the database on the server first

Connected, but selecting database "<name>" failed: …

Login works, but the database could not be opened. Some servers, for example Memgraph, do not support named databases — then leave the Database Name empty

Connected to bolt://<host>:<port> over Bolt.

The server answered. Authentication is None, so no login was checked

Reachable at <host>:<port> (TCP only — the API key, project id and graph name are verified when a GraphRAG topic starts).

CYROCK_DB: the network path is fine. The other values are still unchecked

Reached … but authentication was rejected: … Check the credentials.

Host, port and TLS are right. The username, password or key is wrong

TLS/certificate error connecting to …

With Use TLS off: the server probably requires TLS — turn it on. With Use TLS on: the certificate cannot be verified, for example because it is self-signed

Cannot resolve hostname '<host>'.

The host name is unknown — check the Host field

Connection refused at <host>:<port>. Is the server running?

The host was found, but nothing listens on that port

Connection to <host>:<port> timed out. Check the host, port and network access.

No answer within 5 seconds. A firewall may block the port

Cannot reach … over Bolt: … Check the host and port (Bolt default is 7687) and whether the server is running.

The Bolt connection failed for another reason. The text after the colon gives the detail

Host is required / Port is required

Fill in the field and test again

5. Use the database in a GraphRAG Topic

In the GraphRAG Topic wizard, step Basic Information, section Storage:

  1. Open the Graph Database dropdown. Entries appear as Name (TYPE).

  2. Select your database. The field is required. Without a choice, the wizard shows Required — select a graph database. and does not continue.

  3. If the list is empty, register a database on this screen first.

The vector store in the same section is separate. It holds the search data, not the graph. See Connect Vector DB.

Selecting the database is enough. Host, port, credentials and the graph or database name are passed to the topic container automatically when it starts.

Choose before the first upload, and then keep it. If you later switch a topic to a different graph database, or change the Graph Name or Database Name, the topic works with a different graph. The entities found so far are not moved there, so answers lose them. Upload the documents again after such a change.

6. Editing and deleting

Action Effect

Edit

Changes reach a GraphRAG Topic the next time it starts. A running topic keeps the connection it was started with. Stop and start it to apply the change

Delete

Only removes the entry in this platform. The database and its data stay untouched. The confirmation says: Delete "<name>"? Only this entry is removed — the data in the database itself is not deleted.

A graph database that a GraphRAG Topic still uses cannot be deleted. The platform refuses with a message that names the topics:

"<name>" cannot be deleted: it is still used by <n> GraphRAG topic(s): <topic names>. Choose another database for these topics first.

Select another graph database in those topics first, or delete the topics. The check runs again when you confirm, in case a topic picked the database in the meantime.

Deleting a GraphRAG Topic does not delete its graph. It stays in the graph database and has to be removed there.

7. Limitations

  • No built-in graph store. Every GraphRAG Topic needs a registered graph database.

  • Neo4j Aura and Neo4j clusters with several servers are not supported yet. Only a direct connection to one server (bolt:// or bolt+s://) can be entered.

  • Self-signed certificates cannot be verified with Use TLS.

  • Bolt types do not separate topics on their own. All topics on one connection share one database. Register one connection per topic to keep them apart.

  • The platform creates no database on Neo4j, Memgraph or other Bolt servers. A Database Name must exist before a topic uses it. Only CYROCK.DB creates the graph by itself.

  • The connection test is limited for CYROCK_DB: it checks only the network, not the API key, Project ID or Graph Name.

8. Troubleshooting

Symptom Cause and fix

The Graph Database dropdown in the GraphRAG wizard is empty

No graph database is registered yet. Add one on this screen first

Add Graph Database, Edit and Delete are missing

Your role has SERVER_VIEW but not SERVER_MANAGE

Test Connection: "Cannot resolve hostname"

Wrong Host value. Do not use localhost — see Choosing the Host value

Test Connection: "Connection refused"

Wrong port, or the database is not running. Bolt servers usually use 7687, CYROCK.DB uses 9090

Test Connection: "authentication was rejected"

Host, port and TLS are right, but the login is not. Check username and password, or the key

Test Connection: "TLS/certificate error"

Use TLS does not match the server. Turn it on for a server that requires encryption, or off for one that does not. A self-signed certificate is not supported

Test Connection fails with a host like bolt://… or …

The Host field holds a full address. Enter only the host name

Test Connection succeeds, but the topic cannot use the graph

For CYROCK_DB the test checks only the network, so check the API key, Project ID and Graph Name. Read the topic’s Logs tab

Save rejected: "Project ID is required for CyrockDB"

The Project ID field is empty. It is required for this type

Save rejected: "The project ID must be a UUID, …"

A project name was entered. Use the project’s id, for example 123e4567-e89b-12d3-a456-426614174000

Save rejected: "An API key is required for CyrockDB"

CYROCK.DB logs in with an API key only. Enter the key

Save rejected: "A graph name is required for CyrockDB"

Enter the start of the graph name, for example knowledge

A GraphRAG Topic does not start: "… needs a host, a project ID and a graph name — set them under Admin → Graph Databases."

An older CYROCK_DB entry is incomplete. Open it with Edit, fill in the missing fields, and start the topic again

A topic finds entities from another topic’s documents

Both topics use the same Neo4j, Memgraph or other Bolt connection, so they write into the same database. Register one connection per topic, each with its own Database Name

Neo4j Aura or a Neo4j cluster cannot be connected

Not supported yet — only a single server reached directly works

A change to the entry has no effect

A running topic keeps the connection it was started with. Stop and start the topic

Delete refused: "… is still used by … GraphRAG topic(s) …"

Select another graph database in the named topics first, or delete them

The database still holds data after deleting a topic

Deleting a topic does not delete its graph. Remove it in the graph database itself

Related