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 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

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

Concept.get(key: str, default: Any = None) -> Any

Undocumented; the signature above is the contract.

Concept.refresh

Concept.refresh() -> Concept

Re-read the concept from the platform.

Concept.override

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 for the keyword vocabulary.

Returns (Concept): This handle, refreshed with the updated document.

Concept.revert

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

Ontology.link() -> Any

The workspace's ontology page on the platform, as a clickable URL.

Ontology.concept

Ontology.concept(needle: str | Concept) -> Concept

Resolve a concept by name or id into a Concept handle.

Raises when the name matches more than one concept — resolve those through matching or an id.

Ontology.matching

Ontology.matching(name: str) -> list[Concept]

Every concept whose name matches — the disambiguation escape hatch.

Ontology.override

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). Setting a field back to its detected value unlocks it again.

The idiomatic flow resolves the concept once and operates on the Concept handle:

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

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

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

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 entity, time and location take grains like time(month) or location(country); 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.

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 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 — 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

Ontology.query(args: Any = (), kwargs: Any = {}) -> NoReturn

Removed — the query endpoint now speaks Anchor SQL; use sql.

Ontology.ask

Ontology.ask(args: Any = (), kwargs: Any = {}) -> NoReturn

Removed — server-side translation is gone; write Anchor SQL with sql.