Use structured tables for facts that agents must filter, compare, or aggregate, and documents for the reasons and exceptions behind those facts. Linking the two lets an agent retrieve a precise value and inspect its meaning without reconstructing a dataset from prose.
Key takeaways
- Use a table when the answer is a filtered value, such as "which regions support feature X?"
- Use a document when the answer needs reasons, context, or exceptions.
- Link the two so an agent that finds one can reach the other.
- Apply access controls at query time, so the agent can retrieve only the tables and records its authenticated identity is allowed to read.
Tell tables and documents apart
| Question an agent gets | Better format | Why |
|---|---|---|
| Which data centers support GPU instances? | Table | One filter over rows |
| Why did we leave the Frankfurt region? | Document | Needs reasons and history |
| Who is the escalation contact for vendor A? | Table | One lookup by key |
| What is our policy for vendor exceptions? | Document | Needs conditions and judgment |
Use a table when the question needs a stable key, filter, comparison, or aggregation. Use a document when interpreting the answer requires policy, rationale, or exceptions.
Keep the table and its explanation together
A table without context gets misread. "Supported: no" may mean "never" or "not yet." Put a short document next to each table that defines the columns, names the owner, identifies the source, and states when the data was last updated. Link them, so an agent that queries the table can also read the definitions.
Define how value changes are recorded and reviewed. Table-history and audit behavior should be checked separately from document revisions.
Query with the reader's permissions
Authorize the query using the authenticated reader’s permissions before returning data. Database-enforced permissions can provide a stronger boundary than filtering an over-broad result after retrieval. A link to a policy document must not grant access to it.
Decide where AKB fits
AKB, Dnotitia's agent knowledge base, stores tables alongside documents and files in the same vault. Agents create table schemas with akb_create_table, alter schemas with akb_alter_table, and use akb_sql for supported queries and data operations within their permissions. Each table has its own URI, so a document can link to it with an explicit relation.
AKB documents PostgreSQL ACL enforcement for akb_sql, with user and vault roles. Unauthorized vault references are rejected by the database. The described boundary is vault access; it does not establish per-row permission rules.
Keep authoritative live transactions in their owning systems. AKB can hold supporting reference data or synchronized copies when their source and freshness are clear.
Test one lookup end to end
As a hypothetical, ask an agent a question that needs a table value and its explanation: "Can we launch GPU instances in Seoul, and who approves exceptions?" Test that an allowed user can retrieve the table value and policy, and that a denied user cannot retrieve either unauthorized resource.