The model: entities, fields, relationships
Entities, fields, relationships, filters, checks and examples, and the properties of each.
The governed half: a model of your data that people edit and publish, and that agents use to plan queries. It holds only ontology (entities, fields, relationships, filters, checks and examples); what people know about the business lives in the knowledge library.
Four concepts. Everything an agent or a person needs to know is one of them.
Entities#
The business things: a customer, an order, a contract, a sensor. Each entity has:
| Property | Meaning |
|---|---|
| key | Short lower_snake_case id used everywhere else (customer, order_line). |
| name, domain | Business name and business domain (Sales, Finance...). Domains group the entity list. |
| kind | master, reference, transaction, fact, relationship, bridge, agreement, supertype, derived or technical. Used by the planner and by the demo-data generator (how many rows). |
| definition | What one row of the entity is. |
| table | schema.table that holds it (semantic_table). |
| keys | Primary key; business key (what people use to identify it); system of record. |
| synonyms, not to confuse with | The words people actually use, and things it is often mistaken for. |
| belongs to, subtype of | A parent concept; the supertype entity, if any (a supertype table unifies several subtypes behind a discriminator). |
| model status | confirmed, new or placeholder. |
| standard | Optional: the matching concept in an industry standard you follow (resource, reference, detail). |
| lifecycle states | One line per status column: status: draft > active > closed. |
| example questions | Typical questions the entity answers (searchable). |
Entities also carry:
- Filters: named conditions such as open order =
closed_at IS NULL, with synonyms, a description, a source and a status (governed= agreed,working= not confirmed yet). Agents get them pre-filled instead of guessing values. - Checks: data-quality rules in words, optionally with SQL that counts violations (one column
n, which must be 0). The Model check runs them.
Fields#
What an entity has:
- Attributes are columns of the entity's table.
- Calculated fields (role
calculated) are values computed from the data, not columns: meaning, unit, and optionally the SQL that computes them. That SQL is context for agents; the app never runs it.
| Property | Meaning |
|---|---|
| column, business name | Column name (a short code for a calculated field) and the name people use. |
| role | primary_key, foreign_key, attribute, alternate_reference, dimension, fact_measure, derived_attribute, lineage or calculated. |
| type | text, integer, decimal, boolean, date, timestamp, text[]. |
| description | What the value means. |
| allowed values | The codes stored in the column, each with a label and a note. Agents get the exact values. |
| references | For a foreign key: the entity it points to. |
| format, example | A pattern ("two letters + 6 digits") and a sample value (never a restricted one). |
| business term | Glossary name and definition. |
| standard name, unit | Name in the industry standard; unit of the value (count, EUR, hours). |
| sensitivity | internal, confidential, personal or restricted (see Access control). |
| agent access | full, masked or none. Default: none for restricted, full otherwise. A restricted field must be none. |
| review status | How settled the definition is: confirmed_by_team, by_design, high_confidence, needs_review (default) or source_needed. Pending definitions are flagged to agents. |
Relationships#
How entities connect: from, predicate (the verb: places, belongs to), to, the exact join (a.col = b.col), cardinality (many-to-one, one-to-many, one-to-one, many-to-many, many-to-zero-or-one (optional), subtype-of), and how reliable the link is:
| Status | Meaning |
|---|---|
confirmed | The join holds. |
optional | Holds when filled, may be empty. |
unreliable | Often empty or wrong. Join planning avoids it when it can and says so when it cannot. |
Join planning prefers reliable links, offers an all-confirmed alternative when the best path is not, and warns when a path would match every sibling record through a shared parent (fan-out).
Query examples#
A worked query with its SQL, :parameters, a parameter → entity map and a sample query that returns one row of parameter values; the Model check runs each on real rows, and agents get the ones that apply to the entities of their question as patterns (up to three per query plan, since each carries SQL). Each has an id, a title (the question it answers), a note, optional topic and source, and the entities it applies to.
The model is only the structured ontology: entities, fields, relationships, filters, checks and examples. What people know about the business (rules, definitions, abbreviations, procedures, policies) is not kept here: it is ingested as ordinary documents into the Library, where grants, usage tags, evidence and review govern it, and tools bring it to an agent when it matters (plan_query lists the relevant topics, describe finds a name only the documents know, entity pages list related documents). Older Excel files with a Knowledge sheet still upload: their examples are read, the rest is reported and left out.
Custom properties and model metadata#
Any item (the model, entities, fields, relationships, filters, checks, examples) can carry properties of your own: an owner, a source system, a ticket number, a lineage note. They are kept as written, shown in the app, searchable, and given to agents. In Excel, any extra column is a custom property.
The model itself has a name, id, version, date, source, status text, the standards it follows, what each sensitivity class means in your organisation, a row-level rule in words, and reading notes.
SQL in the model (filters, checks, examples) is written once in PostgreSQL syntax and translated for whichever database is connected.