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 searching/creating/deleting or adding to a dataset.
If you’re using Cognee with ENABLE_BACKEND_ACCESS_CONTROL set to False, you don’t need to configure handlers.

​
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