Branches commands
10 commands. Each entry gives the invocation and an example, in the interface you pick; open the details for parameters, return shape and error codes.
create
Create a new empty root branch.
strata branch create
db.branches.create(name: 'str') -> 'Any'
Creates an empty root branch with no parent and no data. This is not a fork: the new branch starts from nothing, and its `parent` is null. Use `branch.fork` to start from an existing branch's data. Creating a name that already exists fails with `already_exists.engine.branch`; names reserved for engine control data are rejected.
To see the complete help for this command, run:
strata branch create --helphelp(db.branches.create)
Example
strata branch create featurestrata branch list
_ = db.branches.create("feature")sorted(b.name for b in db.branches.list())
delete
Delete an active branch and release its storage claims.
strata branch delete
db.branches.delete(name: 'str') -> 'Any'
Deletes an active branch and reports the deleted branch summary, generation facts, and storage cleanup counts. The `default` branch refuses deletion with `invalid_argument.engine.branch_delete`. Deletion discards the branch's work - promote anything worth keeping onto another branch with `branch merge` before deleting, or keep working on the branch instead.
To see the complete help for this command, run:
strata branch delete --helphelp(db.branches.delete)
Example
strata branch create tempstrata branch delete tempstrata branch list
_ = db.branches.create("temp")_ = db.branches.delete("temp")sorted(b.name for b in db.branches.list())
diff
Compare two branches and report the entities that differ across every primitive.
strata branch diff
db.branches.diff(branch_a: 'str', branch_b: 'str', *, as_of: 'Optional[int]' = None) -> 'Any'
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`.
To see the complete help for this command, run:
strata branch diff --helphelp(db.branches.diff)
Example
strata vector collection create notes 2 --metric cosinestrata kv put config basestrata branch fork default experimentstrata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}' # diverge the key-value entry on the forkstrata command run --command-json '{"branch":"experiment","collection":"notes","key":"n1","type":"vector_upsert","vector":[0.1,0.2]}' # add a vector on the forkstrata branch diff default experiment # reports the key-value change and the new vector, grouped by capability
_ = 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
fork
Fork a new branch from the current head of a source branch.
strata branch fork
db.branches.fork(source: 'str', name: 'str', *, version: 'Optional[int]' = None, timestamp: 'Optional[int]' = None) -> 'Any'
Forks a new branch from the source branch's current head. The new branch sees all data visible on the source at fork time; later writes on either branch stay isolated. The returned branch summary records the parent name, fork version, and generation.
To see the complete help for this command, run:
strata branch fork --helphelp(db.branches.fork)
Example
strata branch fork default experimentstrata branch list
_ = db.branches.fork("default", "experiment")sorted(b.name for b in db.branches.list())
fork_at_timestamp
Fork a new branch from a retained source timestamp.
db.branches.fork(source: 'str', name: 'str', *, version: 'Optional[int]' = None, timestamp: 'Optional[int]' = None) -> 'Any'
Forks a new branch anchored at a retained source timestamp (microseconds, on Strata's logical commit clock). The engine resolves the timestamp to the covering retained commit; the returned parent lineage records both the fork timestamp and the resolved fork version. A timestamp outside retained history fails with `history_unavailable.engine.persistence_history`.
To see the complete help for this command, run:
help(db.branches.fork)
Example
_ = db.branches.fork("default", "experiment")sorted(b.name for b in db.branches.list())
fork_at_version
Fork a new branch from a retained source commit version.
db.branches.fork(source: 'str', name: 'str', *, version: 'Optional[int]' = None, timestamp: 'Optional[int]' = None) -> 'Any'
Forks a new branch anchored at a retained commit version of the source branch, giving time-travel semantics: the new branch sees exactly the data visible at that version. A version outside retained history fails with `history_unavailable.engine.persistence_history`.
To see the complete help for this command, run:
help(db.branches.fork)
Example
_ = db.branches.fork("default", "experiment")sorted(b.name for b in db.branches.list())
get
Read one branch summary by name.
strata branch get
db.branches.get(name: 'str') -> 'Any'
Reads the summary for one branch: name, deterministic branch id, generation, status, parent lineage, and logical creation version. A branch that does not exist is a `not_found.engine.branch` error, not an empty result.
To see the complete help for this command, run:
strata branch get --helphelp(db.branches.get)
Example
strata branch create featurestrata branch get feature
_ = db.branches.create("feature")db.branches.get("feature").name
list
List active branches with their lineage facts.
strata branch list
db.branches.list() -> 'list'
Lists every active branch as a terminal page. Each item carries the branch name, deterministic branch id, generation, status, parent lineage (fork version and timestamp when forked), and logical creation version.
To see the complete help for this command, run:
strata branch list --helphelp(db.branches.list)
Example
strata branch create featurestrata branch list
_ = db.branches.create("feature")sorted(b.name for b in db.branches.list())
merge
Promote one branch's changes into another as a single atomic commit.
strata branch merge
db.branches.merge(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'
Promotes the `source` branch's changes into the `target` branch as a single atomic commit, leaving the source unchanged. The branch point is derived from the recorded fork lineage, and a three-way merge applies every change the source made since that point.
To see the complete help for this command, run:
strata branch merge --helphelp(db.branches.merge)
Example
strata kv put config basestrata branch fork default experimentstrata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}' # change on the forkstrata branch merge experiment default --strategy strict # applies the fork's change onto default
_ = db.kv.put("config", "base")_ = db.branches.fork("default", "experiment")_ = db.at(branch="experiment").kv.put("config", "tuned") # change on the fork_ = db.branches.merge("experiment", "default", strategy="strict") # applies the fork's change onto default
preview
Preview promoting one branch into another, reporting conflicts without mutating either branch.
strata branch preview
db.branches.preview(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'
Previews promoting the `source` branch into the `target` branch: it derives the branch point from the recorded fork lineage, runs a three-way comparison, and reports the conflicts a promotion would hit - entries both branches changed differently since the branch point. Preview is read-only: it mutates neither branch.
To see the complete help for this command, run:
strata branch preview --helphelp(db.branches.preview)
Example
strata kv put config basestrata branch fork default experimentstrata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}' # change on the forkstrata branch preview experiment default --strategy strict # a clean preview - no conflicting changes on default
_ = db.kv.put("config", "base")_ = db.branches.fork("default", "experiment")_ = db.at(branch="experiment").kv.put("config", "tuned") # change on the fork_ = db.branches.preview("experiment", "default", strategy="strict") # a clean preview - no conflicting changes on default