Skip to main content
Product14 min read

211 - Governing the catalog without leaving the portal

Datasets, columns, the glossary, tags, domains, and data products are curated in the portal under the same persona grants that govern the agent, with every change kept in a history you can roll back.

What you will take away from this lesson

206 - Knowledge: from a memory to something the whole team can use named two places a promoted fact can land, and spent its time on one of them: the canonical knowledge page. This lesson is about the other one. The catalog is not only a sink that writes arrive in; it is a set of definitions somebody has to write, keep current, and occasionally retire.

The catalog is part of Plexara and lives in your deployment. Every dataset your connections reach, the glossary, the tags, the domains, and the data products are read and curated in the portal, under the same persona rules that govern the agent, with every change kept in a history you can roll back.

Learning Objectives

  1. 01Say what the catalog holds, where its datasets come from, and why the same table reached through two connections is two datasets.
  2. 02Name the five tabs under Knowledge > Catalog, and say which one holds the described things and which hold the definitions that describe them.
  3. 03List what a dataset’s page shows and edits, including per-column edits, context documents, lineage, and history.
  4. 04Explain how roll back works, and why the catalog refuses an edit made from a value someone else has since changed.
  5. 05Say why a definition still in use cannot be deleted, and what the refusal tells you.
  6. 06Name the grants that decide who reads and who curates, and where every portal edit is recorded.
  7. 07Describe what an administrator sees and sets under Admin > Catalog.

Why this belongs in the portal at all

What the catalog holds

Nobody types tables into the catalog. Plexara scans each connection and records what it finds: the tables and views behind a Trino connection, the operations of an API, the queries and mutations of a GraphQL schema. A table registered over a spreadsheet, or one a webhook source writes, is cataloged when it is registered, before the call that registered it returns.

What people add is the curation: what a dataset is for, what a column means, which business area it belongs to, which glossary term defines it, and the notes too long for a description.

Where datasets come from

SourceDatasetsColumns
A Trino connectionEvery table and view in every catalog the connection readsEach column, in order, with its type and whether it allows nulls
An API connectionEvery operation in the connection’s OpenAPI documentNone; the schema document carries the shape
A GraphQL connectionEvery query and mutation in the stored schemaEach argument, with its type
A registered or webhook tableRecorded at registration, before the call returnsThe columns the registration declares

A dataset belongs to the connection that sees it, so the same table reached through two connections is two datasets. That is what lets persona connection rules apply to the catalog exactly as they apply to queries. A scan never touches curation: a description written last month survives every rescan, and a dataset a scan stops seeing keeps its curation readable until it comes back.

Five tabs: the datasets, then the definitions

Knowledge > Catalog opens on Tables. The other four tabs hold the definitions that describe datasets, and each of them governs the definition itself, not the copy of it one dataset happens to carry. The Tags tab is not a list of the tags on the table you were just looking at; it is the tag vocabulary, with every carrier listed under each tag.

Knowledge > Catalog: five tabs

  • Tables

    Described thing

    Search datasets across every connection your persona reaches, by name, path, or description, optionally on one connection. Open one for its page.

  • Glossary

    Definition

    The terms your organization defines and the nodes that hold them. The top of the tree, or every term and node matching a filter.

  • Tags

    Definition

    The tag vocabulary itself: what each tag means and which datasets and columns carry it.

  • Domains

    Definition

    The business areas datasets are grouped into, each with its description and members.

  • Data products

    Definition

    Named, described groupings of datasets that serve one purpose, such as inventory intelligence or the store network.

Each tab rides in the URL hash and an open entity in the ref parameter, so a catalog reference anywhere in the portal links straight to it. Search spans every connection your persona reaches; the connection filter narrows it to one.

What it looks like

The portal Knowledge page with Catalog selected: Tables, Glossary, Tags, Domains, and Data products tabs above a search box for tables by name, path, or description, an All connections filter, and dataset cards each showing a name, its path, a one-line description, its connection, and tags such as certified, finance, daily, and pii.
Knowledge > Catalog, open on Tables. API operations sit in the same list as tables: the listInvoices card is an operation on a billing API, cataloged beside the warehouse.

A dataset’s page

Everything on a dataset’s page is what the next person reads before they trust the data. With write access, each piece is edited in place. Without it, the same page appears with no editing controls.

A dataset page in Knowledge > Catalog: daily_sales on the acme-warehouse connection with its mcp:dataset reference, a Description card with Edit description, Tags carrying certified and finance, Glossary terms carrying Revenue and Average Ticket, and Owners and Domain cards below.
The top of a dataset's page. Tags and terms are picked by name from the search boxes under each list, and the reference under the title is the one the agent passes to fetch.

A dataset's page

  • The dataset’s own curation

    Description, tags, glossary terms, owners, domain, and properties. Tags are picked from the vocabulary or typed as a new name; terms and domains are picked by name, never by identifier.

  • Columns, each with Edit

    Columns in table order. Edit opens one column for its own description, tags, and glossary terms, with that column’s history on the same editor.

  • Context documents

    Markdown notes with a title and a category, added, edited, and removed in place on the dataset: the reconciliation procedure, the migration history behind a column with two meanings, the reason a metric was redefined.

  • Lineage

    What the dataset was made from and what was made from it, three hops each way, each dataset a link that opens it in place. Lineage connects whole datasets and the files made from them, never individual columns.

  • Schema document

    For an API or GraphQL operation, the OpenAPI document or GraphQL schema it was read from.

  • Knowledge pages that cite it

    The reverse of the citation a page makes. A steward reading a dataset sees what has been written about it without going looking.

  • History

    Every change with who wrote it, when, what it now holds, and what it replaced, each with Roll back.

There is no table create or delete here. A scan finds tables; this page describes them. Nothing on it can drop a dataset.

History and roll back

A catalog that several people and several agents write to needs two guarantees: that any change can be undone, and that nobody’s change is lost to someone else’s. The history panel on every dataset, column, and definition gives the first. The refusal of stale edits gives the second.

The lower half of a dataset page: a context document titled How revenue is counted, a Lineage card with upstream and downstream datasets, and a History list of four changes (a context document, glossary terms written by apply_knowledge from a reviewed insight, and two descriptions), each with who made it, when, the value it replaced, and a Roll back button.
History on a dataset page. Each entry is one aspect written once, with its author and the value it replaced, and each has its own Roll back.

History, roll back, and concurrent edits

  1. 01

    Every write is versioned

    Each aspect (a description, the tag list, the glossary terms, a context document) is written and versioned on its own, with who wrote it, when, and the value it replaced.

  2. 02

    Roll back is a change too

    Rolling back restores the value a change replaced and is recorded in the history as a change of its own, so the record never loses a step.

  3. 03

    A newer write blocks roll back

    If the same aspect has been written since, the roll back is refused and the refusal names the newer write. Rolling back past it would silently discard someone else’s work.

  4. 04

    Stale edits are refused

    Every portal edit carries the value it was made from. If someone changed that value while you were typing, the save is refused with a request to reload, rather than overwriting their change with yours.

Glossary, tags, domains, and data products

The glossary is where the words that cause the most expensive misunderstandings get written down. Active customer, net revenue, fiscal quarter: terms every team uses confidently and no two teams define identically. It is a tree rather than a list, because a real glossary has structure, and it is walked one branch at a time.

Tags, domains, and data products are listed and opened the same way. Each one is an entity with its own description, owners, links, and history.

The four definition tabs

  • Glossary

    A node lists what is filed under it and adds an entry there. A term lists the datasets and columns that carry it.

    A term can sit on a whole dataset or on one column, and the term page shows which. Terms keep their parent node, so the tree reads the same however you arrived.

  • Tags

    What the tag means, and every dataset and column carrying it.

    Tags say something about the thing itself (pii, DimensionTable, external-data), which is why lineage never lends a tag to a downstream column.

  • Domains

    What the business area covers, and the datasets in it.

    A dataset has one domain. Setting a new one replaces the old.

  • Data products

    What the product is for, its owners, and its documentation links.

    A data product is described like any other definition: description, owners, custom properties, links, and history.

Every definition's page edits its description, shows its history with Roll back, lists the knowledge pages that cite it, and offers Delete.

A definition in use cannot be deleted

Retiring a definition is the operation with the widest reach and the least visible consequence. The catalog does not guess at what you meant. A delete of a definition something still uses is refused, and the refusal names what uses it, so the next step is obvious.

What Delete does with a definition in use

  • A tag carried by a dataset or column

    Refused, naming what carries it. Remove it from those first.

  • A glossary term on a dataset or column

    Refused, naming the carriers.

  • A domain a dataset belongs to

    Refused, naming the datasets in it.

  • A glossary node with entries under it

    Refused, naming the entries. Move or delete them first.

  • A definition nothing uses

    Deleted.

Who reads and who curates

None of this introduces a governance model of its own. The portal reads and writes the catalog with the same two tools the agent uses, under the same persona, so the rules covered in 207 decide who sees these tabs and who can change them.

Who reads and who curates

  • Reading

    The persona holds fetch, the same tool the agent reads the catalog with. The persona editor’s Portal access section sets the Catalog area to none, read, or write.

  • Curating

    The persona also holds apply_knowledge, the tool the agent curates with, and its Catalog area is write. Without it, the same pages appear with no editing controls.

  • Connection reach

    A dataset, its columns, and its schema document are shown and written only for a reader whose persona reaches that connection. A definition’s carrier list counts the carriers on other connections instead of naming them.

  • The record

    Every portal edit is audited as an apply_knowledge call with source portal, beside the agent’s own calls. Administrators reach everything.

The checks run on the server, not in the interface. A steward editing a column in the portal and an agent writing the same description through apply_knowledge pass the same checks and land in the same history.

Admin > Catalog: scans and settings

Your administrators see how the catalog is kept current. The Scans tab answers the question a steward asks when a new table is missing: was the connection scanned, when, and did anything stop it.

Admin > Catalog on its Scans tab: a Scan now button above a table of three connections (a Trino warehouse, an API connection, and a GraphQL connection) with each one's kind, last scan time, datasets found, datasets removed, and a Problem column.
Admin > Catalog, Scans. Each connection shows when it was last scanned, how many datasets it holds, and how many the last scan removed.

Admin > Catalog

  • Scans

    Each connection’s last scan: when it finished, how many datasets it wrote and marked removed, and why it failed if it did. A Trino catalog that could not be read is listed as not read, with the reason, and nothing under it is marked removed. Scan now runs one on demand.

  • Settings

    How often connections are scanned (every six hours unless changed, never more often than every five minutes) and exclusions per connection: a catalog, schema, or table prefix for Trino, mutations for GraphQL.

  • Documents

    Every schema document the catalog holds, each downloadable.

One behavior to expect

Where this leads

A catalog is worth governing because of what reads it. Every question an agent answers passes through the descriptions, terms, and context documents on these pages, and every Trino result carries them back as context. Keeping them accurate is not administrative work beside the useful work; it is the input to it.

Key terms

Nine terms cover the vocabulary of catalog governance. Two of them are tool names, fetch and apply_knowledge, and they decide what any given person sees when they open these tabs.

Key Terms

Catalog
Plexara’s record of every dataset your connections reach, their columns, and the glossary, tags, domains, and data products that describe them. It lives in your deployment and is read in Knowledge > Catalog and through fetch.
Dataset
A table or view on a Trino connection, an operation on an API connection, a query or mutation on a GraphQL connection, or a registered or webhook table. It belongs to the connection that sees it.
Scan
The pass that reads a connection and records its datasets and columns. Scans run on a schedule and on demand, mark datasets they no longer see as removed, and never touch curation.
Aspect
One piece of curation on an entity: its description, tags, glossary terms, owners, domain, properties, curated queries, incidents, or context documents. Each is written, versioned, and rolled back on its own.
Context document
A markdown note with a title and a category, attached to a dataset. It holds the explanation too long for a description.
Roll back
Restoring the value a change replaced. It is recorded as a change of its own, and it is refused when the same aspect has been written since.
Data product
A named, described grouping of datasets that serve one purpose, curated like the other definitions.
fetch / apply_knowledge
The two tools that read and curate the catalog, for the agent and for the portal alike. They are ordinary persona grants, checked the same way as every other tool covered in 207.
Reference
The mcp: string that names a catalog entity, such as mcp:dataset:(trino,acme,warehouse.public.transactions). Every picker resolves it from a name, so nobody has to type one.