Agent skill · data analytics · aiskillstore
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 using the `icp` CLI 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-07. 405 stars on the source repository.
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 aiskillstore/extension-querying-oql