Glossaries
Define what your business terms mean, so agents and AI queries read "active customer" or "churn" the way your business does.
Why Use a Glossary
Your users ask questions in business language. "How many active customers do we have?" depends on what "active" means to you: an order in the last 90 days, a paid plan, or a login this month. Without that definition, an AI model picks one, and the answer looks right but counts the wrong rows.
A glossary term answers that once:
Active Customer: A customer who placed an order in the last 90 days.
synonyms: Active Account
collections: customers, orders
query snippet: last_order_at >= CURRENT_DATE - INTERVAL '90 days'
AI queries and agents receive the relevant terms with every question, so they use your definition instead of guessing.
Overview
A glossary holds terms. Each term has a name and a plain-language description, and optionally synonyms. A glossary is guidance for the model: Squid gives the terms to AI queries and agents, and nothing forces or rewrites a query.
There are two kinds of glossaries:
- Database glossary. Each database connector has at most one, with
scope: { type: 'database', integrationId }. Its terms may also list thecollectionsthey are relevant to and aquerySnippetin the database's own query language. - Global glossary. It has
scope: { type: 'global' }and belongs to no database: company-wide vocabulary such as "Fiscal Quarter". Its terms have nocollectionsorquerySnippet. You attach it to agents and ontologies by id.
Squid can generate the terms for you from your database schemas and knowledge bases. Generation never saves: it returns a draft for you to review and save.
Quick Start
Prerequisites
- A database connector with a discovered schema, for a database glossary.
- The Squid backend SDK. Glossary management requires your app's API key, so run it from backend code and expose it to your frontend through an executable.
The glossary API is available in the TypeScript SDK.
Step 1: Save a database glossary
import { SquidService, executable } from '@squidcloud/backend';
import { Glossary } from '@squidcloud/client';
export class GlossaryService extends SquidService {
@executable()
async saveSalesGlossary(): Promise<Glossary> {
// Saves the glossary with exactly these terms. A database glossary is found by its database.
return this.squid
.ai()
.glossary()
.saveGlossary({
glossary: {
name: 'Sales glossary',
scope: { type: 'database', integrationId: 'sales_db' },
},
terms: [
{
name: 'Active Customer',
description: 'A customer who placed an order in the last 90 days.',
synonyms: ['Active Account'],
collections: ['customers'],
querySnippet: "last_order_at >= CURRENT_DATE - INTERVAL '90 days'",
},
{
name: 'Fiscal Quarter',
description: 'Our fiscal quarters start in February, May, August and November.',
},
],
});
}
}
Step 2: Ask a question
AI queries on sales_db now receive the relevant terms. providedDefinitions lists the terms the model was given:
import { SquidService, executable } from '@squidcloud/backend';
export class SalesQuestionService extends SquidService {
@executable()
async countActiveCustomers(): Promise<string> {
const response = await this.squid.ai().executeAiQuery('sales_db', 'How many active customers do we have?');
// For example: [{ type: 'term', id: '...', name: 'Active Customer' }]
console.log(response.providedDefinitions);
return response.answer;
}
}
To give the terms to an agent, connect the database to it. See Connected Ontologies and Glossaries.
Core Concepts
Terms
| Field | Description |
|---|---|
name | The term, such as "Active Customer". Unique within the glossary, ignoring case and spacing. |
description | A plain-language definition, with nothing technical. A database glossary's description may say in words where the term lives. |
synonyms | Other words people use for the term, such as "Customer" for "Account". At most 20. A question that uses a synonym counts as naming the term. |
collections | Database glossaries only: the collections the term is relevant to. Empty means the whole database. An agent or AI query limited to some collections only sees the terms for them. |
querySnippet | Database glossaries only: a fragment in the database's query language that selects the term, at most 2,000 characters. AI queries show it to the model as a hint, not a rule. |
Saving and revisions
saveGlossary() replaces all the terms: the stored terms become exactly the ones you send. Every write increments the glossary's revision. Pass the revision you read to make a save fail with GLOSSARY_REVISION_CONFLICT when someone saved the glossary since:
revision sent | Effect |
|---|---|
| Omitted | The save replaces whatever is stored |
0 | You read no glossary, so the save fails if one was saved since |
| A number | The save fails if the stored revision is newer |
To change one term without sending the rest, use updateTerm() and deleteTerm():
import { SquidService, executable } from '@squidcloud/backend';
import { GlossaryTerm } from '@squidcloud/client';
export class GlossaryTermService extends SquidService {
@executable()
async addPartnerTerm(glossaryId: string): Promise<GlossaryTerm> {
// A term with no id, or an unknown one, is added.
return this.squid.ai().glossary().updateTerm(glossaryId, {
name: 'Partner',
description: 'A company that resells our products.',
});
}
@executable()
async listTerms(glossaryId: string): Promise<GlossaryTerm[]> {
// listTerms({ glossaryId, cursor, limit, search }) reads one page at a time.
return this.squid.ai().glossary().listAllTerms(glossaryId);
}
}
Removed names
Deleting a term, or dropping a generated term before saving it, makes the glossary remember its name, so generation does not propose it again. listExcludedNames(glossaryId) lists the names, and restoreExcludedName(glossaryId, name) lets generation propose one again.
Generating a Glossary
generateGlossary() reads the sources and returns a draft with the changes it made, each with a reason. It saves nothing.
- A database glossary reads the schema of its database.
- A global glossary reads the glossaries of the databases in its
integrationIdsand the knowledge graphs of the knowledge bases in itsknowledgeBaseIds.
| Option | Default | Description |
|---|---|---|
mode | update | update returns the fewest changes the sources call for. regenerate builds the terms from the sources alone, without the previous terms or the removed names. |
instructions | Extra guidance for this run only, such as "Add terms for our loyalty program". Not saved. The glossary's own instructions still apply. | |
terms | Saved | The current draft to update. |
When no source changed since the generation the glossary was saved from, an update returns unchanged: true without calling the model. A run with instructions always calls the model.
import { SquidService, executable } from '@squidcloud/backend';
import { Glossary } from '@squidcloud/client';
export class GlossaryGenerationService extends SquidService {
@executable()
async generateAndSave(): Promise<Glossary> {
const glossaries = this.squid.ai().glossary();
const glossary = {
name: 'Sales glossary',
scope: { type: 'database', integrationId: 'sales_db' } as const,
};
const current = await glossaries.getDatabaseGlossary('sales_db');
const draft = await glossaries.generateGlossary({
glossary: { ...glossary, id: current?.id },
mode: 'update',
});
// Each change is { type: 'add' | 'update' | 'remove' | 'merge', name, reason, ... }.
for (const change of draft.changes) console.log(`${change.type} ${change.name}: ${change.reason}`);
return glossaries.saveGlossary({
glossary: { ...glossary, id: current?.id },
terms: draft.terms,
// Lets a later update skip the model when nothing changed.
generatedFrom: draft.generatedFrom,
// 0 when no glossary was stored yet.
revision: current?.revision ?? 0,
});
}
}
Pass droppedNames to saveGlossary() with the generated terms you dropped from the draft, so generation does not propose them again.
When you save a draft from a regenerate run, pass regenerated: true so the glossary forgets the names it remembered before this save. Either way, the save remembers the droppedNames you pass and every stored term missing from the new draft, so later runs do not propose them. To let generation propose one of them again, call restoreExcludedName().
Global Glossaries
A global glossary holds vocabulary that is not tied to one database. Give it sources to generate from, then attach it to agents and ontologies:
import { SquidService, executable } from '@squidcloud/backend';
export class CompanyGlossaryService extends SquidService {
@executable()
async createCompanyGlossary(): Promise<string> {
const saved = await this.squid
.ai()
.glossary()
.saveGlossary({
glossary: {
name: 'Company vocabulary',
scope: { type: 'global' },
integrationIds: ['sales_db'],
instructions: 'We are a B2B distributor. Skip HR terms.',
},
terms: [{ name: 'Fiscal Quarter', description: 'Our fiscal quarters start in February.' }],
});
return saved.id;
}
}
Where Glossaries Are Used
- AI queries. The relevant terms of the database's glossary guide every stage, with their collections and query snippets. Turn this off for one query with
semanticLayer: { enabled: false }in the AI query options. - Agents. A connected database's terms appear in the agent's instructions by name, synonyms and the first sentence of their description, never with their collections or query snippets. Global glossaries attached to the agent appear there too. See Connected Ontologies and Glossaries.
- Ontology generation. Generation reads the glossaries of the attached databases and the global glossaries in the ontology's
glossaryIds. See Guiding generation with glossaries.
Error Handling
| Error | Cause | Solution |
|---|---|---|
GLOSSARY_REVISION_CONFLICT | The glossary was saved since the revision you sent | Read the glossary again, reapply your changes and save |
GLOSSARY_NOT_FOUND | The glossary id does not exist, or a save with a revision found it deleted | Use listGlossaries() to find the id |
GLOSSARY_TERM_NAME_TAKEN | Another term of the glossary has that name | Rename the term, or update the existing one |
Best Practices
- Keep it small and broad. Define the terms your users actually ask about and the ones the schema gets wrong, not every column.
- Write descriptions for people. A description is plain language. Put the technical part in
querySnippet. - Use synonyms for the words your users say. If users say "account" and the table says "customer", add the synonym.
- Review generated drafts. Generation proposes; you decide. Drop terms that do not fit, and pass them as
droppedNames. - Save with a revision. When several people or processes edit a glossary, pass
revisionso one save does not overwrite another.