Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Find and understand

kater references

Lists everything that reads a field.

For each model, it shows where its SQL names the field, and which of its fields read it. Use it before you rename or remove a field, to see what the change reaches. Nothing runs on the warehouse.

Examples

Terminal window
# Go to the connection's shared models
cd connections/snowflake_prod_connection/modeling
# List what reads the Spend measure of the shared ad_reporting model
kater references sum__spend --relation semantic.ad_reporting
# List only the fields that name it, not the ones that read it through another field
kater references sum__spend --relation semantic.ad_reporting --direct
# Go to the ad_reporting workspace
cd ../workspaces/ad_reporting
# List what reads the Conversions measure of the workspace's root
kater references sum__conversions --relation workspace.ad_reporting
# List only the fields that name the Spend field of the spend_by_platform query
kater references sum__spend --relation query.spend_by_platform --direct

Arguments

ArgumentDescription
<field>The field, by its name in --relation, such as sum__spend. Kater compares names as your warehouse compares them.

Options

OptionDescription
--relation <model>Required. The model that holds the field, by its name or typed address. Use semantic.ad_reporting for a shared model, workspace.ad_reporting for a workspace’s root, or query.spend_by_platform for a query.
--path <file>A SQL file to look from. Kater finds --relation among the models that this file can read.
--directLists only the fields that name the field. It leaves out the fields that read it through another field.

It also takes the global options --json, --kater-root, --scope and --help.

Where to run it

Name a shared model’s field from its connection’s modeling folder. Name the field of a workspace’s root, or of one of its queries, from the workspace.

What it lists

  • Each model that reads the field, by its file.
  • Each place where the model’s SQL names the field, as LINE:COLUMN, counted from 1.
  • Each field of the model that reads the field, and how, such as value or filter. It also says when a field reads it only through another field.
  • A count at the end, of the models that read it.

When more than 1,000 fields read it, the list is cut, and --json has the first 1,000. --json returns the references.list answer. In it, each place is a range of zero-based lines and UTF-16 characters, with each file’s revision.

What it leaves out

  • It lists only the models that you can read.
  • Nothing in a brainstorm folder counts, except a copy’s own queries for a field in that copy.
  • It does not list dashboards, apps and Explore yet.

See also