Skip to main content

​
What is a Data Model?

A Data Model is a curated view of your database that:
  • Selects which tables and columns are available
  • Describes fields with human-readable annotations
  • Secures data with row-level security rules
  • Versions changes so you can track and rollback
Data model showing selected tables and columns

​
Why Use Data Models?

  1. Simplify for AI - Only expose relevant tables so AI agents aren’t overwhelmed
  2. Add context - Descriptions help AI understand what columns mean
  3. Control access - Data Security rules ensure users see only their data
  4. Safe deployments - Versioning prevents breaking changes

​
Creating a Data Model

  1. Navigate to your project’s Data Models tab
  2. Click Create Data Model
  3. Select the connection to base it on
  4. Enter a name for your data model
  5. Click Create
The system will fetch all tables and columns from your connection automatically.
Create data model dialog

​
Configuring Your Data Model

​
Selecting Tables and Columns

By default, all tables are selected. To customize:
  1. Open your data model
  2. Uncheck tables you want to hide
  3. Expand tables to uncheck specific columns
  4. Click Save Changes
Table and column selection interface

​
Adding Descriptions

Help AI and users understand your data:
  1. Click the edit icon next to a table or column
  2. Enter a description
  3. For AI agents, mark columns as “selectable” if they contain categorical values users might filter by
Adding description to a column

​
Data Security

Data Security controls which rows of data each user can access. You can define Global Security Rules that apply across all tables, or configure per-table rules for specific needs.

​
Understanding Data Security

The Data Security system uses SQL-based filtering with dynamic variables:
  • {{user.*}} - Access properties of the currently authenticated user
  • {{organization.*}} - Access properties of the user’s organization
For example, to filter an orders table so users only see their own orders: 
SELECT *
FROM "orders"
WHERE "user_id" = '{{user.id}}'

​
Global Security Rules

Global Security Rules let you define filtering logic once and apply it to all applicable tables automatically. This is ideal when you have consistent patterns like:
  • Multi-tenant data separated by tenant_id
  • User-owned data filtered by user_id
  • Schema-based isolation (each tenant has their own database schema)

​
Accessing Global Rules

  1. Open your data model
  2. Click the Data Security tab in the left sidebar
  3. You’ll see the Global Rules editor
Data Security tab in sidebar showing global rules

​
Rule Types

Schema Rules - Dynamic schema prefixing for multi-tenant databases where each tenant has their own schema:
Schema rule configuration form
This generates SQL like: 
SELECT *
FROM "{{user.schema}}"."orders"
Column Rules - Automatic WHERE clause filtering based on column names:
Column rule configuration form
This generates SQL like: 
SELECT *
FROM "orders"
WHERE "user_id" = '{{user.id}}'

​
Creating a Global Rule

  1. Click the Data Security tab in the sidebar
  2. Click Add Rule
  3. Choose Schema Rule or Column Rule
  4. Configure the rule settings
  5. The rule is automatically enabled
Add rule dialog with rule type options

​
How Rules Are Applied

  • Schema rules affect all tables - they change where data is fetched from
  • Column rules only affect tables that have the specified column - tables without the column are unaffected
  • Multiple rules are combined with AND logic
  • Rules are applied in priority order (lower priority number = applied first)
Preview showing which tables are affected by rules

​
Per-Table Data Security

When you select a table and go to its Data Security tab, you’ll see how the global rules apply to that specific table.
Per-table Data Security showing global rules are active

​
Manual Overrides (Break Glass)

Sometimes you need custom logic for a specific table. You can override global rules:
  1. Select the table
  2. Go to the Data Security tab
  3. Click Edit manually
  4. Confirm the warning dialog
  5. Edit the SQL directly
Warning dialog when switching to manual edit mode
Once in manual mode, you have full control over the SQL:
Per-table Data Security in manual override mode

​
Resetting to Global Rules

To return a table to global rule management:
  1. Click Reset to global
  2. Confirm the dialog
  3. Your manual edits will be replaced with the auto-generated SQL
Confirmation dialog for resetting to global rules

​
Testing Data Security

You can test your security rules to see exactly what data a specific user would see:
  1. Select a table
  2. Go to the Data Security tab
  3. Select a user from the top-right user dropdown
  4. Click Test Query
  5. View the filtered results
RLS testing showing filtered results for a user
Testing uses your actual database connection and shows real data filtered by the security rules. This helps verify your configuration before deploying.

​
Versioning

Every change to a data model creates a new version. This means:
  • You can see the history of changes
  • You can compare versions
  • Agents and applications link to specific versions

​
Viewing Versions

  1. Open your data model
  2. Click the Versions tab in the sidebar
  3. See all versions with timestamps and change information
Data model versions list

​
Production Status

Before agents and applications can use a data model in production, you must mark a version as “Production.”

​
Setting Production

  1. Open your data model
  2. Go to the Versions tab
  3. Click Set as Production on the version you want
  4. The system validates the schema against your connection
  5. If successful, the version is now production
Set version as production button

​
Validation

When setting production, the system checks:
  • All tables in your data model exist in the connection
  • All columns in your data model exist in their tables
  • If validation fails, you’ll see which tables/columns are missing
If your database schema changes, you may need to update your data model to match.

​
Syncing with Connection Changes

If your database schema changes:
  1. Open your data model
  2. Go to the Connection tab
  3. Click Refresh Schema
  4. New tables/columns will appear (you can select them)
  5. Missing tables/columns will show warnings
Sync with connection showing new and missing items

​
Data Model Errors

If a production data model has errors (e.g., missing tables), you’ll see a warning banner. This typically happens when:
  • A table was dropped from the database
  • A column was renamed or removed
  • The connection credentials changed

​
Next Steps