#1887·subql

[Reward Cancelled] Allow query historical data by block range

Author: jiqiang90Created Jul 17, 2023Updated May 4, 2026
LabelsQuery ServiceNew FeaturecrucialDocumentation Requiredguild

Description

We currently allow pass a block height, and get any result less equal than this height

image

We now want to add a filter for block height, so it can filter data with in a specific block range

image

Single entities

To start with we should have the ability to query an entity by its id and specify a block range. We need to consider that we only return 100 results and there might be more in the block range.

Possible example query:

gql

{
  # current single entity query
  example1: entity(id: 'foo') {
    id
    field1
    field2
  }
  # extend the current query
  example2: entity(id: 'foo', blockRange: [0, 100]) {
    id
    field1
    field2
  }
  # a new entity name
  example3: entityHistory(id: 'foo', blockRange: [0, 100]) {
    id
    field1
    field2
  }
}

Example response:

typescript

{
  example1: {
    id: 'foo',
    field1: 1,
    field2: 'bar',
  },
  example2: {
    // Keyed by block height
    5: {
      id: 'foo',
      field1: 1,
      field2: 'bar',
    },
    10: {
      id: 'foo',
      field1: 2,
      field2: 'bazz',
    },
    90: null, // indicates the entity was deleted
  },
  // example3 same result as example 2
}

Multiple entities

This is more complex and can come as another improvement at a later stage

Requirements

  • Tests which generate a schema and correctly show gql being converted to the appropriate sql
  • Documentation should be updated to include how to use this feature
  • Backwards compatible, i.e it should not change the behaviour of any current queries
  • Work with all other graphql plugins and features such as filtering, ordering, relations