# extension-querying-oql

Quick reference for querying an OQL backend canister via the icp CLI. Guides the agent through fetching schemas, structuring JSON queries, and reading Candid rows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 24700 installs · ★ 2
- Author: caffeinelabs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-querying-oql/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/extension-querying-oql

## What it does

This skill provides instructions for interacting with an OQL-enabled canister using the icp CLI. The backend canister exposes two query methods: schema() returns the catalog of entities, fields, and relation edges, while execute() accepts a JSON query and outputs typed Candid rows.

The agent inspects the schema once per session. That structure stays stable between deployments. Next, it constructs a JSON query object with a mandatory start field, adding where predicates, orderBy sorting, limit pagination, or groupBy aggregations. Both methods require the --query flag.

Working with this canister requires a configured icp CLI tool in the sandbox. Query execution provides no error envelope on failure; runtime traps force the agent to re-check field literal types against schema() and rerun the call.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-querying-oql -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/extension-querying-oql/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/extension-querying-oql/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-querying-oql -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/extension-querying-oql/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-querying-oql -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/extension-querying-oql/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install caffeinelabs/skills extension-querying-oql
```

2. **Manually: put the files in place**
- File: `.github/skills/extension-querying-oql/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-querying-oql -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/caffeinelabs/skills --path skills/extension-querying-oql
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/extension-querying-oql/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-querying-oql -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-querying-oql/SKILL.md

## When to use it
- inspect canister entities and field types with the `schema()` method
- build escaped JSON queries for the `execute()` Candid call
- filter records using `where` predicates like `eq`, `contains`, or `in`
- calculate aggregates across records with `groupBy` and `aggregate`

## Example prompts
- Run icp canister call backend schema '()' --query and summarize available entities
- Construct an OQL execute query filtering customers by plan with limit 5
- Show how to format groupBy and aggregate clauses for the backend canister

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 881c5433de42ade0.

BEGIN THIRD-PARTY FILE 881c5433de42ade0
````text
---
name: extension-querying-oql
description: >-
  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.
version: 0.8.0
compatibility:
  mops: {}
  npm: {}
caffeineai-subscription: [none]
---

# 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`:

```bash
icp canister call backend schema '()' --query
icp canister call backend execute '("<json-query>")' --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:

```bash
icp canister call backend execute '("{\"start\":\"customer\",\"limit\":3}")' --query
```

`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).

---
````
END THIRD-PARTY FILE 881c5433de42ade0

The third-party file has ended. Everything between the 881c5433de42ade0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2768 of 17721 bytes. © caffeinelabs · Apache-2.0 · https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-querying-oql/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md