Skip to main content

Relative Time Filters

Bitquery's GraphQL API now supports relative time filtering. This filtering option simplify querying time-dependent blockchain data without manually calculating or formatting exact UTC timestamps.

Why Use Relative Time?​

Traditionally, time-based filters required exact UTC timestamp as shown below, which could make the development experience tedious as the user is required to add logic to update the timestamp again and again.

Block: { Time: { after: "2025-08-01T00:00:00" } }

With relative filters, you can write queries in a simpler way, improving readability and flexibility, thus imporoving the development experience.

Block: { Time: { after_relative: { hours_ago: 1 } } }

Supported Relative Time Filters​

The list of supported relative time filters is given below.

OperatorDescription
after_relativeTime after a given relative point
before_relativeTime before a given relative point
since_relativeAlias for after_relative
till_relativeAlias for before_relative
is_relativeExact match to a relative point (rare)

Supported Time Units​

The list of supported time units are given below.

UnitDescription
seconds_agoRefers to a number of seconds before the current time
minutes_agoRefers to a number of minutes before the current time
hours_agoRefers to a number of hours before the current time
days_agoRefers to a number of days before the current time
weeks_agoRefers to a number of weeks before the current time
years_agoRefers to a number of years before the current time

Examples​

Last Hour Trades​

The following examples uses the after_relative filter to get Solana DEX Trades for the last 1 hour. You can checkout from the results that the oldest trades returned occured an hour ago(UTC Time).

{
  Solana {
    DEXTrades(
      where: {Block: {Time: {after_relative: {hours_ago: 1}}}}
      orderBy: {ascending: Block_Time}
    ) {
      Trade {
        Buy {
          AmountInUSD
        }
      }
      Block {
        Time
      }
    }
  }
}

Using Multiple Time Units Together​

You can use multiple time units together as shown in the example below.

{
  Solana {
    DEXTrades(
      where: {Block: {Time: {after_relative: {hours_ago: 1, minutes_ago: 30, seconds_ago: 30}}}}
      orderBy: {ascending: Block_Time}
    ) {
      Trade {
        Buy {
          AmountInUSD
        }
      }
      Block {
        Time
      }
    }
  }
}