FalkorDB adapter¶

FalkorGraphDB is the project's current GraphDB implementation. Most applications should start with GraphRAG, which uses the adapter through the backend-agnostic database interface. Use FalkorGraphDB directly when you need to configure the backend, inspect Cypher queries, or work with FalkorDB-specific helpers.

Connection modes¶

FalkorGraphDB supports two deployment modes.

FalkorDBLite uses db_path and runs an embedded, file-backed database. This mode does not require Docker.
Full FalkorDB uses host and port to connect to an external server process.

Provide exactly one of db_path or host. Passing both, or neither, raises ValueError.

Installation¶

Install the dependency set that matches the deployment mode.

FalkorDBLite¶

pip install 'grawiki[falkordblite]'

Full FalkorDB server¶

pip install 'grawiki[falkordb]'

If you are working from a repository checkout and want a local editable environment instead, use uv sync --extra falkordblite or uv sync --extra falkordb.

If you want a local Docker-backed server for examples or notebook work, start the compose file from the repository root:

docker compose -f notebooks/docker-compose.yml up -d

Minimal examples¶

FalkorDBLite¶

from grawiki.db import FalkorGraphDB

database = FalkorGraphDB(
    "my_graph",
    db_path="/tmp/my_graph.db",
)

Full FalkorDB server¶

from grawiki.db import FalkorGraphDB

database = FalkorGraphDB(
    "my_graph",
    host="localhost",
    port=6379,
)

Operational notes¶

close() should be called explicitly in tests and short-lived scripts. This is especially important for FalkorDBLite, which manages an embedded Redis-backed process.
The FalkorDB Browser UI at http://localhost:3000 applies to server mode, including the Docker setup above. FalkorDBLite does not expose that browser.
GraphRAG.ingest(...), GraphRAG.ingest_text(...), and GraphRAG.remember(...) usually call setup() for you. Direct adapter usage may require an explicit await database.setup(...) before indexing or search operations.

Advanced adapter helpers¶

FalkorGraphDB also exposes backend-specific methods that are useful when you are debugging queries or building custom tooling:

query(...) executes write-capable Cypher.
ro_query(...) executes read-only Cypher and is the simplest option for ad hoc inspection.
explain(...) returns FalkorDB's execution plan for a Cypher query.

Advanced users can also tune vector index creation through the constructor arguments vector_similarity_function, vector_index_m, vector_index_ef_construction, and vector_index_ef_runtime.

grawiki.db.falkordb.FalkorGraphDB ¶

Bases: GraphDB

Graph adapter supporting both FalkorDBLite and full FalkorDB.

Parameters:

Name	Type	Description	Default
`graph_name`	`str`	Logical graph name within the database.	required
`db_path`	`str \| Path \| None`	Filesystem path for FalkorDBLite persistence. Use this or `host`/`port`, not both.	`None`
`host`	`str \| None`	Hostname of a running FalkorDB server. When provided the adapter connects via TCP instead of using an embedded database.	`None`
`port`	`int`	Port number for the FalkorDB server. Defaults to `6379`.	`6379`
`vector_similarity_function`	`Literal['cosine', 'euclidean']`	Similarity function used for vector indexes.	`'cosine'`
`vector_index_m`	`int`	HNSW graph connectivity parameter used for vector indexes.	`16`
`vector_index_ef_construction`	`int`	HNSW construction candidate count used for vector indexes.	`200`
`vector_index_ef_runtime`	`int`	HNSW query-time candidate count used for vector indexes.	`10`

close ¶

close()

Close the database connection.

Notes

FalkorDBLite runs an embedded Redis process underneath the adapter. Tests should call this explicitly during teardown instead of relying on redislite's atexit cleanup hook. Server-mode connections (via host/port) may not require explicit close, but calling this method is safe in both modes.

setup `async` ¶

setup(embedding_dimensions=None)

Prepare FalkorDB indexes used by the application.

Parameters:

Name	Type	Description	Default
`embedding_dimensions`	`dict[str, int] \| None`	Mapping from node label to embedding dimensionality used for vector index creation.	`None`

query ¶

query(query, params=None)

Execute a write-capable query.

Parameters:

Name	Type	Description	Default
`query`	`str`	Cypher query to execute.	required
`params`	`dict[str, Any] \| None`	Query parameters.	`None`

Returns:

Type	Description
`Any`	Backend-native query result.

ensure_indexes `async` ¶

ensure_indexes(*, labels, vector_dims=None)

Ensure full-text and vector indexes exist for labels.

Parameters:

Name	Type	Description	Default
`labels`	`Iterable[str]`	Node labels whose indexes should be created.	required
`vector_dims`	`Mapping[str, int] \| None`	Per-label embedding dimensionality. Labels omitted from the mapping do not get a vector index.	`None`

upsert_nodes `async` ¶

upsert_nodes(nodes)

Upsert nodes, creating indexes on first use per label.

Parameters:

Name	Type	Description	Default
`nodes`	`Sequence[Node]`	Nodes to create or update. Dispatches on concrete type and label.	required

upsert_relationships `async` ¶

upsert_relationships(rels)

Upsert relationships, dispatching on label for match semantics.

Parameters:

Name	Type	Description	Default
`rels`	`Sequence[Relationship]`	Relationships to create or update.	required

Notes

__has_chunk__ matches both endpoints by node id. __mentions__ matches the entity target by id. All other labels match entity endpoints by id. Every relationship persists the same id, label, and serialized properties fields.

fulltext_search `async` ¶

fulltext_search(*, labels, query_text, limit=10)

Run a full-text search across one or more node labels.

Parameters:

Name	Type	Description	Default
`labels`	`Sequence[str]`	Labels whose full-text indexes should be queried.	required
`query_text`	`str`	Raw full-text query string.	required
`limit`	`int`	Maximum number of hits to return per label.	`10`

Returns:

Type	Description
`list[NodeHit]`	Flat list of hits across the requested labels.

vector_search `async` ¶

vector_search(*, labels, query_embedding, limit=10)

Run a vector similarity search across one or more node labels.

Parameters:

Name	Type	Description	Default
`labels`	`Sequence[str]`	Labels whose vector indexes should be queried.	required
`query_embedding`	`list[float]`	Pre-computed query embedding.	required
`limit`	`int`	Maximum number of hits to return per label.	`10`

Returns:

Type	Description
`list[NodeHit]`	Flat list of hits across the requested labels.

neighbor_relationships `async` ¶

neighbor_relationships(*, node_ids, limit_per_node=5)

Fetch one-hop relationship context for each seed node.

Parameters:

Name	Type	Description	Default
`node_ids`	`Sequence[str]`	Seed node identifiers.	required
`limit_per_node`	`int`	Maximum number of relationship rows returned for each seed.	`5`

Returns:

Type	Description
`dict[str, list[NeighborRelationship]]`	Relationship context keyed by seed id.

recall_subgraph `async` ¶

recall_subgraph(*, memory_ids, hops=1, limit_per_memory=20)

Fetch a flattened k-hop recall subgraph for memory seeds.

list_entities `async` ¶

list_entities(*, include_embeddings=False)

Return persisted entity nodes ordered by semantic key then id.

Parameters:

Name	Type	Description	Default
`include_embeddings`	`bool`	Whether to include entity embeddings in the result.	`False`

Returns:

Type	Description
`list[Node]`	Persisted entity nodes.

entity_relationship_counts `async` ¶

entity_relationship_counts(node_ids)

Return total incident relationship counts for entity ids.

merge_entity_nodes `async` ¶

merge_entity_nodes(*, master, duplicate_ids)

Merge duplicate entity nodes into master.

delete_memory `async` ¶

delete_memory(memory_id)

Delete one memory and prune directly-mentioned orphan entities.

ro_query ¶

ro_query(query, params=None)

Execute a read-only query.

Parameters:

Name	Type	Description	Default
`query`	`str`	Cypher query to execute.	required
`params`	`dict[str, Any] \| None`	Query parameters.	`None`

Returns:

Type	Description
`Any`	Backend-native query result.

explain ¶

explain(query, params=None)

Explain a Cypher query plan.

Parameters:

Name	Type	Description	Default
`query`	`str`	Cypher query to explain.	required
`params`	`dict[str, Any] \| None`	Query parameters.	`None`

Returns:

Type	Description
`Any`	Backend-native explain result.

query_fulltext_nodes ¶

query_fulltext_nodes(label, search_term, *, return_expression='node')

Run a full-text node query.

Parameters:

Name	Type	Description	Default
`label`	`str`	Node label targeted by the full-text index.	required
`search_term`	`str`	Full-text search string.	required
`return_expression`	`str`	Cypher expression returned for each matched node.	`'node'`

Returns:

Type	Description
`Any`	Backend-native query result.

query_similar_nodes ¶

query_similar_nodes(label, embedding, k, *, attribute='embedding', return_expression='node, score', order_by=None)

Run a vector similarity search against node embeddings.

Parameters:

Name	Type	Description	Default
`label`	`str`	Node label targeted by the vector index.	required
`embedding`	`list[float]`	Query embedding vector.	required
`k`	`int`	Maximum number of nearest neighbors requested.	required
`attribute`	`str`	Indexed vector property name.	`'embedding'`
`return_expression`	`str`	Cypher expression returned from the procedure output.	`'node, score'`
`order_by`	`str \| None`	Optional `ORDER BY` clause content. When omitted, cosine indexes are normalized to similarity and sorted by descending score, while euclidean indexes keep their backend distance ordering.	`None`

Returns:

Type	Description
`Any`	Backend-native query result.

explain_vector_query ¶

explain_vector_query(label, embedding, k, *, attribute='embedding', return_expression='node')

Explain a vector node query plan.

Parameters:

Name	Type	Description	Default
`label`	`str`	Node label targeted by the vector index.	required
`embedding`	`list[float]`	Query embedding vector.	required
`k`	`int`	Maximum number of nearest neighbors requested.	required
`attribute`	`str`	Indexed vector property name.	`'embedding'`
`return_expression`	`str`	Cypher expression returned from the procedure output.	`'node'`

Returns:

Type	Description
`Any`	Backend-native explain result.

save_documents_and_chunks `async` ¶

save_documents_and_chunks(documents, chunks)

Persist source documents and their chunks.

Parameters:

Name	Type	Description	Default
`documents`	`list[Document]`	Source documents to persist.	required
`chunks`	`list[Chunk]`	Source chunks to persist and connect to their parent documents.	required

save_docs_and_chunks_to_db `async` ¶

save_docs_and_chunks_to_db(doc_nodes, chunk_nodes)

Persist prepared document and chunk nodes.

Parameters:

Name	Type	Description	Default
`doc_nodes`	`list[DocumentNode]`	Prepared document nodes ready for persistence.	required
`chunk_nodes`	`list[ChunkNode]`	Prepared chunk nodes ready for persistence.	required

save_entities_and_rels `async` ¶

save_entities_and_rels(owner_ids, owner_graphs)

Persist extracted owner-linked entities and relationships.

Parameters:

Name	Type	Description	Default
`owner_ids`	`Sequence[str]`	Node identifiers that own the extracted graphs, such as chunk or memory ids.	required
`owner_graphs`	`dict[str, KnowledgeGraph]`	Extracted graphs keyed by owner identifier.	required

Raises:

Type	Description
`ValueError`	Raised when a graph references a chunk identifier that is not present in `owner_ids`.

search `async` ¶

search(query, method, *, limit=10, query_embedding=None)

Search documents, chunks, and entities.

Parameters:

Name	Type	Description	Default
`query`	`str`	Raw user query text.	required
`method`	`('fulltext', 'vector')`	Search strategy to execute.	`"fulltext"`
`limit`	`int`	Maximum number of results to return per node family.	`10`
`query_embedding`	`list[float] \| None`	Embedded query vector required for vector search.	`None`

Returns:

Type	Description
`SearchResults`	Search hits grouped by node family.

FalkorDB adapter¶

Connection modes¶

Installation¶

FalkorDBLite¶

Full FalkorDB server¶

Minimal examples¶

FalkorDBLite¶

Full FalkorDB server¶

Operational notes¶

Advanced adapter helpers¶

grawiki.db.falkordb.FalkorGraphDB ¶

close ¶

setup async ¶

query ¶

ensure_indexes async ¶

upsert_nodes async ¶

upsert_relationships async ¶

fulltext_search async ¶

vector_search async ¶

neighbor_relationships async ¶

recall_subgraph async ¶

list_entities async ¶

entity_relationship_counts async ¶

merge_entity_nodes async ¶

delete_memory async ¶

ro_query ¶

explain ¶

query_fulltext_nodes ¶

query_similar_nodes ¶

explain_vector_query ¶

save_documents_and_chunks async ¶

save_docs_and_chunks_to_db async ¶

save_entities_and_rels async ¶

search async ¶

setup `async` ¶

ensure_indexes `async` ¶

upsert_nodes `async` ¶

upsert_relationships `async` ¶

fulltext_search `async` ¶

vector_search `async` ¶

neighbor_relationships `async` ¶

recall_subgraph `async` ¶

list_entities `async` ¶

entity_relationship_counts `async` ¶

merge_entity_nodes `async` ¶

delete_memory `async` ¶

save_documents_and_chunks `async` ¶

save_docs_and_chunks_to_db `async` ¶

save_entities_and_rels `async` ¶

search `async` ¶