Customizable Output Queries

Customizable output queries, also known as dynamic queries or flexible-output queries, allow users to specify which fields to include in the response. This flexibility enables users to tailor the query results to their specific needs.

Advantages:

• Flexibility: Users can select only the data they need, reducing the amount of unnecessary information.
• Efficiency: Customizable queries can improve performance by fetching only the required fields.
• Adaptability: Easily adjust queries to meet different data requirements without changing the underlying query structure.

On this page, we demonstrate through simple examples how to selectively query different data elements.

We will employ Parametrized Queries to maintain generality and flexibility in our examples.

Example: Retrieving Index Data

This section provides an illustrative example to demonstrate how to fetch index data from a specific source within a given time range.

Example Query

query myIndexQuotes($spotQuotesInput: SpotQuotesInput!) {
  spotQuotes(spotQuotesInput: $spotQuotesInput) {
    source
    price {
      mid
    }
  }
}

Explanations:

• query myIndexQuotes initiates the GraphQL query block, while myIndexQuotes serves as an optional identifier for the query.
• spotQuotesInput is a variable of the type SpotQuotesInput, allowing users to define the data structure through an input object node.
• spotQuotes is a method in the schema that accepts a SpotQuotesInput object. The specified object shapes the input for this query.
• The data structure returned by spotQuotes method is specified within the brackets and is of type SpotQuotesResponse, determining the data to be returned by the query.

Defining JSON Input for Variables

The JSON provided below illustrates an example of input variables accepted by the query:

{
  "spotQuotesInput": {
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "assetType": "INDEX",
    "source": "DERIBIT",
    "valuationDateTime": {
      "timeZone": "America_New_York",
      "range": {
        "start": "25/02/2024 16:32:15",
        "end": "25/02/2024 16:32:20"
      }
    }
  }
}

Detailed Explanations:

• The spotQuotesInput object specifies the input variable for the query.
• The baseAsset field identifies the specific base of the asset (e.g., BTC for BTCUSD) for which data is requested.
• The quoteAsset field identifies the specific quote currency (e.g., USD for BTCUSD) in which the baseAsset is measured.
• The assetType is an optional ENUM value that distinguishes between SPOT or INDEX, with the default set to INDEX.
• The source defines the origin of the data.
• The valuationDateTime parameter is optional node and defaults to the current date and time if unspecified. Users can specify a date range within this object for the data retrieval. The example specifies a five-second interval during which the data is to be retrieved, aligned to the New York timezone.

Many other options are possible, we invite you to consult the API documentation within your dashboard.

Running the Query in the GraphQL IDE

Summary

This example illustrates a query for BTCUSD index data from the Deribit exchange, specifying a time range aligned to New York timezone and focusing on retrieving only the source name and the mid-price.

Retrieving Additional Data

By modifying the existing query, users can customize the data retrieved to include more or less information based on their specific needs. For instance, within the same defined time range, a user might want to access additional fields such as the quote and base assets, along with both the mid and ask prices. Furthermore, they might need the valuation dates in timestamp format (milliseconds since the UNIX epoch) as well as the date of each spot data and the date format. Below is the modified query to accommodate these requirements:

query myIndexQuotes($spotQuotesInput: SpotQuotesInput!) {
  spotQuotes(spotQuotesInput: $spotQuotesInput) {
    source
    price {
      mid,
      ask
    }
    quoteAsset
    baseAsset
    valuationDateTime {
      dateTime,
      timestamp,
    dateTimeFormat
    }
  }
}

Please note that the order of nodes within the output object is flexible. Users are free to rearrange these as needed without impacting the functionality of the query. This query can be used with the same JSON defined above to retrieve the requested additional data.

With these examples, we have demonstrated the versatility of GraphQL in data querying. Additionally, querying analytics on demand is also supported. For further information, please refer to the API documentation page located within the Developer Portal on your dashboard.