Skip to main content
Human guide: task steps and agent prompt → Use a semantic layer to reuse metric names and field expressions in warehouse queries. This guide uses the current Snowflake connector. The semantic-layer reference lists supported fields and query behavior.

Define a small model

Start with one physical table whose columns and grain you have already checked. For example, adapt this model to your own warehouse. RAW.CRM.ACCOUNTS and its columns are illustrative, not built-in Deepline tables.
Define exactly one main_id: true dimension across the model; use its actual identity column. Here ID is illustrative, and unique: true declares the expected identity rather than checking warehouse rows. This query selects the named active_accounts filter explicitly. A table-level base_filter applies automatically; relationships can supply joins when a query references another logical table. Inspect the rendered SQL before relying on either.

Validate and save

Save the model as semantic-layer.yml. Bind a test workspace with access to the intended warehouse. Inspect the connector contract, then validate without changing the stored layer:
A successful dry run checks parsing and table references. It does not check that warehouse objects exist or that each expression produces the intended result. Semantic queries use the stored workspace model; they cannot query an unsaved YAML file. Save any existing model before replacing it:
Keep the full response and locate the returned yaml so you can restore the previous model. Save the proposed model in the test workspace:

Compare with direct SQL

Run a small semantic query against your connected warehouse:
Inspect the returned sql and rows. Compare the count and grouping with known direct SQL for the same population. Check physical column names, null handling, what each row represents, filters, and timezones. Promote the same reviewed YAML to the intended workspace only after the comparison passes. Save that workspace’s previous model before replacing it.

Change definitions safely

Treat logical table, dimension, metric, and filter names as downstream query contracts. Prefer additive names when their meaning changes. Keep the last validated YAML available, and test representative queries before replacing an existing workspace model.