フィルタリング

ChainStream GraphQL でデータを絞り込む方法は 2 つあります。

セレクター省略形 — tokenAddress のようなトップレベル引数で、よく使うフィルターを簡潔に書く
where 引数 — ネストしたフィルターオブジェクトで、すべての演算子と任意のディメンションによる絞り込みが可能

ベストプラクティス: 必ず時間フィルターを付ける。 DWD（明細）Cube（DEXTrades、Transfers、BalanceUpdates など）では、Block.Time フィルターなしのクエリは非常に大きなテーブルパーティションをスキャンする可能性があります。where: {Block: {Time: {after: "..."}}} でスキャン範囲を限定し、OLAP エンジン上のメモリ制限を避けてください。

同じクエリで両方を組み合わせられます。

セレクター省略形

セレクターは Cube フィールド上の利便性のための引数で、よく使う where パターンにマップされます。プレーン文字列ではなく、where のフィールドと同じフィルター入力型（例: is、in、like などを持つ StringFilter）を受け取ります。

セレクター	マップ先	利用可能な Cube
`tokenAddress`	各 Cube の主トークンアドレス列	DEXTrades, Transfers, BalanceUpdates, DEXPools, TokenSupplyUpdates, Pairs, Tokens, DEXPoolEvents, TokenHolders
`walletAddress`	ウォレット／アカウント所有者アドレス	DEXTrades, WalletTokenPnL
`poolAddress`	プールコントラクトアドレス	DEXTrades, DEXPools
`senderAddress`	転送の送信元アドレス	Transfers
`receiverAddress`	転送の受信先アドレス	Transfers
`ownerAddress`	トークンアカウント所有者アドレス	BalanceUpdates
`dexProgram`	DEX プログラム／コントラクトアドレス	DEXTrades
`date`	ブロックタイムスタンプ（DateTime フィルター）	DEXTrades, Transfers, BalanceUpdates, DEXPools

次の 2 つのクエリは等価です。

セレクター使用
where フィルター

query {
  Solana {
    DEXTrades(
      tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
      limit: { count: 10 }
    ) {
      Block { Time }
      Trade { Buy { Amount PriceInUSD } }
    }
  }
}

query {
  Solana {
    DEXTrades(
      where: {
        Trade: {
          Buy: {
            Currency: {
              MintAddress: {
                is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
              }
            }
          }
        }
      }
      limit: { count: 10 }
    ) {
      Block { Time }
      Trade { Buy { Amount PriceInUSD } }
    }
  }
}

セレクターは完全一致だけでなく、すべてのフィルター演算子をサポートします。例: tokenAddress: {in: ["ADDR_1", "ADDR_2"]} で複数トークンにマッチし、date: {after: "2025-01-01T00:00:00Z"} で時間で絞れます。

`where` 引数

where 引数は、Cube のディメンション階層を反映したネストした入力オブジェクトを受け取ります。各リーフフィールドは、型付き演算子を持つフィルタープリミティブにマップされます。

構造

where: {
  DimensionGroup: {
    DimensionField: {
      operator: value
    }
  }
}

例 — ブロック時刻が指定日より後で、かつ買い数量が 1000 超の DEXTrades に絞る:

query {
  Solana {
    DEXTrades(
      where: {
        Block: { Time: { after: "2025-01-01T00:00:00Z" } }
        Trade: { Buy: { Amount: { gt: 1000 } } }
      }
      limit: { count: 20 }
    ) {
      Block { Time }
      Trade { Buy { Amount PriceInUSD } }
    }
  }
}

where の同一レベルに複数フィールドがある場合、AND で結合されます。

フィルタープリミティブの型

各リーフディメンションは、次のいずれかのフィルター入力型にマップされます。

StringFilter

アドレス、ハッシュ、プロトコル名などのテキストフィールド向け。

演算子	型	説明
`is`	`String`	完全一致
`not`	`String`	不一致
`in`	`[String!]`	リスト内のいずれかに一致
`notIn`	`[String!]`	リスト内の値をすべて除外
`like`	`String`	SQL LIKE パターン（`%` ワイルドカード）

where: {
  Trade: {
    Dex: {
      ProtocolName: { in: ["Raydium", "Orca"] }
    }
  }
}

IntFilter / FloatFilter

数量、価格、件数などの数値フィールド向け。

演算子	型	説明
`eq`	`Number`	等しい
`ne`	`Number`	等しくない
`gt`	`Number`	より大きい
`gte`	`Number`	以上
`lt`	`Number`	より小さい
`lte`	`Number`	以下
`in`	`[Number!]`	リスト内のいずれかに一致
`notIn`	`[Number!]`	リスト内の値をすべて除外

where: {
  Trade: {
    Buy: {
      PriceInUSD: { gte: 0.001, lte: 1.0 }
    }
  }
}

DateTimeFilter

タイムスタンプフィールド向け。値は ISO 8601 文字列です。

演算子	型	説明
`after`	`DateTime`	この時刻より後（排他的）
`before`	`DateTime`	この時刻より前（排他的）
`since`	`DateTime`	この時刻以降（包含）
`till`	`DateTime`	この時刻まで（包含）
`between`	`[DateTime!, DateTime!]`	2 つの時刻の間（両端包含）

where: {
  Block: {
    Time: { since: "2025-03-01T00:00:00Z", till: "2025-03-31T23:59:59Z" }
  }
}

after / before は排他的（狭義の不等号）。since / till は包含です。between は 2 要素の配列で、両端とも包含です。

BoolFilter

真偽フィールド向け。

演算子	型	説明
`eq`	`Boolean`	`true` または `false` と等しい

where: {
  IsSuspect: { eq: true }
}

`any` による OR ロジック

既定では where 内の条件はすべて AND で結合されます。OR を表すには any 配列フィールドを使います — 各要素は完全なフィルターオブジェクトで、いずれかに一致する行が返されます。

query {
  Solana {
    DEXTrades(
      where: {
        any: [
          { Trade: { Buy: { Currency: { MintAddress: { is: "TOKEN_A" } } } } }
          { Trade: { Buy: { Currency: { MintAddress: { is: "TOKEN_B" } } } } }
        ]
      }
      limit: { count: 20 }
    ) {
      Trade {
        Buy { Currency { MintAddress } Amount }
      }
    }
  }
}

any は他のトップレベル where フィールドと併用できます。any 内の条件同士は OR で結合され、その結果が兄弟条件と AND で結合されます。

既定フィルター

一部の Cube では既定フィルターが自動適用されます。where で明示的に設定すると上書きできます。

Cube	既定フィルター	効果
DEXTrades	`IsSuspect = false`	既定でボット／MEV 取引を除外

疑わしい取引を含めるには、フィルターを明示します:

query {
  Solana {
    DEXTrades(
      where: { IsSuspect: { eq: true } }
      limit: { count: 10 }
    ) {
      Block { Time }
      Trade { Buy { Amount } }
      IsSuspect
    }
  }
}

where に IsSuspect を書かないと、既定の false のままです。疑わしさに関係なくすべての取引を取得するには OR を使います:

where: {
  any: [
    { IsSuspect: { eq: true } }
    { IsSuspect: { eq: false } }
  ]
}

セレクターと `where` の併用

セレクターと where は AND で結合されます。主エンティティはセレクター、追加の絞り込みは where に書けます:

query {
  Solana {
    DEXTrades(
      tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
      where: {
        Block: { Time: { after: "2025-03-01T00:00:00Z" } }
        Trade: { Buy: { Amount: { gt: 100 } } }
      }
      orderBy: {descending: Block_Time}
      limit: { count: 50 }
    ) {
      Block { Time }
      Transaction { Hash }
      Trade {
        Buy { Amount PriceInUSD }
        Sell { Currency { MintAddress } Amount }
        Dex { ProtocolName }
      }
    }
  }
}

このクエリは、Solana 上の USDC で買い数量が 100 を超える直近 50 件の取引を、時刻の降順で取得します。

次のステップ

並び順とページネーション

orderBy と limit で結果を並べ替え、ページングします。

メトリクスと集計

count、sum、avg、min、max、uniq でフィルター済みデータを集計します。

Documentation Index

​セレクター省略形

​where 引数

​構造

​フィルタープリミティブの型

​StringFilter

​IntFilter / FloatFilter

​DateTimeFilter

​BoolFilter

​any による OR ロジック

​既定フィルター

​セレクターと where の併用

​次のステップ

並び順とページネーション

メトリクスと集計

セレクター省略形

`where` 引数

構造

フィルタープリミティブの型

StringFilter

IntFilter / FloatFilter

DateTimeFilter

BoolFilter

`any` による OR ロジック

既定フィルター

セレクターと `where` の併用

次のステップ