Branches, tags, and aliases

LambdaDB data versioning provides named histories for the knowledge or memory stored in a collection. Every collection starts with a default branch named main.

Ref type	Purpose	Writable	Target can change
Branch	Isolated line of document history	Yes	Advances when writes commit
Tag	Immutable name for one committed snapshot	No	No
Alias	Stable read name for a branch or tag	No	Yes, with `PATCH`

Refs are scoped to one collection. Branch merge, direct branch reset, ref rename, and cross-collection snapshot sharing are not part of this API. Branch, tag, and alias names must contain 3 to 52 letters, numbers, underscores, or hyphens.

Use the SDKs

Install a supported SDK version and use your project’s connection details from LambdaDB Cloud. These examples assume an existing knowledge-base collection with a title text field and no branch named candidate. Run one language example or the REST alternative below, not both against the same branch name. The Go function accepts a client configured as shown in the Quickstart.

from lambdadb import BranchSource, LambdaDB, Ref

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    collection = client.collection("knowledge-base")
    branch = collection.branches.create(
        "candidate", source=BranchSource.branch("main")
    ).branch
    if branch.parent_branch is not None:
        print(branch.parent_branch.name)
    if branch.head_snapshot is not None:
        print(branch.head_snapshot.snapshot_id)

    collection.docs.upsert(
        docs=[{"id": "doc-1", "title": "Candidate document"}], branch="candidate"
    )
    result = collection.docs.fetch(
        ids=["doc-1"], ref=Ref.branch("candidate"), consistent_read=True
    )

import { LambdaDBClient, branchRef, branchSource } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});
const collection = client.collection("knowledge-base");
const { branch } = await collection.branches.create({
  branchName: "candidate",
  source: branchSource("main"),
});
if (branch.parentBranch !== null) console.log(branch.parentBranch.name);
if (branch.headSnapshot !== null) console.log(branch.headSnapshot.snapshotId);

await collection.docs.upsert({
  docs: [{ id: "doc-1", title: "Candidate document" }],
  branch: "candidate",
});
const result = await collection.docs.fetch({
  ids: ["doc-1"],
  ref: branchRef("candidate"),
  consistentRead: true,
});

import (
    "context"
    "fmt"

    lambdadb "github.com/lambdadb/go-lambdadb"
)

func versioningExample(ctx context.Context, client *lambdadb.Client) error {
    collection := client.Collection("knowledge-base")
    branch, err := collection.Branches().Create(ctx, lambdadb.CreateBranchInput{
        BranchName: "candidate",
        Source:     lambdadb.BranchSource("main"),
    })
    if err != nil {
        return err
    }
    if branch.ParentBranch != nil {
        fmt.Println(branch.ParentBranch.Name)
    }
    if branch.HeadSnapshot != nil {
        fmt.Println(branch.HeadSnapshot.SnapshotID)
    }

    _, err = collection.Docs().Upsert(ctx, lambdadb.UpsertDocsInput{
        Docs:   []map[string]interface{}{{"id": "doc-1", "title": "Candidate document"}},
        Branch: lambdadb.String("candidate"),
    })
    if err != nil {
        return err
    }
    _, err = collection.Docs().Fetch(ctx, lambdadb.FetchDocsInput{
        Ids:            []string{"doc-1"},
        Ref:            lambdadb.BranchRef("candidate"),
        ConsistentRead: lambdadb.Bool(true),
    })
    return err
}

This fetch includes eligible pending writes on candidate; it does not prove that a snapshot has committed. Before creating a tag, verify the intended committed data with consistentRead: false. See Consistent reads for limits and the bulk-import exclusion. The SDK functions below take an initialized client and use the same knowledge-base collection. Call Python functions inside the client’s with LambdaDB(...) as client: block, before it closes. Each example states its required refs and data; they are not an automatic sequence after the write above.

Create and list branches

Create a branch from main:

curl -i -X POST \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/branches" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
    "branchName": "candidate",
    "source": { "kind": "branch", "name": "main" }
  }'

Omit source to use main. A branch can be created only from another branch in the same collection; tag and alias sources return 400 BadRequest. A branch created from an empty source has explicitly null headSnapshot and parentSnapshot, but parentBranch still identifies the source branch. Branch creation copies the source’s committed state. It does not copy pending writes. Schema and retention updates remain collection-scoped; tag reads use their pinned schema.

{
  "branch": {
    "name": "candidate",
    "parentBranch": {
      "branchId": "<main-branch-id>",
      "name": "main"
    },
    "headSnapshot": {
      "snapshotId": "<snapshot-id>",
      "snapshotCommittedAt": 1788335940000
    },
    "parentSnapshot": {
      "snapshotId": "<snapshot-id>",
      "snapshotCommittedAt": 1788335940000
    },
    "createdAt": 1788336000000
  }
}

List branches:

curl -i \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/branches" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"

The response contains a branches array with the same fields as the create response:

Field	Meaning
`parentBranch`	Fixed direct source branch at creation time, with `branchId` and `name`. Explicitly `null` for `main` or when no parent was recorded.
`headSnapshot`	Current committed head, or `null` before a committed head exists.
`parentSnapshot`	Fixed snapshot from which the branch was created, not the previous head. `null` for `main` and branches created from an empty source, even after their first commit.
`snapshotCommittedAt`	Snapshot commit time in Unix epoch milliseconds, inside each non-null snapshot object alongside `snapshotId`.
`createdAt`	Branch creation time in Unix epoch milliseconds, independent of snapshot commit times.

When created from a nonempty source, a branch initially has matching head and parent snapshots. The head can advance while the parent stays fixed. Parent metadata does not guarantee that the original snapshot remains available beyond retention. Branch responses do not have a top-level snapshotId. parentBranch records the requested source branch, not the branch where the selected snapshot originated. For example, a branch created from dev records dev even if its snapshot originated on main, including when selected through asOf. This historical metadata does not prevent deleting the parent branch. Deleting the parent or recreating its name does not change the recorded identity.

Point-in-time branches

Set source.asOf to select the latest committed snapshot at or before that Unix epoch-millisecond timestamp:

{
  "branchName": "recovery-check",
  "source": {
    "kind": "branch",
    "name": "main",
    "asOf": 1788336000000
  }
}

asOf is valid only when source.kind is branch. Missing or no-longer-retained history returns 400 BadRequest. It selects committed history, so it cannot recover a write that was still pending at the requested time. There is no public snapshot-history-list API. Pass a cutoff within your collection’s retained history. The new recovery-check branch must not already exist. Python takes epoch milliseconds; TypeScript accepts a Date, and Go accepts time.Time through its source helper:

from lambdadb import BranchSource

def create_historical_branch(client, cutoff_ms: int):
    return client.collection("knowledge-base").branches.create(
        "recovery-check", source=BranchSource.branch("main", as_of=cutoff_ms)
    )

import { LambdaDBClient, branchSource } from "@functional-systems/lambdadb";

async function createHistoricalBranch(client: LambdaDBClient, cutoff: Date) {
  return client.collection("knowledge-base").branches.create({
    branchName: "recovery-check",
    source: branchSource("main", cutoff),
  });
}

import (
    "context"
    "time"

    lambdadb "github.com/lambdadb/go-lambdadb"
)

func createHistoricalBranch(ctx context.Context, client *lambdadb.Client, cutoff time.Time) error {
    _, err := client.Collection("knowledge-base").Branches().Create(ctx, lambdadb.CreateBranchInput{
        BranchName: "recovery-check",
        Source:     lambdadb.BranchSourceAt("main", cutoff),
    })
    return err
}

A tag pins one committed snapshot and cannot be retargeted:

curl -i -X POST \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/tags" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
    "tagName": "validated-2026-09",
    "source": { "kind": "branch", "name": "candidate" }
  }'

Omit source to pin the current main snapshot. The create response wraps the ref in tag; GET .../tags returns a tags array. A tag source can be a branch or another tag in the same collection, but not an alias. Creating a tag from a tag pins the same snapshot; it does not create a chain of tags. source.asOf is allowed only for a branch source. Tag responses contain name, snapshotId, snapshotCommittedAt, and createdAt. Unlike branch responses, the snapshot fields are at the top level of the tag object. snapshotCommittedAt is the pinned snapshot’s commit time, while createdAt is the tag’s creation time; both use Unix epoch milliseconds.

{
  "tag": {
    "name": "validated-2026-09",
    "snapshotId": "<snapshot-id>",
    "snapshotCommittedAt": 1788335940000,
    "createdAt": 1788336060000
  }
}

A tag cannot be created from an empty head. Verify the intended committed data with consistentRead: false before creating a release tag; a read that includes pending writes does not prove those writes will be captured by the tag. Ref lists are unpaginated, and there are no individual branch, tag, or alias GET routes.

Create, retarget, and list aliases

An alias points to a branch or tag:

curl -i -X POST \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/aliases" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
    "aliasName": "production-read",
    "target": { "kind": "tag", "name": "validated-2026-09" }
  }'

Retarget it without changing the alias name used by readers:

curl -i -X PATCH \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/aliases/production-read" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
    "target": { "kind": "branch", "name": "main" }
  }'

GET .../aliases returns an aliases array. Alias objects include aliasId, aliasName, targetKind, targetName, targetId, aliasRevision, dangling, and epoch-millisecond createdAt. Request kind values are lowercase; response targetKind values are BRANCH or TAG. Deleting a non-default branch or a tag that is referenced by any alias returns 409 Conflict. Delete or retarget every referencing alias before deleting the target; retrying the same deletion without changing those references will not resolve the conflict. Deleting an alias does not delete its target. Aliases bind to the target’s identity, not just its name. The response retains a dangling field for a missing target; if such a state is encountered, reads return 400 BadRequest. It is not the normal result of target deletion, which is blocked while aliases reference it. Recreating a target name does not repair the old identity binding. Selecting a ref that does not exist returns 404 ResourceNotFound.

Publish a tag through an alias with the SDKs

First verify that candidate contains the intended committed data using a fetch or query with consistentRead: false. The following example assumes that verification is complete and that neither validated-2026-09 nor production-read exists. It pins a tag, creates an alias initially targeting main, switches that alias to the tag, and reads through the alias. For an existing alias, use only the retarget call instead of creating it again.

from lambdadb import AliasTarget, Ref, RefSource

def publish_tag(client):
    collection = client.collection("knowledge-base")
    collection.tags.create(
        "validated-2026-09", source=RefSource.branch("candidate")
    )
    collection.aliases.create("production-read", target=AliasTarget.branch("main"))
    collection.aliases.retarget(
        "production-read", target=AliasTarget.tag("validated-2026-09")
    )
    return collection.docs.fetch(ids=["doc-1"], ref=Ref.alias("production-read"))

import { LambdaDBClient, aliasRef, branchSource, branchTarget, tagTarget } from "@functional-systems/lambdadb";

async function publishTag(client: LambdaDBClient) {
  const collection = client.collection("knowledge-base");
  await collection.tags.create({
    tagName: "validated-2026-09", source: branchSource("candidate"),
  });
  await collection.aliases.create({
    aliasName: "production-read", target: branchTarget("main"),
  });
  await collection.aliases.retarget("production-read", {
    target: tagTarget("validated-2026-09"),
  });
  return collection.docs.fetch({ ids: ["doc-1"], ref: aliasRef("production-read") });
}

import (
    "context"

    lambdadb "github.com/lambdadb/go-lambdadb"
)

func publishTag(ctx context.Context, client *lambdadb.Client) error {
    collection := client.Collection("knowledge-base")
    _, err := collection.Tags().Create(ctx, lambdadb.CreateTagInput{
        TagName: "validated-2026-09", Source: lambdadb.BranchSource("candidate"),
    })
    if err != nil {
        return err
    }
    _, err = collection.Aliases().Create(ctx, lambdadb.CreateAliasInput{
        AliasName: "production-read", Target: lambdadb.BranchTarget("main"),
    })
    if err != nil {
        return err
    }
    _, err = collection.Aliases().Retarget(ctx, "production-read", lambdadb.RetargetAliasInput{
        Target: lambdadb.TagTarget("validated-2026-09"),
    })
    if err != nil {
        return err
    }
    _, err = collection.Docs().Fetch(ctx, lambdadb.FetchDocsInput{
        Ids: []string{"doc-1"}, Ref: lambdadb.AliasRef("production-read"),
    })
    return err
}

Read from a ref

Query, fetch, and extended list request bodies accept:

{
  "ref": {
    "kind": "branch",
    "name": "candidate"
  }
}

ref.kind accepts branch, tag, or alias. Add this object alongside the endpoint’s normal fields. Omitting ref reads from main. The GET list endpoint has no request body. Supply refKind and refName together:

curl -i \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/docs?refKind=alias&refName=production-read" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"

Supplying only one of refKind or refName is invalid.

Consistent reads

Query and fetch requests support consistentRead: true only when they directly select a branch. Tag and alias reads reject it, including an alias that currently targets a branch. Consistent reads overlay eligible pending writes on committed data. They can return 429 when that pending payload exceeds the limit, independently of request rate limits. Pending bulk imports are excluded and become visible only after indexing commits them. List requests do not support consistentRead. Page tokens record a search position, not a fixed snapshot. Branches can advance and aliases can move between pages. Use the same immutable tag on every page for a stable export, keeping filters and projection options unchanged. Query responses do not include a resolved snapshot ID.

Iterate over a tag with the SDKs

These examples assume validated-2026-09 already exists. Each pagination helper keeps the same tag on subsequent requests. Python pages contain document dictionaries; TypeScript and Go pages contain result items whose doc or Doc field holds the document.

from lambdadb import Ref

def print_tag_documents(client):
    collection = client.collection("knowledge-base")
    for page in collection.docs.list_pages(size=100, ref=Ref.tag("validated-2026-09")):
        for document in page:
            print(document)

import { LambdaDBClient, tagRef } from "@functional-systems/lambdadb";

async function printTagDocuments(client: LambdaDBClient) {
  const collection = client.collection("knowledge-base");
  for await (const page of collection.docs.listPages({
    size: 100, ref: tagRef("validated-2026-09"),
  })) {
    for (const item of page.docs) console.log(item.doc);
  }
}

import (
    "context"
    "fmt"

    lambdadb "github.com/lambdadb/go-lambdadb"
)

func printTagDocuments(ctx context.Context, client *lambdadb.Client) error {
    iterator := client.Collection("knowledge-base").Docs().ListIterator(ctx, &lambdadb.ListDocsOpts{
        Size: lambdadb.Int64(100), Ref: lambdadb.TagRef("validated-2026-09"),
    })
    for {
        page, err := iterator.Next(ctx)
        if err != nil {
            return err
        }
        if page == nil {
            return nil
        }
        for _, item := range page.Docs {
            fmt.Println(item.Doc)
        }
    }
}

Write to a branch

Upsert, update, delete, and bulk-upsert request bodies accept an optional branch string. Omitting it writes to main.

{
  "branch": "candidate",
  "docs": [
    { "id": "doc-1", "title": "Candidate document" }
  ]
}

The value is resolved as a branch name. A tag or alias is not a valid write target. For bulk upsert, use the same branch for both control calls:

GET  .../docs/bulk-upsert?branch=candidate
POST .../docs/bulk-upsert
{
  "objectKey": "...",
  "type": "application/json",
  "branch": "candidate"
}

Set Content-Type to the response’s type value and send every entry in its headers map unchanged with the presigned PUT.

Delete a ref

Delete a named ref with its type-specific route:

DELETE .../branches/{branchName}
DELETE .../tags/{tagName}
DELETE .../aliases/{aliasName}

The default main branch cannot be deleted independently from its collection; an attempt returns 400 BadRequest. Other branches and tags cannot be deleted while any alias references them (409 Conflict). Delete or retarget those aliases first. Deleting a ref does not delete the collection. The default branch cannot be changed. Deleting an already absent ref can return 404.

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Use the SDKs

Create and list branches

Point-in-time branches

Create, retarget, and list aliases

Publish a tag through an alias with the SDKs

Read from a ref

Consistent reads

Iterate over a tag with the SDKs

Write to a branch

Delete a ref

​Use the SDKs

​Create and list branches

​Point-in-time branches

​Create and list tags

​Create, retarget, and list aliases

​Publish a tag through an alias with the SDKs

​Read from a ref

​Consistent reads

​Iterate over a tag with the SDKs

​Write to a branch

​Delete a ref

Use the SDKs

Create and list branches

Point-in-time branches

Create and list tags

Create, retarget, and list aliases

Publish a tag through an alias with the SDKs

Read from a ref

Consistent reads

Iterate over a tag with the SDKs

Write to a branch

Delete a ref