# LookML & Cortex

The semantic layer is a file, so moving in and out of it is a file conversion, not a
migration project. Every import and export writes to stdout unless you pass `--out`,
so you can review the conversion before committing it.

## Import LookML

```bash
sqldash import lookml views/ --out .sqldash/metrics.yaml
```

Converts LookML views and measures into a `metrics.yaml`. Takes a single `.lkml` file
or a directory, and needs the `lookml` install extra.

## Import a Snowflake semantic view

```bash
sqldash import cortex semantic_view.yaml --out .sqldash/metrics.yaml
```

Converts a Snowflake semantic view into a `metrics.yaml`. Connection details it cannot
know come out as placeholders, each with a warning, so fill them in or run
`sqldash setup`.

Snowflake stores an unquoted name uppercased, so a view read back with
`SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW` says `REVENUE`. The import folds those names back
to lowercase, which Snowflake treats as the same identifier, and keeps mixed-case names
as written, since only a quoted identifier can produce one.

## Export to LookML

```bash
sqldash export lookml --out views/sqldash.lkml
```

Exports the semantic layer as LookML views, so metrics defined in sqldash can be used
from Looker.

## Export a Snowflake semantic view

```bash
sqldash export cortex --out semantic_view.yaml
```

Emits a semantic-view YAML for `SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML`, so the metrics
your dashboards and agents use and the ones Cortex Analyst answers from are the same
definitions, maintained once, in git. `--name` sets the view name, which defaults to the
project directory's name, and `--description` writes a description into it. A
`timezone: session` time dimension exports as `CAST(<expr> AS TIMESTAMP_LTZ)`, and
`import cortex` reads that cast back.

## What does not round-trip

Derived metrics and aggregates LookML has no measure type for still export, with a
warning naming what was lost. Cumulative and window metrics warn too, because Looker
computes the per-bucket sum itself, but they do round-trip, since the exported measure
carries their meaning in `tags:` and `import lookml` reads it back. A metric's `title`
and `format` become LookML's `label:` and `value_format_name:`, and descriptions and
`synonyms` carry across both ways. `owners`, and formats Looker has no name for such as
`compact`, are dropped with a warning. Merging per-metric filters onto shared tables can
change meaning, and that is warned too. Read the warnings before committing the output.

## Export a Cortex Agent

This needs an agent in `agents.yaml` whose metrics all come from one Snowflake account,
in a single project. From a workspace, pass the project path after the agent name.

```bash
sqldash export cortex-agent finance_analyst --out finance.sql
sqldash export cortex-agent finance_analyst --schema ANALYTICS.AGENTS --model auto
sqldash export cortex-agent finance_analyst --spec-only --out agent.yaml --view-out view.yaml
```

The SQL creates a semantic view scoped to the agent's allowed metrics and dimensions,
named `<agent>_metrics`, then the agent itself with `CREATE OR REPLACE AGENT`.
Instructions, response guidance, and sample questions carry over, and
[verified examples](/docs/agents/) become verified queries in the view.

`--schema DATABASE.SCHEMA` defaults to the common schema of the agent's Snowflake metrics,
and destination names must be unquoted identifiers. `--model` defaults to `auto`.
`--spec-only` writes the agent YAML instead of SQL, and then you create the exported view
in that schema yourself before using the spec.

sqldash only generates the script. Review it and its warnings before running it in
Snowflake, where it replaces the named objects. Data tools, external MCP servers, and
evals are not exported as hosted capabilities and are omitted with warnings. Warehouse
grants remain the access boundary.