Graph Node项目中的时间序列与聚合功能详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01116/article/details/148755838

Graph Node项目中的时间序列与聚合功能详解

graph-node Graph Node indexes data from blockchains such as Ethereum and serves it over GraphQL 项目地址: https://gitcode.com/gh_mirrors/gr/graph-node

引言

在区块链数据索引领域，Graph Node项目提供了一套强大的时间序列数据处理和聚合功能。本文将深入解析这一功能的设计原理、实现机制以及实际应用场景，帮助开发者更好地利用这一特性构建高效的数据索引服务。

时间序列与聚合功能概述

时间序列数据在区块链应用中非常常见，如代币价格波动、交易量变化等。Graph Node通过特殊的类型注解和聚合机制，为这类数据提供了原生支持。

核心概念

时间序列类型：使用@entity(timeseries: true)注解标记，用于存储原始数据点
聚合类型：使用@aggregation注解标记，定义如何对原始数据进行聚合计算

时间序列类型详解

基本结构

时间序列类型必须包含两个特殊字段：

id: Int8!：自动生成的递增ID
timestamp: Timestamp!：自动设置为当前区块的时间戳

type Data @entity(timeseries: true) {
  id: Int8!
  timestamp: Timestamp!
  price: BigDecimal!
}

重要特性

不可变性：时间序列实体一旦创建便不可修改
自动时间戳：即使映射中设置了时间戳，最终也会被Graph Node覆盖为区块时间戳
ID自增：系统自动维护ID的递增顺序

聚合类型深入解析

基本定义

聚合类型通过@aggregation注解声明，必须指定：

intervals：聚合间隔（如"hour"、"day"）
source：数据来源的时间序列类型

type Stats @aggregation(intervals: ["hour", "day"], source: "Data") {
  id: Int8!
  timestamp: Timestamp!
  sum: BigDecimal! @aggregate(fn: "sum", arg: "price")
}

维度与聚合字段

维度字段：用于数据分组，不参与聚合计算
聚合字段：使用@aggregate注解标记，定义聚合方式和数据源

type TokenStats @aggregation(intervals: ["hour", "day"], source: "TokenData") {
  id: Int8!
  timestamp: Timestamp!
  token: Token!  # 维度字段
  totalVolume: BigDecimal! @aggregate(fn: "sum", arg: "amount") # 聚合字段
}

聚合函数全解析

Graph Node支持多种聚合计算方式：

| 函数名 | 描述 | 适用场景示例 | |---------|----------------|-------------------------| | sum | 求和 | 计算总交易量 | | count | 计数 | 统计交易次数 | | min | 最小值 | 寻找最低价格 | | max | 最大值 | 寻找最高价格 | | first | 第一个值 | 获取区间开盘价 | | last | 最后一个值 | 获取区间收盘价 |

累积聚合与非累积聚合

通过cumulative参数可控制聚合范围：

false（默认）：仅计算当前区间内的数据
true：计算从开始到当前区间的所有数据

高级聚合表达式

除了简单的字段引用，Graph Node还支持复杂的表达式计算：

支持的运算符

算术运算：+, -, *, /, %, ^
比较运算：=, !=, <, <=, >, >=
逻辑运算：and, or, not

支持的函数

数学函数：abs, ceil, floor, power等
条件函数：coalesce, nullif, greatest, least
CASE表达式

实际应用示例

# 计算交易价值总和
@aggregate(fn: "sum", arg: "priceUSD * amount")

# 获取两个金额中的较大值
@aggregate(fn: "max", arg: "greatest(amount0, amount1, 0)")

# 条件聚合
@aggregate(fn: "sum", arg: "case when amount0 > amount1 then amount0 else 0 end")

查询聚合数据

Graph Node为每个聚合类型自动生成顶级查询字段，支持丰富的过滤和排序选项：

查询参数

interval：必须指定聚合间隔
current：是否包含当前未完成的区间（默认忽略）
时间范围过滤：timestamp_gte, timestamp_lt等
维度字段过滤：可对每个维度字段进行精确匹配

查询示例

query {
  token_stats(
    interval: "hour",
    where: {
      token: "0x1234",
      timestamp_gte: "1704164640000000"
    }
  ) {
    id
    timestamp
    token
    totalVolume
  }
}