> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.cessy.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server. # Projection Queries > Query Cessy projections with filters, sorting, pagination, and output shaping while preserving generated runtime contracts. Projection queries read current runtime state. They should be narrow, predictable, and tied to the projection's published schema. Legacy Design MCP v1 `query_projection_data` can target a Design Workspace with `workspaceId`. That read lazily activates the exact Workspace runtime scope and uses the same fenced projection namespace as Custom Page preview, including both inherited published projections and projections added in the Workspace. Activation failures return structured `reason`, `workspaceId`, and `recoveryAction` fields; follow the returned action before retrying. ## Common controls | Control | Purpose | | -------- | ---------------------------------------------------------- | | `limit` | Maximum number of rows to return. | | `offset` | Pagination offset. | | `sort` | Sort field and direction when supported by the projection. | | `filter` | JSON filter expression over projection fields. | Exact query parameters come from the generated OpenAPI contract for the app. For REST list endpoints, pass projection predicates as a URL-encoded JSON object in `filter`, for example `?filter=%7B%22status%22%3A%22scheduled%22%7D`. Direct field parameters such as `?status=scheduled` return `400`; they are never silently ignored. ## Filter shape Use structured filters instead of string-built query fragments. Supported operators depend on the projection query contract and can include equality, containment, prefix matching, and case-insensitive matching. Scalar equality also matches array-valued fields containing that scalar. For example, `{ "tags": "urgent" }` matches `tags: ["urgent", "customer"]`. Avoid unbounded text search unless the projection is designed for it. ## Policy polling Each awaited `ctx.getProjection(...)` call in a custom-code policy bypasses response caches and executes a new live read against the policy's exact Production or Workspace runtime source. A Workspace callback never falls back to Production. Every callback is capped at 30 seconds and below the policy handler's remaining absolute deadline, with a terminal guard. Deadline expiry aborts cooperative work and returns a structured retryable response without waiting for an uncooperative storage call. The `projection_callback` slot remains occupied until every underlying physical read settles, so timed-out work cannot escape the process-wide bound. If no lease is available in budget, runtime returns a retryable 503 in phase `admission` before resolving the runtime or reading the projection. Queue and server timing remain charged to the one handler deadline. Policy execution evidence retains up to 32 bounded, value-free `projectionCallbackDiagnostics` entries for successful and failed reads. They record outcome, phase, exact source, elapsed time, timeout, remaining budget, response reach/status, and query shape. Document IDs, filters, response bodies, and error messages are excluded. HTTP policy workers bind each callback to the runtime-config revision that produced their projection manifest. Unknown projections and invalid app ownership are distinct non-retryable failures. A stale worker/runtime revision or a transient app/runtime-registry lookup is marked retryable and remains under the durable invocation's bounded retry or reconciliation contract; it never falls back to another runtime source. Operator diagnostics state whether to correct ownership/configuration or reconcile the current invocation. Poll with a finite attempt or deadline limit and add delay or backoff between attempts. List reads remain capped at 1,000 documents per call. Separate calls, especially calls to different projections, are not one atomic snapshot. When a completion decision depends on several projections, require two consecutive stable exact reads before returning the completion command. An intentional settle or retry path may return no command. ## Output shaping Projection tools and APIs can support output controls to reduce payload size. Use them for agent workflows so the model receives only the fields needed for the task. ## Copying fixtures to a Workspace On legacy Design MCP v1, `copy_projection_document_to_workspace` can copy Production read-model documents into a Workspace without replaying events. Use the singular `id` from a query or page diagnostic `copyAction` for one document. Existing singular calls remain compatible. For an exact set, pass `ids` (1 to 500, at most 1,024 UTF-16 code units per ID) and an `idempotencyKey`. Optional `expectedSourceHashes` and `expectedSourceAggregateHash` pin the copy-safe Production snapshot. Optional `expectedTargetHashes` provides per-ID target CAS: `null` requires absence, while a hash permits replacement only with `overwrite: true`. Hashes are lowercase 64-character SHA-256 hex values, and per-ID maps may only name selected IDs. Existing identical documents are deterministic no-ops. Exactness is scoped to the requested manifest. Counts and aggregate hashes do not include unrelated destination documents, and the operation never deletes those documents. Hashes use projection-copy canonical JSON v1: SHA-256 over UTF-8, with object keys sorted by UTF-16 code units at every depth. Arrays preserve order, `undefined` object properties are omitted, and `undefined` array entries become `null`. A document hash covers the default-redacted document. The aggregate input is the UTF-16-code-unit-ID-sorted array of `{ "id": , "hash": }` objects, canonicalized the same way. For a fixed check, `{ "é": 1, "z": 2, "😀": 3 }` becomes `{"z":2,"é":1,"😀":3}` and hashes to `4177f29d85d48c133fea6e4531c5817e8ad4a86eca582296fe34d6322db0799c`. Cessy de-duplicates and sorts the manifest and processes document work through a process-wide shared FIFO scheduler with two permits. The first source hashes are persisted and rechecked before write and during final verification. The durable result contains counts, per-ID statuses and source/target hashes, plus aggregate hashes when complete; it contains no document bodies. After a timeout, call the same tool with `operation: "status"` or `"resume"` and the original app, Workspace, projection, and key. Omit the IDs, hashes, and overwrite flag for those operations. A completed receipt is immutable point-in-time evidence; use a new key to verify the target after later Workspace mutations. Hashes cover the default-redacted document payload that is actually copied, not raw secret-bearing Production storage. The fixture is Workspace-only and non-event-backed: Production is not mutated, and no commands, events, policies, triggers, subscriptions, or external HTTP run. This capability is not on the current Design MCP vNext surface. vNext remains the five-tool Begin/Inspect/Apply/Evaluate/Finalize lifecycle, and its evaluation-only projection snapshot flow is tracked separately. ## Builder guidance Design projections around real read questions. If every client has to fetch a large projection and filter locally, the projection shape is probably wrong.