Modelling knowledge for humans and for agents

Part 3 of 4. The series starts with From raw data to usable knowledge, and the metadata in between.

Structured knowledge has three types of consumers, each with specific needs.

For Humans

For humans, structured knowledge is invaluable across roles: data analysts, analytics engineers, and data scientists benefit first, gaining the context to interpret fields like status_cd, understanding how tables can be joined, and correctly discerning whether a negative amount signals a refund or an error–in the absence of clear documentation, newcomers are forced to relearn what was already known. Stakeholders and business users rely on a common language to avoid ambiguity: a shared glossary ensures that everyone understands terms like "churn" and calculates KPIs, such as "revenue," using consistent logic, while enabling cross-team communication so that Marketing and Finance speak the same language. Operational and data engineers, along with new team members, need living documentation to grasp data processes, accelerating onboarding so that the information system becomes navigable in days rather than months, and facilitating traceability and audit by making it clear where numbers come from and how calculations happen.

Agents

This is where it gets really interesting. Let's directly take the really common Text-to-insights agent use case.

The Text-to-insights Challenge

Everyone wants to chat with their data, but everyone is not ready to do what is necessary.

Whether the data is in a Data Lake, a Data Warehouse, a simple relational database, the problem is the same: translating a business question into a technical query.

To achieve this, the agent must be able to:

1. Map business concepts → "revenue" corresponds to which column?
2. Understand values → "World Cup" is the code WC or WORLD_CUP?
3. Know the joins → How do you link customers to orders?
4. Respect business rules → Is revenue calculated before or after tax?

What Agents Need

Concretely, a performant Text-to-insights agent needs:

Element	Description	Example
Glossary	Concept → technical mapping	"revenue" = SUM(orders.amount)
Enriched schema	Tables + columns + descriptions	status_cd: Status code (A=Active, I=Inactive)
Joins	Relationships between tables	orders.customer_id → customers.id
Validated examples	Question/SQL pairs	"Top 10 customers" → SELECT...
Business rules	Constraints and calculations	Revenue = amount before tax, excluding cancellations

The Measured Impact

This isn't theory. Research (notably from LinkedIn and Snowflake on Cortex) has quantified the impact of metadata on the quality of generated queries.

The difference between an agent that hallucinates non-existent columns and an agent that produces correct queries? The quality of metadata provided in context.

Where to Start?

1. Start small: A CSV file with a glossary of business terms
2. Document key tables: The most queried ones first
3. Describe columns: Possible values, meaning, usage patterns
4. Map joins: Relationships between main tables
5. Collect examples: Question/SQL pairs validated by humans

Perfection is not required. Progress is.

This metadata can be AI-assisted: take samples from your tables, pass them to an LLM to generate descriptions, then manually validate and adjust. It's tedious work, but it's the work that makes the difference between a POC that impresses and an agent that delivers value in production.

---

Next: Why classic RAG retrieves text instead of knowledge