How to use GraphicWalker in React

GraphicWalker is a embeddable, interactive, visual analytic component written in React. It is designed to be used in a React application. This document describes how to use GraphicWalker in a React application.

1. Install GraphicWalker

GraphicWalker is available as a npm package. To install it with dependencies, run the following command:

npm install @kanaries/graphic-walker styled-components

2. Prepare the data and metas to be visualized

GraphicWalker requires a data to be visualized. There are two ways to provide the data to GraphicWalker:

2.1. Provide the data as a JSON object

Flat data

If your data is small, you can provide the data as a JSON object, load it in the browser, and pass it to GraphicWalker. The data should be a Array of flat objects.

data.json

[
    {
        "gender": "female",
        "race/ethnicity": "group B",
        "parental level of education": "bachelor's degree",
        "lunch": "standard",
        "test preparation course": "none",
        "math score": 72,
        "reading score": 72,
        "writing score": 74
    },
    {
        "gender": "female",
        "race/ethnicity": "group C",
        "parental level of education": "some college",
        "lunch": "standard",
        "test preparation course": "completed",
        "math score": 69,
        "reading score": 90,
        "writing score": 88
    }
]

Then, you should provide a meta info of the data.

meta.json

[
    {
        "fid": "gender",
        "semanticType": "nominal",
        "analyticType": "dimension"
    },
    {
        "fid": "race/ethnicity",
        "semanticType": "nominal",
        "analyticType": "dimension"
    },
    {
        "fid": "parental level of education",
        "semanticType": "nominal",
        "analyticType": "dimension"
    },
    {
        "fid": "lunch",
        "semanticType": "nominal",
        "analyticType": "dimension"
    },
    {
        "fid": "test preparation course",
        "semanticType": "nominal",
        "analyticType": "dimension"
    },
    {
        "fid": "math score",
        "semanticType": "quantitative",
        "analyticType": "measure"
    },
    {
        "fid": "reading score",
        "semanticType": "quantitative",
        "analyticType": "measure"
    },
    {
        "fid": "writing score",
        "semanticType": "quantitative",
        "analyticType": "measure"
    }
]

Or you can use a function provided by GraphicWalker to infer the meta info from the data.

fields.ts

import { inferMeta } from '@kanaries/graphic-walker/lib/inferMeta';
import data from './data.json';
 
export const fields = inferMeta({ dataSource: data, fields: Object.keys(data[0]).map(k => ({ fid: k, analyticType: '?', semanticType: '?' })) });

Complex data

If your data contains objects, you can't provide it directly to GraphicWalker.

data.json

[
    {
        "name": "Alice",
        "age": 20,
        "address": {
            "city": "New York",
            "street": "5th Ave"
        }
    },
    {
        "name": "Bob",
        "age": 30,
        "address": {
            "city": "Los Angeles",
            "street": "Hollywood Blvd"
        }
    }
]

You can use the transData function to infer the meta of the data automatically, and transform the data to a flat one.

data.ts

import { transData } from '@kanaries/graphic-walker/dataSource/utils';
import data from './data.json';
 
const { dataSource, fields } = transData(data);
 
export { dataSource, fields };

2.2 Provide the data from a server

If your data is large and is stored in a database, you can provide them by providing a computation function, so that GraphicWalker will send queries to the server to get a computed chart data of current view, and user don't need to download the entire data at once.

You can use Pygwalker, a python package that can parse the queries from GraphicWalker and return the computed data.

You can see the instructions of building a server using Pygwalker here.

2.3 Provide the data with wasm module

If your data is large, and you want to have a better performance, you can use duckdb to process the data in the browser, and pass a computation function to GraphicWalker.

You can see the instructions of using duckdb with GraphicWalker here.

3. Use GraphicWalker in your React component

After you have prepared the data, you can use GraphicWalker in your React component.

3.1 Using GraphicWalker with local data

Just import the GraphicWalker component and pass the data and meta to it.

app.tsx

import React from 'react';
import { GraphicWalker } from '@kanaries/graphic-walker';
import data from './data.json';
import fields from './meta.json';
 
export default function App() {
    return (
        <GraphicWalker data={dataSource} fields={fields} />
    );
}

3.2 Using GraphicWalker with server data

After you have a server running, you can use the computation property of GraphicWalker to provide the computation function.

Here is a example of how to use the computation function.

import { GraphicWalker, type IDataQueryPayload, type IMutField } from "@kanaries/graphic-walker";
import { useFetch } from "./utils";
 
export default function Walker(props: { table: string }) {
    const data: { data: { fieldsMeta: IMutField[] } } = useFetch(`/table/${props.table}`);
    return (
        <GraphicWalker
            key={props.table}
            keepAlive={props.table}
            fields={data.data.fieldsMeta}
            computation={async (payload: IDataQueryPayload) =>
                fetch(`/table/${props.table}/query`, {
                    method: "POST",
                    headers: {
                        "Content-Type": "application/json",
                    },
                    body: JSON.stringify(payload),
                }).then(async resp => {
                    const result = await resp.json();
                    return result.data;
                })
            }
        />
    );
}

Quick start Using Graphic Walker in NextJS