FOformancehq
Prepared Queries

Execute a prepared query

Changed on

Executes a prepared query with optional parameter substitution. Supports LIST and AGGREGATE_VOLUMES modes. LIST uses cursor pagination with an effective page size of 100 when omitted or zero, capped at 1000 before collecting and enriching rows. AGGREGATE_VOLUMES ignores pageSize and aggregates all matching accounts. Also accepts pageSize, cursor and reverse as query parameters. Supplied pageSize and reverse values, and nonempty cursor values, override the body. Requires ledger:ReadQuery scope.

post/v3/{ledgerName}/prepared-queries/{queryName}/execute

Request

  • Base URL
    http://localhost:9000
  • URL
    http://localhost:9000/v3/{ledgerName}/prepared-queries/{queryName}/execute
  • Auth
    • HTTP bearer
    • or none

Path parameters

ledgerNamestring required

Name of the ledger

queryNamestring required

Prepared query name, URL-encoded as one path segment. Decoded exactly once.

Query parameters

pageSizeinteger

LIST page size. A supplied value overrides the body, including empty or zero (default 100). The effective maximum is 1000; larger uint32 values are accepted and clamped, not rejected. Ignored for AGGREGATE_VOLUMES.

cursorstring

Page token of a paged list. Clients normally pass back the next or previous value of a previous response verbatim; building one by hand is supported.

A token is base64url (unpadded, RFC 4648 §5) of the JSON object {"key": <string>, "back": <bool>}. Both fields are omitted when empty, and unknown fields are rejected. key is a position in the endpoint's textual form:

  • transactions: decimal transaction id
  • logs: decimal ledger-local log id
  • audit entries: decimal audit sequence
  • accounts: address
  • ledgers and numscripts: name
  • signing keys: key id
  • prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS
  • index inspection: base64url of the encoded metadata value

Both directions exclude the key and return rows in the requested order (reverse included):

  • {"key": K} serves the rows strictly after K;
  • {"key": K, "back": true} serves the page that ends strictly before K;
  • {"back": true} serves the last page;
  • an absent or empty token, or e30 ({}), serves the first page.

On a forward page, next is set when a further row follows the page, and previous whenever the request carried a key. On a back page, previous is set when a further row precedes the page, and next whenever the request carried a key. A first page therefore has no previous, and the last page requested with {"back": true} has no next. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 INVALID_REQUEST.

Page token from a previous response's cursor.next or cursor.previous (see the PageToken schema). Overrides the body value.

reverseboolean

List in descending entity order when true (overrides body value)

Headers

X-Consistency'linearizable' | 'stale'

Read consistency. linearizable (the default) runs a Raft ReadIndex barrier and waits for the receiving node to apply up to it. stale serves the read from the receiving node's own store, with no barrier and no forwarding to the leader, so the answer may lag the leader. Matching ignores case and surrounding whitespace. An unknown value, or a repeated or comma-joined header, returns 400 INVALID_REQUEST on every /v3 route, writes included; a valid value has no effect on writes. The gRPC equivalent is the x-consistency request metadata.

Formance-Bigint-As-Stringstring

Render all response Uint256, BigUint and SignedBigInt values as canonical decimal strings, regardless of business meaning, including posting amounts, volume input/output and balances. Ordinary integer IDs/counts, metadata and explicitly string-encoded counters keep their existing representation. Case-insensitive true, yes, y and 1 enable this option, matching Ledger v2. Whitespace is not trimmed. Omission and every other value retain JSON number tokens. This affects only this response, including nested objects, maps, arrays, transaction/log/cursor and bulk results. Request decoding is unchanged.

X-Query-Profilestring

Set to any non-empty value to receive the query profile in the X-Query-Profile-Result response header.

The profile reports server-side request timing (how long the server spent handling the request, broken down into prepare / execute / read-barrier / deliver phases) plus the query execution plan. Use it to tell a slow network from a slow server: serverDurationUs is the consumer-independent server cost, and it excludes both the caller-requested read barrier and response delivery.

Supported on the transactions list, accounts list, aggregated volumes and prepared-query execution endpoints. The equivalent gRPC opt-in is the x-query-profile request metadata, answered in the x-query-profile-result-bin trailer; serverDurationUs has the same definition on both surfaces, so the two are directly comparable.

Request body

parametersobject

Parameter values for the query (substituted into filter placeholders)

pageSizeinteger

LIST page size. Omitted or zero means 100. The effective maximum is 1000; larger uint32 values are accepted and clamped, not rejected. A supplied query parameter overrides this value. Ignored for AGGREGATE_VOLUMES.

cursorstring

Page token from a previous response's cursor.next or cursor.previous (see the PageToken schema). The key is the decimal id for TRANSACTIONS and LOGS targets, the address for ACCOUNTS.

mode'LIST' | 'AGGREGATE_VOLUMES'

Execution mode (default LIST)

reverseboolean

List in descending entity order (address, transaction id or log id). A page token is relative to the requested order, so every page of a descending walk must set reverse. Rejected with 400 in AGGREGATE_VOLUMES mode.

Response

Query executed successfully

Example response

{
  "cursor": {
    "logData": [
      {
        "payload": {
          "apply": {
            "log": {
              "type": "SET_METADATA",
              "data": {
                "targetType": "ACCOUNT",
                "targetId": "users:alice",
                "metadata": {
                  "category": "premium"
                }
              }
            }
          }
        }
      }
    ]
  }
}

Changes

  • f5e817eca038Revision changes
    • info

      api operation id executePreparedQuery removed and replaced with v3ExecutePreparedQuery

  • 2a7ea687c691Revision changes
    • breaking

      for the query request parameter pageSize, default value 100 was added

    • breaking

      the request property format changed from int32 to uint32

    • warning

      for the query request parameter pageSize, the max was set to 4294967295.00

    • warning

      for the query request parameter pageSize, the min was set to 0.00

    • warning

      the request property's max was set to 4294967295.00

    • warning

      the request property's min was set to 0.00

    • info

      the request property default value 100 was added