Skip to main content

Filtering

Treasury API​

When applicable, data queried on our Treasury API can be filtered using the filter=<FILTER> query argument. The value for this filter must be compatible with AIP-160.

Example: Query all accounts of variant internal.

curl localhost:8777/v1/accounts -G --data-urlencode 'filter=variant = "internal"'

Example: Query all accounts with note "description" of value "desc1".

curl localhost:8777/v1/accounts -G --data-urlencode 'filter=notes.description = "desc1"'

Indexes​

Treasury maintains indexes on various fields for all of the resources. For any given filter, Treasury will try to match to an internal index to speed up the query.

If you are filtering a large number of items (e.g. millions), it is worth ensuring you are using a filter that is compatible with an index.

The currently implemented indexes are listed here.

Details

All resources​

All resources maintain indexes on labels and notes.description. Any filter on a label or the description will be fast.

  • By label labels.user_id = "42"
  • By label prefix labels.user_id = "4*"
  • By description notes.description = "gas tank"
  • By description prefix notes.description = "gas*"

Addresses​

  • By chain: name="chains/CHAIN/*"
  • By address ID: name="chains/CHAIN/addresses/ADDRESS_ID"
  • By address ID prefix: name="chains/CHAIN/addresses/ADDRESS*"
  • By address ID: address="ADDRESS_ID"
  • By address ID prefix: address="ADDRESS*"
  • By account: account="accounts/ACCOUNT"
  • By account prefix: account="accounts/ACCO*"

Transactions​

  • By state: state="preparing"
  • By origin: origin="transfers/42"

Signatures​

  • By state: state="signing"

Keys​

  • By state: state="generating"

Do's and Don'ts​

Do not include OR conditions in your query, as this will most likely prevent an index from being used. Using AND conditions is fine.

Oracle API​

Various endpoints on oracle.cordialapis.com support filtering and ordering.

Depending on the resource, the following fields typically can be targetted:

  • create_time
  • update_time
  • block.time
  • block.height
  • block.hash
  • block.chain_id
  • confirmations
  • failed
  • asset_id
  • to_id
  • balance

Examples:

  • Filter by chain: filter='block.chain_id="SOL"'
  • Filter by confirmations: filter='block.confirmations < 10'

Ordering​

Values in order_by should be a comma separated list of fields, with an optional " desc" or " asc" suffix. Default ordering is descending (" desc").

Examples:

  • Sort by block height: order_by=block.height
  • Sort by confirmations: order_by=confirmations asc
  • Sort by update_time: order_by=update_time desc