branch
diff
Compare two branches and report the entities that differ across every primitive.
strata branch diffdb.branches.diff(branch_a: 'str', branch_b: 'str', *, as_of: 'Optional[int]' = None) -> 'Any'wire branch_diff
Compares two branches and reports the authored entities that differ, grouped by capability and space: entries `added` on `branch_b`, `removed` relative to `branch_a`, and `modified` on both sides. The comparison is directional from `branch_a` to `branch_b`.
Every data primitive is compared - key-value, JSON documents, vectors, event streams, and graphs. Graph changes are reported per row class: nodes, edges, and ontology appear as separate capabilities in the result. Derived rows (search and vector indexes, graph reverse maps) are omitted. A graph or space whose deletion is still being swept on a branch compares as absent on that branch, exactly as a deleted one does. A missing branch is rejected with `not_found.engine.branch`.
Status commands return a scalar or compact status payload and do not mutate database state.
To see the complete help for this command, run:
strata branch diff --helphelp(db.branches.diff)
Example
Compare a fork against the branch it came from, across primitives.
strata vector collection create notes 2 --metric cosinecreated collection notes (2 dimensions, cosine)strata kv put config basecreated configstrata branch fork default experimentforked experiment from defaultstrata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}' # diverge the key-value entry on the forkupdated configstrata command run --command-json '{"branch":"experiment","collection":"notes","key":"n1","type":"vector_upsert","vector":[0.1,0.2]}' # add a vector on the forkcreated n1 in notesstrata branch diff default experiment # reports the key-value change and the new vector, grouped by capabilitybranch_a defaultbranch_b experimentSPACE CAPABILITY CHANGE IDENTITY VERSIONdefault kv modified config …default vector added base64:AAVub3Rlc24x …
_ = db.vectors.create_collection("notes", 2, metric="cosine")_ = db.kv.put("config", "base")_ = db.branches.fork("default", "experiment")_ = db.at(branch="experiment").kv.put("config", "tuned") # diverge the key-value entry on the fork_ = db.at(branch="experiment").vectors.upsert("notes", "n1", [0.1, 0.2]) # add a vector on the fork_ = db.branches.diff("default", "experiment") # reports the key-value change and the new vector, grouped by capability
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| branch_a | string | yes | The first branch (the `A` side). |
| branch_b | string | yes | The second branch (the `B` side). |
| at_timestamp | integer or null | no | Optional read-as-of commit timestamp: compare each branch as of the `timestamp` from `history` output (a commit-timeline position, not the `version`). |
Returns
StatusResponse<BranchComparisonItem>
- dataBranchComparisonItem
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.
| Code | Retry | Commit outcome |
|---|---|---|
| failed_precondition.engine.runtime_closed | never | not_started |
| not_found.engine.branch | never | not_applicable |
| invalid_argument.engine.branch_name | never | not_started |
| invalid_argument.engine.branch_name_reserved | never | not_started |