/dbt-model-index

name: dbt-model-index
description: 'Use when a human-curated dbt model index must guide BigQuery SQL for a warehouse question. Not for discovering undocumented models or executing warehouse changes.'
disable-model-invocation: true

dbt model index

Contract

| Field | Bound contract | |---|---| | Trigger | The user needs to query data in a dbt-powered data warehouse or resolve a data question. | | Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. Consults the curated model index and emits SQL without executing it. | | Side effect | Produces a BigQuery SQL query that references the correct model; no warehouse mutation | | Done | Query uses the correct fully-qualified model name, respects documented standard filters, partition fields, grain, and cost controls |

Inputs

• A data question or query intent (required). May be vague or ambiguous.
• The human-curated model index in the Curated Model Index section (required). The human maintains one entry per dbt model, organized by domain. Each entry must record: fully-qualified table reference, grain (one row per what), useful-for query patterns, join keys, standard filters, and partition fields.
• Standard filters, production dataset path, plan or tier valid values, and sensitive-dataset callouts documented in the Curated Model Index section (required when the project has them).

Procedure

1. Read the data question. If it names specific models, skip to step 4. Done when: the data question is read and the path (model-named or index-scan) is determined. 2. Scan the Curated Model Index section. Match the question to the model whose grain and useful-for patterns best fit the intent. Done when: the best-fit model is identified from the index. 3. If no single model fits, identify the join keys that connect candidate models and note each model's grain to avoid fan-out. Done when: join keys are identified and grains noted, or a single model is selected. 4. Construct the fully-qualified table reference using the production dataset path documented in the Curated Model Index section. For sensitive datasets, use the separate dataset path called out there. Done when: the fully-qualified table reference uses the correct dataset path. 5. Apply every standard filter documented in the Curated Model Index section (for example, excluding test accounts, soft-deleted records, internal users, flagged or fraudulent users). Omit none. Done when: every documented standard filter is applied. 6. For partitioned tables, filter on the partition field and constrain the date range. Never issue an unbounded scan of a large partitioned table. Done when: partitioned tables are filtered on the partition field with a bounded date range. 7. Include a comment stating the model grain (one row per what) so join cardinality is explicit. Done when: the query includes a grain comment. 8. If the query references plan or tier types, filter only on the valid values documented in the Curated Model Index section. Done when: plan or tier filters use only documented valid values. 9. Emit the BigQuery SQL query. Done when: the BigQuery SQL query is emitted with correct model name, all standard filters, partition constraints, grain comment, and valid-value filters.

Failure and recovery

• No model in the index matches the question: stop and report which models were considered and why each was rejected. Do not invent a model or guess a table name.
• The index is empty or an entry is missing required metadata (grain, filters, partition fields): stop and report the gap. Do not emit SQL that skips an undocumented standard filter or partition constraint.
• Joining models would cause a grain fan-out: report the conflict and the grains involved. Do not emit SQL that silently multiplies rows.
• Partial result: never emit a query that respects some but not all documented standard filters or cost controls. The done predicate is all-or-nothing.

Output

A BigQuery SQL query that references the correct fully-qualified model name, applies every documented standard filter, constrains partitioned-table scans to a bounded date range, and states the model grain. Also name each selected model and explain why it was chosen.