Build Your Ontology, End to End

A hands-on guide to turning the context your organization already has — databases, documents, spreadsheets, diagrams, transcripts — into a governed, queryable ontology with TextQL's analytics agent, Ana, and keeping it current as new information arrives.

It's written for teams who want to learn to build, use, and maintain an ontology themselves — whether you're standing up your first one or teaching a wider group how it's done.

What an ontology is here

An ontology is the mapping between your technical assets (tables, catalogs, documents) and your business (metrics, workflows, terminology). In TextQL it's just files — Markdown for human context and .tql for a typed, SQL-rendering semantic layer — kept in a git-backed repository with review, versioning, and access control. Ana reads it, renders inspectable warehouse SQL from it, and helps you extend it.

Two ways to build (do either, or both)

• From a connected database — point Ana at a data source, and she helps you discover the schema, draft the documentation, define governed metrics, and reconcile conflicting definitions into one source of truth.
• From a pile of documents — start with the messy reality most teams actually have (policies, metric docs, data dictionaries, process diagrams, call transcripts, spreadsheets) and watch it become one coherent, governed model — then add the next document with a targeted edit, not a rebuild.

Plus role-based access: one governed ontology can serve many teams, each with its own data scope and response style — without duplicating the model.

What's in this guide

File / folder	What it is
01_THE_METHOD.md	The principles and the step-by-step method for building an ontology
02_WALKTHROUGH.md	A hands-on walkthrough with the exact prompts to use with Ana (both ways to build)
03_ROLE_BASED_ACCESS.md	How one ontology serves multiple teams with different scopes and behaviors
DATASETS.md	The example datasets used in the walkthrough (and how to connect your own)
DOCUMENT-SOURCES.md	Ways to bring your documents into Ana (upload, Drive, SharePoint, object storage, git)
example-scenario/	A complete, illustrative input set — a member-services contact center — in every input type
ontology-example/	The built-out .tql ontology + decision notes for that scenario

How to use it

1. Read 01_THE_METHOD.md for the concepts.
2. Follow 02_WALKTHROUGH.md end to end — it's prompt-by-prompt.
3. Use example-scenario/ as the worked example (it's synthetic and illustrative); then point Ana at your data and documents and repeat the same steps.

The example scenario uses a fictional health plan ("Northwind Health") and synthetic data — no real PII/PHI. The method generalizes to any domain; swap in your own documents and data sources.