semlayer

What this server has, what it can see, and what to do next. Call this first. It answers with the loaded layer (its size, age, and how many claims nobody has reviewed yet), the warehouse connections visible from this machine, and a `next` field saying what to do -- including when there is no layer at all, which is the state a fresh install is in.

無需輸入參數。

Which warehouses are reachable from this machine, by name. Reads DuckDB files in the working directory, warehouse environment variables, `$SEMLAYER_HOME/.env`, dbt's profiles.yml and Snowflake's connections.toml. Names only: no credential is read, no value that could be one is reported, and no connection is opened. Each entry says whether semlayer can open it (`supported`) and what it would need if not (`note`). requested: the warehouse the user NAMED, in their words, when it is not in the list -- "databricks", "our iceberg tables in s3", "redshift". The answer says whether semlayer opens it after all (Redshift is the postgres connection), and if not, the nearest route and what to tell them. Pass it rather than guessing: a wrong guess here is either a promise we cannot keep or a user sent away who did not need to be.

Load one of the layers `status` listed under `layers`. ref: the `ref` from that list, the connection it is for, or a path to a layer file. Returns the new status. Use it when several layers are on this machine and the user has said which warehouse they mean -- and after it, tell them which one you loaded.

Build the semantic layer for a warehouse. Ask the user first. This READS THEIR WAREHOUSE -- metadata and sample values -- under the connection given, and on a real warehouse it takes minutes and uses their own LLM key, which costs them money. Ask before calling it, and say which warehouse you are about to model. connection: a uri from `status.connections`, or one the user gave. Omit it to use the session's. question: what the user actually asked. Keep it here: when the layer is ready, `status` reminds you to answer it, so a run that outlives this turn does not lose the point of itself. scope: schema names, comma-separated, to model only those. The way to make a big warehouse finish quickly. wait_seconds: how long to hold this call open (capped at 60). A DuckDB file finishes inside it and comes back `ready`, so you can answer in the same turn. Anything larger comes back `inferring`. use_llm: false for a statistics-only layer -- no descriptions, no decode validation, no cost, and much faster. While this call is open it streams progress notifications, so a client that renders them shows a bar. Nothing will wake you AFTER it returns. Tell the user that, and call `status` when they next speak.

Stop the inference that is running. Takes effect at the next stage.

無需輸入參數。

START EVERY QUESTION HERE once a layer is loaded. Returns the part of the layer that bears on this question -- the tables it selected, their columns, keys, required filters and metrics, the routing knowledge for choosing between them -- plus `open_questions`: the claims underneath that nobody has confirmed. Write your SQL from this, `check_sql` it, then `run_sql`. Put the open questions under your answer as assumptions.

Run ONE read-only SELECT against the session's warehouse. `check_sql` runs first and an error means the SQL is NOT executed -- a query that sums cancelled orders runs perfectly well, so "it ran" was never the standard. Warnings do not block, and come back with the rows because they are about whether the number means what the user thinks. Rows are capped and there is a ten-minute time limit; the cap, the limit and whether rows were truncated are all stated in the result, so you can tell the user what actually applied. Nothing is written, nothing is persisted, and your SQL is never rewritten: a required filter is reported, never silently applied. Refused while an inference is running -- one connection is not shared between the two. Ask again when `status` says `ready`. The result carries `assumptions` -- the unconfirmed claims the answer rests on. Answer the user in words first, then render those under it.

What is uncertain in this layer, as questions you can answer. Pull this when the user asks what is unreviewed or unreliable. Do NOT walk the user through it after inference: the questions that matter are the ones an answer rested on, and `run_sql` hands you those as `assumptions`. tables: comma-separated, to scope it to what you are looking at.

One question in full: every object it covers, and the evidence.

Record a verdict. Takes effect immediately, and says who decided. verdict: `accept`, `reject`, or `set:<value>` -- `review_question` gives the shape `set` takes. decided_by: `agent` if this is YOUR call, `person` if the user said it. Never guess this. You may accept a claim whose accept changes no behaviour; rejecting, setting, and accepting anything that unlocks behaviour are the person's, and you will be told which this is. by: the name to record. For a person, what they told you -- ask once if you do not know, never invent it, and never use your own client's name. For yourself, something recognisable like `claude-code/opus`. exclude: comma-separated object locations the verdict should skip. note: your reasoning, kept on the question whether or not the verdict was recorded. This is how you PROPOSE one you may not decide. If the layer is a set (a hub with members) this is refused and tells the user which terminal command records it, so do not promise them it is kept until you have the result.

Every verdict in this layer and who stands behind each one. Read `signal`: `agent` means nobody has confirmed it. Say so when an answer rests on one.

無需輸入參數。

Write the layer into the user's project so their team has it. The cache is per-machine; a file in the repository is what a colleague reads. From then on this session's verdicts land there. Ask where they want it rather than choosing for them. Refused on a set: a hub and its members are several files the user already chose the paths for, and one file cannot hold them.

Write a snapshot of the layer in another tool's format. target: `dbt` today. On request only, and lossy -- the result says what the format could not carry. Nothing keeps it in step with the layer afterwards and you must keep answering from the layer, never from the export.

Search tables, columns, and metrics by keywords. The starting point.

List warehouse domains (table groupings) for navigation.

無需輸入參數。

List table summaries, optionally within a domain.

Full detail for one table: columns, keys, relationships, REQUIRED FILTERS.

List defined metrics (name, measure, aggregation, filter).

無需輸入參數。

Which tables to use (and avoid) for an analytical intent.

Lint SQL you wrote against the semantic layer BEFORE running it. Deterministic checks: unknown tables/columns, correlated references, deprecated tables, missing required filters, fan-out aggregates, SCD2 joins without a validity window. Fix every error and warning (each finding carries a fix hint), then re-check.

Compile a metric to correct SQL (joins, filters, time bucketing). group_by: comma-separated columns. On refusal the response lists legal alternatives — retry with those or ask the user; do NOT hand-assemble SQL for a refused request. scd: "current" or "asof", required when the join path crosses a history table. These are different questions — a customer's segment now, or their segment when they ordered — so ask the user which they meant rather than guessing.