> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LanceDB Dataset Database Handler

> Handler for using LanceDB in Cognee multi-user mode.

<Warning>
  Make sure that `ENABLE_BACKEND_ACCESS_CONTROL` in your `.env` file is **NOT** set to `False`.
  Multi-user mode is enabled by default, therefore `ENABLE_BACKEND_ACCESS_CONTROL=True` by default.
</Warning>

The LanceDB adapter is one of Cognee's core vector adapters, along with PGVector.

## Installation

LanceDB is part of Cognee's core dependencies, so no extra installation steps are required.

## Setup and Usage

Since LanceDB is a file-based database, and its handler is registered in Cognee by default,
all that needs to be set is the information about the provider, and to let Cognee know which
handler you are using:

```dotenv theme={null}
VECTOR_DB_PROVIDER="lancedb"
VECTOR_DATASET_DATABASE_HANDLER="lancedb"
```

LanceDB vector files are stored by default in the .cognee\_system folder (within the Cognee package), with each dataset assigned its own persistent vector database file.

<Note>
  When the handler provisions a dataset, it ensures the per-user databases directory (`<system_root_directory>/databases/<user_id>`) exists through Cognee's storage abstraction rather than a direct local `mkdir`. Provisioning therefore routes to the correct backend based on your configured path: it creates a local filesystem directory for local `system_root_directory` values (ensure the process has write permission; defaults to `.cognee_system`), and uses S3 object storage when `system_root_directory` is an `s3://` URI. In the standard S3 setup, `STORAGE_BACKEND=s3` is used together with S3 data and system roots, so LanceDB dataset provisioning no longer fails for S3-backed targets.
</Note>

## Schema Migrations

When you upgrade Cognee and the LanceDB payload schema changes, `run_startup_migrations()` migrates existing collections to the new schema. In multi-user mode this runs for every dataset database automatically.

**Migration behavior for existing rows:**

* If all existing rows can be backfilled to the new schema (including required fields that have defaults or types that admit a safe fallback), the migration completes and the collection is updated in place.
* If any existing row cannot be backfilled — for example because a newly added field is required and has no default — the migration **aborts with a `RuntimeError`** and leaves the collection unchanged.

The error message names the collection and how many rows failed, along with sample validation errors. To resolve it:

1. Add an explicit default value to the new required field in your DataPoint model, **or**
2. Make the new field `Optional[YourType]` (which defaults to `None`).

Then re-run `run_startup_migrations()`.

<Note>
  If a dataset database migration fails, Cognee logs the error and continues migrating the remaining dataset databases. The failed dataset is left in its original state and can be retried after you fix the schema.
</Note>

## Local Cleanup with prune

When you wipe the vector store — for example via `cognee.prune.prune_system(vector=True)` — the LanceDB handler also removes its on-disk database directory for local filesystem paths. This local directory cleanup now works for any local path regardless of OS path format, including Windows paths (e.g. `C:\...`) and relative paths; previously it only triggered for POSIX absolute paths beginning with `/`, leaving the directory behind on Windows or when a relative path was configured.

Removal is skipped for remote-backed LanceDB instances, identified by a URL scheme of `db://`, `http://`, `https://`, `s3://`, `gs://`, or `az://`.

<Note>
  If you ran cleanup on Windows or with a relative LanceDB path on an earlier version, leftover database directories may remain on disk. Re-running the prune workflow on this version removes them.
</Note>

<CardGroup cols={2}>
  <Card title="Vector Stores" icon="book" href="/setup-configuration/vector-stores">
    Details About Cognee's Vector Stores
  </Card>

  <Card title="Multi-User Overview" icon="users" href="/core-concepts/multi-user-mode/multi-user-mode-overview">
    More Details About Multi-User Mode
  </Card>
</CardGroup>