> ## Documentation Index
> Fetch the complete documentation index at: https://basedash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Transform data and define reusable business logic for every AI workflow

Models are reusable SQL datasets with semantic metadata. Use them to transform raw tables, document dimensions, define measures and segments, and give every Basedash AI a shared understanding of your business.

Describe what you want to model—such as active users, monthly recurring revenue, or retention rate—and Basedash AI can create the SQL, column descriptions, measures, segments, and default time column for you. The resulting model is available across chat, charts, dashboards, insights, automations, and the SQL editor.

## What you can model

Use models anywhere reusable data logic should stay consistent:

* **Transformations**: Clean, join, rename, and reshape raw tables into analysis-ready datasets
* **Measures**: Define aggregate expressions such as revenue, active users, conversion rate, or retention
* **Segments**: Define reusable predicates such as active customers, paid accounts, or completed orders
* **Dimensions**: Document model columns and choose a default time column for time-based analysis
* **Shared business logic**: Give every person and AI workflow the same source of truth

Models are scoped to one data source and use that source's native SQL dialect. They appear as read-only virtual tables in the `models` schema.

## Create a model with AI

1. Open **Models** from the main navigation.
2. Describe the dataset or metric you want to model.
3. Submit the prompt and review the model Basedash creates.
4. Run the SQL to preview its rows, then refine any details, columns, measures, or segments.

For example:

```text theme={"dark"}
Create a customer activity model and define active users as people who completed at least one session in the last 30 days.
```

The AI can inspect your schema, choose the relevant tables and joins, create reusable row-grain SQL, document the output columns, and add the measure and segment expressions needed for future analysis.

You can also create a blank model and write the SQL and metadata manually.

## Model editor

The model editor includes four sections:

* **Details**: Set the model name, SQL reference name, description, data source, and verification status
* **Columns**: Document inferred output columns and select a default date column
* **Measures**: Add named aggregate SQL expressions, such as `SUM(monthly_amount)`
* **Segments**: Add named SQL predicates, such as `status = 'active'`

The SQL editor and data preview make it possible to test the model against real data before using it elsewhere.

### Choose the right grain

Prefer model SQL that returns reusable row-grain data. Put aggregate calculations in measures and reusable filters in segments so the AI can group, filter, and drill into the model for different questions.

For example, a subscriptions model can return one row per subscription while defining:

* A `monthly_recurring_revenue` measure with `SUM(monthly_amount)`
* An `active_subscriptions` segment with `status = 'active'`
* `started_at` as its default time column

Pre-aggregated models are supported when you intentionally need a fixed grain, but they are less flexible for later drill-downs.

## Query a model

Query models with normal SQL using `models.<reference_name>`:

```sql theme={"dark"}
SELECT
  DATE_TRUNC('month', started_at) AS month,
  SUM(monthly_amount) AS monthly_recurring_revenue
FROM models.subscriptions
WHERE status = 'active'
GROUP BY 1
ORDER BY 1;
```

Models can join other models and tables on the same data source:

```sql theme={"dark"}
SELECT
  customers.plan,
  COUNT(DISTINCT activity.user_id) AS active_users
FROM models.customer_activity AS activity
JOIN models.customers AS customers
  ON activity.user_id = customers.id
WHERE activity.occurred_at >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY 1;
```

## How AI uses models

Basedash gives its AI agents the models available for each data source, including their dimensions, measures, segments, default time columns, descriptions, and verification status. The AI can:

* Create or update a complete model from a plain-language request
* Query models when answering questions or building visualizations
* Reuse measure expressions in `SELECT` and segment expressions in `WHERE`
* Prefer verified models when multiple models could answer a question
* Inspect model SQL and metadata before editing or using it

After a model exists, a request such as:

```text theme={"dark"}
Show monthly recurring revenue for active subscriptions by plan.
```

can reuse the model's SQL, measure, and segment instead of reconstructing your business logic from raw tables.

## Verification and version history

Every change to model SQL or semantic metadata creates a new version. Open **History** to review earlier versions and restore one when needed.

Organization admins can mark a model as verified. Verification tells people and AI agents which models are approved, while unverified models remain usable. Changing SQL, columns, measures, segments, or the default time column removes verification until an admin reviews the new version.

## Permissions

Members can view and edit models for data sources they can access. Existing row-level and object-level data access rules also filter the model SQL and semantic metadata they can use. Only organization admins can change verification.

Before changing or deleting a model, review its **Used by** list to see dependent models, charts, variables, and automations.

## Best practices

* Keep model output at the most reusable grain.
* Put aggregates in measures and reusable predicates in segments.
* Use stable reference names because queries address models through them.
* Describe the business meaning of models, columns, measures, and segments.
* Set a default time column when a model supports time-based analysis.
* Verify models that represent approved business logic.
* Keep each model within one data source and its native SQL dialect.