AML Overview
Why a semantic layer needs a real language, what AML gives you that YAML configs cannot, and the vocabulary you will meet in every AML file.
What AML is
AML (Analytics Modeling Language) is the language a semantic layer is written in. A semantic layer is the layer between your warehouse and everything that consumes data: reports, AI agents, embedded analytics, ad-hoc questions. It is where models, dimensions, measures, metrics, datasets and relationships are defined once, so every consumer reasons from the same governed definitions.
AML is declarative and typed. You describe what the business means by order, customer and revenue, and the compiler turns those definitions plus an AQL question into SQL against your warehouse.
Why AML
Every BI tool has some form of semantic layer. Most of them hit the same wall, which we call the semantic ceiling: the layer can express first-order questions (a metric, sliced by a dimension, filtered) and nothing more. The moment someone asks a real analytical question, "revenue by region, compared to the same period last year, for customers active in both periods", the logic leaks out into derived tables, spreadsheet formulas and one-off SQL. AI assistants built on such a layer inherit the same ceiling. They either refuse, guess, or return a confident number that is subtly wrong.
The ceiling comes from three structural gaps, and they compound:
- Not programmable. The layer is YAML. YAML is schemaless (no type check until runtime), ambiguous (
enabled: yesis a boolean in one parser and a string in another) and has no abstractions, so reuse degrades into Jinja templating that breaks at runtime and cannot be debugged. - Not composable. Metrics are SQL strings with metadata. A metric cannot reference another metric, so period comparisons, cohort retention and ratios across grains need pre-built tables that lock their dimensions.
- Not truly as-code. The UI is the source of truth and Git is an export. Pull requests review the artifact, not the intent, and environments are a manual copy.
AMQL closes all three. AML closes the first and third: it is a typed language with real abstractions, and the files are the system of record. AQL closes the second, which is why it gets its own section. The rest of this page is about what AML gives you.
What AML gives you
AML treats your analytics logic as code, not configuration. Four properties make this concrete:
- First-class, typed objects. Models, dimensions, measures, metrics, datasets and relationships are language constructs with defined types, not SQL strings inside generic key-value structures. You can reference them, pass them around and compose them.
- Static type checking. A built-in type system validates the model as you write it. A typo in a dimension name, a number compared to a text, a reference to a model that does not exist: all surface at authoring time, not as a wrong number in a report. The same checks feed editor tooling: autocomplete, inline docs, go-to-definition. See AML vs YAML for the full argument.
- Reusable constructs. Constant, Func, Module, Extend and Partial let you factor out and compose logic instead of copy-pasting it. A change to a base definition propagates to everything built on it. See Reusability.
- Plain files in a repository. An AML project is a folder of text files. That is what makes business logic durable:
| Capability | What it gives you |
|---|---|
| History and authorship | Every change to a metric definition has an author, a timestamp and a diff. "Who changed revenue?" is answered in seconds. |
| Review | Wrong logic does not merge silently. The discipline that protects production code protects business definitions. |
| Branches | Try a new definition in isolation, on real data, without touching what everyone else sees. |
| Validation before merge | AML compiles. Type-check the whole project in CI and catch breaks before users do. |
| Inspectable output | Every query compiles deterministically to SQL you can read, so trust comes from seeing exactly what runs. |
| Rollback | Reverting a bad change is one commit, not a forensic exercise. |
The cumulative effect is a semantic layer that gets stronger over time instead of drifting: definitions improve through review, and every consumer, human or AI, picks up the improvement at once.
Static types as a feedback loop for AI
Because AML is statically typed, the compiler checks every edit against the model immediately, whether a person writes it or an AI agent generates it. When an agent produces an invalid reference or a type mismatch, the compiler flags it at once, rather than letting the error surface later as a wrong number. This tight author-to-check loop is what makes agentic development on the semantic layer safe to trust. And when an agent queries, it generates AQL against definitions you have already reviewed, not SQL against raw tables.
The vocabulary
Six words carry most of AML. You will meet them in every file. The longer explanation is on Core concepts.
| Concept | Definition |
|---|---|
| Model | An object on top of a database table or a SQL query, where business meaning is added. Two kinds: table model and query model. |
| Dimension | A non-aggregate field of a model: a column, or an expression derived from columns. What you group and filter by. |
| Measure | An aggregating field defined inside a model, such as a sum or a distinct count. |
| Metric | A full aggregation written in AQL, defined on a dataset or standalone. Composable, reusable and independent of any single query. |
| Relationship | The declared link between two models, like a foreign key but defined once at the model level so queries never write joins. |
| Dataset | A curated collection of models and their relationships. The unit that consumers explore and that metrics are attached to. |
"Measure" and "metric" are often used interchangeably elsewhere. In AMQL they are deliberately distinct: a measure lives on a model, a metric lives on a dataset or stands alone, and both are AQL expressions at different scopes. See Defining a metric.
AML files
AML is written in .<object-type>.aml files. The core objects are:
- Model:
model_name.model.aml - Dataset:
dataset_name.dataset.aml - Relationships:
relationships.aml
A project is a folder of these files. The compiler reads them together, so a dimension defined in one model can be referenced from a dataset or a metric in another file.
Design principles
- Declarative: you specify the semantic model and its logic, not the steps to build it.
- Friendly yet rigorous syntax: inspired by JSON, YAML and JavaScript, but strict and well-defined, so there is no ambiguity in what a value means.
- Static type checking: instant feedback for humans and AI agents alike, and the basis for editor tooling.
- Composability and reusability: every construct is designed to be reused and composed, so analytics logic scales across a team without duplication or drift.
The longer version is on Design principles.
Where to go next
Shape the model
- Core concepts: models, dimensions, measures, relationships and datasets, and how they map onto SQL.
- Modeling patterns: facts, dimensions, star, snowflake, galaxy and role-playing dimensions, in AML.
- Reusability: the step-by-step process for factoring logic out, with five worked recipes:
Look it up
- AML examples: side-by-side syntax for every object
- Model, Dimension and measure, Dataset: the core modeling path
For what you can query once the model exists, see the AQL cookbook.
AML vs YAML
AML is a purpose-built typed language for analytics modeling. This page is the structural argument for why we didn't use YAML, and why YAML-based 'analytics-as-code' tools end up in the Jinja-templating trap.
Core concepts
Models, dimensions, measures, relationships and datasets: the building blocks every AML file is made of, and how they map onto SQL.