Plexara
What you will take away from this lesson
The last three lessons treated the catalog as a record of tables. It is wider than that. Every API connection and every GraphQL connection is scanned too, and each operation becomes a dataset: searchable, curated, and governed exactly like a warehouse table.
That matters because a growing share of what a company knows lives behind APIs: a weather forecast, a carrier's tracking feed, a CRM, a government statistics service. When those operations sit in the same catalog as the warehouse, one search reaches both, and the agent picks the right source for the question rather than the one it happened to look at first.
Learning Objectives
- 01Say how an API operation and a GraphQL query or mutation become catalog datasets, and what each carries in place of columns.
- 02Read an operation’s catalog record with fetch, and its schema document beside it.
- 03Curate an operation the way you curate a table: a description, tags, a glossary term, and a context document.
- 04Explain why a curated operation turns up in search for a question that never names the API.
Where we are in the curriculum
If any term in this lesson feels unfamiliar, the 100 series is one click back. The 200 series assumes that mental model.
100 Series: the foundation
- 101What is a Large Language Model?Brilliant at language, blind about your data. Tokens, hallucination, the grounding problem.
- 102Tokens and your budgetSubscription-plan economics, session limits, and Plexara enrichment dedup.
- 103Context, compression, and memoryThe keep / compress / clear playbook and how memory carries across sessions.
- 104Frontier models, specialized models, and why enterprise AI uses bothThree knowledge sources (training, web search, tools). MCP as the exposure protocol.
- 105What is an AI agent?The think/call-tool/observe loop. Professor's knowledge, child's literalism.
- 110Is MCP just an API wrapper?MCP as an application layer. Spectrum from thin wrapper to full application server.
If a term in this lesson looks unfamiliar, back up to the 100 series. The 200 series assumes that mental model. Every row above is a direct link.
Operations are datasets
The scan that records a Trino connection’s tables also reads every API and GraphQL connection. An operation does not have rows and columns the way a table does, so it carries a schema document instead, but everything else about it is the same: a reference, a page in the portal, curation, history, and the persona connection rules.
Operations as datasets
API operation
mcp:dataset:(api,<connection>,<operationId>)
No columns. The connection’s OpenAPI document is its schema document.
GraphQL query or mutation
mcp:dataset:(graphql,<connection>,query.<field>)
Each argument is a column, with its type. The stored schema is its schema document.
Each scan records the operations in the connection's current document. An administrator can exclude a GraphQL connection's mutations from the catalog under Admin > Catalog > Settings.
An operation’s catalog record
The ACME demo has a forecast connection, open-meteo-forecast, with one operation: a 16-day daily forecast for any coordinate. Fetching its dataset reference returns the same shape of record a table returns.
An API operation's catalog record
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
fetch {
"reference": "mcp:dataset:(api,open-meteo-forecast,getDailyWeatherForecast)"
}
→ "type": "api_operation",
"schema_document":
"mcp:schema_document:(api,open-meteo-forecast,\"open-meteo-forecast.yaml\")",
"columns": [],
"aspects": {
"description": "Daily weather forecast for one latitude and longitude, up to 16 days
ahead: rain, snow, temperature high and low, and wind. Merchandising
uses it to stage weather-driven stock ... at stores ahead of a front.
warehouse.public.stores holds addresses, not coordinates: resolve a
store's address ... through the census-geocoder connection first. ...",
"tags": ["weather", "external-data"],
"glossary_terms": ["mcp:glossary_term:1fd54d92-464c-48f9-9a40-59bd1a98a2ba"],
"context_documents": [
{ "title": "Calling the forecast for a set of stores",
"category": "usage_guide", ... } ]
}Trimmed from the ACME demo, after the curation shown below. The record names its schema document as a reference, so the full OpenAPI text is one more fetch away.
The schema document
Why curation matters more for an API
Curating an operation
An operation takes every kind of curation a table takes: a description, tags, glossary terms, owners, a domain, properties, curated queries, incidents, and context documents. The agent wrote the forecast operation’s in one call, as a merchandising lead described how the team uses it.
Curating an operation in one apply
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
apply_knowledge {
"action": "apply",
"entity_urn": "mcp:dataset:(api,open-meteo-forecast,getDailyWeatherForecast)",
"changes": [
{ "change_type": "update_description", "detail": "Daily weather forecast ..." },
{ "change_type": "add_tag", "detail": "weather" },
{ "change_type": "add_tag", "detail": "external-data" },
{ "change_type": "add_glossary_term", "detail": "Weather-Driven Demand" },
{ "change_type": "add_context_document",
"target": "Calling the forecast for a set of stores",
"query_description": "usage_guide",
"detail": "## One call per location ..." }
],
"confirm": true
}
→ "changes_applied": 5,
"changeset_id": "6065d0e5aa8a915633a1089265a8a4ad",
"created_ids": [
"mcp:glossary_term:1fd54d92-464c-48f9-9a40-59bd1a98a2ba",
"51374954-25bd-4177-b26d-edc96f14e554" ],
"message": "Changes written to the platform catalog. Roll back with
action=rollback changeset_id=6065d0e5aa8a915633a1089265a8a4ad.",
"revertible": trueTrimmed from the ACME demo. The five changes were written together or not at all. The glossary term did not exist yet, so the apply created it and returned its reference, and the whole changeset rolls back with one call. The same edits are available on the operation's page under Knowledge > Catalog.
Found by meaning
Catalog search ranks datasets by what their text means, and an operation’s text is now the description above. A question asked in the business’s words reaches it.
A merchandising question finds the forecast
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
search {
"intent": "should we move umbrellas and rain gear to stores before a wet weekend",
"sources": ["catalog", "governance"]
}
→ "groups": [
{ "source": "catalog", "hits": [
{ "reference": "mcp:dataset:(api,open-meteo-forecast,getDailyWeatherForecast)",
"text": "getDailyWeatherForecast Daily weather forecast for one latitude
and longitude, up to 16 days ahead ...", "score": 1 },
{ "reference": "mcp:dataset:(trino,acme,warehouse.public.inventory)",
"text": "warehouse.public.inventory Current inventory levels for products
across all store locations ...", "score": 0.96 } ] },
{ "source": "governance", "hits": [
{ "reference": "mcp:glossary_term:1fd54d92-464c-48f9-9a40-59bd1a98a2ba",
"text": "glossary term: Weather-Driven Demand Sales that move with the
weather rather than with price or promotion ...", "score": 1 } ] }
],
"ranking": "hybrid"Trimmed from the ACME demo. The question names no API, no weather service, and no connection. The forecast operation ranks first in the catalog beside the inventory table it would be planned against, and the glossary term that defines the idea comes back from the governance source in the same response.
Where this leads
With the warehouse and the APIs in one catalog, the agent can plan the next step the way the merchandising lead would: read the forecast for the stores in the path of the weather, then check inventory for the products the Weather-Driven Demand term names. Both are governed by the same persona and both are cited by reference.
Key terms
Four terms cover APIs in the catalog.
Key Terms
- API operation dataset
- One operation of an API connection, cataloged as a dataset named by its operation id. It has no columns; its schema document describes its parameters and responses.
- GraphQL operation dataset
- One query or mutation of a GraphQL connection, cataloged as a dataset whose columns are its arguments.
- Schema document
- The OpenAPI document or GraphQL schema an operation was read from, fetched as text and versioned when its content changes.
- Changeset
- The record of one apply_knowledge call: every change it wrote, together, with the id that rolls all of them back.