過濾 - 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`

下一步