Skip to main content

Configuring metadata tables

Most databases have a catalogue of tables that describe the database itself: data dictionaries, UDF configuration, column descriptions, lookup definitions. Common examples:

  • Oracle: ALL_TABLES, ALL_TAB_COLUMNS, plus any application-level dictionary tables your team or vendor maintains.
  • SQL Server: INFORMATION_SCHEMA.COLUMNS, sys.columns, plus any application-level metadata tables your team maintains.

DataStar surfaces the tables you add to the metadata tables list to the AI agent — their names are included in the workspace info the agent reads at the start of a conversation (get_workspace_info), so it knows which dictionary tables are worth querying through execute_sql.

Why configure them​

With a metadata table list in place, an agent can answer questions like:

  • "What user-defined columns exist on the ACCOUNT table?"
  • "Which tables reference a specific party code?"
  • "How many columns have no description?"

Without configuring any, the MCP still works — the agent can inspect physical schema by running read-only execute_sql queries against INFORMATION_SCHEMA, sys.*, or the Oracle data dictionary. Listing your application-level dictionary tables just means the agent is told about them up front, instead of having to discover or guess them.

How to configure​

  1. Open the workspace you want to configure for.
  2. Workspace → Workspace Settings (or the cog icon on the workspace in the sidebar).
  3. Select the MCP tab.
  4. Click Add table and enter a table name. You can enter:
    • Just the table name, e.g. UDF_CONFIG
    • Or schema-qualified, e.g. APP.UDF_CONFIG
  5. Repeat for each metadata table you want to expose.
  6. Save.

Workspace Settings, Metadata Tables tab

  1. Tab bar: select the Metadata Tables tab.
  2. Description: explains what metadata tables are and how the AI agent uses them.
  3. Table list: the tables exposed to MCP; Add and Delete buttons on the right.
  4. Action buttons: Reset, Cancel, or Save.

The settings are per-workspace, stored in the workspace's user settings file. Your teammates won't inherit them automatically; share the list as part of your onboarding.

What the agent can then do​

Once a table is in the list, its name is surfaced to the agent in get_workspace_info. The agent then reads it with execute_sql in read mode — an ordinary, validated SELECT:

SELECT column_name, description FROM UDF_CONFIG WHERE table_name = 'ACCOUNTS'

Because read mode accepts any single SELECT, the agent can filter, join, project, count, and search across these tables however it needs — there's no separate query DSL to learn.

  • ALL_TABLES
  • ALL_TAB_COLUMNS
  • ALL_CONSTRAINTS
  • ALL_TAB_COMMENTS
  • ALL_COL_COMMENTS

Safety​

  • The agent reaches these tables through execute_sql in read mode, which validates the SQL up front and rejects any write (INSERT/UPDATE/DELETE/DDL/multi-statement) before it reaches the database.
  • The list is a discovery hint, not a security boundary. Read mode can SELECT from any object the connection's database user can see — so restrict what the agent can read by restricting that user's grants, not by trimming the metadata list.
  • Nothing is cached; every call runs against the live database, so data is fresh.

Troubleshooting​

The agent doesn't know a dictionary table exists. It's told about the tables you list here (via get_workspace_info). Add the table in Workspace Settings → MCP so the agent is pointed at it — or just name it directly in your prompt.

An agent keeps using the wrong schema prefix. Ask it to resolve the effective schema first with execute_sql in read mode — e.g. SELECT SYS_CONTEXT('USERENV','CURRENT_SCHEMA') FROM DUAL on Oracle, or SELECT SCHEMA_NAME() on SQL Server — and build names from that.

See also​

Last updated on