Query a consistent set of Arkiv entities

When to use

Use this skill to turn a known entity model into a read query. Use arkiv-data-modeling when field encodings or relationships are undecided, arkiv-security-trust for publisher/auth decisions, and arkiv-troubleshooting first when the task includes an existing error.

Inspect the installed SDK version and declarations. This guidance targets SDK 0.8.1 and Tiramisu; SDK exports and node capabilities differ. For Python, Rust or tools without this SDK, read json-rpc.md for the current wire protocol instead of adapting an older SDK API from memory.

Rules that change the result

• .fetch() requires at least one filter: .where(...), .ownedBy(...) or .createdBy(...). Raw arkiv_query also accepts *; use a bounded, scoped query for application reads rather than scanning the shared database.
• .where() accumulates predicates with AND. Repeated .ownedBy() or .createdBy() replaces that respective filter. Use or(...) for alternatives.
• Pair every predicate with its write constructor. A bare number is i32, bigint is u256, string is str, boolean is bool. u64 timestamps and expiry blocks must remain u64 in queries.
• A typed predicate matches only cells stored with that type. gte('price_minor', u256(0n)) also excludes legacy i32 prices; a bare-number predicate does the reverse. Do not replace this with unsupported EXISTS or TYPEOF.
• Use .createdBy(trustedAddress) or $creator = addr(...) for original publisher scope. $owner is current mutation authority and can change after transfer. project and entity_type are namespaces, not authentication.
• Pin a block from getBlockNumber({ cacheTime: 0 }) with .atBlock(snapshot) for a complete walk. Preserve query, projection and snapshot across its opaque cursors. page.next() returns a new immutable page; reassign the variable. The previous page stays readable.
• Pages hold at most 200 entities. A short or full page does not prove completion: check hasNextPage(). Bound requests and restarts; return complete results or an explicit error, never silently treat a partial set as complete.
• A typed QueryError with kind === 'cursor' can restart the complete walk. Discard accumulated rows. For a current-state read, choose a fresh snapshot; for an explicitly historical read, keep its requested block. A block error must preserve that historical intent and surface the failure.
• Current Tiramisu returns matches newest first by creation block, with descending keys within a block. For the latest N by creation, a first page with limit(N) suffices when N is at most 200. There is no arbitrary attribute ordering or general aggregate API: fetch every page in scope and sort a copy for attribute-based top-N. A raw filtered count is available; SDK getEntityCount() is chain-wide.