过滤

使用选择器快捷方式与 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

以下两个查询等价：

使用 Selector

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

使用 where 筛选

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 对筛选后的数据聚合。