Vistelio | Renaming and Retiring LookML Fields Without Breaking Dashboards

Every Looker project that has survived a few years carries dead weight: total_revenue_v2, a dimension whose name was a typo nobody dared fix, three flavours of "active user" that disagree with each other. Developers know which one is right. Business users do not, and they keep building Looks on the wrong one.

The reason nobody cleans this up is that deleting a LookML field is not a code change — it is a change to every saved Look, dashboard tile, schedule, alert and embedded URL that references it. Delete a field carelessly and the failure shows up hours later as a broken 7am email to the CFO.

This tutorial sets out a deprecation workflow that makes field cleanup boring and reversible: measure usage, stage the change, migrate saved content, then remove.

Step 1: Prove the field is actually unused

Never start from intuition. Looker's System Activity model records which fields appear in queries. In the Field Usage explore you can see, per model / explore / field, how many times a field has been queried and when it was last used:

Field Usage → Times Used — total query count over the retained history window
Field Usage → Field and Explore — the fully-scoped name, e.g. orders.total_revenue_v2
Join to History to split ad-hoc Explore queries from scheduled and embedded traffic

Two cautions. First, System Activity retention is finite (and shorter on some editions than people assume), so a field with zero uses may simply be quarterly. Sanity-check anything that smells like a period-end metric before you touch it. Second, Field Usage tracks queried fields. A field can sit unqueried in a saved Look that is never opened, and that Look will still error when the field disappears.

So pair usage data with a content search. The Content Validator (Develop → Content Validator) can search saved content by field name, and the API exposes the same thing:

# Every piece of saved content that references a field
curl -s -H "Authorization: Bearer $LOOKER_TOKEN" \
  "$LOOKER_HOST/api/4.0/content_validation" | jq '.content_with_errors | length'

# Search saved Looks for a specific field reference
curl -s -H "Authorization: Bearer $LOOKER_TOKEN" \
  "$LOOKER_HOST/api/4.0/looks/search?fields=id,title,query.fields&limit=500" \
  | jq '[.[] | select(.query.fields[]? | contains("total_revenue_v2")) | {id, title}]'

Write the result down. "Nine Looks, two dashboards, one schedule, one embed URL" is a migration plan. "Probably nothing" is not.

Step 2: Mark it deprecated in LookML before you change anything

The cheapest deprecation tool in LookML is metadata. Make the field unattractive and unfindable for new work while leaving it functional for existing content:

measure: total_revenue_v2 {
  label: "Total Revenue (DEPRECATED — use Total Revenue)"
  description: "Deprecated 2026-03-01. Excludes tax and refunds. Replaced by total_revenue. Scheduled for removal 2026-06-01."
  group_label: "Deprecated"
  type: sum
  sql: ${TABLE}.revenue_net ;;
  value_format_name: usd
  # hidden: yes   # switch on once saved content has been migrated
  tags: ["deprecated"]
}

Why this works:

label and description carry the removal date, so anyone who stumbles on the field knows the deadline. These strings are also what Gemini and the Conversational Analytics API read, so a clear "deprecated" note steers AI-generated queries away from the field too.
group_label: "Deprecated" collapses the junk drawer into one section of the field picker instead of scattering it through the explore.
hidden: yes removes the field from the field picker but keeps it queryable — existing Looks, dashboards and API calls keep working. That is exactly the property you want mid-migration: no new usage, no broken content.
tags give you a machine-readable marker. A small SDK script can list every tagged field and its age, which turns "we should clean up someday" into a report you can actually work through.

If the field is genuinely dangerous rather than merely redundant, hidden: yes plus a required_access_grants fence is a stronger step than a label.

Step 3: Renames — use `alias` for fields, `from` for views

A rename is a delete plus a create, and Looker treats it that way unless you tell it otherwise.

For a field rename, the alias parameter keeps the old name resolvable so saved content does not break:

dimension: customer_lifetime_value {
  alias: [ltv, cust_ltv]
  type: number
  sql: ${TABLE}.clv ;;
}

Any Look referencing orders.ltv now resolves to customer_lifetime_value. Keep the alias for one deprecation window, then drop it — aliases accumulate into their own mess if they live forever.

At the view level, renaming a view breaks every reference at once. Use the explore-level from (or view_name) so the exposed name stays stable while the underlying file is renamed:

explore: orders {
  from: orders_v2   # file renamed; explore name unchanged, content unaffected
}

For explore renames there is no alias equivalent, so treat those as full content migrations — which is what the Content Validator is for.

Step 4: Migrate saved content with the Content Validator

The Content Validator finds and, crucially, fixes references in bulk. Work in a development branch so validation runs against your proposed LookML before it reaches production:

Make the LookML change in a dev branch (rename, remove, or move the field).
Open Develop → Content Validator and run validation in development mode. Errors show every Look, dashboard tile, alert and schedule that would break.
Use Replace field to point broken references at the new field — you can filter by model, explore, or field name and apply the replacement across all matching content at once.
Re-run validation until the error list is empty, then deploy.

Things the validator will not fix, and that belong on your checklist:

Hard-coded Explore URLs in Confluence pages, Slack bookmarks and emails
Embedded tiles and signed embed URLs built by your application, where filter and field names may be constructed in application code
API and SDK consumers, including anything hitting the Open SQL Interface / JDBC, where field names appear in third-party queries
Liquid references such as {{ orders.total_revenue_v2._value }} inside html, link or drill parameters — grep the repo for the old name rather than trusting validation alone

Always grep the LookML repo itself for the old identifier before removal:

grep -rn "total_revenue_v2" --include="*.lkml" .

Step 5: Enforce it in CI

Deprecation only sticks if the rules are mechanical. Two cheap gates:

Add a LookML data test or a LAMS rule that fails the build if a field tagged deprecated is referenced anywhere else in the project (in a derived table, a sql: block, or a LookML dashboard).
Add a scheduled job that calls the content validation endpoint against production weekly and posts the error count. A rising number means someone deployed a rename without migrating content.

If your project already runs Spectacles or a LAMS step in a pull-request pipeline, these are a few extra lines rather than new infrastructure.

Step 6: Remove

On the removal date: confirm zero usage in Field Usage since the field was hidden, confirm zero content references in the validator, delete the field and its aliases in a branch, re-validate, deploy. Keep the deprecation note in the commit message — six months later somebody will ask where the metric went, and the answer should be in git rather than in someone's memory.

A workable default deprecation window for a business-critical metric is one full reporting cycle plus a buffer: label and announce, hide after two weeks, remove after 60–90 days.

The shape of a healthy project

Teams that do this well end up with a semantic layer where every visible field is one somebody is meant to use. That matters more in 2026 than it did five years ago: AI-assisted querying reads your labels, descriptions and field lists and cannot tell that total_revenue_v2 is the one finance disowned. Model hygiene is now part of the answer quality your users see.

If your Looker project has drifted into hundreds of fields nobody trusts, Vistelio's senior Looker developers run exactly this exercise as a scoped engagement — usage audit, deprecation plan, staged renames and content migration — without pausing your reporting. Get in touch or read more about our Looker health check and technical audit.

Renaming and Retiring LookML Fields Without Breaking Dashboards