Querying the Ontology

The Octostar ontology is a semantic data layer backed by Timbr. You query it using SQL through platform-specific table namespaces.

Table Namespaces

Namespace	Contents	Example use
timbr	Concept-specific tables — one table per concept type	timbr.os_file, timbr.os_tag, timbr.person
etimbr	Extended workspace views — filesystem objects and workspace items across all types	etimbr.os_workspace_item, etimbr.os_wsfs_object
dtimbr	Denormalized/display views — pre-joined data suited for listing and browsing	dtimbr.os_workspace

From the Frontend (OntologyAPI)

const { OntologyAPI } = useOctostarContext()

const workspaces = await OntologyAPI.sendQueryT<WorkspaceRow>(
  "SELECT os_entity_uid, entity_label FROM dtimbr.os_workspace"
)

From the Backend (Octostar SDK)

The Octostar Python client is not in requirements.txt — it is downloaded at container startup by main.sh directly from your platform instance, so it always matches the running version.

import asyncio
from octostar.utils.ontology import query_ontology

result = await asyncio.to_thread(
    client.execute,
    query_ontology.sync,
    "SELECT os_entity_uid, entity_label FROM dtimbr.os_workspace"
)

The SDK is synchronous. Wrap all SDK calls with asyncio.to_thread to avoid blocking the FastAPI event loop.

Common Queries

List workspaces:

SELECT os_entity_uid, entity_label, os_item_content
FROM dtimbr.os_workspace

List files in a workspace:

SELECT os_entity_uid, entity_id, entity_label, entity_type,
       os_item_content_type, os_content_size
FROM timbr.os_file
WHERE os_workspace = '{workspace_id}'

List all items (files + folders) in a workspace:

SELECT os_entity_uid, entity_id, entity_label, entity_type,
       os_item_content_type, os_content_size
FROM etimbr.os_workspace_item
WHERE os_workspace = '{workspace_id}'

Get folder contents:

SELECT os_entity_uid, entity_id, entity_label, entity_type
FROM etimbr.os_wsfs_object
WHERE os_workspace = '{workspace_id}'
AND (os_parent_folder = '{folder_id}' OR os_parent_folder_uid = '{folder_id}')

List tags:

SELECT os_entity_uid, entity_label, os_workspace, color
FROM timbr.os_tag

List template files (.aiquestions) in a workspace:

SELECT os_entity_uid, os_parent_folder, os_workspace, entity_label
FROM timbr.os_file
WHERE entity_label LIKE '%.aiquestions'
AND os_workspace = '{workspace_id}'

SQL Safety

Always escape user-provided values before interpolating into SQL strings:

def escape_sql_string(value: str) -> str:
    return str(value).replace("'", "''") if value