create_model
Create a reusable semantic model from a database table or SQL query, defining columns and measures so AI agents can query data by intent.
Instructions
Create a new semantic model, either from a database table or from a query.
Host a column/measure on the model whose row grain is 1:1 with what
it describes — not merely one where its input columns live. Choose
join keys by column Description (author intent); on ties take the
shortest declared join path (long chains through lookup/log tables
fan out rows). Encode definitions in dependency order, referencing
already-defined entities by name rather than re-deriving them inline;
in row-level SQL parenthesise weighted sums in comparisons
((a*w1 + b*w2) > t).
From a table or sql query (provide sql_table or sql): create_model(name="orders", sql_table="public.orders", data_source="mydb", columns=[...], measures=[...])
From a query (provide query): create_model(name="monthly_summary", query={"source_model": "orders", "measures": ["count(*)", "sum(amount)"], "time_dimensions": [{"dimension": "created_at", "granularity": "month"}]}) Columns are auto-introspected from the query result.
Args:
name: Unique model name (lowercase, underscores).
sql_table: Database table name, e.g. "public.orders".
sql: Alternative to sql_table — a custom SQL expression for the model's source.
data_source: Name of the datasource (from list_datasources).
description: What this model represents.
columns: List of column definitions. Each: {"name": "col", "sql": "col", "type": "string"}.
Types: string, number, time, date, boolean. Optional fields: primary_key,
unique (single-column uniqueness that is not the PK; primary_key
already implies it), allowed_aggregations (whitelist), filter
(CASE WHEN inside aggregation), label, description, hidden,
meta.
measures: List of named formula definitions on the model. Each:
{"name": "aov", "formula": "sum(revenue) / count(*)", "label": "...",
"description": "...", "meta": {...}}.
Queries can reference these by bare name (e.g. {"formula": "aov"}).
meta is an optional opaque dict for caller bookkeeping
(e.g. linking the formula back to a source identifier).
query: A SLayer query dict (or list of stage dicts for a multi-stage backing
query). When provided, the query is saved as the model's source_queries
and the model becomes query-backed. Mutually exclusive with sql_table, sql,
columns, and measures.
variables: Default values for {var} placeholders in the backing query.
Saved as query_variables on the model. Only meaningful when query
is provided.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | No | ||
| name | Yes | ||
| query | No | ||
| columns | No | ||
| measures | No | ||
| sql_table | No | ||
| variables | No | ||
| data_source | No | ||
| description | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |