Agent skill · data analytics · caffeinelabs
extension-querying-oql
Quick reference for the Caffeine Data Intelligence agent to query an OQL-exposing canister (schema() + execute()) through the `icp` CLI against the project's `backend` canister: read the schema, form JSON queries (filter / order / paginate / aggregate / dotted-path edges), and parse the Candid result rows.
Why this skill is useful
Provides specific commands and patterns for querying an OQL canister that the AI wouldn't reliably generate on its own.
What it needs
Requires icp installed locally. About 10k tokens when loaded. Last updated 2026-08-06.
What this skill does
Querying OQL — quick reference An OQL canister exposes two read-only methods: Method Returns Purpose --- --- --- schema() one JSON Text Catalogue of the canister's entities: each entity's primary key, fields, and edges. execute(qJson : text) typed Candid Result Runs a JSON-encoded query and returns matching rows. Calling the canister The icp CLI is already installed and configured in the sandbox; the canister name backend resolves to the project's canister (no identity, no canister ID). Both methods are query calls, so every invocation uses --query: execute takes one text argument — the JSON query embedded as a Candid text literal. Wrap the JSON in ("...") and escape every " as \". The query {"start":"customer","limit":3} becomes: schema() returns its JSON the same way — a Candid text literal ("...escaped json..."); unescape \" → " (and \\ → \) to read it. Add --branch live to read the deployed canister instead of the draft (live is query-only). If a string value contains a single quote, escape it for the shell with '\''. --- Recipe 1. Get the schema once. icp canister call backend schema '()' --query — cache it for the session; it changes only between deployments (§1). 2. Map the request to entities. Pick the entity that holds the answer. Use each field's typeName and values to choose literal types, and role: {"edge": ...} to see how entities connect. 3. Translate into one or more queries. Start from the entity whose rows you want (§2). Add where (§2.1), orderBy / limit / offset, select, and aggregate / groupBy (§2.2). Cross a forward edge with a dotted path in a single query (§4.1); a reverse one-to-many needs the parent keys first, then in (§4.2). 4. Run and read. icp canister call backend execute '("<json>")' --query — parse the Candid rows by cell name (§3); if hasMore, page with offset (§5). 5. Retry on traps. There is no error envelope — re-read the schema, fix the query, rerun (§6). --- 1. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills caffeinelabs/extension-querying-oql