semantic-query
/semantic-query
Pisze zapytania do zestawów danych z MetricFlow: agregacje, ścieżki atrybutów zamiast złączeń i pułapki kompilacji.
- Autor
- dbt-labs ↗
- Repozytorium
- dbt-charts ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Pisze zapytania do zestawów danych z MetricFlow: agregacje, ścieżki atrybutów zamiast złączeń i pułapki kompilacji.
Oryginalny opis (EN)
Write a board query against a source that carries a MetricFlow bundle (`metricflow:` on the source): `AGG()` over declared calculations and metrics, `relationship.attribute` paths instead of joins, constellations as tables, and the pitfalls that make a semantic query fail to compile or fail in the warehouse. Use whenever a query reads a dataset or constellation the bundle declares.
Jak działa
- The grammar
- Don't
- Write the warehouse's SQL
Podgląd SKILL.md
---
name: semantic-query
kind: pattern
description: >
Write a board query against a source that carries a MetricFlow bundle
(`metricflow:` on the source): `AGG()` over declared calculations and
metrics, `relationship.attribute` paths instead of joins, constellations as
tables, and the pitfalls that make a semantic query fail to compile or fail
in the warehouse. Use whenever a query reads a dataset or constellation the
bundle declares.
metadata:
author: fivetran
---
# Semantic query
A source with `metricflow: <dir>` carries a bundle: datasets (tables with
calculations and relationships), entities (keys and attributes) and
constellations (metrics conformed across datasets). A query that names one of
them is compiled into the warehouse's SQL before it runs; everything else is
ordinary SQL on the same connection. A source that sets `required: true` under
`metricflow:` allows no ordinary SQL: a query reading a table the bundle does
not declare is refused with `ERR-METRICFLOW-OUTSIDE-BUNDLE`.
{{#if_tool describe_semantics}}## Discover before writing
Call `{{ s_describe_semantics }}` without a name first: every dataset, entity
and constellation with its description and how many fields it has. Then call
it again with the `name` of the one or two objects the question is about to
get their calculations, relationships, attributes, roles and metrics, or
with `search` and the question's words to find the object or field that
means them, including the namespaces and pages the overview only counts. A
page holds a saved query, and a derived dataset shows its SQL: read one that
fits, then run or adapt that SQL, keeping its filters, when a question needs a
different cut. Use
those names exactly. A name that is not in the listing does not exist,
however natural it reads.
{{/if_tool}}
## The grammar
```sql
SELECT account.industry AS industry, -- relationship.attribute
DATE_TRUNC(created_at, MONTH) AS month, -- a plain column, in BigQuery's argument order
AGG(invoiced_total) AS invoiced_total, -- a declared calculation
AGG(collection_rate) AS collection_rate -- a ratio calculation, never a SUM
FROM invoices -- the dataset's bare name
WHERE account.country = 'US'
GROUP BY 1, 2
ORDER BY 1, 2
```
- `AGG(<calculation>)` aggregates with the expression the bundle declares. A
ratio such as `collection_rate` is `paid_total / invoiced_total` inside the
compiler; `AGG(collection_rate)` is right, `AVG(collection_rate)` is wrong.
- `account.industry` follows the `account` relationship to that entity's
attribute. Chain them: `document.owner.plan`. The join is declared
many-to-one, so the aggregate never fans out.
- `FROM <constellation>` reads metrics from several datasets at once, each
aggregated in its own branch and joined on the conformed roles. Group by the
roles (`month`, `account.industry`) and read metrics with `AGG()`.
- `WHERE`, `GROUP BY ALL`, `ORDER BY`, `LIMIT`, CTEs and board variables all
work. `{{ filter('account.industry', industry) }}` applies a dropdown through
a relationship path, on a dataset or a constellation.
## Don't
- `COUNT(*)`, `SUM(amount)` or `AVG(x)` on a dataset or constellation: the
bundle already declares the aggregate; use `AGG(<name>)`.
- `GROUP BY` a raw column of a joined table or a hand-written `JOIN`: name the
path (`account.industry`) and let the compiler join.
- The physical location of a bundle object: `FROM invoices`, never
`` FROM `proj`.dataset.invoices ``. The warehouse path names the raw table,
which the bundle does not declare, so the query runs as plain SQL, or is
refused when the source requires its bundle.
- An output alias that repeats the dataset's name (`AGG(ticket_count) AS
tickets FROM tickets`): BigQuery resolves the compiled `GROUP BY` against
the select list first and rejects it. Alias the calculation by its own
name.
## Write the warehouse's SQL
A query without `dialect:` is read in the source's dialect, so the functions
around the semantic names are the warehouse's: BigQuery takes
`DATE_TRUNC(created_at, MONTH)`, Postgres and DuckDB take
`DATE_TRUNC('month', created_at)`. A compile error names the unknown
calculation, attribute or table; fix the name, do not fall back to plain SQL.
Wersje
W bazie nie ma innych skilli o nazwie semantic-query.
Migawka bazy z 13.11.2026 · wersja paczki 21395c3cc208 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100dbt-to-steep
Przenosi projekt dbt Semantic Layer (MetricFlow) do plików YAML Steep z wymiarami, metrykami, filtrami i ścieżkami złączeń. - 98omni-to-dbt-metricflow
Przenosi logikę z widoków Omni Analytics (wymiary, miary, klucze główne) i relacje do dbt Semantic Layer jako YAML MetricFlow, sprawdza ją przez dbt i mf, a potem usuwa nadpisanie w Omni. - 100building-dbt-semantic-layer
Tworzy i zmienia komponenty Semantic Layer dbt: modele semantyczne, metryki (proste, pochodne, kumulatywne, ilorazowe, konwersji), wymiary, encje, miary i osie czasu, z konfiguracją MetricFlow i walidacją. - 86dbt-data-transformation
Pomaga w projektach dbt: modele, testy, dokumentacja, MetricFlow, dbt Mesh i przyrostowe strategie przetwarzania danych. - 100bigquery-graph-query
Podaje wytyczne do odpytywania grafów właściwości i semantycznych w BigQuery: GQL, ścieżki wielokrokowe i o zmiennej długości, agregacje, top-N, GRAPH_TABLE oraz zapytania semantyczne przez GRAPH_EXPAND. - 100query
Wykonuje zapytania semantyczne do bazy przez airlayer, testuje definicje widoków i sprawdza wyniki zapytań.