Namespace Branching

search⌘K

IntroductionQuickstartRoadmap & Changelog

Database<br>ArchitectureRegionsConceptsGuaranteesTradeoffsLimitsBranchingShardingEmbeddingPinning

ProductionSecurityEncryptionPrivate NetworkingAudit LogsBackupsPerformance

GuidesVector SearchFull-Text SearchHybrid SearchChunkingTestingPermissionsIngestion

API<br>OverviewWriteQueryNamespace metadataExportWarm cacheList namespacesDelete namespaceRecall

Namespace Branching

Branching creates an instant, copy-on-write clone of a namespace via branch_from.

li]:relative [&>li]:pl-5 [&>li]:before:absolute [&>li]:before:left-0 [&>li]:before:top-[calc((1lh-0.8em)*0.5)] [&>li]:before:h-[0.8em] [&>li]:before:w-[0.8em] [&>li]:before:bg-slate-600 [&>li]:before:content-[''] [&>li]:before:[mask-image:url(/puffy-bullet.svg)] [&>li]:before:[mask-repeat:no-repeat] [&>li]:before:[mask-size:contain] [&_ul>li]:relative [&_ul>li]:pl-5 [&_ul>li]:before:absolute [&_ul>li]:before:left-0 [&_ul>li]:before:top-[calc((1lh-0.4em)*0.5)] [&_ul>li]:before:h-[0.4em] [&_ul>li]:before:w-[0.4em] [&_ul>li]:before:bg-slate-400 [&_ul>li]:before:content-[''] [&_ul>li]:before:[mask-image:none] [&_ul]:list-none [&_ul_ul>li]:before:border [&_ul_ul>li]:before:border-slate-400 [&_ul_ul>li]:before:bg-transparent"><br>Constant-time regardless of namespace size

Fully independent — reads, writes, queries, and deletes on either namespace don't affect the other

Branch from branches — multi-level workflows like per-developer branches from staging

Unlimited — no limit on child branches per namespace (A→B, A→C, A→D, ...) nor on length of branch chains (A→B, B→C, C→D, ...)

Per-namespace configuration like pinning is not inherited; the branch starts unpinned.

┏━━━━━━━━━┓ ┏━━━━┓<br>┃namespace┃ ┃data┃<br>┗━━━━━━━━━┛ ┗━━━━┛<br>┌──────┐ ┌────────────┐<br>│source│─────────▶│source/1.bin│<br>└──────┘ ▲ └────────────┘<br>┌──────┐ │ ┌────────────┐<br>│branch│─────┴───▶│branch/1.bin│<br>└──────┘ └────────────┘┏━━━━━━━━━┓ ┏━━━━┓<br>┃namespace┃ ┃data┃<br>┗━━━━━━━━━┛ ┗━━━━┛<br>┌──────┐ ┌────────────┐<br>│source│─────────▶│source/1.bin│<br>└──────┘ ▲ └────────────┘<br>┌──────┐ │ ┌────────────┐<br>│branch│─────┴───▶│branch/1.bin│<br>└──────┘ └────────────┘

Pricing

Branching is billed at a flat rate of $0.032.

Storage of a branched namespace is billed on logical bytes at standard rates —<br>each branch is billed as if it were an independent namespace. We plan to reduce<br>this once we've observed branching in production and learned what the reuse<br>rates are.

When to use branching vs copy_from_namespace

Use copy_from_namespace when you<br>need a backup with full data isolation (branching shares underlying storage),<br>when copying across regions or organizations (see the cross-region backups<br>guide), or when re-encrypting a namespace with a different<br>CMEK key.

Use branching otherwise.

Use cases

li]:relative [&>li]:pl-5 [&>li]:before:absolute [&>li]:before:left-0 [&>li]:before:top-[calc((1lh-0.8em)*0.5)] [&>li]:before:h-[0.8em] [&>li]:before:w-[0.8em] [&>li]:before:bg-slate-600 [&>li]:before:content-[''] [&>li]:before:[mask-image:url(/puffy-bullet.svg)] [&>li]:before:[mask-repeat:no-repeat] [&>li]:before:[mask-size:contain] [&_ul>li]:relative [&_ul>li]:pl-5 [&_ul>li]:before:absolute [&_ul>li]:before:left-0 [&_ul>li]:before:top-[calc((1lh-0.4em)*0.5)] [&_ul>li]:before:h-[0.4em] [&_ul>li]:before:w-[0.4em] [&_ul>li]:before:bg-slate-400 [&_ul>li]:before:content-[''] [&_ul>li]:before:[mask-image:none] [&_ul]:list-none [&_ul_ul>li]:before:border [&_ul_ul>li]:before:border-slate-400 [&_ul_ul>li]:before:bg-transparent"><br>Codebase indexing. Embed a codebase once; branch per local checkout so only changed files need re-indexing.

Test pipelines. Branch a production namespace, run tests against real data, tear it down when done.

Development environments. Give each developer a sandbox of a shared dataset.

Snapshots. Capture the state of a changing namespace at a point in time, query the immutable snapshot many times, discard when finished.

Deleting branches

Both the source and branched namespaces are fully independent after creation.<br>Deleting a branch does not affect the source namespace, and deleting the source<br>does not affect any branches. Use the standard<br>delete namespace endpoint to remove either one.

Example

li>&]:-ml-8 [ol>li>&]:w-[calc(100%+2rem)] [ul>li>&]:-ml-5 [ul>li>&]:w-[calc(100%+1.25rem)]" data-lang-tabs="true">python

li>&]:-ml-8 [ol>li>&]:w-[calc(100%+2rem)] [ul>li>&]:-ml-5 [ul>li>&]:w-[calc(100%+1.25rem)] [&_span]:!inline-block [&_span]:align-top">import turbopuffer

tpuf = turbopuffer.Turbopuffer(<br>region='gcp-us-central1', # choose best region: https://turbopuffer.com/docs/regions

source = tpuf.namespace(f'branching-example-source-py')<br>source.write(upsert_rows=[{'id': 1, 'title': 'Hello'}, {'id': 2, 'title': 'World'}])

ns = tpuf.namespace(f'branching-example-py')<br>ns.branch_from(source_namespace=f'branching-example-source-py')

# Write to the branch<br>ns.write(upsert_rows=[{'id': 3, 'title': 'New'}])

# Branch has source data + new write<br>result =...