About Queries

This document provides detailed information on how to use query filters for various list endpoints in the ledger service, in order to precisely narrow down records that the api caller is interested in. The filtering mechanism follows (unrelated to the actual DB the ledger uses) the syntax of MongoDB query filters and is implemented through query parameters

Supported Endpoints

Filtering can be applied to all records that have an endpoint that lists them, e.g. /intents, /wallets, etc.

Query Operators

At the moment, the following query operators are supported:

Filtering Syntax

Filters are passed through query parameters. The syntax follows the pattern of some.field.path.$operator=value. If no operator is listed, $eq is assumed.

The path of a field is the same as in the response when fetching a record of the same type. So, if intent has a data property with a handle that is a string, the path for filtering by handle is data.handle

If the query params contain multiple filters, they must all be a match for a record to be returned.

Below are some examples to illustrate how filters can be used:

GET /v2/intents?data.handle.$eq=my-intent
# these two calls are equivalent
GET /v2/intents?data.handle=my-intent 

The above filter will match intents where data.handle equals my-intent.

GET /v2/wallets?data.schema.$eq=bank-wallet

The above filter will match wallets the schema of which is bank-wallet.

GET /v2/wallet?meta.status.$eq=active

The above filter will match wallets that are marked as active.

Using Filters with SDK

The ledger SDK supports filtering with typings to aid with autocomplete and type-checking. Here is an example of how to use filters with the SDK:

const { wallets, response, page } = await sdk.wallet.list({
    page: {
        index: 0,
        limit: 10,
    },
    "meta.moment.$gt": new Date('2021-01-01T00:00:00Z'),
});

Due to technical limitations, the only property type that does not support autocomplete and type-checks is filtering of individual items in array fields like data.claims in intents. Exact matches may still be filtered and autocompleted with something like the following:

const { wallets, response, page } = await sdk.wallet.list({
    page: {
        index: 0,
        limit: 10,
    },
    "data.claims.$eq": [{ 
        action: 'transfer', 
        amount: 50, 
        source: 'abcd', 
        target: 'defg', 
        symbol: 'usd' 
    }],
});

The below section describes the principles for filtering of items contained in arrays.

Array Property Filtering

For array properties like claims in intents, two types of filtering can be applied:

1. Specific Index Filtering

   GET /v2/intents?data.claims.0.amount.$gt=20

   This filter will match intents where the first claim's amount is greater than 20. Equivalent SDK:

   const { wallets, response, page } = await sdk.wallet.list({
       page: {
           index: 0,
           limit: 10,
       },
       "data.claims.0.amount.$gt": 20,
   });

2. Any Element Filtering

   GET /v2/intents?data.claims.amount.$gt=20

   This filter will match intents where any claim's amount is greater than 20. Equivalent SDK:

   const { wallets, response, page } = await sdk.wallet.list({
       page: {
           index: 0,
           limit: 10,
       },
       "data.claims.amount.$gt": 20,
   });

Known Limitations

• Some fields are not filterable, depending on record. If a user attempts to filter by a non-supported field, an error will be returned indicating which fields are not supported.
• Currently, some filtering is done in memory. Future versions of the ledger will optimize this by processing more filters in the database for efficient querying.
• For now, querying is done in query params on GET endpoints. Due to syntax limitations, we do not currently support $and and $or operators. Everything is assumed to be under one root $and. In the future, we may introduce POST endpoints for search, where these operators may be used to build more complex expressions.