retrofit element history
retrofit element history <operand> prints the history of one element: one
record per op of the selected oplog that created,
changed, renamed, moved or ended it, named it from another element, or
belongs to the elements it was derived from. It reads the configuration
and the oplog, reads no data corpus and writes nothing.
Find an element’s ID and history is the task guide.
Synopsis
From retrofit element history --help:
Usage:
retrofit element history <operand> [flags]
Description
element history binds its operand to one element of one schema’s oplog,
by a live name, an earlier name or an ElementID
prefix, and prints every op in that element’s history in log order.
retrofit element list prints the ids this verb takes.
The operand
The operand names one element, and the verb refuses to pick between two.
- A live element by name binds first, by the name path
op addresolves (customer,orders.amount,public.orders.amount, a function’sname(args)), under each kind or the one--kindnames. - Otherwise the element that held the name at some
cut binds, its last name before it ended included. A
table renamed
customertoclientanswers tocustomer; a droppedordersanswers toorders. Each qualifier matches in the same cut as the name it qualifies, socustomer.identbinds nothing when the column was only everidentafter its table was renamed. - Otherwise the elements whose ElementID starts with the token bind (1 to 12
hex, or
<container>.<hex>). One live candidate binds over ended ones.
Two or more candidates refuse with ambiguous-element and every
candidate: its id, name, container, kind and, for one that is not
live, ended, the opid that ended it. A ref that two
kinds share (a constraint and the index named after it) is two candidates.
A token no element held, and any token on an oplog with no op, refuses with
no-match.
--schema <name> or the root -f <path> selects one schema’s oplog, as
op show does; with neither, the schema is the one the
resolver chain
selects.
Which ops belong
An op is in an element’s history when, at that op, the element or a child of it appears, ends, moves to another parent or changes; a hyperedge of the op mentions it or a child; an element-ID parameter of the op holds it or a child; or an element whose body references it or a child appears, ends or changes. Sealed and unsealed ops alike belong.
The history also continues into the elements the element was derived or
folded from, before the op that did so: CopyTable, MergeTable into a kept
table, InlineTable, PartitionTable, SplitTable, JoinTable,
ExtractTable, UnjoinTable, a ChangePrimaryKey replaced key and a
DetachPartition column. Those records are lineage. The walk never goes
forward: the op that derived new elements from this one lists them as
derived_to, and the walk does not enter their histories.
A family column’s history folds every attached partition’s pre-ATTACH
column: each AttachPartition record on it is a reference record that
lists the absorbed columns as derived_from, and the partitions’ own
earlier records follow as lineage.
A born partition’s column does not exist apart from the family column, so
its <partition>.<column> token refuses with no-match; an absorbed
partition’s <partition>.<column> binds the column the partition held
before the ATTACH.
Output
Under --as=json each op is one item record, in log order, and a
terminal ok follows.
| member | meaning |
|---|---|
opid, op | the op’s full opid and operator |
sealed | the op is at or before the oplog’s last Seal, the range op revise refuses |
via | self (the element or a child changed, or the op names it in a parameter of role in, on, source, sources, id or ids), reference (the op only names it from another element’s parameter or body, or links it by a hyperedge), lineage (an origin’s op) |
origin_via | on a lineage record, the self or reference the origin’s own history gives the op |
id, kind, name, parent | the element, as of the op (a lineage record names the origin) |
renamed_from | the name before, when the op renamed it |
children | the children that put the op in the history, each {id, kind, name} |
derived_from, derived_to | the elements the op derived or folded this one from; the ones it derived from this one or consumed it into |
A field that does not apply is absent. Every list sorts by ElementID. The
terminal ok holds schema (absent on a registry-less -f run), the
record count, the sealed record count and the element: id, kind,
name (its last name once ended), ended when it is not live and
also_named, the other elements the name match takes for the operand.
Text mode prints opid<TAB>op<TAB>via<TAB>id<TAB>qualified-name<TAB>sealed|-
per record, with no header, and one courtesy note on stderr (-q drops it).
kind, parent, renamed_from, children, derived_from and
derived_to are JSON-only. A run over the same log prints the same bytes.
Load, resolution and the walk finish before the first record, so a refusal
leaves stdout holding only its failed envelope
under --as=json, and empty in text.
Options
From retrofit element history --help:
Flags:
-h, --help help for history
--help-all show extended help (vocabulary, semantics, caveats)
--kind kind bind only an element of this kind: schema, table, column, constraint, index, view, matview, type, extension, policy, function, trigger
--schema <name> registered schema <name> (default: the project's one schema)
The global flags (--as, -C, --config, -f, -q, -v,
--no-consolidate) are in the output contract.
Diagnostics
A refusal prints no record, and Refusal codes
gives the exit status of every code element history refuses with. An
unreconciled fork anywhere in the oplog refuses with
fork-in-range, whatever op the operand binds.
Advisory codes lists every code with its class.
See also
Find an element’s ID and history,
retrofit element list,
Operators,
Output contract,
The oplog.