> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/sdk-getting-started/sdk-api-reference/ontology.md). # Ontology Ontology concepts and queries over them. ## AnchorSqlResult One Anchor SQL response: rows, a metadata listing, or a validated plan. | Attribute | Type | Description | | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `kind` | `str` | `rows` for a materialised result, `metadata` for SHOW/DESCRIBE output, `validated` for a compile-only pass. | | `rows` | `list[dict]` | The first page of rows. | | `columns` | `list[str]` | Column order for the rows. | | `units` | `dict[str, str]` | Unit id per column, where the ontology knows one. | | `row_count` | `int \| None` | Rows in this page. | | `total_row_count` | `int \| None` | Total rows the statement matched, when the engine counted them. | | `truncated` | `bool` | Whether the result was cut at the engine's cap. | | `next_start_key` | `int \| None` | Resume point for the next page — pass it back as `start_key=`, or let [`to_frame`](#to_frame) page for you. None when this page is the last. | | `plan` | `dict` | The compiled plan: scope, spine, join and grain chips, plus the join strategy the ontology chose. | | `warnings` | `list[str]` | Anything the planner wants you to know. | | `statement` | `str` | The statement as the engine echoed it back. | ### AnchorSqlResult.to\_frame ```python AnchorSqlResult.to_frame(max_rows: int | None = None) -> pd.DataFrame ``` Every row, paging transparently through `next_start_key`. | Parameter | Type | Default | Description | | ---------- | ------------- | ------- | ----------------------------------------------------------- | | `max_rows` | `int \| None` | `None` | Stop after this many rows. Fetches everything when omitted. | **Returns** (`pd.DataFrame`): The rows as a DataFrame, columns in engine order. ## Concept A handle to one ontology concept — resolve it once, then operate on it. Supports dict-style access to the underlying document (`concept["metadata"]`), so it drops in wherever the raw doc was used. ### Properties * **id** (`str`) * **name** (`str`) * **metadata** (`dict[str, Any]`) * **detected** (`dict[str, Any]`): What the auto-profiler detected, shadowing any overrides. * **locks** (`pd.DataFrame`): The overridden metadata fields: current value vs detected. ### Concept.get ```python Concept.get(key: str, default: Any = None) -> Any ``` *Undocumented; the signature above is the contract.* ### Concept.refresh ```python Concept.refresh() -> Concept ``` Re-read the concept from the platform. ### Concept.override ```python Concept.override( *, metadata: dict[str, Any] | None = None, overrides: Any = {}, ) -> Concept ``` Override this concept's metadata or structure, locked against re-profiling. See [`Ontology.override`](#override) for the keyword vocabulary. **Returns** (`Concept`): This handle, refreshed with the updated document. ### Concept.revert ```python Concept.revert(fields: str = ()) -> Concept ``` Revert overridden fields to their detected values; all locked fields when none given. **Returns** (`Concept`): This handle, refreshed with the updated document. ## Ontology The workspace's semantic layer: concepts, and the query engine over them. ### Properties * **concepts** (`pd.DataFrame`) ### Ontology.link ```python Ontology.link() -> Any ``` The workspace's ontology page on the platform, as a clickable URL. ### Ontology.concept ```python Ontology.concept(needle: str | Concept) -> Concept ``` Resolve a concept by name or id into a [`Concept`](#concept) handle. Raises when the name matches more than one concept — resolve those through [`matching`](#matching) or an id. ### Ontology.matching ```python Ontology.matching(name: str) -> list[Concept] ``` Every concept whose name matches — the disambiguation escape hatch. ### Ontology.override ```python Ontology.override( concept: str | Concept, *, metadata: dict[str, Any] | None = None, overrides: Any = {}, ) -> dict[str, Any] ``` Override a concept's metadata or structure, locked against re-profiling. Overridden metadata fields are marked as human-set: the auto-profiler preserves them on every future ingest, and the detected value keeps shadowing underneath (see [`revert`](#revert)). Setting a field back to its detected value unlocks it again. The idiomatic flow resolves the concept once and operates on the [`Concept`](#concept) handle: ```python revenue = onto["Revenue"] revenue.override(monotonically_increasing=True, min_value=0) revenue.override(unit="GBP", nan_fill_strategy="interpolate") revenue.revert("unit") ``` This method also accepts a name or id directly as a convenience. | Parameter | Type | Default | Description | | ------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `concept` | `str \| Concept` | required | Concept name or id. | | `metadata` | `dict[str, Any] \| None` | `None` | Any concept metadata field by its camelCase name, for fields without a keyword below. | | `**overrides` | `Any` | `{}` | Metadata keywords — `monotonically_increasing`, `monotonically_decreasing`, `min_value`, `max_value`, `unit`, `unit_modifier`, `nan_fill_strategy`, `categories`, `date_time_format`, `display_format`, `is_cyclic`, `is_unique` — and concept-level `name`, `description`, `classification`, `schema_type`, `schema_subtype`, `suggested_role`, `temporal_prerequisites`. | **Returns** (`dict[str, Any]`): The updated concept document. ### Ontology.revert ```python Ontology.revert(concept: str | Concept, fields: str = ()) -> dict[str, Any] ``` Revert overridden metadata fields to their auto-detected values. Setting a field back to its detected value also unlocks it, so the profiler owns it again on future ingests. | Parameter | Type | Default | Description | | --------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `concept` | `str \| Concept` | required | Concept name or id. | | `*fields` | `str` | `()` | Fields to revert, as `override` keywords or camelCase metadata names. With none, every locked field reverts. | **Returns** (`dict[str, Any]`): The updated concept document. ### Ontology.locks ```python Ontology.locks(concept: str | Concept) -> pd.DataFrame ``` The concept's overridden metadata fields: current value vs detected. | Parameter | Type | Default | Description | | --------- | ---------------- | -------- | ------------------- | | `concept` | `str \| Concept` | required | Concept name or id. | **Returns** (`pd.DataFrame`): One row per locked field, with `value` and `detected` columns. ### Ontology.sql ```python Ontology.sql( statement: str, *, limit: int = 1000, start_key: int | None = None, projection_mode: Literal['related', 'minimal'] = 'related', ) -> AnchorSqlResult ``` Run an Anchor SQL statement over the workspace's concepts. Anchor SQL is SQL over ontology concepts, not tables. Concepts go by quoted name, and the ontology plans the joins across every mapped source — there are no tables to FROM and no JOINs to write (`FROM source:"name"` exists only to narrow scope). The reserved anchors are `entity`, `time` and `location`; `time` and `location` additionally take grains like `time(month)` or `location(country)`, while `entity` takes no arguments; aggregates with GROUP BY / HAVING / ORDER BY / LIMIT work as in SQL, and metrics defined in the workspace are referenced by name verbatim. `SHOW CONCEPTS`, `SHOW METRICS`, `SHOW SOURCES` and `DESCRIBE "x"` answer metadata about what there is to query. ```python onto.sql('SELECT "Monthly Charges" WHERE "Contract" = \'Month-to-month\'') onto.sql('SELECT time(month), avg("Revenue") GROUP BY time(month)') onto.sql("SHOW CONCEPTS") onto.sql('DESCRIBE "Revenue"') ``` | Parameter | Type | Default | Description | | ----------------- | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `statement` | `str` | required | The Anchor SQL statement. | | `limit` | `int` | `1000` | Rows per page, 1 to 10000. | | `start_key` | `int \| None` | `None` | Resume paging from a previous result's `next_start_key`. [`to_frame`](#to_frame) pages transparently, so this is only for driving pages by hand. | | `projection_mode` | `Literal['related', 'minimal']` | `'related'` | `related` adds ontology-linked context columns; `minimal` returns only selected concepts and their anchors. | **Returns** (`AnchorSqlResult`): An [`AnchorSqlResult`](#anchorsqlresult) — rows for a SELECT, a metadata listing for SHOW/DESCRIBE. **Raises** * `AnchorSqlError`: The engine refused the statement; carries the error code, the offending span, near-miss candidates and a suggested corrected statement when the engine has one. ### Ontology.query ```python Ontology.query(args: Any = (), kwargs: Any = {}) -> NoReturn ``` Removed — the query endpoint now speaks Anchor SQL; use [`sql`](#sql). ### Ontology.ask ```python Ontology.ask(args: Any = (), kwargs: Any = {}) -> NoReturn ``` Removed — server-side translation is gone; write Anchor SQL with [`sql`](#sql).