Data and semantics

What the layer covers

Every agentic system eventually asks a question that only data can answer. How many accounts churned last quarter. Which orders are still unshipped. What the current price is. What a customer already told support. The quality of that answer is decided long before a model sees a prompt, and it is decided by this layer.

Data and semantics is the foundation of the open agentic platform because it holds the facts an agent works from. It has two halves that people often collapse into one. The data half is mechanical: bytes, files, columns, tables, snapshots, permissions. The semantic half is human: what a column is called, what it counts, which definition of revenue applies, and which of four tables named something like customer is the one the finance team actually trusts.

A system can be excellent at the first half and useless at the second. Storing a petabyte in open formats does not tell an agent that rev_net_adj excludes returns processed after the close date. Meaning has to be written down somewhere, in a form both people and software can read, or every consumer of the data reinvents it from context clues.

Why it comes first

There is a practical reason this layer sits at the bottom of the stack rather than off to the side. The three layers above it all inherit its constraints.

Models inherit them because retrieval quality bounds answer quality. A well-chosen model reasoning over a stale, ambiguous table produces confident errors. Harnesses inherit them because an agent that cannot check a fact has to guess, and guessing is where autonomy turns expensive. Standards inherit them because portability of an agent is worth very little if the data it depends on cannot move with it.

There is also a sequencing argument. Model choices change every few months. Harness choices change every year or so. Storage and table decisions tend to last five to ten years, because migrating them means rewriting pipelines, retraining teams, and re-validating every downstream report. Putting the longest-lived decision at the bottom and the shortest-lived at the top is simply good architecture. It means the parts that churn can churn without disturbing the parts that should not.

The five jobs of this layer

It helps to separate the layer into jobs rather than products. Products change. The jobs do not.

1. Represent records in memory

When a query engine, a Python process, and a Java service all need the same batch of rows, something has to define what those rows look like in RAM. Historically each system had its own answer, so every hop between systems paid a serialization cost. A shared in-memory format removes that cost and lets processes hand data to each other without translating it first. This is Apache Arrow's job.

2. Store records durably

Memory is temporary. Data has to land in files that compress well, skip cleanly, and survive being read years later by software that does not exist yet. Columnar file formats do this by grouping values of the same column together, which compresses better and lets readers skip whole chunks that cannot match a filter. This is Apache Parquet's job.

3. Make a pile of files behave like a table

Files alone are not a table. A table has a schema that can change without rewriting history, a notion of what the current state is, atomic commits so readers never see half of a write, and a record of what it looked like last Tuesday. Table formats add that behavior on top of files in object storage. This is Apache Iceberg's job.

4. Decide who may read and write what

Once tables exist, something has to list them, resolve names to locations, and enforce who can touch them. That component is the catalog, and it is the single most important control point in the layer. It is also the place where agent access is most cleanly governed. This is what Apache Polaris and other catalog implementations do.

5. Record what the data means

Finally, someone has to say that this table is the authoritative order table, that this metric is defined this way, that these two columns are the join keys, and that this dataset is not safe for customer-facing answers. Semantic metadata is the least standardized of the five jobs and the one that most directly determines whether an agent is useful. Apache Ossie is one effort in this space, and semantic layers built into query engines are another.

How the formats divide the work

People new to this stack often ask why there are three formats where one might do. The answer is that they operate at different lifetimes and different distances from the CPU.

The layering is deliberate. An Iceberg table points at Parquet files. A query engine reads those Parquet files and decodes them into Arrow batches. An agent tool then receives Arrow batches or a small result set derived from them. Each format is replaceable in principle, which is exactly the property the openness test looks for, and each is boring in the good sense: widely implemented, specified in public, and not owned by the vendor selling you a query engine.

The catalog as control point

If you only get one thing right in this layer, make it the catalog. The catalog is where table names resolve, where permissions are enforced, and where credentials are handed out. That makes it the natural boundary for agent access.

Consider the alternative. If every agent tool holds its own storage credentials, then every tool is a separate security perimeter, revocation means chasing configuration files, and no one can answer the question of what an agent actually read. If instead every tool goes through a catalog that authenticates the caller and vends short-lived, scoped credentials, then access is centrally visible, centrally revocable, and centrally auditable.

This matters more for agents than for people. A human analyst reads a handful of tables a day and remembers doing it. An agent can touch hundreds of objects in a minute, at three in the morning, on behalf of a request that no one is watching. Central credential handling is the difference between an incident you can reconstruct and one you cannot.

The catalog is also where a shared protocol pays off. The Iceberg REST catalog specification means an engine, a notebook, and an agent tool can all speak to the same catalog without vendor-specific clients. That is the interoperability property applied to governance rather than to storage.

Semantics, the part that gets skipped

Teams reliably invest in storage and reliably underinvest in meaning, then wonder why their agents produce answers that are technically derived from real data and still wrong.

The failure is easy to describe. An agent is asked for last month's revenue. It finds four tables whose names contain the word revenue. It picks one, because it has to pick one. The table it picked is a staging table refreshed hourly and not reconciled against returns. The number it reports is close enough to look right and wrong enough to matter. No component in the system did anything incorrect. The system simply never recorded which table was authoritative.

A semantic layer fixes this by making meaning a first-class artifact rather than tribal knowledge. In practical terms it records things like:

• Canonical entities. There is one definition of customer, and these tables are its physical expression.
• Metric definitions. Net revenue means gross minus returns minus discounts, computed on the close-date basis.
• Relationships. Orders join to customers on this key, and the relationship is many to one.
• Trust level. This dataset is certified for external reporting; this other one is exploratory.
• Freshness and grain. This table is daily, refreshed by 6am, and one row means one order line.

Humans work around missing semantics by asking a colleague. Agents cannot, so they substitute a guess. The payoff of writing this down is therefore much larger in an agentic system than it was in a purely human analytics stack, which is why semantic metadata has moved from a nice-to-have to a load-bearing part of the architecture.

What changes when agents read

Most of this layer predates agents by a decade. The formats did not change. The requirements around them did, in four specific ways.

Access patterns get wider and less predictable

A dashboard queries the same six tables forever. An agent explores. It lists what exists, samples, checks a related table, and follows a hunch. That means metadata operations matter as much as scan performance, and it means broad read permissions are dangerous in a way that narrow, purpose-built service accounts were not.

Descriptions become part of the interface

Column comments and table descriptions used to be documentation. Now they are input. An agent choosing between two tables reads their descriptions the way a developer reads a function signature. Empty description fields are no longer a documentation debt, they are a correctness problem.

Reads need to be attributable

When an agent produces an answer, someone will eventually ask where the number came from. Being able to point at a table, a snapshot, and a timestamp turns an unverifiable claim into a checkable one. Table formats that keep snapshot history give you this almost for free, provided the harness records which snapshot it read.

Write paths need much stricter boundaries

Reading badly produces a wrong answer. Writing badly produces a wrong dataset that other systems then treat as truth. Most teams start with read-only agent access to this layer for good reason, and add write paths only behind explicit approval, to specific tables, with the change recorded.

Common failure modes

• Open formats, closed catalog. The tables are Iceberg and the files are Parquet, but the only catalog that can read them is proprietary and speaks a private protocol. The data is portable in theory and stuck in practice.
• Credentials scattered across tools. Each agent tool holds long-lived storage keys. Nothing can be revoked quickly and nothing can be audited centrally.
• Semantics living in a BI tool. Metric definitions exist, but only inside a dashboard product, so agents and pipelines cannot reach them and quietly define their own.
• No freshness contract. Nothing states when a table is expected to be current, so agents report stale numbers without any signal that they are stale.
• Everything is one grain. Tables mix order-level and customer-level rows without documenting which is which, so aggregations double count.
• Snapshot history turned off. Retention is set aggressively to save storage, and with it goes the ability to reconstruct what an agent saw last week.

How to evaluate this layer

A short set of questions separates a foundation that will hold from one that will not. Each maps to one of the six properties in the openness test.

• Replaceable. If you removed your query engine tomorrow, could a different engine read the same tables without a migration project?
• Inspectable. Can an engineer read the table specification and the catalog API, and understand what the system is doing without a support contract?
• Portable. Can the tables, the catalog entries, and the semantic definitions move to another environment, including a different cloud?
• Bounded. Does agent access go through a credential-vending catalog with scoped, expiring grants, or through shared keys?
• Grounded. Is there a written, machine-readable answer to what a metric means and which table is authoritative?
• Auditable. Can you reconstruct, for a given answer produced last month, which tables and snapshots it came from?

Answering no to any of these is not fatal. Answering no to most of them means the layers above will spend their effort compensating for the foundation instead of doing their own work.

A worked example

Abstract layers are easier to judge against a concrete request. Take a single question asked of an agent by a regional sales manager: which of my accounts had a drop in monthly spend of more than twenty percent last month, and did any of them file a support ticket in the same period.

In a system with a weak foundation, the agent does what it can. It searches available tables by name, finds something plausible, guesses that a column called amount is the one that means spend, has no way to know whether the month is closed, cannot tell which accounts belong to this manager, and cannot join support tickets to accounts because the key relationship is undocumented. It returns a list. The list is partly right. Nobody can tell which part.

In a system with a solid foundation, the same request resolves differently at each step:

• Authorization happens first.The agent presents the manager's identity to the catalog and receives scoped, expiring credentials that already exclude regions this person cannot see. The filter is not something the agent has to remember to apply.
• Table selection is decided, not guessed. The semantic layer names one authoritative account revenue table and marks the others as staging. There is nothing to choose between.
• Metric meaning is explicit. Monthly spend has a written definition, including whether refunds are netted and on what date basis. The agent does not invent one.
• Freshness is checkable. The table declares that the month closes on the fifth business day. If the request arrives on the third, the agent can say the month is not closed rather than reporting a partial figure as final.
• Joins are documented. The relationship between accounts and support tickets is recorded with its key and its cardinality, so the join is correct and does not double count.
• The read is recorded. The answer carries the table names and the snapshot identifiers it came from, so a skeptical reader can reconstruct it next quarter.

Notice how little of this involves the model. The difference between the two outcomes is almost entirely a property of the layer underneath. This is the practical case for spending real effort here before spending it on prompt engineering.

A build sequence that works

Teams that get this layer right tend to move in roughly the same order, and it is not the order that feels most exciting.

1. Pick the table format first. This decision is the hardest to reverse. Choose an open specification with multiple independent implementations and a public governance process.
2. Stand up a catalog that speaks an open protocol. Even if you start with one engine, the protocol is what keeps the second engine cheap.
3. Move access behind the catalog. Retire direct storage credentials in application and agent code before the number of tools grows.
4. Write descriptions as you go. Table and column descriptions are cheapest to write when the table is created and most expensive to reconstruct two years later.
5. Define the top twenty metrics explicitly. Not every metric. The ones that appear in decisions. Record the definition where software can read it.
6. Give agents read access to a curated subset. Start narrow. Widen based on observed need rather than on the theory that more access will help.
7. Record snapshot identifiers in agent output. This turns every agent answer into something a person can verify later without re-running anything.

How it feeds the rest of the stack

The foundation is not consumed directly by a model. It reaches the rest of the stack through specific, nameable paths, and it is worth being precise about them because each one is a place where grounding can be lost.

Through tools, usually over a protocol

The most common path is a tool that an agent calls: a query tool, a table listing tool, a metric lookup tool. In an open stack these are exposed through a protocol such as the Model Context Protocol rather than being compiled into one harness, which is what makes the same data access work across different agent runtimes. The protocol carries the call, and the catalog decides whether it is allowed.

Through retrieval over documents

Unstructured sources sit alongside tables and are usually reached by similarity search. The important discipline here is not to let retrieval answer questions that require exact figures. Retrieval is for finding relevant text. Structured queries are for producing numbers. Systems that blur this produce fluent summaries containing invented totals.

Through context assembled by the harness

The harness decides what a model sees. Table descriptions, metric definitions, and the list of tables the current user may reach are all context, and they are usually assembled fresh for each task. Where that context comes from matters: pulled live from the catalog it stays correct, copied into a prompt template it starts drifting the day it is written.

Through evidence attached to output

The return path is the one teams forget. Data flows up into an answer, and identifiers should flow back down into a record: which tables, which snapshots, which query, which user. That record is what makes the auditable property real rather than aspirational, and none of the layers above can produce it if the foundation does not expose stable identifiers to begin with.

What this layer is not

A few clarifications save a lot of confusion.

This layer is not a vector database, and vector search does not replace it. Embeddings are excellent at finding text that resembles a question and poor at producing an exact number. A mature system uses both, with retrieval pointing at documents and structured queries producing figures.

This layer is also not agent memory. What an agent remembers about a conversation, a task, or a user is state belonging to the execution layer. Conflating the two leads to agent memory being written into analytical tables, which is bad for both.

Finally, this layer is not a substitute for policy. Knowing what data means does not decide who should see it or what an agent may do with it. That belongs to the harness, and it is the subject of the execution layer. Grounding tells an agent what is true. Authority tells it what it may act on. Both are required, and neither substitutes for the other.