> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 过滤
> 使用选择器快捷方式与 where 参数过滤查询结果 — 运算符、嵌套过滤器、OR 逻辑与默认值
在 ChainStream GraphQL 中筛选数据有两种方式：
1. **Selector 快捷参数**——顶层参数如 `tokenAddress`，为常见筛选提供便捷写法
2. **`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 |
**以下两个查询等价：**
```graphql theme={null}
query {
Solana {
DEXTrades(
tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
limit: { count: 10 }
) {
Block { Time }
Trade { Buy { Amount PriceInUSD } }
}
}
}
```
```graphql theme={null}
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 的维度层级一致。每个叶子字段对应一个**筛选原语**，带类型化运算符。
### 结构
```graphql theme={null}
where: {
DimensionGroup: {
DimensionField: {
operator: value
}
}
}
```
**示例**——筛选区块时间在某日期之后 **且** 买入数量大于 1000 的 DEXTrades：
```graphql theme={null}
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 模式匹配（`%` 通配符） |
```graphql theme={null}
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!]` | 排除列表中所有值 |
```graphql theme={null}
where: {
Trade: {
Buy: {
PriceInUSD: { gte: 0.001, lte: 1.0 }
}
}
}
```
### DateTimeFilter
用于时间戳字段。值为 ISO 8601 字符串。
| 运算符 | 类型 | 说明 |
| :-------- | :----------------------- | :------------- |
| `after` | `DateTime` | 晚于该时间戳（不含边界） |
| `before` | `DateTime` | 早于该时间戳（不含边界） |
| `since` | `DateTime` | 从该时间戳起（含边界） |
| `till` | `DateTime` | 直到该时间戳（含边界） |
| `between` | `[DateTime!, DateTime!]` | 介于两个时间戳之间（两端含） |
```graphql theme={null}
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` |
```graphql theme={null}
where: {
IsSuspect: { eq: true }
}
```
***
## 使用 `any` 表达 OR
默认情况下，`where` 中所有条件以 AND 组合。若要表达 OR，使用 `any` 数组字段——每个元素为完整筛选对象，匹配**任一**条件的记录会被返回。
```graphql theme={null}
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 成交 |
若要**包含**可疑成交，请显式设置：
```graphql theme={null}
query {
Solana {
DEXTrades(
where: { IsSuspect: { eq: true } }
limit: { count: 10 }
) {
Block { Time }
Trade { Buy { Amount } }
IsSuspect
}
}
}
```
若不在 `where` 中指定 `IsSuspect`，默认仍为 `false`。若要查询**全部**成交（不论可疑与否），可使用 OR：
```graphql theme={null}
where: {
any: [
{ IsSuspect: { eq: true } }
{ IsSuspect: { eq: false } }
]
}
```
***
## 组合 Selector 与 `where`
Selector 与 `where` 以 AND 组合。便于用 Selector 锁定主体实体，用 `where` 做进一步细化：
```graphql theme={null}
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 对筛选后的数据聚合。