过滤 - ChainStream

在 ChainStream GraphQL 中筛选数据有两种方式：

Selector 快捷参数——顶层参数如 tokenAddress，为常见筛选提供便捷写法
where 参数——嵌套筛选对象，支持完整运算符与任意维度筛选

最佳实践：务必加上时间筛选。 对于 DWD（明细）类 Cube（如 DEXTrades、Transfers、BalanceUpdates），未带 Block.Time 筛选的查询可能扫描极大分区。请始终包含 where: {Block: {Time: {after: "..."}}} 以限制扫描范围，避免 OLAP 引擎触发内存上限。

同一查询中可以同时使用二者。

Selector 快捷参数

Selector 是 Cube 字段上的便捷参数，映射到常见的 where 筛选模式。它们接受与 where 字段相同的筛选输入类型（例如带 is、in、like 等的 StringFilter），而不是裸字符串。

Selector	映射到	适用于
`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

以下两个查询等价：

使用 Selector
使用 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 } }
    }
  }
}

Selector 支持全部筛选运算符——不限于精确匹配。例如 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!]`	介于两个时间戳之间（两端含）

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

after/before 为不含边界（严格不等）。since/till 为含边界。between 接受二元数组，两端均含。

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 } }
  ]
}

组合 Selector 与 `where`

Selector 与 where 以 AND 组合。便于用 Selector 锁定主体实体，用 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 上取最近 50 笔 USDC 成交，且买入数量大于 100，按时间降序排列。

下一步

排序与分页

使用 orderBy 与 limit 排序并分页浏览数据。

指标与聚合

使用 count、sum、avg、min、max、uniq 对筛选后的数据聚合。

快速开始

GraphQL IDE

Schema 与数据模型

查询示例

计费与额度

过滤

Selector 快捷参数

`where` 参数

结构

筛选原语类型

StringFilter

IntFilter / FloatFilter

DateTimeFilter

BoolFilter

使用 `any` 表达 OR

默认筛选

组合 Selector 与 `where`

下一步

排序与分页

指标与聚合

​Selector 快捷参数

​where 参数

​结构

​筛选原语类型

​StringFilter

​IntFilter / FloatFilter

​DateTimeFilter

​BoolFilter

​使用 any 表达 OR

​默认筛选

​组合 Selector 与 where

​下一步

排序与分页

指标与聚合

Selector 快捷参数

`where` 参数

结构

筛选原语类型

StringFilter

IntFilter / FloatFilter

DateTimeFilter

BoolFilter

使用 `any` 表达 OR

默认筛选

组合 Selector 与 `where`

下一步