From c126c8ae908b7769217a817f7034cdb29235d3dc Mon Sep 17 00:00:00 2001 From: kay-kim Date: Fri, 3 Jul 2026 16:21:57 -0400 Subject: [PATCH] edu-34: add ontology docs --- .../content/architecture-patterns/_index.md | 1 + .../content/architecture-patterns/ontology.md | 88 +++++++++++++++++++ .../content/integrations/mcp-server/_index.md | 3 + .../integrations/mcp-server/mcp-agent.md | 23 +++-- .../integrations/mcp-server/mcp-developer.md | 7 ++ 5 files changed, 114 insertions(+), 8 deletions(-) create mode 100644 doc/user/content/architecture-patterns/ontology.md diff --git a/doc/user/content/architecture-patterns/_index.md b/doc/user/content/architecture-patterns/_index.md index 7f6ff16248b35..d35eef973c476 100644 --- a/doc/user/content/architecture-patterns/_index.md +++ b/doc/user/content/architecture-patterns/_index.md @@ -12,3 +12,4 @@ menu: Pattern | Description --------|------------ [Live Context Graph](/architecture-patterns/live-context-graph/) | Model your business as a compounding ontology of live data products and build apps, services, and AI agents on top of it. +[Use an ontology table](/architecture-patterns/ontology/) | Create an ontology table of join relationships that agents query before writing multi-table SQL. diff --git a/doc/user/content/architecture-patterns/ontology.md b/doc/user/content/architecture-patterns/ontology.md new file mode 100644 index 0000000000000..a6c9a5a83de00 --- /dev/null +++ b/doc/user/content/architecture-patterns/ontology.md @@ -0,0 +1,88 @@ +--- +title: "Use an ontology table" +description: "Create an ontology table that helps agents write correct joins." +menu: + main: + parent: architecture-patterns + weight: 10 +--- + +The ontology table is a curated catalog of join relationships between tables in +your database. Each row describes a single join: the columns in one table that +reference columns in another. + +Through the Materialize [MCP server](/integrations/mcp-server/)'s `query` tool, +an agent can query the ontology table before writing multi-table SQL. + +{{< note >}} +This pattern relies on the MCP server's `query` tool, which is enabled by +default starting in v26.27 for the agent MCP server and v26.30 for the developer +MCP server. +{{}} + +```sql +CREATE TABLE ontology ( + table_name text NOT NULL, + columns text[] NOT NULL, + referenced_table text NOT NULL, + referenced_columns text[] NOT NULL +); + +COMMENT ON TABLE ontology IS +'Defines the join relationships between tables in the database. Each row +describes a single join: the columns in table_name that reference +referenced_columns in referenced_table. ALWAYS query this table before +writing any multi-table query. Use it to confirm exact join keys rather +than guessing column names. Filter by table_name OR referenced_table to +find all relationships involving a given table.'; + +COMMENT ON COLUMN ontology.table_name IS +'The dependent table, the one that holds the foreign key.'; +COMMENT ON COLUMN ontology.columns IS +'The FK columns in table_name, in order. Pair positionally with referenced_columns.'; +COMMENT ON COLUMN ontology.referenced_table IS +'The parent table, the one being pointed to.'; +COMMENT ON COLUMN ontology.referenced_columns IS +'The PK or unique columns in referenced_table, in order matching columns.'; + +CREATE DEFAULT INDEX ON ontology; +``` + +## Agent system prompt + +Add the following to the agent's system prompt to enforce the intended behavior: + +```text +Before writing or executing any joins, query the ontology table for the involved table names. Use the returned join keys verbatim. +``` + +## Example: e-commerce schema + +Given the following tables and join-relevant columns: + +| Table | Key columns | +| --- | --- | +| `customers` | `id`, `email` | +| `addresses` | `id`, `customer_id` | +| `orders` | `id`, `customer_id`, `shipping_address_id` | +| `order_items` | `id`, `order_id`, `product_id` | +| `products` | `id`, `category_id` | +| `categories` | `id` | +| `support_tickets` | `id`, `customer_email` *(implicit join, no FK)* | + +The ontology table is populated as: + +```sql +INSERT INTO ontology (table_name, columns, referenced_table, referenced_columns) VALUES +('addresses', ARRAY['customer_id'], 'customers', ARRAY['id']), +('orders', ARRAY['customer_id'], 'customers', ARRAY['id']), +('orders', ARRAY['shipping_address_id'], 'addresses', ARRAY['id']), +('order_items', ARRAY['order_id'], 'orders', ARRAY['id']), +('order_items', ARRAY['product_id'], 'products', ARRAY['id']), +('products', ARRAY['category_id'], 'categories', ARRAY['id']), +('support_tickets', ARRAY['customer_email'], 'customers', ARRAY['email']); +``` + +Tables with multiple relationships, like `orders`, contribute one row per +relationship. Implicit joins, such as `support_tickets` → `customers`, are +documented exactly like the declared foreign-key relationships. diff --git a/doc/user/content/integrations/mcp-server/_index.md b/doc/user/content/integrations/mcp-server/_index.md index 72d12049f8aa1..ec8341db24328 100644 --- a/doc/user/content/integrations/mcp-server/_index.md +++ b/doc/user/content/integrations/mcp-server/_index.md @@ -31,6 +31,9 @@ and support the MCP `initialize`, `tools/list`, and `tools/call` methods. ## See also +- [Use an ontology table](/architecture-patterns/ontology/) to curate join + relationships that agents query through the `query` tool before writing + multi-table SQL. - [MCP Server Troubleshooting](/integrations/mcp-server/mcp-server-troubleshooting/) - [Appendix: MCP Server (Python)](/integrations/mcp-server/llm) for locally-run, diff --git a/doc/user/content/integrations/mcp-server/mcp-agent.md b/doc/user/content/integrations/mcp-server/mcp-agent.md index 0023c22e41b65..b0bdf74f7cd54 100644 --- a/doc/user/content/integrations/mcp-server/mcp-agent.md +++ b/doc/user/content/integrations/mcp-server/mcp-agent.md @@ -781,14 +781,6 @@ curl -X POST /api/mcp/agent \ ## Start querying -Once connected to the MCP server, you can query your curated data products using -either natural language or SQL: - -- *Via `materialize-agent`: What data products can I query?* -- *SELECT * FROM mcp_product_performance LIMIT 5;* -- *What's the `total_revenue` for product 42?* -- *Perform a Pareto analysis on my products.* - {{< warning >}} By default, the [`query` tool](/integrations/mcp-server/mcp-agent-tools/#query) @@ -803,9 +795,24 @@ configuration](/integrations/mcp-server/mcp-agent-config/). {{< /warning >}} +{{< tip >}} +Because the `query` tool can join across objects, consider maintaining an +[ontology table](/architecture-patterns/ontology/): a curated catalog of the +join relationships in your schema that the agent can query to confirm exact join +keys before writing multi-table SQL. +{{< /tip >}} + +Once connected to the MCP server, you can query your curated data products using +either natural language or SQL: + +- *Via `materialize-agent`: What data products can I query?* +- *SELECT * FROM mcp_product_performance LIMIT 5;* +- *What's the `total_revenue` for product 42?* +- *Perform a Pareto analysis on my products.* ## Related pages +- [Use an ontology table](/architecture-patterns/ontology/) - [`materialize-agent` MCP Server available tools](/integrations/mcp-server/mcp-agent-tools/) - [`materialize-agent` MCP Server diff --git a/doc/user/content/integrations/mcp-server/mcp-developer.md b/doc/user/content/integrations/mcp-server/mcp-developer.md index 14bb473f6d4ad..49ceea96ef0af 100644 --- a/doc/user/content/integrations/mcp-server/mcp-developer.md +++ b/doc/user/content/integrations/mcp-server/mcp-developer.md @@ -468,6 +468,12 @@ curl -X POST /api/mcp/developer \ ## Start asking questions +{{< tip >}} +When the agent reads your user objects with the `query` tool, an [ontology +table](/architecture-patterns/ontology/) of curated join relationships in your +schema helps it confirm exact join keys before writing multi-table SQL. +{{< /tip >}} + Once connected to the MCP server, you can ask natural language questions like: | Question | What the agent does | Tool | @@ -500,6 +506,7 @@ The privileges required to use the `materialize-developer` MCP server are: ## Related pages +- [Use an ontology table](/architecture-patterns/ontology/) - [`materialize-developer` MCP Server available tools](/integrations/mcp-server/mcp-developer-tools/) - [`materialize-developer` MCP Server