Rudder Lookout is currently in Public Beta. Contact the Product team if you have any questions.
Lookout reads the metric views your data team defines in Unity Catalog. It then answers questions and builds audiences with the governed descriptions, display names, and synonyms on those views.
Lookout reads the definition, not your data. It runs two metadata queries, and only when a question needs them. One query lists the metric views in the connection’s catalog. One query per view reads that view’s descriptions, display names, and synonyms. Lookout screens and caps that text, then matches your words to the view’s fields.
When one field matches, Lookout writes the answer or the audience rule with the real field name. When a word fits two fields, Lookout asks which field you mean.
Both queries read catalog metadata only. Lookout creates nothing in your Databricks workspace.
Lookout runs these queries from Chat and Ask Questions and from Audiences and Activation. Lookout in Slack does not read metric views yet.
Lookout reads metric views only in the catalog on that connection. One connection covers one catalog. When the views sit in two catalogs, add a connection for each.
Only an admin can add the connection — see Roles and Permissions for more information.
If your warehouse restricts network access, allow the Lookout IP addresses before you test the connection. See Allow Lookout to reach your warehouse.
The principal on the connection needs to see the metric views and read them. Display names and synonyms need no extra privilege. They come back in the same read as the definition.
| Privilege | On | Why Lookout needs it |
|---|---|---|
USE CATALOG |
The connection’s catalog | Lists the catalog’s metric views from information_schema.tables |
USE SCHEMA |
Each schema that holds metric views | Reaches the views inside it |
SELECT |
Each metric view, or the whole schema | Reads the definition with DESCRIBE TABLE EXTENDED ... AS JSON, and lets Lookout query the view |
Grant those privileges to the principal Lookout uses. Replace main, sales, and the principal name with your own:
GRANT USE CATALOG ON CATALOG main TO `lookout-service-principal`;
GRANT USE SCHEMA ON SCHEMA main.sales TO `lookout-service-principal`;
GRANT SELECT ON SCHEMA main.sales TO `lookout-service-principal`; -- or ON VIEW, one view at a timeLookout uses the same fields your team already writes for Databricks AI/BI dashboards and Genie. Nothing in the YAML is specific to Lookout. See Agent Metadata in Metric Views in the Databricks documentation.
CREATE OR REPLACE VIEW main.sales.orders_metrics
WITH METRICS LANGUAGE YAML AS $$
version: 1.1
source: main.sales.orders
fields:
- name: order_status
expr: o_orderstatus
comment: "F = fulfilled, O = open, P = partial"
display_name: Order status
synonyms:
- fulfilment state
- status
measures:
- name: order_count
expr: COUNT(1)
synonyms:
- orders
- number of orders
$$;| YAML field | What Lookout does with it |
|---|---|
name |
Lookout reports this field and uses it in SQL. Lookout never replaces it with a display name or a synonym. |
comment |
The field’s meaning, up to 200 characters. Lookout reads it only when expr is a plain column. For a measure or an expression, Lookout says no single column is behind it and doesn’t use its comment. |
display_name |
Another word a user may say for the field. |
synonyms |
More words a user may say. When a synonym is why Lookout chose a field, Lookout says so. |
filter |
Lookout warns that the filter applies to every query through the view. |
A few rules keep the match unambiguous:
Lookout reads only catalogs, schemas, and views whose names use ASCII letters, digits, and underscores, and don’t start with a digit.
Three questions in the web app’s chat confirm the setup. Replace the names with your own.
main.sales.orders_metrics, what does fulfilment state mean?” Lookout names order_status, quotes its description, and says it matched the synonym “fulfilment state”.If any of these fail, see Troubleshooting for help.
| Limit | Value |
|---|---|
| Metric views listed per catalog | 100 |
| Synonyms used per field | 20. Databricks allows 10 on a field. |
| Length of a display name | Clipped at 100 characters |
| Length of a synonym | Dropped over 100 characters |
| Vocabulary per definition, field names included | 8,000 characters |
| Words flagged as ambiguous per definition | 20 |
When a limit applies, Lookout says so in its notes.
RudderStack support can stop Lookout from reading display names and synonyms for a workspace. The same switch also turns off Unity Catalog table tags. Lookout still reads the rest of each definition. The change takes effect from the next message, within about a minute. Words already in a chat stay in that chat.
| What Lookout says | Why | Fix |
|---|---|---|
| “Databricks refused the read — permission denied” | The principal can see the view but cannot read it | Grant SELECT on the view. See Grant catalog privileges. |
“Metric-view discovery failed for <catalog>” |
The list query failed, often for lack of USE CATALOG |
Grant USE CATALOG, and check that the Databricks SQL warehouse is running |
| It cannot look in another catalog | Lookout reads metric views only in the connection’s catalog | Add a connection for that catalog |
| “The view’s name uses characters other than letters, digits and underscores” | Lookout reads only catalogs, schemas, and views whose names use ASCII letters, digits, and underscores, and don’t start with a digit | Rename the view, or define it again under such a name |
| It ignores your display names and synonyms | The YAML is version 0.1, or the feature is switched off for your workspace | Set version to 1.1. If that doesn’t fix it, contact RudderStack support |
| A synonym is missing, and Lookout’s notes say it was withheld or trimmed | The term looked sensitive, or a limit was reached | Reword or shorten it |
| Only 100 views are listed | Lookout lists the first 100 per catalog | Ask about a view by its full name |