FOformancehq
Indexes

Inspect a metadata index

Changed on

Scans a metadata index and returns distinct values, facets (value + count), or a summary (cardinality, min/max, existence counts). The index must be in READY state. Only metadata indexes are inspectable (builtin indexes return 400). Requires ledger:read scope.

get/v3/{ledgerName}/indexes/{canonicalId}/inspect

Request

  • Base URL
    http://localhost:9000
  • URL
    http://localhost:9000/v3/{ledgerName}/indexes/{canonicalId}/inspect
  • Auth
    • HTTP bearer
    • or none

Path parameters

ledgerNamestring required

Name of the ledger

canonicalIdstring required

Canonical form of the target IndexID, e.g. metadata:TARGET_TYPE_ACCOUNT:color. Must resolve to a metadata index; builtin indexes (tx_builtin:..., etc.) are rejected.

Query parameters

mode'summary' | 'distinctValues' | 'facets'

Inspection mode. The deprecated distinct-values alias for distinctValues remains accepted. An explicitly empty or unsupported value returns 400.

pageSizeinteger

Page size for distinctValues/facets modes (defaults to 100 when omitted). Any supplied value must be in 1..10000, including in summary mode, which does not use pagination. Empty or invalid values return 400.

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 nextCursor or previousCursor, for distinctValues/facets modes (see the PageToken schema; the key is the base64url encoding of the metadata value). Omit for the first page.

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.

Response

Index inspection result

Changes

  • f5e817eca038Revision changes
    • info

      api operation id inspectIndex removed and replaced with v3InspectIndex

  • 3da23d327316Revision changes
    • info

      added the media type text/plain for the response with the status

    • info

      added the media type text/plain for the response with the status