Connecting Business Vocabulary to a Database Schema

A user asks, “How many employees have an engineering title?” People are stored in H_OSOBA, their title code is in TITUL_PRED_KOD, and the labels live in H_C_TITUL_PRED. Someone familiar with the database knows how these fit together. A model may not infer that from the names.

A domain glossary connects the words in a question to tables, columns, and their meanings. In an agent design, this can be called an association layer.

More than a list of synonyms

A useful table entry includes a short description and notes about fields that are easy to misread:

• Aliases: employee, worker, staff.
• Description: the main person record; employment contracts may live elsewhere.
• Column note: TITUL_PRED_KOD references the lookup for titles before a name.
• Relationship: the keys that connect the record to that lookup.

The distinction between a person and an employee needs review by someone who understands the data. An unchecked alias can lead the bot to count people who have no employment contract.

Use the glossary twice

Relevant entries belong in the context used to select tables. They also belong in the context used to generate SQL. If the second step receives only technical names, useful information gets lost between stages.

The glossary can be edited without retraining the model. When a change takes effect depends on metadata loading and index refreshes. Even a small alias change should be checked against questions that already worked.

Start with a question you need to answer

Choose a few supported questions and prepare a verified query for each. Use those queries to identify the tables, columns, and explanations the bot needs. Then test different ways of asking the same thing.

When the bot selects the wrong table, inspect what was missing: a synonym, a description, or a business rule. That gives the next glossary edit a clear purpose. There is no need to annotate the entire schema before testing the first useful questions.

Keep entries in a versioned file or another store with revision history. A development database can hold a working copy, but rebuilding it should not erase reviewed knowledge. The format and loader can be reused across deployments; the vocabulary still needs to match each client's data.