Build Your Ontology: Quickstart

​

Before You Start

• Metric definitions — how your team actually calculates revenue, churn, conversion, activation. If different teams use different definitions, collect all of them. Ontology is where you canonicalize.
• Existing SQL and notebooks — recurring analyses your team runs are direct evidence of what Ana will need to produce. These are your ground truth.
• Schema documentation — any notes on non-obvious joins, unreliable columns, or connector-specific quirks that wouldn’t be apparent from table names alone.
• Tribal knowledge — meeting notes, Slack threads, recorded data reviews, onboarding docs, ad-hoc write-ups where your team has captured how numbers behave, which fields have edge cases, or why a given metric is calculated the way it is.

​

Build incrementally, not exhaustively

​

Step-by-Step Guide

​

Method 1: GitHub Integration

• Edit outside TextQL — your team can edit ontology files directly in GitHub, VS Code, or any editor, and changes sync back
• Use existing repos — if your organization already has a documentation repository, connect it and bring everything in without migrating manually
• Pull requests — optionally route Ana’s proposed changes through GitHub PRs instead of the in-app Reviews flow
• Works with any Git host — GitHub, GitLab, AWS CodeCommit, Bitbucket, or any standard Git remote

• GitHub App
• SSH Key
• HTTPS Token (Recommended)

The easiest option for GitHub users. Click Install GitHub App and you’ll be redirected to GitHub to install the TextQL Library Sync app on your organization. Once installed, select the repository and branch to connect.

Paste in your repository URL and private key. Works with any Git host, including self-hosted instances.

Use a personal access token for HTTPS-based authentication. Enter the repository URL and your token.Finding your repository URL: On GitHub, click the green Code button, select the HTTPS tab, and copy the URL (e.g. https://github.com/your-org/your-repo.git).

Getting a GitHub Personal Access Token:

1. Go to GitHub → profile picture → Settings
2. In the left sidebar, scroll to Developer settings
3. Go to Personal access tokens → Fine-grained tokens
4. Click Generate new token, set a name and expiration, then under Repository permissions grant:
   • Contents — Read and write
   • Pull requests — Read and write
   • Metadata — Read-only
5. Copy the token immediately — GitHub won’t show it again

• TextQL → Git: Approved changes in Ontology are pushed to the repo (as commits or PRs, depending on your push mode)
• Git → TextQL: Changes committed to the repo’s connected branch are pulled into Ontology automatically, typically within a few minutes

​

Method 2: Create Files Directly

• Files — the main file browser. Create folders, add files, and edit content.
• Graph — a visual map of all files in your Files tab. Shows how your defined objects, metrics, and relationships connect to each other.
• Reviews — proposed changes from Ana waiting for approval.
• History — a full audit log of every change made to Ontology.

• Create new file — opens the editor to write a file directly
• Upload files — upload an existing file from your machine (PDFs, images, CSVs, etc.)
• Create new folder — add a new folder to organize your files

ANA.md                          ← org-wide entry point
Finance/
  README.md                     ← what's in this folder and when Ana should use it
  revenue-definitions.md
  fiscal-calendar.md
  exclusion-rules.md
Go-To-Market/
  README.md
  pipeline-definitions.md
  crm-field-glossary.md
Product/
  README.md
  engagement-metrics.md
Connectors/
  snowflake-notes.md
  salesforce-notes.md

• One topic per file. A focused revenue-definition.md is more useful than a finance-misc.md that grows unbounded. Atomic files are easier to version, permission, and retrieve.
• Index every folder. A short README.md at the top of each folder — what’s here, when to use it — lets Ana navigate a large ontology without loading every file inside it.
• Treat it like code: stale definitions cause real errors. Unlike human-facing docs that get skipped, Ana follows instructions precisely. An outdated revenue definition produces wrong numbers silently. Update Ontology when business logic changes.

# Org Instructions

- Always cite the date range and source tables in your analysis
- Exclude test accounts (account_type = 'test') from all revenue calculations
- Fiscal year runs July 1 – June 30: Q1=Jul-Sep, Q2=Oct-Dec, Q3=Jan-Mar, Q4=Apr-Jun

## Navigation

| When asked about | Go to |
|---|---|
| Revenue, ARR, MRR, bookings | `Finance/revenue-definitions.md` |
| Pipeline, deals, CRM data | `GTM/pipeline-definitions.md` |
| Active users, engagement | `Product/engagement-metrics.md` |
| Data source quirks (Snowflake) | `Connectors/snowflake-notes.md` |

​

Method 3: Build Through Threads (Non-Admin Friendly)

• A metric definition or calculation rule (“exclude refunded orders from revenue”)
• A fiscal calendar or date convention (“Q1 starts February 1”)
• A data quirk or known issue (“the status column in orders uses 1/0, not true/false”)
• A business rule or exclusion (“don’t include test accounts in any analysis”)
• A clarification about what a table or column represents
• A correction to an existing definition you know is wrong

• “Save what you learned about this connector to Ontology.”
• “Add a rule that we always exclude refunds from net revenue.”
• “The churn calculation we just worked out — can you save that?”
• “Update the Finance folder with the new fiscal year start date.”
• “What did you learn today that would be useful to save?”

• Approve — applies the change immediately
• Discard — throws it away, nothing is saved

• Schema quirks — non-obvious join keys, unexpected column encodings, table-specific behavior discovered during analysis
• Business definitions — if you correct Ana mid-Thread (“actually, ‘active users’ means last 30 days, not 7”), she can save that immediately
• Query patterns — complex logic that comes up repeatedly for a specific connector or metric
• Org rules — anything you find yourself repeating across Threads

​

Ontology Query - .tql Files

​

Features

• Date and Timestamp params are strings at validation time. Document format expectations in comments.
• Plain SQL bodies only support param-name interpolation. Use expression-style .tql for computed fragments.
• Structured source assembly with compiler-managed join aliases is a design direction, not the current authoring surface. Today, joins are authored as SQL fragments.

​

Short Language Spec

params {
-- Country code. Examples: "US", "CA", "BR"
country: String = "US"

-- Inclusive lower bound in ISO 8601 timestamp format.
created_after: Timestamp?
}

SELECT *
FROM visits
WHERE country = ${country}
AND created_at >= ${created_after}

params {
include_region: Bool = false
}

let
  select_expr = if include_region then sql"region, COUNT(*)" else sql"COUNT(*)"
  group_clause = if include_region then sql"GROUP BY region" else sql""
in sql''
  SELECT ${select_expr}
  FROM orders
  ${group_clause}
''

import t from "../relations/transactions.tql"
import dims from "../dimensions/standard.tql"
import { eq } from "../filters/compare.tql"

params {
-- Metrics to include.
metrics: Set<"revenue" | "order_count"> = []

-- Optional dimensions.
dimensions: Set<"customer" | "month"> = []

-- Filters to apply. Allowed keys: customer_name (equals, like), ordered_at (gte, lte, between).
filters: List<FilterInput> = []

-- Optional region override.
region: String?
}

• Literals: numbers, strings, booleans, null, lists, and records.
• Bindings: let ... in ..., evaluated in order. Duplicate binding names are rejected.
• Records: { expr = sql"b.name", join = sql"JOIN buyers b ON ..." }.
• Record shorthand: { expr, join }.
• Field access: dims.buyer.expr.
• Conditionals: if condition then value else value. Only the selected branch is evaluated.
• Lambdas: \col val -> sql"${col} = ${val}". Function application is whitespace-separated.
• Set matching: matchSet dimensions { "buyer" -> ... }.

let
  where_clause =
    if created_after == null
    then sql""
    else sql"WHERE created_at >= ${created_after}"
in sql"SELECT * FROM visits ${where_clause}"

​

Supported Parameter Types

​

Walkthrough

​

Dynamic Loading — How Ana Uses Your Ontology

​

Auto-attached files

​

On-demand files

​

Practical example

​

History & Version Control

​

The Reviews tab

• Who proposed it — the user (via Ana) who initiated the change
• The source thread — a link to the Thread where the change was proposed
• The diff — a line-by-line view of what’s being added or removed
• The target file — which file will be affected

​

The History tab

​

What to Build First

1. ANA.md with org-wide rules and a navigation table
2. One folder per major business domain with a README.md in each
3. Metric definitions as .md files — revenue, ARR, churn, conversion first
4. Objects and links (via Ana chat) for the 3–5 tables your team queries most
5. .tql metric queries for calculations that need deterministic, structurally enforced SQL
6. Role-scoped files and auto-attach configuration once the baseline is stable