Skip to main content
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:
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>:
Models can join other models and tables on the same data source:

​
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:
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.