API Documentation


Filtering, sorting and paging

Blocktap supports advanced filtering, sorting and paging to retrieve exactly the data you need.

Filtering

The filter argument is supported on types that return an array of results, such as assets, markets, and exchanges. The filter input field accepts an object that includes one or more terms to filter the resultset on. Each filter term is a combination of the name of the field and an operator that will be performed against the field.

Filter objects take the form:

{
  field1: { operation1: value }
  field2: { operation2: value }
}

An operator is the right hand side. This object consists of two parts: the operation and the value. An operator looks like {_eq: 100} which means equals 100.

When we combine a field with an operator we create a filter. For example, filtering assets by market cap marketCap greater than gt 4000 would look like:

{
  marketCap: {_gt: 4000}
}

You can filter by multiple fields as well. For example filtering assets that have a type of Coin and are named bit% would look like:

{
  assetType: {_eq: Coin}
  assetName: {_like: "bit%"}
}

All filters follow this same structure. However, each field will have operators that are specific to its type. Below are some examples of the base types: String, Int, and Enum.

String Filter

Name Meaning Accepts Notes
_eq Equal to String
_neq Not equal to String
_like Like String Accepts % as wildcard
_in Value in Array of strings
_nin Value not in Array of strings
query someAssets {
  assets(filter: { assetName: { _like: "bit%" } }) {
    assetName
    assetSymbol
  }
}

Numbers

Name Meaning Accepts
_eq Equal to Number
_neq Not equal to Number
_gt Greater than Number
_gte Greater than or equal to Number
_lt Less than Number
_lte Less than or equal to Number
query someAssets {
  assets(filter: { marketCapRank: { _lt: 20 } }) {
    assetName
    assetSymbol
  }
}

Enum

Name Meaning Accepts
_eq Equal to Enum value
_neq Not equal to Enum value
_in Value in Array of enum values
_nin Value not in Array of enum values
query someAssets {
  assets(filter: { assetType: { _eq: Coin } }) {
    assetName
    assetSymbol
  }
}

Boolean Operators

Filters can be nested inside of boolean operators. These can create complex filters for advanced searching.

Name Meaning Accepts
_and All the filters inside the _and object must match Filter object
_or At least one of the filters inside the _or object must match Filter object

For example, to add omnibox style search for assets, we may write a query like this:

query Omnibox {
  assets(
    filter: { _or: [{ assetName: { _like: "%Bit%" } }, { assetSymbol: { _like: "%Bit%" } }] }
  ) {
    assetName
  }
}

Sorting

Sorting works on most of the same fields as filtering. The sort argument accepts an object where each name is the field to sort by and the value is the direction. Sort accepts multiple values and will use the order the values are supplied as the sort order. For example:

sort: {
  baseSymbol:DESC
  exchangeSymbol:ASC
}

This sort argument will sort first by base symbol in a descending order, then exchange symbol in ascending order.

Paging

Pagination in Blocktap happens via the page object. Page accepts two parameters, limit and skip. Limit is the number of results you want to get back. Skip is the number of results you want to skip.

As an example for pagination, we have 25 assets per page, and the user is on the third page. We limit to 25 results and skip 50 ( (page - 1) * limit ).

query Pages {
  assets(page: { skip: 50, limit: 25 }) {
    assetName
  }
}