跳轉到主要內容
在 ChainStream GraphQL 中有兩種方式篩選資料：
  1. Selector shortcuts — 頂層引數如 tokenAddress，為常見 Filter 提供便捷寫法
  2. where 引數 — 巢狀 Filter 物件，支援完整運算子範圍與任意維度篩選
同一查詢中可以同時使用兩者。

​
Selector shortcuts

Selectors 是 Cube 欄位上的便捷引數，對映到常見的 where Filter 模式。它們與 where 欄位接受相同的 Filter 輸入型別（例如帶 is、in、like 等的 StringFilter），而非普通字串。
Selector對映關係可用 Cube
tokenAddress各 Cube 的主 token 地址列DEXTrades, Transfers, BalanceUpdates, DEXPools, TokenSupplyUpdates, Pairs, Tokens, DEXPoolEvents, TokenHolders
walletAddress錢包 / 賬戶所有者地址DEXTrades, WalletTokenPnL
poolAddress流動性池合約地址DEXTrades, DEXPools
senderAddress轉賬傳送方地址Transfers
receiverAddress轉賬接收方地址Transfers
ownerAddressToken 賬戶所有者地址BalanceUpdates
dexProgramDEX 程式 / 合約地址DEXTrades
date區塊時間戳（DateTime Filter）DEXTrades, Transfers, BalanceUpdates, DEXPools
以下兩個查詢等價： 
query {
  DEXTrades(
    network: sol
    tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
    limit: { count: 10 }
  ) {
    Block { Time }
    Trade { Buy { Amount PriceInUSD } }
  }
}
Selectors 支援全部 Filter 運算子，不僅限於精確匹配。例如 tokenAddress: {in: ["ADDR_1", "ADDR_2"]} 可匹配多個 token，date: {after: "2025-01-01T00:00:00Z"} 可按時間篩選。

​
where 引數

where 接受巢狀輸入物件，結構映象 Cube 的維度層級。每個葉子欄位對映到帶型別運算子的 Filter 原語。

​
結構

where: {
  DimensionGroup: {
    DimensionField: {
      operator: value
    }
  }
}
示例 — 篩選區塊時間在某日期之後 且 買入金額大於 1000 的 DEXTrades： 
query {
  DEXTrades(
    network: sol
    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 邏輯組合。

​
Filter 原語型別

每個葉子維度對映到以下 Filter 輸入型別之一：

​
StringFilter

用於地址、雜湊、協議名等文字欄位。
OperatorTypeDescription
isString精確匹配
notString不等於
in[String!]匹配列表中任一值
notIn[String!]排除列表中所有值
likeStringSQL LIKE 模式匹配（% 萬用字元）
where: {
  Trade: {
    Dex: {
      ProtocolName: { in: ["Raydium", "Orca"] }
    }
  }
}

​
IntFilter / FloatFilter

用於金額、價格、計數等數值欄位。
OperatorTypeDescription
eqNumber等於
neNumber不等於
gtNumber大於
gteNumber大於等於
ltNumber小於
lteNumber小於等於
in[Number!]匹配列表中任一值
notIn[Number!]排除列表中所有值
where: {
  Trade: {
    Buy: {
      PriceInUSD: { gte: 0.001, lte: 1.0 }
    }
  }
}

​
DateTimeFilter

用於時間戳欄位。值為 ISO 8601 字串。
OperatorTypeDescription
afterDateTime晚於該時間戳（不含邊界）
beforeDateTime早於該時間戳（不含邊界）
sinceDateTime從該時間戳起（含邊界）
tillDateTime直到該時間戳（含邊界）
between[DateTime!, DateTime!]兩時間戳之間（兩端含邊界）
where: {
  Block: {
    Time: { since: "2025-03-01T00:00:00Z", till: "2025-03-31T23:59:59Z" }
  }
}
after/before 為不含邊界（嚴格不等）。since/till 為含邊界。between 為二元陣列，兩端均含邊界。

​
BoolFilter

用於布林欄位。
OperatorTypeDescription
eqBoolean等於 true 或 false
where: {
  IsSuspect: { eq: true }
}

​
使用 any 表達 OR 邏輯

預設 where 中所有條件以 AND 組合。要表達 OR，使用 any 陣列欄位 — 每個元素為完整 Filter 物件，匹配任意一條即返回。 
query {
  DEXTrades(
    network: sol
    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。

​
預設 Filter

部分 Cube 會自動應用預設 Filter。可在 where 中顯式寫出以覆蓋。
CubeDefault FilterEffect
DEXTradesIsSuspect = false預設排除 bot/MEV 交易
要包含 suspect 交易，顯式設定 Filter： 
query {
  DEXTrades(
    network: sol
    where: { IsSuspect: { eq: true } }
    limit: { count: 10 }
  ) {
    Block { Time }
    Trade { Buy { Amount } }
    IsSuspect
  }
}
若不在 where 中指定 IsSuspect，預設仍為 false。要查詢全部交易（無論 suspect 狀態），使用 OR： 
where: {
  any: [
    { IsSuspect: { eq: true } }
    { IsSuspect: { eq: false } }
  ]
}

​
組合 Selectors 與 where

Selectors 與 where 以 AND 組合。可用 selector 鎖定主體實體，用 where 進一步細化： 
query {
  DEXTrades(
    network: sol
    tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
    where: {
      Block: { Time: { after: "2025-03-01T00:00:00Z" } }
      Trade: { Buy: { Amount: { gt: 100 } } }
    }
    orderBy: Block_Time_DESC
    limit: { count: 50 }
  ) {
    Block { Time }
    Transaction { Hash }
    Trade {
      Buy { Amount PriceInUSD }
      Sell { Currency { MintAddress } Amount }
      Dex { ProtocolName }
    }
  }
}
該查詢獲取 Solana 上 USDC 最近 50 筆買入金額大於 100 的 DEX 成交，按時間降序。

​
下一步

排序與分頁

使用 orderBy 與 limit 排序並分頁瀏覽資料。

指標與聚合

使用 count、sum、avg、min、max、uniq 對篩選後資料聚合。