Names and changes
Source: docs/guide/13-names-and-changes.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A query spells names: FROM commerce, MEASURE(revenue), orders.region. A saved query, a data
app and a cube all keep working only while those names do. So the layer changes names rarely and
deliberately, and keeps old names working when it does.
Which names can change
| Resource | Its name |
|---|---|
| dataset, field, relationship | never changes. To rename one, create it under the new name and delete the old one. |
| domain, metric | changes only through its rename action: POST /domains/{id}/rename or POST /metrics/{id}/rename, with {"name": …} |
An ordinary update whose body carries a different name is refused (NAME_IMMUTABLE), naming the
rename action. display_name is free text, and changing it moves nothing.
A rename keeps the old name working
After revenue is renamed net_revenue, revenue becomes a former name:
MEASURE(revenue)still answers the same metric, with aRENAMEDwarning, and its output column is still calledrevenue. A saved query's columns do not move.- No other metric of the domain may take
revenuewhile it is a former name (NAME_TAKEN, saying who holds it). - The id, the definition and the computation do not change, so cubes keep serving.
- Describe lists
former_names, oldest first. Renaming back to a former name is allowed.
DELETE /metrics/{id}/former-names/{name} (or the domain's) frees a former name, and saved
queries still spelling it will then break. It is refused (FORMER_NAME_IN_USE) while the metric,
or any metric of the domain, carries a cache directive, because the cube's refresh spells the old
name.
Deleting
A dataset, field, relationship or metric that something still uses cannot be deleted
(REFERENCES_EXIST, listing what uses it). Remove the uses first. A relationship that a stored
path walks counts as used. Deleting a domain deletes it and every metric it owns.
A deleted domain's or metric's names are retired. A query spelling one gets UNKNOWN_DOMAIN
or UNKNOWN_METRIC with retired: {last_name, deleted_rev, deleted_at}, not a bare "unknown". A
new resource may take a retired name.
How a name is found
FROM <name> and MEASURE(<name>) resolve in this order:
- the current name
- a former name: the same resource, with
RENAMED - a retired name: refused, with
retired - anything else: refused, with
did_you_mean, the closest names, matched ignoring case and separators and against display names too (total_revenuefinds the metric titled "Total Revenue")
What sync does to names
Sync names each object once, when it first imports it, and matches it by its upstream id after
that. A use case, event type or KPI that is retitled upstream keeps its name, and only its
display_name follows. Sync also:
- keeps what a person added to a synced object: a field, a link, a dataset in a domain's selection, a metric with no KPI behind it
- overwrites a person's edit to something sync wrote, such as a new description on a synced
field, or a
cacheon a synced metric (Caching) - never deletes a live object because the warehouse lost a table or column. It keeps the live version and reports it.
- removes a domain whose use case is gone upstream, with every metric in it, and says which person-written metrics went with it
Revisions and concurrent writes
Every write advances the tenant's revision, head_rev, and every answer says which revision it
read (as_of).
- Send
base_revwith a write to refuse it if what it touches changed since (STALE_WRITE, with the current version). - A write that another write overtook, between being checked and being applied, applies nothing
and answers
WRITE_CONFLICTwith the newhead_rev. Send it again. ?mode=validateruns every check of a write and saves nothing.
When a stored definition breaks
If something a stored definition points at is gone, reading the document still works. It lists each
broken reference under broken with where it is, so you can fix it and write it back. A query
naming that metric is refused with BROKEN_DEFINITION, and the domain's other metrics still answer.