Skip to main content

​
What is a Dataset Database Handler?

Dataset Database Handlers are small, pluggable classes that define how a Cognee dataset maps to concrete storage backends for:
  • Graph databases
  • Vector databases
They act as the abstraction layer between a logical dataset and its physical storage. Extensible by design: You can write custom handlers to integrate Cognee with any database and database backend (AWS, Azure, GCP, local setups and etc.) without modifying core code. Dataset Database Handler Diagram In this diagram, we can see that each dataset is mapped to its own unique Neo4j graph database instance using a Neo4j Aura Dataset Database Handler. This connection is automatically resolved at runtime based on the authenticated user and dataset being accessed and is done when recalling, remembering, forgetting, creating, or otherwise modifying a dataset.
If you’re using Cognee with ENABLE_BACKEND_ACCESS_CONTROL set to False, you don’t need to configure handlers.

​
How graph isolation works

Dataset Database Handlers matter specifically in multi-user mode, because that is when Cognee stops treating datasets as logical partitions inside one shared graph and starts routing each dataset to its own storage backend.
Single-user modeMulti-user mode
Graph databasesOne shared instanceOne per dataset
Separation mechanismdataset_id metadata filterPhysical database boundary
Handler requiredNoYes (GRAPH_DATASET_DATABASE_HANDLER)
All datasets share one physical graph database. There are no hard graph-level boundaries between them. Dataset separation is tracked logically in the relational database through dataset_id, and queries are scoped using that metadata at runtime.

​
What Dataset Database Handlers Do

Handlers encapsulate all backend-specific logic required to manage dataset storage, including:
  • Provisioning or resolution of per-dataset storage
  • Runtime connection resolution, such as:
    • Secret decryption
    • Fetching short-lived credentials
  • Teardown and deletion of per-dataset storage
Handlers are selected through configuration and registered in a central handler registry. This allows Cognee to support multiple providers and custom storage setups without modifying core pipeline code.

​
Why Dataset Database Handlers Exist

Dataset Database Handlers solve several core system needs:
  • Multi-tenant isolation — Each dataset can map to its own graph and/or vector database, enabling clean separation when backend access control is enabled.
  • Pluggability — Providers like LanceDB, Kùzu, or Neo4j Aura can be added or swapped without changing application logic.
  • Secure secret handling — Credentials can be resolved at connection time instead of being stored in plaintext in the relational database.
  • Lifecycle control — All create, resolve, and delete semantics for a backend live in one well-defined place.
Cognee requires database instances provisioned via the Dataset Database Handler to be active and running. While Cognee facilitates the creation and deletion of these databases, it does not manage the operational lifecycle—such as starting or stopping containers—during its own startup or shutdown processes.

Datasets

Learn about datasets as the core unit of storage in Cognee

Dataset Database Handlers: How to use them

Deep dive into configuring and using dataset database handlers