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

# Collections and data model

> Understand how LambdaDB collections organize searchable documents, embeddings, and metadata.

A LambdaDB collection organizes a dataset for storage, search, and versioning. It is a logical namespace that holds documents, where each document can contain source data, embeddings, and metadata as key-value fields.

## Database structure comparison

LambdaDB's structure differs from traditional relational databases. Here's how they compare:

| RDBMS | LambdaDB |
| :- | :- |
| Database | Project |
| Table | Collection |
| Column/row | Document with key-value pairs |

Think of a LambdaDB project as a database that can contain many collections (similar to tables). Each collection holds documents as flexible key-value pairs.

> [!NOTE]
>
> Indexes in LambdaDB are not the same as you'd find in a relational database. The whole document is stored as is regardless of its existence in index configurations, but being stored does not necessarily mean it is searchable.

## API interaction

LambdaDB provides a RESTful JSON-based API for interacting with document data. You can perform the following operations by sending HTTP requests to the appropriate endpoints:

* **Upsert** documents into collections
* **Search** across documents using various query types
* **Delete** individual documents or entire collections
* **Update** document data and collection configurations

These CRUD-like operations can take place at both individual document level and collection level, giving you flexibility in how you manage your data.

## Data versioning

Every collection has a default branch named `main`. Data versioning adds three kinds of named ref within that collection:

* A **branch** is a writable line of history and can be created only from another branch in the same collection.
* A **tag** is an immutable name for one committed snapshot.
* An **alias** is a mutable read name that points to a branch or tag.

Reads use `main` when no ref is supplied. Queries, fetches, and lists can instead select a branch, tag, or alias. Writes select a branch name and cannot target a tag or alias.

### Key benefits

* **Isolated writes**: Develop or validate changes without writing to `main`.
* **Pinned reads**: Use a tag when a workflow must keep reading the same committed snapshot.
* **Stable routing**: Retarget an alias without changing the read-side ref name.
* **Point-in-time starts**: Create a branch from a committed snapshot at or before a Unix epoch-millisecond timestamp.

### Use cases

This feature is particularly useful when you want to:

* Create isolated environments for testing without affecting production data.
* Set up staging or validation histories inside one collection.
* Pin a dataset version for evaluation or reproducible retrieval.
* Move a read alias between a branch and a tag during a controlled rollout.
* Create a recovery branch from retained history.

> [!NOTE]
>
> Changes written to one branch do not change another branch. Schema updates, metadata tags, partitioning, and retention are configured at the collection level. Branches are not independent schema-editing environments; tag reads retain the schema pinned with their snapshot.

See [Branches, tags, and aliases](https://docs.lambdadb.ai/guides/data-versioning/branches-tags-aliases.md) for the REST contract and consistency rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.