Initial Setup

There are two ways to get started: seed your models with a one-time import from an existing semantic layer, or author them from scratch. Either way, your semantic layer lives in a connected git repository and is built and evolved through the Data Modeling Agent — you don't hand-write or manually commit the YAML.

One-time import from dbt MetricFlow

If you already have a semantic layer defined in dbt MetricFlow (or a comparable tool), you can seed your models from it in a single pass. The import reads your dbt semantic manifest, translates each semantic model and metric, and writes the result into Sundial's semantic layer. After the import succeeds, you own the models directly — later dbt syncs will not overwrite them.

The import is a bootstrap, not a live mirror: it happens once to give you a starting point that you then curate.

Git sync

The complete semantic model lives in your git repository, which makes git the source of truth. A sync connection watches a branch; when a commit lands, Sundial reads the changed files, validates them, and applies the changes.

Repository layout

The sundial/ directory lives once at the repository root, no matter how many dbt projects the repo contains.

<repo-root>/
  sundial/
    context_engine.yaml           # managed by Sundial — do not edit
    semantic_models/
      orders/
        orders.yaml               # folder name == file name == model slug
        pre_aggs/
          orders_daily.yaml       # pre-aggregations nest under their base model
      events/
        events.yaml
  analytics/                      # a dbt project
    dbt_project.yml
    models/
      sundial_pre_aggs/           # rollup .sql + .yml that materialize pre-aggs

File envelope

Every YAML file uses the same envelope:

apiVersion: context-engine/v1
kind: SemanticModel               # or PreAgg
metadata:
  id: 7d4c1e2f-1a3b-4c8e-9f10-2a3b4c5d6e7f   # stable UUID — never edit after the first commit
  name: orders                    # must equal the folder/file slug
spec:
  # kind-specific fields — see the reference pages

• metadata.id is the stable handle that binds a file to its stored definition. Renaming or moving a file is safe — the binding follows the id, not the path. Never edit an existing file's id and never reuse one.
• metadata.name must equal the path slug: lowercase, with every run of non-alphanumeric characters collapsed to _. Use underscores, never hyphens (My Orders → my_orders).

How a sync applies

When a commit lands on the watched branch, Sundial reads the changed files, validates them, and applies them — new definitions are created and existing ones updated (matched by their stable metadata.id).

The Data Modeling Agent

The Data Modeling Agent is the primary way to build and evolve the semantic layer. You describe what you want in natural language — "add a weekly-active-users measure", "create a customer_region dimension", "set up a daily pre-aggregation for orders" — and the agent writes or edits the YAML (and, for pre-aggregations, the companion dbt rollup model).

The agent authors through pull requests:

1. You describe the change in natural language.
2. The agent inspects the current definitions and drafts the YAML edits (and any companion dbt rollup for a pre-aggregation), checking them for validity.
3. It opens a pull request with the changes for you to review.
4. You review and merge the PR. Git sync picks up the commit and the changes take effect.

Because the model lives in git and every change is a PR, your semantic layer gets normal code-review, history, and rollback. The agent can edit your dbt models in the same session too, so you can adjust a base table and its semantic definitions together.

Next: define your first model in Semantic model.