Skip to main content

Names and changes

Synced from semantic-layer

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​

ResourceIts name
dataset, field, relationshipnever changes. To rename one, create it under the new name and delete the old one.
domain, metricchanges 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 a RENAMED warning, and its output column is still called revenue. A saved query's columns do not move.
  • No other metric of the domain may take revenue while 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:

  1. the current name
  2. a former name: the same resource, with RENAMED
  3. a retired name: refused, with retired
  4. anything else: refused, with did_you_mean, the closest names, matched ignoring case and separators and against display names too (total_revenue finds 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 cache on 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_rev with 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_CONFLICT with the new head_rev. Send it again.
  • ?mode=validate runs 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.