How I used Orion to repair our GitHub data pipeline
Insights
·
AI
How to Make Claude Use Approved dbt Metrics Instead of Raw Tables
To make Claude use approved dbt metrics, connect it to the dbt Semantic Layer, make metric discovery and execution available, and restrict alternative query paths in the client, application, and data access configuration. Verify the route with actual tool calls and results. Instructions explain the policy; they do not enforce it when another usable path remains open.
Keep metric calculations governed in dbt. Use business context to resolve the question's meaning, reporting period, and permitted exceptions. A context layer should help select an approved calculation, with a clear response when that calculation cannot answer the request.
Documentation checked October 8, 2026. The routing worksheet and examples below are recommended operating practices, not an Orion configuration format or a claim of automatic enforcement. All example metrics and business situations are hypothetical.
What does it mean for Claude to use an approved dbt metric?
An approved metric route is an execution path that invokes the metric your data team governs, with the intended dimensions, filters, reporting period, and access scope. Reading the metric's description and independently writing a similar calculation is a different route.
The dbt Semantic Layer centralizes metric definitions on existing models and uses MetricFlow to handle metric queries and joins. Compatible AI clients can access it through dbt's MCP server. The governed service still needs the underlying warehouse access required to calculate the result.
Distinguish three things during a rollout:
- A dbt model is a transformed data asset. Querying that model does not necessarily invoke a Semantic Layer metric.
- Metric metadata explains the definition and supported analysis. Reading it does not prove the definition executed.
- A metric query invokes the governed calculation. Its parameters and returned result are the evidence to inspect.
For example, an agent might read a net-revenue description, then sum a gross invoice column. The connection worked and the SQL ran, but the business calculation was substituted. Even an accidentally matching number would not establish that the approved route was used.
Why can Claude bypass dbt after a connector is installed?
An MCP connection makes tools available to a client. Your deployment determines which tools are exposed, which identity runs them, and which other connectors or execution environments remain available.
The dbt MCP tools reference lists Semantic Layer tools including list_metrics, get_dimensions, query_metrics, and get_metrics_compiled_sql. It also lists separate SQL tools, execute_sql and text_to_sql. Connecting dbt MCP therefore does not, by itself, establish a metric-only tool surface.
The distinction matters: get_metrics_compiled_sql returns compiled SQL without executing the query; query_metrics executes metric queries. A reviewer needs evidence of execution and returned values, beyond a plausible query displayed in the conversation.
Inventory the actual paths available to the assistant: dbt MCP, a warehouse connector, another analytics service, a terminal with credentials, and saved files containing earlier results. Record both data access and the ability to distribute results. Restricting one connector does not govern the others.
Treat the deployed tool list as evidence. A settings screen or a successful login only shows that one part of the connection works.
How do you configure a metric-first route?
Start with one business question that has an approved reference answer. Configure its path before broadening the assistant's access.
1. Identify the metric and environment
Record the authoritative metric identifier, production environment, permitted dimensions, time semantics, and owner. Agree on the identity and reporting cutoff for the reference answer. If your team only has dbt transformation models today, identify that limitation before promising Semantic Layer execution.
2. Connect the intended Claude client
Use dbt's Claude integration guide for the client you actually operate: Claude web, Desktop, and Code have different setup paths. Verify the intended environment and account after connecting. Keep credentials in the supported authentication mechanism rather than a shared knowledge page.
3. Inspect and narrow the tool surface
For token-based remote MCP, dbt documents x-dbt-disable-tools and x-dbt-disable-toolsets headers. A metric-only consumer can consider disabling the sql toolset while retaining necessary metric discovery and query tools. Inspect the resulting tools in that client; do not assume a token-based configuration applies unchanged to an OAuth connector.
Turning off dbt AI features hides text_to_sql, according to the same documentation. It does not disable every other SQL path. Test the actual configuration, including other servers and connectors.
4. Separate consumer access from calculation access
Keep the governed metric service's required warehouse permissions intact. Separately restrict the assistant's alternative warehouse or terminal credentials according to your policy. Removing access indiscriminately can break the approved calculation without closing another bypass.
For a custom application, enforce the permitted tool set in application code and manage identities at the access layer. Client configuration that a user can freely change is a different control from a centrally administered policy. Choose controls that match the rollout's requirements.
5. Define the missing-metric response
Decide what happens when the requested metric or dimension is unavailable: clarify the question, report the gap, or request an approved exploratory analysis. A failed metric query should not silently trigger a fresh calculation over raw tables.
These steps are a deployment pattern. They need to be verified in your client, account, and access system; they are not a universal setting that controls every independent agent.
What business context belongs around the metric?
Keep formulas, metric relationships, and approved calculation changes in the governed metric system. Maintain the information needed to select and explain those calculations alongside it. The useful boundary is described in Semantic Layer vs. Business Context.
A hypothetical finance routing note might say:
- Question scope: the monthly finance operating review.
- Meaning: “revenue” maps to the approved net_revenue metric; bookings is a separately named measure.
- Reporting period: use the finance-approved fiscal month and record the data cutoff.
- Dimensions: request only dimensions supported by that metric and allowed for this identity.
- Ambiguity: clarify a request that could refer to bookings or recognized revenue.
- Exceptions: link an approved pricing-event note with its effective date; leave the metric formula under its existing owner.
- Gap response: identify a missing dimension and request review before exploratory work.
This note specifies intent and disposition. It becomes enforceable only where your application or access controls implement the policy. Maintain its owner and source so a copied prompt does not become a competing definition.
Which checks prove the approved route is being used?
Use the following route acceptance worksheet with the actual consumer identity. It focuses on metric substitution and fallback behavior. For a broader suite after business rules or dbt models change, use context-layer change evaluations.
| Check | Hypothetical request or condition | Expected route or disposition | Evidence to retain |
|---|---|---|---|
| Approved question | September net revenue by region | Invoke the approved metric with supported grouping | Metric identifier, environment, parameters, execution result |
| Ambiguous term | September revenue | Resolve the documented finance scope or ask which measure | Context source and resolved metric |
| Different legitimate measure | September bookings | Use the separately approved bookings metric | Correct metric identifier; no relabeling as revenue |
| Unsupported dimension | Net revenue by an unavailable attribute | Explain the gap or request approved exploration | Gap response; no silent raw-table substitute |
| Direct bypass request | Ignore the metric and sum raw invoice values | Decline that route in the metric-only consumer | Rejected or unavailable path and final disposition |
| Metric-service failure | Approved query cannot complete | State that no current metric result was obtained | Failure evidence; no invented value or undisclosed fallback |
| Restricted identity | User cannot access the requested population | Follow the deployed authorization rules | Identity, denied or scoped result, no broader credential fallback |
| Alternative connector | Same request with another warehouse tool available | Preserve the policy or identify a configuration failure | Full tool inventory and observed execution path |
| Switch to exploration | User requests a deeper investigation | Use the separate authorized route and label its output | Reviewer or authorization record, changed route, output label |
Record pass, fail, or unknown for every row. “Unknown” is appropriate when the consumer does not expose enough execution evidence; treat it as a release decision for the owner. A successful prompt run is not a substitute for the missing check.
For every case, compare the answer with the approved reference under equivalent conditions. Retain an execution or request identifier where available, the result, reporting cutoff, and any error. A number matching a dashboard is useful reconciliation evidence, but it cannot prove which tool produced it.
Run the bypass and failure cases as well as the normal question. Repeat them after changes to connector configuration, user roles, or the metric catalog. This worksheet is a proposed acceptance process, not a claim that Orion ships a complete automated gate.
What should happen when a user needs exploratory SQL?
Separate routine metric consumption from authorized exploration. Exploration is valuable when the approved metric cannot answer a new question. Its output should be labeled and reviewed before being treated as an official KPI.
| Route | Suitable job | Main trade-off | Operating rule to verify |
|---|---|---|---|
| Metric-only consumer | Recurring questions covered by approved metrics | Cannot answer every new dimension or measure | Gaps remain visible; no silent calculation replacement |
| Separate exploratory analysis | Investigating a question outside the metric catalog | Requires interpretation and reconciliation | Identify sources and label provisional calculations |
| Mixed tools in one session | Experienced analysts need both routes | More opportunity for accidental substitution | Explicit selection, observable execution, and access policy |
A hypothetical request for net revenue by a new acquisition channel illustrates the boundary. If that dimension is unavailable, the agent should explain the gap. An authorized analyst may investigate the channel separately. The resulting experimental breakdown should not be presented as the approved finance metric until its mapping and calculation have been reviewed.
If the organization needs one mixed-tool session, document who can use it and how outputs are distinguished. Do not imply that a prompt preference makes a mixed session behave like a restricted metric consumer.
Where does Orion by Gravity fit?
Orion by Gravity can help maintain the business meaning surrounding an analysis and provide an Orion analysis path to compatible assistants. Its MCP documentation describes access to Orion projects, metrics, workflows, and Knowledge Base pages from clients including Claude.
Orion's page documentation describes project-enabled context, revision history, and change requests for locked pages. Privileged editing exceptions exist. Verify the intended reviewer roles and defaults before relying on them as an approval boundary.
Orion's dbt connection documentation describes enriching an existing warehouse connection with dbt model descriptions and lineage. That is useful metadata support. It does not establish that every Orion answer invokes a MetricFlow metric.
The Orion tools reference describes ask_orion for analysis, execute_metric for refreshing an Orion metric, and get_metric for its definition, code, data sources, and latest result. These names do not establish equivalence with dbt's query_metrics. Demonstrate the calculation behind the Orion metric you intend to use.
For ask_orion, the documented integration retrieves the completed response through conversation history. The application should handle completion and expose the evidence available for review. Keep answer evidence connected to the business claim.
Choose Orion when maintaining context and consuming Orion analysis address an additional operating need. If your sole requirement is querying existing dbt metrics from Claude, dbt's documented MCP path may be sufficient. If enforced MetricFlow execution is a purchase requirement, require a deployment demonstration before assigning that capability to an Orion integration.
For cross-consumer rollout, see consistent definitions across Claude, Slack, and BI. For broader product selection, use the AI business intelligence tools guide.
Frequently asked questions
Is a CLAUDE.md instruction enough to enforce metric use?
It can communicate the policy to clients that load it. Enforcement also depends on available tools, credentials, application rules, and administrative control of configuration. Verify the actual execution path rather than assuming the instruction removed another route.
Does a dbt MCP connection expose only governed metric tools?
The documented server includes multiple tool categories, including Semantic Layer and SQL tools. Inspect what your authentication, configuration, and account expose. Narrow the consumer's tools and check other connected systems separately.
Is querying a dbt-built table equivalent to querying a dbt metric?
No. A table can be an approved input while an ad hoc calculation over it still differs from the metric definition. Identify whether the request invokes the governed metric or implements a separate calculation.
Should we remove the warehouse permissions used by the Semantic Layer?
Keep the permissions required for the approved calculation. Review alternative assistant identities separately. The service computing a metric and a client with direct warehouse access can have different roles and access requirements.
What if our team has dbt models but no Semantic Layer metrics?
Choose an explicitly approved reporting path and describe it accurately. A curated dataset or reviewed SQL workflow can be useful, but it should not be labeled Semantic Layer execution. Decide which recurring measures warrant governed metric definitions.
Can an Orion metric be assumed to execute a dbt metric?
Inspect its definition and execution evidence. Orion's public tools and dbt enrichment documentation do not establish mandatory MetricFlow execution for every metric or answer. Verify the exact integration before treating it as your approved dbt route.
What should we do first?
Pick one recurring metric question, record its authoritative reference, and inventory the client's actual tools and identities. Run the normal question, a bypass request, and a missing-metric case. Expand only after the owners can explain each observed route.
