Data Computation

Graphic Walker supports two computation modes: client-side (default) and server-side. Choose based on your dataset size and architecture requirements.

Client-Side Computation

When you pass the data prop, Graphic Walker runs all computations in a Web Worker on the client. This is the simplest setup — no backend required.

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

Advantages:

Zero server-side setup
Works offline
Instant interaction

Limitations:

Dataset must fit in browser memory
Initial transfer of all data to the client
Performance depends on client hardware

Recommended for: Datasets under 100K rows.

DuckDB WASM (Optional)

For better client-side performance with larger datasets, Graphic Walker can use DuckDB WASM. Install the optional package:

npm install @kanaries/graphic-walker-duckdb

This enables SQL-based aggregation in the browser, which is significantly faster for large datasets.

Server-Side Computation

For large datasets or when data can't leave the server, pass a computation function instead of data. Graphic Walker sends query payloads to your function, and you return the results.

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}
    />
  );
}

Advantages:

Handle datasets of any size
Data stays on the server
Leverage server-side databases (PostgreSQL, DuckDB, etc.)

Limitations:

Requires implementing a query endpoint
Network latency affects interaction speed

Computation Function Signature

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

The function receives a IDataQueryPayload with a workflow array — a pipeline of processing steps:

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

Workflow Steps

The workflow is an ordered array of steps. Your server processes them sequentially:

1. Filter Step

Apply row-level filters before any aggregation:

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

2. Transform Step

Compute derived fields:

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

3. View Step

Aggregate or select data. This is the most common step:

Aggregate query:

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

Raw query (no aggregation):

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

Fold query (unpivot):

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

Bin query:

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

4. Sort Step

Sort the results:

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

Server Implementation Example

Here's a minimal Express.js endpoint using SQL:

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);
});

Security note: The example above is simplified. In production, use parameterized queries to prevent SQL injection.

Computation Timeout

Both modes support a timeout setting:

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

Choosing the Right Mode

Factor	Client-Side	Server-Side
Setup complexity	Minimal	Requires backend endpoint
Dataset size	< 100K rows	Unlimited
Data privacy	Data sent to browser	Data stays on server
Interaction speed	Fast (no network)	Depends on network + server
Offline support	Yes	No