Skip to main content
Every workspace has a Data Model page. It decides two things:
  • What data the agent can access: which tables and columns of your connection it may query.
  • What that data means: table and column descriptions, and which columns hold values worth filtering by.
A well-configured data model is the difference between an agent that writes plausible SQL and one that writes the right SQL for your business. Every other kind of context (System Prompts, Skills, Knowledge Base, Golden Assets, User Memory) builds on top of it.
A workspace's Data Model page: tables on the left, column list with descriptions and Selectable toggles on the right, and a Test RLS as user picker
You don’t create a data model on its own — it comes with the workspace. Create a workspace on a connection and Upsolve fetches every table and column from it automatically. A workspace is its data model: there is one schema and one agent in each workspace, versioned and shipped together.
The Builder Agent can do most of this for you: ask it to “describe my tables” and it reads your schema and real values, then writes the descriptions for you to review.
The Data Model page also has the workspace’s security rules: who can see which rows. Those are covered in Data Governance.

​
Select tables and columns

Not every table in your database is relevant to every question your agent will answer. Narrowing the schema to what matters reduces ambiguity, improves accuracy, and keeps the agent away from data it shouldn’t touch.
A workspace Data Model page: the table list on the left, and the selected table's columns with their descriptions and Selectable toggles
  1. Open the workspace’s Data Model page, on the Tables tab. Every table from the connection is listed and selected by default.
  2. Uncheck the tables that aren’t relevant to what you’re building.
  3. Expand a table and uncheck any columns that are unnecessary, sensitive, or likely to confuse the agent.
The agent can only query what’s checked: a query naming any other table or column is refused. See Data Governance.
Less is more. An agent scoped to 5 relevant tables with clear descriptions will significantly outperform one with access to 50 tables it has to guess about.

​
Describe tables and columns

Descriptions are how you encode institutional knowledge directly into the schema. The agent reads them when it writes SQL: they tell it what your data actually means, not just what it’s called.
The purchase_orders columns with plain-English descriptions, such as what category_id refers to and how delivery_date relates to order_date
Table descriptions give context for the whole table: what it represents, how it’s populated, any important caveats. Click into a table and use the Table Description field at the top of the column panel. Column descriptions sit next to each column. A useful one answers the question a developer would have on first seeing the column: what does this value represent, in what units, and is there anything non-obvious about how it’s calculated? For example:
  • contact_name → “Name of the customer’s point of contact for this order”
  • owner_name → “Name of the sales rep (seller) who owns this account”
  • arr → “Annual Recurring Revenue in USD, calculated as MRR × 12. Excludes one-time fees.”
The more specific your descriptions, the more reliably the agent applies the right column to the right question.

​
Mark columns as selectable

The Selectable toggle lets the agent look up a column’s distinct values when it answers.
Column rows with their types, descriptions and Selectable toggles
The agent then uses those values in two ways:
  • Filtering on real values. It knows that region contains “North America”, “EMEA” and “APAC” before it writes a WHERE clause, so it filters on real values rather than guessing at spellings.
  • Matching loose references. It can search a column’s values to find the exact entry a user referred to loosely, matching “acme” to the customer_name value “Acme Corp (US)”.
Turn it on for columns with categorical values people naturally filter by (region, product, owner, status), where the distinct values are finite and meaningful. Leave it off for high-cardinality columns (IDs, free text, timestamps) where the values would be noise.

​
Beyond the schema

Descriptions cover what your data means. Context that isn’t about any one column (business policies, company background, definitions of terms people use loosely, known caveats about the data) belongs in the Knowledge Base. See Encode Your Context for where each kind of knowledge goes.

​
Save a version

Changes to the data model autosave to the workspace’s draft; there is no separate save step. Your users keep getting the version in production until you save a new version and promote it, which ships the schema together with the rest of the agent’s context. See Workspaces.

​
When your database changes

If your database schema changes:
  1. Open the workspace’s Settings and go to the Connection tab.
  2. Refresh the connection’s schema.
  3. New tables and columns appear in the Data Model, ready to select. Tables and columns that disappeared show warnings.
If the version in production refers to something that no longer exists, a warning banner appears. This usually means a table was dropped, a column was renamed or removed, or the connection’s credentials changed.

​
Next steps

Data Governance

Control which rows each user can see, and how much data reaches the AI.

Encode Your Context

Layer prompts, skills and knowledge on top of the schema.

Knowledge Base

Reference documents the agent searches to interpret your terms.

Builder Agent

Have the Builder agent write your descriptions.