数据计算

Graphic Walker 支持两种计算模式：客户端（默认）和服务端。根据数据集大小和架构需求选择合适的模式。

客户端计算

当你传入 data 属性时，Graphic Walker 在客户端的 Web Worker 中运行所有计算。这是最简单的配置方式 — 无需后端。

<GraphicWalker data={myData} fields={fields} />

优势：

零服务端配置
支持离线使用
交互即时响应

限制：

数据集必须能放入浏览器内存
需要将所有数据传输到客户端
性能取决于客户端硬件

推荐用于： 100K 行以下的数据集。

DuckDB WASM（可选）

为了在客户端获得更好的大数据集性能，Graphic Walker 可以使用 DuckDB WASM。安装可选包：

npm install @kanaries/graphic-walker-duckdb

这启用了浏览器中基于 SQL 的聚合，对于大型数据集速度显著提升。

服务端计算

对于大型数据集或数据不能离开服务器的场景，传入 computation 函数代替 data。Graphic Walker 会将查询负载发送给你的函数，由你返回结果。

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IComputationFunction } from '@kanaries/graphic-walker';
 
const computation: IComputationFunction = async (payload) => {
  const response = await fetch('/api/data/query', {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: { 'Content-Type': 'application/json' },
  });
  return response.json();
};
 
function App() {
  return (
    <GraphicWalker
      computation={computation}
      fields={fields}
    />
  );
}

优势：

处理任意大小的数据集
数据保留在服务端
利用服务端数据库（PostgreSQL、DuckDB 等）

限制：

需要实现查询端点
网络延迟影响交互速度

计算函数签名

type IComputationFunction = (payload: IDataQueryPayload) => Promise<IRow[]>;

函数接收一个包含 workflow 数组的 IDataQueryPayload — 一个处理步骤的管道：

interface IDataQueryPayload {
  workflow: IDataQueryWorkflowStep[];
  limit?: number;
  offset?: number;
}

工作流步骤

工作流是一个有序的步骤数组。你的服务端按顺序处理它们：

1. 筛选步骤

在任何聚合之前应用行级筛选：

{
  "type": "filter",
  "filters": [
    {
      "fid": "country",
      "rule": { "type": "one of", "value": ["US", "UK", "DE"] }
    },
    {
      "fid": "revenue",
      "rule": { "type": "range", "value": [1000, null] }
    }
  ]
}

2. 转换步骤

计算派生字段：

{
  "type": "transform",
  "transform": [
    {
      "key": "log_revenue",
      "expression": {
        "op": "log10",
        "params": [{ "type": "field", "value": "revenue" }],
        "as": "log_revenue"
      }
    }
  ]
}

3. 视图步骤

聚合或选择数据。这是最常见的步骤：

聚合查询：

{
  "type": "view",
  "query": [{
    "op": "aggregate",
    "groupBy": ["country", "product"],
    "measures": [
      { "field": "revenue", "agg": "sum", "asFieldKey": "sum_revenue" },
      { "field": "revenue", "agg": "count", "asFieldKey": "count_records" }
    ]
  }]
}

原始查询（无聚合）：

{
  "type": "view",
  "query": [{
    "op": "raw",
    "fields": ["country", "product", "revenue", "date"]
  }]
}

Fold 查询（逆透视）：

{
  "type": "view",
  "query": [{
    "op": "fold",
    "foldBy": ["q1_sales", "q2_sales", "q3_sales", "q4_sales"],
    "newFoldKeyCol": "quarter",
    "newFoldValueCol": "sales"
  }]
}

分箱查询：

{
  "type": "view",
  "query": [{
    "op": "bin",
    "binBy": "age",
    "newBinCol": "age_bin",
    "binSize": 10
  }]
}

4. 排序步骤

对结果排序：

{
  "type": "sort",
  "sort": "descending",
  "by": ["sum_revenue"]
}

服务端实现示例

以下是一个使用 SQL 的简单 Express.js 端点：

app.post('/api/data/query', async (req, res) => {
  const { workflow, limit, offset } = req.body;
  let query = 'SELECT * FROM dataset';
  const params = [];
 
  for (const step of workflow) {
    if (step.type === 'filter') {
      const conditions = step.filters.map(f => {
        if (f.rule.type === 'range') {
          const [min, max] = f.rule.value;
          if (min !== null && max !== null) return `${f.fid} BETWEEN ${min} AND ${max}`;
          if (min !== null) return `${f.fid} >= ${min}`;
          if (max !== null) return `${f.fid} <= ${max}`;
        }
        if (f.rule.type === 'one of') {
          return `${f.fid} IN (${f.rule.value.map(v => `'${v}'`).join(',')})`;
        }
        return '1=1';
      });
      query += ` WHERE ${conditions.join(' AND ')}`;
    }
 
    if (step.type === 'view') {
      for (const q of step.query) {
        if (q.op === 'aggregate') {
          const groupCols = q.groupBy.join(', ');
          const measureCols = q.measures.map(m =>
            `${m.agg.toUpperCase()}(${m.field}) AS ${m.asFieldKey}`
          ).join(', ');
          query = `SELECT ${groupCols}, ${measureCols} FROM (${query}) t GROUP BY ${groupCols}`;
        }
        if (q.op === 'raw') {
          query = `SELECT ${q.fields.join(', ')} FROM (${query}) t`;
        }
      }
    }
 
    if (step.type === 'sort') {
      query += ` ORDER BY ${step.by.join(', ')} ${step.sort === 'ascending' ? 'ASC' : 'DESC'}`;
    }
  }
 
  if (limit) query += ` LIMIT ${limit}`;
  if (offset) query += ` OFFSET ${offset}`;
 
  const results = await db.query(query);
  res.json(results);
});

安全提示： 上述示例已简化。在生产环境中，请使用参数化查询以防止 SQL 注入。

计算超时

两种模式都支持超时设置：

<GraphicWalker
  data={data}
  fields={fields}
  computationTimeout={30000}  // 30 seconds
/>

选择合适的模式

因素	客户端	服务端
配置复杂度	最简	需要后端端点
数据集大小	< 100K 行	无限制
数据隐私	数据发送到浏览器	数据保留在服务端
交互速度	快（无网络延迟）	取决于网络 + 服务端
离线支持	是	否