transform init), write or refactor model SQL from staging to marts, add tests and docs in schema.yml, manage dependencies, and define or update the semantic layer, whether that is dbt semantic models (MetricFlow: entities, dimensions, measures, metrics) or native Apache Ossie documents in a repo with no dbt project at all. Reach for this rather than editing model files by hand whenever the change spans more than one file or has to stay consistent with the rest of the project: it validates the edit against the real schema before writing, returns the change as a reviewable diff with a plan id, and catches the class of error that only surfaces at dbt run, such as wrong column names, broken refs, or a materialization that fights the project config. On a large project that check is worth more than the round trip costs. It applies to bug-fix tickets too: \"this model returns wrong numbers, fix it\" is a transform task. Trigger it for requests like \"set up a dbt project in this repo\", \"build a staging model for this table\", \"refactor this model\", \"add tests to this model\", \"create a mart for X\", \"define a revenue metric\", \"add a dimension to this entity\", \"add a metric to my Ossie semantic model\", or \"update semantics/commerce.ossie.yaml\". Any warehouse build is dev-target only, gated, and cost-surfaced first. If you do not yet know the source tables'' columns or grain, use explore first, then come back. To reconcile a project that has drifted out of sync with the warehouse, use maintain.'Author and refactor the dbt project: both the SQL transformations (staging to\nmarts, tests, docs) and the semantic layer on top (entities, dimensions,\nmeasures, metrics). Both are the same job, writing reviewable diffs to the dbt\nproject, which is the source of truth. This is the building half of the loop. It\nwrites only to the repo, as reviewable diffs, and runs against a dev target only.
\nuv run --no-project --script \"${CLAUDE_SKILL_DIR}/scripts/run.py\" <subcommand> [flags]\ndex runs its engine through uv, which is a prerequisite and is not installed by\nClaude Code. If the shell reports uv: command not found, stop and tell the user\nto install it (curl -LsSf https://astral.sh/uv/install.sh | sh, or\nbrew install uv, or pipx install uv), then re-run. Never fall back to editing\nthe dbt project by hand instead: the validation, the diffs, and the dev-target\ngating live in the engine, so any other path is unguarded.
The first command in a fresh environment installs the engine, so it can take tens\nof seconds where later ones take well under a second. --warm pays that install up\nfront and exits without running anything:
uv run --no-project --script \"${CLAUDE_SKILL_DIR}/scripts/run.py\" --warm\nOffer it once at setup. It is not something to run before an ordinary command.
\nYou author the dbt file content; the engine validates it, computes the diffs,\nand stores the proposal as a plan. Hand content over with --edits-file <path>\n(or - to read stdin), a JSON payload:
{\"edits\": [\n {\"path\": \"models/staging/stg_orders.sql\", \"kind\": \"model_sql\", \"content\": \"...\"},\n {\"path\": \"models/staging/stg_orders.yml\", \"kind\": \"schema_yml\", \"content\": \"...\"},\n {\"path\": \"snapshots/snap_orders.sql\", \"kind\": \"snapshot_sql\", \"content\": \"...\"},\n {\"path\": \"seeds/country_vat.csv\", \"kind\": \"seed_csv\", \"content\": \"...\"},\n {\"path\": \"tests/assert_totals_reconcile.sql\", \"kind\": \"test_sql\", \"content\": \"...\"},\n {\"path\": \"analyses/email_skew.sql\", \"kind\": \"analysis_sql\", \"content\": \"...\"},\n {\"path\": \"models/marts/dim_orders.sql\", \"kind\": \"model_sql\", \"op\": \"delete\"}\n]}\nkind is model_sql, schema_yml, semantic_yml (optional on\nsemantic define|update|plan, which imply it), macro_sql (a macro file under\nthe project's macro paths), snapshot_sql (a snapshot under the snapshot\npaths), seed_csv (a seed's CSV under the seed paths), test_sql (a singular\ntest or a generic test definition under the test paths), analysis_sql (SQL dbt\ncompiles but never runs, under the analysis paths), packages_yml,\nproject_yml (the project-root dbt_project.yml), or profiles_yml (the\nproject-root profiles.yml). Model SQL must be a single read-only SELECT once\nits jinja is stripped; semantic YAML is validated against MetricFlow's schemas,\ncross-reference-checked, and (when dbt is available) parsed by dbt itself before\nthe plan is accepted; a macro file must hold only macro definitions and jinja\ncomments. A snapshot must hold exactly one {% snapshot %} block whose\nconfig() names a unique_key and a strategy of timestamp (with\nupdated_at) or check (with check_cols), and whose body is a single\nread-only SELECT. A seed must parse as CSV with a named, duplicate-free header\nand one field per column on every row, and stays under 5,000 data rows and 1 MiB\n(past that it is data rather than a lookup: load it into the warehouse and\nsource() it). A test_sql file is read to decide which of the two shapes\nsharing the test paths it is: one holding {% test %} blocks is a generic test\ndefinition and must hold only those and jinja comments, balanced; anything else\nis a singular test and must be a single read-only SELECT. A singular test that\nnames no ref() or source() is warned about, not refused, because it runs\nagainst nothing and passes unconditionally. An analysis must be a single\nread-only SELECT too, even though dbt only compiles it. project_yml must keep\na name; profiles_yml must reference\nevery secret via {{ env_var('NAME') }} (a literal credential is refused so\nnone reaches the diff). Config kinds, snapshots and seeds are all parsed by dbt\nat plan time.
Each kind is confined to its own family of paths, and filing one in the wrong\nfamily is refused naming both fixes. schema_yml is the exception, accepted\nbeside a model, a snapshot, a seed, a test or an analysis, because that is where\ndbt expects a snapshot's tests, a seed's column types, a singular test's severity\nand an analysis's description declared.
Three things here are called a test, and they are not interchangeable.\nGeneric tests are declared inside a schema.yml (data_tests: on a model or a\ncolumn). Unit tests come from transform test --scaffold <model>, which writes a\nunit_tests: block, also schema_yml. Singular tests and generic test\ndefinitions are files under test-paths, and test_sql is the kind for those.\ntransform test --mutate <model> measures all three at once, since a defect has\nto get past every one of them to reach production.
A seed puts values, not logic, into a diff, and a diff goes into git and stays\nthere. So a seed whose header names a column that looks like personal data is\nrefused, and the refusal names the pii_overrides entry in .dex/config.yml\nthat a human can add to clear it. Detection reads names and types and never\nvalues (everywhere in dex), so it cannot see personal data hiding under a\nneutral column name: do not build a seed out of warehouse rows you have not\nlooked at.
dbt build runs seeds, snapshots and singular tests natively, so transform build after an apply is all it takes; there is no separate seed or test step. A\nsnapshot writes a table and a test runs a scanning SELECT, so both are priced in\nthe cost handshake; a seed scans nothing and an analysis is never built at all,\nso neither is. A singular test and an analysis build no relation and nothing can\nref() either, so neither is a node: neither enters maintain's drift baseline,\nand deleting one raises no dangling-reference guard.
op is upsert (the default: create or update, carrying content) or\ndelete (remove the file, no content). A delete is a first-class reviewable\ndiff like any other edit, so a reclassification or refactor is one plan rather\nthan a plan plus a manual rm. Deletes are guarded: the plan is refused if any\nfile that survives it still ref()s a deleted model, naming the offenders.\nCarry the edits that remove those references in the same plan (for a rename,\ndelete the old model, create the new one, and update every referrer to\npoint at it, all together) so the post-change project is validated as one unit.\nAn unconfirmed delete against a file a human edited after planning surfaces as\nneeds_confirmation, never a silent removal.
For a rename or a removal, reach for transform rename / transform remove\ninstead of assembling the edits yourself. They generate the whole change from the\nreference graph and refuse when they cannot promise it is complete, which is the\nguarantee hand-assembly cannot give you.
If no dbt project exists in the repo, offer transform init before anything\nelse: transform plan needs a project to edit. Ask the user for the project\nname and confirm the connector with them, then run:
uv run --no-project --script \"${CLAUDE_SKILL_DIR}/scripts/run.py\" transform init \"<name>\" --connector <c>\nThe engine renders the whole skeleton (dbt_project.yml, models/staging/ and\nmodels/marts/, a profiles.yml with a single dev target and no secrets) and\nrecords connector, dbt_project_dir, and dbt_target: dev in\n.dex/config.yml; do not hand-write these files yourself. Init never assumes a\nconnector: it errors rather than defaulting, so always pass the user's confirmed\nchoice (a connector: already committed in .dex/config.yml also counts).\nEvery connector is supported: DuckDB, BigQuery, Snowflake, Databricks,\nPostgres, Redshift, and ClickHouse. DuckDB needs a warehouse path (--path, or the\nduckdb.path config). BigQuery needs a GCP project (usually\nbigquery.project in .dex/config.yml; confirm it with the user) and writes\nbuilds to a dedicated dev dataset (bigquery.dev_dataset, default\ndbt_dev); auth is Application Default Credentials, so if credentials are\nmissing tell the user to run gcloud auth application-default login, never\nask for a key. Snowflake writes builds to a dedicated\nsnowflake.dev_database/dev_schema on the pinned warehouse; Databricks\nwrites builds to a dedicated databricks.dev_catalog/dev_schema on the\npinned SQL warehouse (if credentials are missing tell the user to run\ndatabricks auth login, never ask for a token); Postgres writes builds to a\ndedicated postgres.dev_schema (default dbt_dev), with the password\nreaching dbt only through the PGPASSWORD environment variable. Redshift\nwrites builds to a dedicated redshift.dev_schema (default dbt_dev): with\na redshift.workgroup pinned the profile renders IAM auth (temporary\ncredentials from the AWS chain, nothing persisted), otherwise the password\nreaches dbt only through the REDSHIFT_PASSWORD environment variable.\nClickHouse writes builds to a dedicated clickhouse.dev_database (default\ndbt_dev), rendered as the profile's schema: because dbt-clickhouse has no\ndatabase: key, with the password reaching dbt only through the\nCLICKHOUSE_PASSWORD environment variable; the rendered profile also carries\na custom_settings block whose env_var references are how transform build\nturns the confirmed budget into a per-statement server-side cap, so do not\nstrip them from a profile you edit. All of them discover their connections and refuse with the fix named when none\nresolves. Init refuses if any dbt project already exists.
When the user wants staging/intermediate/marts isolated in their own\ndatasets/schemas (a common ask when the warehouse is shared with unrelated\nwork), offer --layered-schemas: init then also scaffolds\nmodels/intermediate/, a generate_schema_name override, and per-folder\n+schema: config, so builds land in staging_dev / intermediate_dev /\nmarts_dev instead of one shared dev namespace. Do not hand-write that macro;\nexisting projects can adopt it later via transform macro generate_schema_name. Note dbt warns about \"unused configuration paths\" until\nthe first model lands in each layer folder; that resolves itself.
Init also checks (free, metadata-only) whether each namespace the project\nwould build into already exists with content, and warns naming the namespace\nand a few object names. The warning is advisory: relay it to the user and ask\nwhether the content is theirs (a previous dev build) or unrelated; when it is\nunrelated, discard the freshly scaffolded project (nothing has been built),\npoint the config at a different dev namespace, and re-run init. A \"could not\ncheck\" note just means no connection was reachable at init time.
\ntransform plan \"<intent>\" --edits-file <path|-> validates the edits and\nreturns them as diffs with a plan id. Nothing is applied yet. Add\n--scaffold <table> (repeatable) to generate a staging skeleton\n(stg_<table>.sql plus per-model YAML with key tests and PII meta) from the\n.dex/ cache instead of, or on top of, hand-authored edits.
When you edit a model that already exists, the plan reports what your change\ndoes to its row population under data.row_attribution: every predicate,\njoin, source and grain change is named, and each is measured on its own against\nthe prior model. Read it before applying. A change you were not asked to make\ncarrying a non-zero delta is the signal to look at: the model still compiles\nand the columns are still right, and it is now returning a different set of\nrows. It is advisory, never a refusal, because changing the filter is sometimes\nthe job. On DuckDB the deltas are measured automatically; on a billed connector\nthe changes are named for free and measuring them needs --attribute-rows\n(then the usual --confirm --budget once priced), so ask the user before\nspending. A change reported with attributed: false names why it could not be\nmeasured; treat that as unknown, not as zero.
The plan also warns about the shape of what you authored, in warnings.\nA SELECT list that diverges from the columns the model's schema.yml declares\nis named in both directions; fix whichever side is actually stale, and say\nwhich one you decided it was.
A warning that the model exposes a raw foreign key with no resolved\ncounterpart is dex reading a convention out of the project's own models: the\nsiblings it names all resolve keys of that shape, and it names the parent\nmodel yours could resolve against. Prefer resolving it, by joining that parent\nthe way the siblings do. Where the raw key is deliberate (a fact-shaped model\nin a dimension folder, a key the consumer needs verbatim), say so plainly to\nthe user rather than quietly leaving it. Never switch the check off to make\nthe warning go away: conventions.resolved_keys: false in .dex/config.yml\nis a decision about the house's style, so recommend it for the user to accept,\nthe same way you would a pii_overrides entry.
transform apply [plan-id] writes the plan into the dbt project (the latest\nunapplied plan when no id is given; any plan kind, semantic included). The\nresult is still a reviewable git diff for the user. If a human edited a file\nafter the plan was made, nothing is written: the divergence comes back as\ndiffs with needs_confirmation, and you should re-plan against current state\n(or, only when the user says so, re-run with --confirm).
transform plans lists stored plans (pending and applied, newest first), so\nyou never need to browse .dex/plans/ by hand.
transform references <name> [more...] answers \"where is this used\" before you\nchange it. Reach for this whenever a change has to land in more than one\nplace: removing a project variable, renaming a column, deleting a model,\nchanging what a macro returns. Editing the files you happen to have open and\nhoping that was all of them is the failure this prevents, and it is a quiet\none, because the project still compiles with one use left behind.
It is repo-only and free on every connector, so there is never a cost reason\nnot to run it. The positional is variadic, so one call covers a whole rename.\n--kind narrows to model, source, seed, snapshot, macro, var,\ncolumn, metric, entity, dimension or measure; leave it off when you\nare not sure what the project calls the thing, and the answer will tell you.
Read data.completeness before you act on the list. When it says incomplete,\ndata.limits says why and data.indeterminate lists the call sites dex could\nnot resolve, each with a file and a line. Those are references that may name\nwhat you asked about, so open them and decide yourself; do not treat the list\nof resolved hits as exhaustive when the verdict says it is not. A bare column\nname is matched across the project (scope: name_matched), so qualify it as\nmodel.column when you want the lineage separated from same-named columns\nelsewhere.
Once you know where a name is used, transform rename and transform remove\nbelow make the change; you do not have to carry the list into hand edits.
transform rename <kind> <old> <new> generates every edit the rename needs\nand stores them as one plan: the definition, every model that selects the name,\nevery schema.yml that documents or tests it, every semantic reference, and a\nseed header. Kinds are column, var, model, seed, snapshot, macro,\nsource. Repo-only and free, like references.
Use this instead of editing the files yourself. Retyping a rename across\nnine files and missing the tenth is the failure mode this exists for, and it is\na quiet one: the project still compiles.
\nName a column as model.column. A bare name is refused, and the refusal lists\nthe models that define a column of that name so you can pick. That asymmetry\nwith references is deliberate: a report you read can afford to be imprecise\nand a rewrite cannot, because renaming a bare id project-wide would rewrite\nevery unrelated id there is.
It refuses rather than half-applying, and each refusal names what to fix:\na reference dex could not resolve statically, a name an installed package also\ndefines, a column handed to a macro as a literal string (dex cannot tell a\ncolumn argument from a display label), a SELECT list it cannot read. Fix what\nit names and re-run. There is no override flag, because a completeness\nguarantee you can switch off is a suggestion. A bare select * is not a\nrefusal: it carries the column through under the new name with no edit, and the\nplan's notes says so.
Read data.sites against the transform references output you ran first. It\ncounts occurrences per reference form in the same vocabulary, so the two\nagreeing is your evidence that nothing was dropped between reading and writing.
transform remove <kind> <name> removes the definition and verifies every\nread is gone, refusing while any survives and naming each with a file and line.
It never rewrites a read, and that boundary is the point rather than a gap.\n{% if var('using_department') %} can be deleted or unguarded, and\n{{ var('x') }} sitting in an expression has no value dex may invent. You are\nthe one who knows. Author those edits yourself and pass them with\n--edits-file in the same call: they are validated and stored in the same\nplan, so the removal is still atomic.
transform place <column> --targets <a,b> --expr \"<sql>\" answers where a\nderived column that several models need should be defined. It walks ref()\nupward from every target, takes the lowest model they all descend from that\nalready projects the inputs your expression reads, defines the column there,\nand threads it down every chain. The inputs come from parsing --expr, so\nthere is no separate list to get out of sync with it.
Read data.reasoning before you apply. It names the ancestor, why it is\nthe lowest, which targets descend from it, and the chain. You are supposed to\nbe able to disagree with it; --explain gives you the same answer with no plan\nstored, which is the cheap way to ask.
When data.strategy is per_target the shared definition was not available\nand the reasoning says why: no common ancestor, or the lowest one is missing an\ninput, or two candidates tie. dex will not go further upstream to pull an input\ndown, because that turns one placement into an unbounded rewrite of everything\nabove it. The fallback duplicates the derivation in each target and those\ncopies will drift, so relay the reason to the user rather than applying it on\ntheir behalf. Often the named fix (add the missing column to the ancestor\nfirst) is what they actually want.
transform build --target dev runs dbt build against a dev target. The\nengine surfaces a cost preflight first and runs only with --confirm (plus a\n--budget on billed connectors). dbt itself has no dry-run, but the engine\ncompiles the project and dry-runs each node itself, so on BigQuery the first\nunconfirmed call already returns needs_confirmation with estimated_bytes\nand a per_table_bytes breakdown, the same shape the scanning explore\ncommands use. Never invent a --budget figure: read the reported estimate\n(per_table_bytes is the actionable half, since it names which node is\ndriving the cost) and confirm with a --budget grounded in that number.\nIf the build is refused over the ceiling, the refusal carries a calibration\nline from .dex/spend.jsonl: what this connector's recent commands billed as\na fraction of estimate, or a sentence saying there is too little history to\nsay. Builds over-estimate most on a partitioned or clustered warehouse, so\nrelay it, and note that the ceiling binds on the estimate rather than on what\nsettles, so a budget set at that fraction of the estimate is refused again.\nA suggested_session_ceiling on that envelope is the project's one-time ask\nfor a cumulative daily cap, separate from --budget: relay it and add the\nuser's answer (--session-ceiling <value> or --no-session-ceiling) to the\nsame re-issue, which records it in .dex/config.yml for good.\nEach statement dbt runs is capped server-side by the profile's\nmaximum_bytes_billed, and the envelope reports billed bytes afterward.\nProduction-looking targets are refused\noutright; --confirm cannot override that. dbt runs with its working\ndirectory pinned to the project dir, so relative paths in profiles.yml\nresolve against the project. When the project declares packages\n(packages.yml) and dbt_packages/ is missing, the engine runs dbt deps\nautomatically before the build.
transform build --verify is how you answer \"is it right\", not just \"did it\nrun\". A green build tells you dbt executed. It does not tell you the model\nholds the rows it should, and that is where the expensive defects live: an\ninner join written where a left join was meant loses rows, raises nothing, and\npasses every uniqueness and not-null test over the smaller result. --verify\nsweeps the nodes this build touched and reports the findings in the same\nenvelope, under data.verification. Reach for it whenever the build was meant\nto prove a change is correct, which is most of the time you build at all.
Read data.verification.ran before reading anything else. It is always\npresent, because a build that did not verify and a build that verified and\nfound nothing look identical otherwise, and only the second one means the\nmodels are clean. When it ran, findings is ranked the way maintain verify\nranks it, scope names the models covered, and suppressed names each class\nthat could not run and why. Relay a suppression rather than reading past it:\nit is the difference between \"checked and clean\" and \"not checked\".
Findings never fail the build and never appear in errors. Do not treat one\nas a build failure or re-run to make it go away: relay the finding, its two\ncounts, and the join it names, and let the user decide. A failed build still\nreports which node failed and which were skipped because of it, which is\nusually a faster read than the dbt log.
On a billed connector the sweep is priced into the build's own estimate as a\n(row counts) line, so the --budget you already read off the unconfirmed\nenvelope covers both. Never add a second budget for it. If the envelope comes\nback ok with a data.offer, the build is done and billed and the offer buys\nonly the counts it could not afford; relay the number rather than re-running\nthe build.
transform test --mutate <model> answers \"are these tests worth\nanything\". Writing a test is not the same as writing a test that would catch\nsomething, and nothing else in the dbt ecosystem tells the two apart. This\nplants one standard analytics defect at a time in the model's SQL (a flipped\nboundary, a dropped or negated filter, a swapped join type, a removed CASE\nbranch, an inverted ratio, a shifted window frame, sum for max), runs the\nmodel's own tests against each, and reports which ones nothing caught.
Reach for it right after you author or scaffold tests, and before telling the\nuser the model is covered. It is also the honest answer when a user asks\nwhether their tests are any good, which is otherwise unanswerable.
\nRead data.counts and then the survivors, which are listed first. Each carries\ndefect, a sentence saying what would now be wrong, and suggested_test, the\ntest that would catch it. Relay those two: the user's next action is to write\nthat test, not to read the SQL. A score is reported but it is a ratio of two\nsmall integers over one model, so quote it as context and never as a grade, and\nnever compare it between models.
Check baseline.excluded before trusting a clean-looking result. Every verdict\nis relative to the tests that passed against the unmutated model, so a test\nthat was already failing is excluded and named there. And read cap.elided:\nthe run is capped at 20 mutants, so a model with more sites than that was\nmeasured on a sample, spread across defect classes.
It writes nothing. Mutants build as ephemeral models in a throwaway copy, so\nthe project is untouched and no relation is created or replaced. On a billed\nconnector the whole batch is one estimate and one --confirm, and if the\nbudget runs out partway the rest come back not_run: relay that rather than\nreading a short list as a clean bill.
transform deps installs dbt packages explicitly (also the refresh path when\ndbt_packages/ exists but is stale). No confirmation needed: deps writes only\ninside the project and never touches the warehouse.
transform macro lists the macros dex ships; transform macro <name>\nproposes scaffolding one into the project's macro directory as a plan,\napplied with transform apply like any other. The user's copy is theirs to\nedit; re-running the command diffs it back against the shipped version (a\nwarning says whether it is customized or stale), and applying that plan\noverwrites deliberately.
unpivot_json_object turns a JSON object column with dynamic keys (the\nNoSQL-sourced shape: a Firestore/Mongo/DynamoDB document keyed by a related\nentity's id) into one row per top-level key. Use it instead of hand-rolling\nJSON SQL; it renders a complete SELECT:
select id, key as related_id, value as attrs\nfrom (\n {{ unpivot_json_object(relation=ref('stg_entities'),\n json_column='attributes', passthrough=['id']) }}\n)\nThe contract on every connector: one row per top-level key, key a plain\nstring, value the warehouse's native semi-structured type (BigQuery JSON,\nSnowflake VARIANT, Databricks VARIANT, Postgres jsonb, Redshift SUPER,\nDuckDB JSON, ClickHouse raw JSON text in a String), a NULL object yields no\nrows, and a nested object's own field\nnames never surface as top-level keys. For a string-typed source column\npass the parse expression as json_column (parse_json(payload) on\nBigQuery, Snowflake, and Databricks; json_parse(payload) on Redshift);\nPostgres, DuckDB, and ClickHouse accept JSON-bearing text directly. Databricks needs\nVARIANT support (DBR 15.3+ or a current SQL warehouse). Two BigQuery quirks\nare absorbed by the macro, so do not \"fix\" them back in: a JSON path\nargument must be a compile-time literal (the macro reads values with the\nsubscript operator, which accepts a computed key), and JSON_KEYS recurses\ninto nested objects unless depth-limited (the macro pins depth 1). When a\nplanned model calls the macro and the project lacks it, the plan warns and\nnames the scaffold command; scaffold it rather than inlining a copy.
Before the cost gate, and for free, transform build refuses two things and\nnames the fix for each. Neither costs anything to check, so both surface on the\nunconfirmed call rather than after a budget has been agreed.
Config that has drifted from the profile. transform init renders\n.dex/config.yml into the project's profiles.yml, and dbt reads only the\nprofile from then on. If a later config edit never reached it (a retargeted\ndev_database, a different warehouse), the build refuses and names both values\nand both files. Edit one to match the other. The engine never rewrites\nprofiles.yml, which you may legitimately have hand-edited.
A dev target that does not exist. On Snowflake, dbt creates schemas but never\ndatabases, so a missing dev_database is refused with the CREATE DATABASE\nstatement to run; dex will not create it for you, because its only writes are\nreviewable diffs inside the repo. On Postgres, Redshift, and ClickHouse, dbt creates the dev\nnamespace but only if the profile's user may, so the missing privilege is what\ngets refused, with the CREATE SCHEMA/GRANT statement to run. On ClickHouse\nthat check can also come back with no verdict, because a server may not let dex\nread another user's grants; it then warns instead of guessing, and the build\nproceeds with dbt's own error as the backstop. On DuckDB the dev target is a database file,\nand dbt would happily create an empty one, then fail every source() relation\nwith a confusing catalog error. The convention there: copy the shared source\nwarehouse to the dev target path (for example\ncp shared/f1.duckdb <project>/dev.duckdb), or point the dev target at an\nexisting file. Projects without sources just get a warning and an empty\ndatabase, which is fine for model-only builds.
semantic define ... and semantic update ... author and evolve the dbt\nsemantic models (entities, dimensions, measures, metrics) as plans. define\nrefuses names that already exist (use update); update refuses names that\ndo not (use define). For one logical change that mixes both (evolve existing\nmetrics and add the helpers they depend on), use semantic plan ...: it\naccepts mixed intent and classifies each name, and the envelope reports the\nsplit as defined, updated, unchanged, and removed.
Prefer --definitions-file over --edits-file for the semantic layer. A\nreal project keeps its metrics in one shared file, so a whole-file payload\nmeans retyping every definition you are not touching: the diff and the\nupdated list then describe the whole file instead of your change, and every\nrestated line is a chance to corrupt a definition by hand. Send only what\nchanges instead:\n{\"definitions\": [{\"kind\": \"metric\", \"content\": \"name: ...\\n...\"}]}, where\nkind is semantic_model or metric and content is that definition's YAML\nbody with no leading - . The name comes from the content, and path can be\nomitted for anything the project already declares (the engine rewrites it\nwhere it lives). Everything else in the file, comments included, is preserved\nbyte for byte. Reach for --edits-file when you are creating a file, moving a\ndefinition between files, or emptying one, and when the engine refuses a layout\nit will not splice into.
Removing one definition is the same payload with \"op\": \"delete\":\n{\"definitions\": [{\"kind\": \"metric\", \"name\": \"doubled\", \"op\": \"delete\"}]}, the\nname declared (there is no content to read it from) and no content beside it.\nNothing is removed for going unmentioned, so you can send a removal and an\nedit in one payload and everything you did not name stays as it is. Use\nsemantic update or semantic plan, not define. The envelope reports it\nunder removed.
If a metric still reads what you are removing (its input is that metric, or a\nmeasure of the semantic model you are removing), the plan is refused and the\nreader is named: add that reader's own delete or update to the same payload,\nin any order, and it goes through. A removal that would leave a file with no\nsemantic model or metric in it is refused too, because deleting or emptying a\nfile is a whole-file edit: do that with transform plan --edits-file and\n\"op\": \"delete\".
unchanged means you re-stated a definition exactly as the project already\nhas it. It is not an error, but if a plan is entirely unchanged it changes\nnothing, and the envelope warns as much: check whether you meant to edit\nsomething.
Plan-time validation is layered so a plan that validates will build:\nMetricFlow's schemas check the shape; the engine resolves every metric input\n(ratio and derived metrics reference metrics, not measures; a measure only\nbecomes a metric via create_metric: true, and the error names that fix); and\nfinally the emitted YAML is run through dbt's own parser against a\nthrowaway copy of the project. A plan that fails parse is refused, not stored.\nIf dbt is not installed the parse degrades to a warning; --no-parse skips it\nexplicitly.
A semantic plan is applied like any other: transform apply [plan-id] writes\nits YAML into the dbt project (no id applies the latest unapplied plan).
For native Ossie use semantic ossie define|update|plan with\n--edits-file <path|->. Supply whole documents whose paths are listed in\nsemantic.ossie.files; the command implies the semantic_document kind,\nvalidates the complete prospective configured layer, and writes the accepted\nbytes exactly when the plan is later applied. This is a semantic-layer write\nsurface and does not make Ossie the transformation project.
The namespace guards match the dbt ones: define refuses a semantic-model name\nthe layer already has, update refuses one it does not, and plan accepts\nboth and reports each under defined or updated. Neither removes a model, and\na configured file may be absent before define, so a new document is planned\nonce its path is committed to config.
What validates an Ossie plan is not what validates a dbt one, and the\ndifference matters. There is no external parser to gate on: dex checks the\ndocument's structure against the Ossie schema it pins (needs [ossie]), its\ninternal consistency in pure Python, and each SQL expression's syntax through\nthe dialect engine (needs [sql], which every connector extra carries).\nWithout [sql] the third layer degrades to a named skipped-validation note,\nnever to a silent pass. All three run over the complete prospective layer, your\nedits overlaid on the other configured documents, before a plan is stored.
It then checks the references against the exploration cache, opening no\nconnection. A source relation the cached inventory positively lacks, or a\ncolumn absent from a relation the cache profiled, refuses and stores no plan.\nAnything the cache cannot speak to is a named note instead: an unprofiled\nrelation, a computed or non-SQL expression, a quoted identifier, a query-backed\nsource. Read those notes rather than treating them as failures; they say what\nwas not checked.
\nAccepted bytes are written exactly as authored on apply. dex does not parse and\nre-serialize the document, so comments, key order, quoting and whitespace all\nsurvive, and a configured document the payload did not mention is untouched. A\ntarget file that changed after planning refuses the whole apply rather than\nwriting part of it, unless you confirm the overwrite deliberately.
\nreferences/ossie-walkthrough.md in the engine repository runs the whole\nsequence on a local warehouse if you want to see it end to end.
dbt cannot parse semantic models in a project without a MetricFlow time\nspine; the engine warns when one is missing and defers the parse gate until\none exists. Author it like any other model (a day-grain date model plus YAML\nwith a time_spine: config) in the same or a separate plan.
viz preview is not yet implemented (it returns not_implemented); the Viz\nintegration arrives later.
semantic.ossie.files. Neither surface can\nreach the other, an absolute path or a .. escape is refused on both, and dex\nnever writes to source warehouse data.references/cost-controls.md; the PII policy that governs what\na seed may carry and what gets stamped into meta: references/pii-policy.md.meta),\nnever example values. Stamping is presence-based at any confidence; only a\ncolumn cleared by a human pii_overrides entry in .dex/config.yml is\nscaffolded without the meta.