Index branching

An index branch is a new, independent index initialized from an existing index. It is not a read-time alias, a query filter, or a pointer to production. Talqora copies the active dense vectors, metadata, sparse text, and version ledger into a new physical retrieval store. After creation, writes, deletes, processing jobs, API keys, and usage are isolated between the source and branch.

Use a branch when the question is, “Can we change this retrieval workload without changing what production returns?”

When to use a branch

Branches are designed for controlled retrieval changes:

• Evaluate a new embedding model or a new chunking strategy against the same corpus.
• Test different sparse_text enrichment before changing a product search experience.
• Create a release candidate to run recall, latency, relevance, and safety checks.
• Give a staging agent a stable corpus without allowing it to write to production.
• Reproduce an issue on a snapshot-like copy before applying a destructive deletion or import.

Do not use a branch as a cheap backup, as a tenant isolation boundary, or for a continuously synchronized replica. A branch is a complete materialized copy at creation time; later writes on either side do not replicate automatically.

What is preserved

The branch inherits the source index’s immutable contract:

The branch has its own index ID, API-key scopes, document count, storage, rows written, query usage, and lifecycle. File jobs and connector connections are not a shared control surface: create new processing sources only where you want future changes to land.

Create a branch

Branching is a control-plane operation and uses a dashboard session token:

curl --fail-with-body \
  -X POST "https://api.talqora.com/v1/indexes/$SOURCE_INDEX_ID/branches" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"catalog-ranking-v2"}'

The name follows the same rule as a normal index: lowercase, 3–63 characters, beginning and ending with a letter or number, with letters, numbers, periods, and hyphens allowed.

Talqora creates the regional dense and sparse stores, copies active records, and returns only after the branch is durable. If a dependent store cannot be created or the copy cannot complete, the operation fails instead of returning a partially usable branch.

A safe release workflow

1. Start with a production index that has a known baseline of queries and relevance expectations.
2. Create a branch such as support-rag-v2.
3. Apply the candidate change only to the branch: rewrite records, add better metadata, or process a new corpus.
4. Run an evaluation set against both indexes with the same queries, filters, top_k, and relevance threshold.
5. Compare result quality, source provenance, p50/p95 latency, queried transfer, and cost.
6. Create a read-only API key restricted to the branch for a staging service or assistant playground.
7. Change the application configuration to use the branch only after the evaluation is accepted.
8. Retire the prior index when rollback is no longer required.

For a model migration that changes dimensions, create a new index rather than a branch, backfill it, and use the same comparison workflow. Dimensions are part of the branch contract and cannot be changed.

Cost and limits

Because a branch is a physical copy, it counts toward index, document, storage, rows-written, and write-transfer allowances. Querying a branch creates its own query and transfer usage. Budget for the duplicate during the evaluation window; delete it when the experiment has concluded.

The initial copy is intentionally explicit rather than a hidden background mutation. This makes it possible to audit which release was queried and prevents an experimental write from altering live customer retrieval.

API keys and access

Existing keys do not gain access to a branch automatically when they are restricted to explicit index IDs. Create a new read-only key for the branch, or edit a key’s scopes after confirming the deployment is ready. Never give a staging service a broad workspace key when an index-scoped key is enough.

Delete and rollback

Deleting a branch deletes only that branch’s dense, sparse, processing-source, and control-plane state. The source remains unchanged. If a rollout fails, point the application back to the original index rather than attempting to merge branch writes into it. A branch has no automatic reverse-sync or merge operation by design.

Checklist

• Is the change compatible with the source dimensions and metric? If not, create a new index.
• Do you have a representative evaluation set and expected sources?
• Is a branch-scoped read-only key available for staging?
• Have you budgeted for the duplicate storage and write activity?
• Is the application rollback target explicit before changing traffic?