> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 4 · Ontology as Code

> Goal: ship your authored files into the org’s Ontology from the terminal (or CI), without giving up the review discipline that makes governance credible. (~20 min)

**Goal:** ship your authored files into the org's Ontology from the terminal (or CI), without giving up the review discipline that makes governance credible.

## 4.1 · Search, then call

`refinery rpc` reaches every backend method. Always `search` before you `call` — never guess a method or field name:

```text Prompt theme={null}
refinery rpc search ontology upsert
refinery rpc call OntologyManagementService/UpsertOntologyFile --body '{"path":"databases/[source]/queries/[name].tql","content":"...","commitMessage":"add [name] query surface"}'
```

<Check>
  **You'll see:** the file lands in the org's Ontology immediately. Loop it over a local directory and a whole semantic layer installs in seconds — every file with its own commit message.
</Check>

<Warning>
  **⚠️ Writes are real and immediate** — `UpsertOntologyFile` commits straight to the org's Ontology — no draft, no review step. That's right for a workspace you own (POCs, sandboxes, pre-user builds) and wrong for a production org with users: there, author in a sandbox and file a **reviewed patch**, or route through git-sync PRs. The rule of thumb: **direct upsert until the first real user joins; reviewed changes after.**
</Warning>

## 4.2 · What to install

Follow the Save-to-Ontology conventions: a root **ANA.md** routing document, one folder per source with a README (tables, grains, joins, dead-ends), a **definitions.md** (one definition per term; unknowns marked OPEN with "don't guess" instructions), tested query surfaces, and dated append-only findings. Profile the data first — every coded value a definition references should have been *observed*, never assumed.

## 4.3 · Prove it round-trips

```text Prompt theme={null}
refinery connector db query [connector-id] --tql databases/[source]/queries/[name].tql --param '[name]=[value]' --sandbox [my-task-name]
```

<Check>
  **You'll see:** `--tql` runs the APPROVED copy — so this is the proof your installed file is the file you tested. If render errors name grammar problems, Module 3's table is the fix-it list.
</Check>

### ✅ Checkpoint

* [ ] Your files are in the org's Ontology with meaningful commit messages
* [ ] The installed .tql executes governed, with output matching your pre-install test
* [ ] You can state when direct upsert is acceptable and when reviewed patches are required