dbt-model-index

dbt model index

Contract

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.