Grounding in practice

Registering a table is the easy part. Turning it into context an AI can answer from is where the work is, and it is what grounding means in practice.

Introspection gives you structure

When an admin introspects a data source, SEMANTIX discovers its tables and columns and registers them as entities and fields. At that point an entity has a name, a schema, a table, and a column list — real structure, no meaning.

You can now find orders.customer_id and know it exists. You cannot ask “who are our enterprise customers?” and get a trustworthy answer, because nothing says what customer_id means or which of the four customer tables is authoritative.

Descriptions are the actual payload

The high-value work is writing the description on an entity, and the description on its fields. This is what the agent reasons over instead of a bare identifier.

A field that says “number of units shipped; excludes samples and returns” is answerable. A field named qty is a coin flip.

Field roles help too. Marking a column as a dimension, measure, or time column tells the agent how it is expected to be used — which is a surprisingly large reduction in plausible-but-wrong groupings.

Trust is a human judgement

Not every table deserves equal confidence. An entity’s trust level (0–5) is set by a person, and it is a deliberately blunt instrument: how much do I trust this source to answer a business question?

It is also audited — every change to trust or certification is written to a log recording who changed it, from what, to what, and when.

Note

Do not confuse the two trust signals. Entity trust is the human 0–5 level described here. The metric system trust score is a machine-computed percentage shown on metrics. See entity trust.

Certified metrics are the ones for decisions

A metric is a defined, reusable calculation: a label, a description, a query, and a run history. A metric can be certified, which is the signal that it has been reviewed and is cleared for decision-making.

Certification also propagates in one direction worth knowing: an entity with a high enough trust level is treated as certified automatically, so lifting trust on a well-governed source table promotes the metrics built on it.

Living business knowledge

Definitions are not the whole story. A scope also accumulates the things people learned: business rules and investigation findings.

Findings are captured automatically from conversations — something the agent worked out while answering. They arrive uncertified, and only a scope owner or admin can promote one to a certified business rule. That promotion is the governance step: an observation becomes policy deliberately, not as a side effect of a chat happening.

Caution

Scope knowledge is edited in place. There is no version history and no per-item rollback — a change to a business rule overwrites the previous text, and a deletion is permanent. Keep consequential rules somewhere with history if you need to audit how a definition changed over time. Metric definitions are different: they do have an append-only change log recording each edit.

What an agent actually receives

In a scoped conversation, the agent’s context is built from the scope’s governed material:

• the registered entities reachable from the scope’s metrics, with their full column lists from the Registry (not a live re-read of the warehouse);
• the scope’s certified metrics and their definitions;
• the scope’s certified business rules.

It is not the entire warehouse schema, and it is not a pile of sample rows. When the agent needs to resolve a filter value it can look up the distinct values of a specific column on demand. For large scopes the metric snapshot is capped, so very large scopes answer from a subset.

Every query is validated before it runs

Generated SQL passes an AST validator and a dry-run gate before execution. A query that is not read-only, or that fails validation, is refused with a structured reason rather than being run optimistically. What actually executed is visible in the thread.

What is saved

Each successful answer is persisted with the question, the user, the timestamp, the validated SQL, and a bounded sample of the result — viewable in the thread.

There are limits worth stating plainly. A failed turn is not retained, so the history shows what worked rather than every attempt. Results are truncated to a sample, not stored in full. And the thread is visible to its author, not to an administrator — there is no cross-user answer audit screen today.

Note

These are honest limits rather than product intent, and they are tracked as follow-ups. If you need a compliance-grade audit trail, capture it downstream until the admin-side view ships.

Next: context scopes for how this context is organised and bounded.