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 make a pull request on the connected Git host the merge gate. A change approved in the in-app Reviews flow is proposed as a pull request, and only applies once your team merges it
• Works with any Git host — GitHub, GitLab, AWS CodeCommit, Bitbucket, or any standard Git remote

• GitHub App
• SSH Key
• HTTPS Token (Recommended)
• AWS CodeCommit (IAM Role)

The easiest option for GitHub users, and the only one that can open pull requests on GitHub. Click Install GitHub App and you’ll be redirected to GitHub to install the TextQL Ontology Sync app on your organization. Once installed, select the repository and branch to connect.The app needs Contents (read and write) and Pull requests (read and write) repository permissions; the second is what the Create PRs push mode uses.

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

For repositories hosted in AWS CodeCommit. TextQL authenticates with the IAM role of its own AWS deployment — no IAM user, token, or key is required, which makes this the right option when your AWS account prohibits IAM user creation.Enter the repository’s HTTPS clone URL (e.g. https://git-codecommit.us-east-1.amazonaws.com/v1/repos/your-repo) or its ARN (e.g. arn:aws:codecommit:us-east-1:123456789012:your-repo). The region is read from the URL or ARN.Grant the deployment’s IAM role these permissions on the repository:

• codecommit:GitPull — sync from CodeCommit into TextQL
• codecommit:GitPush — push TextQL edits back to CodeCommit
• codecommit:CreatePullRequest — only needed for the Create PRs push mode

1. Ana (or a team member) proposes a change; it appears in Ontology → Reviews as usual.
2. A reviewer approves it in Ontology. Nothing changes in the ontology yet: TextQL pushes the change to its own branch and opens a pull request against your connected branch. The review shows Awaiting PR merge with a link to it.
3. Your team reviews the pull request in GitHub, using your normal checks, CODEOWNERS, and merge rules.
4. When the pull request is merged, the next sync pulls the commit back and the change becomes live in the ontology. The review flips to Approved.
5. If the pull request is closed without merging, the review returns to Pending review so it can be revised or re-proposed.

• TextQL → Git: Approved changes in Ontology are pushed to the repo — as commits on the connected branch with Direct push, or as a pull request awaiting your merge with Create PRs
• 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