Data structure

In the Graphy SDK, your data and your spec are separate. Data is a plain table you pass to GraphProvider as the data prop; the spec references that table’s columns by key through its mapping. Keeping them apart means the same spec can be re-used across datasets, and the same data can be drawn several ways.

Basic structure

Data is a table with explicitly defined columns and rows:

const data = {
  columns: [
    { key: 'category', label: 'Category' },
    { key: 'value', label: 'Value' },
  ],
  rows: [
    { category: 'A', value: 100 },
    { category: 'B', value: 200 },
    { category: 'C', value: 150 },
  ],
};

The columns array defines the shape; rows holds the values.

Referencing columns from a spec

A spec never contains data — it names the columns it needs through its mapping. The variable strings you pass to mapping (or the createSpec shorthand) are column keys:

const spec = pipe(
  // 'category' and 'value' are column keys
  createSpec({ x: 'category', y: 'value' }),
  geom.bar(),
  scale.x(),
  scale.y()
);

Because the binding is by key, the label on a column is purely presentational — it’s what shows in axes, legends and tooltips. If you omit it, the key is used.

Row keys must exactly match a column key. Values under keys with no matching column definition are ignored.

Value format detection

Graphy inspects each column’s values and infers a value format — this drives how a scale interprets the column and how the renderer formats it. The first match wins.

Numbers

Numbers and numeric strings are detected as quantitative values. Thousands separators, decimals and magnitude suffixes are supported:

{ category: 'A', value: 100 }
{ category: 'B', value: '1,250.50' }
{ category: 'C', value: '2.5m' }       // k, m, b, t suffixes supported

Dates

Date-like strings are parsed automatically across a wide range of formats — ISO dates, named months and locale-specific orderings:

{ date: '2024-01-15', value: 100 }           // YYYY-MM-DD
{ date: 'January 2024', value: 200 }         // month name + year
{ date: '15/01/2024', value: 150 }           // DD/MM/YYYY (en-GB, the default locale)
{ date: '01/15/2024', value: 150 }           // MM/DD/YYYY (en-US)
{ date: '2024-01-15T12:30:00Z', value: 300 } // ISO datetime
{ date: 'Q1 2024', value: 400 }              // quarter

Short month names (Jan, Feb) are recognised alongside full names. Set data._metadata.parsingLocale to control whether ambiguous dates like 01/02/2024 are read as DD/MM (en-GB) or MM/DD (en-US). Weekly date ranges are also detected — values like 1 Feb – 7 Feb or 1 Feb 2024 – 7 Feb 2024 representing 7-day spans.

Percentages

Values with a % suffix are detected as percentages:

{ category: 'Desktop', share: '64.5%' }
{ category: 'Mobile', share: '28.3%' }

Currencies

Currency-formatted strings are parsed with automatic symbol recognition. Supported symbols: $, €, £, ¥, ₹, ₱, ₩, ₪, ₫, ₽, ฿, ₦, ₺, zł, kr, Fr, R, R$, Rp, RM, د.إ, ﷼, Ch$, NT$, HK$, S$, A$, C$, NZ$, MX$.

{ product: 'A', price: '$1,250' }
{ product: 'B', price: '£2,450.50' }
{ product: 'C', price: '€3,000' }

Symbols can appear as prefix or suffix, and negative values are supported (-$100, $-100).

Text

Any value that doesn’t match the above is treated as text (categorical data).

How formats reach scales

The inferred format feeds the scale you declare for each aesthetic. Calling a position scale bare (scale.x()) lets the engine choose a scale type from the column’s format:

A text column → a discrete (band) scale.
A numeric, percentage or currency column → a continuous scale.
A date column → a temporal scale.

You can always override the inference with an explicit method — scale.x.continuous(), scale.x.discrete(), scale.x.datetime() — when you want to force a particular treatment. See the line chart guide for worked examples.

Missing values

Use null for a missing cell. How a geom treats gaps is geom-specific — for lines, the missingValues param chooses whether to break the path, bridge it, or treat the gap as zero.

rows: [
  { month: 'Jan', revenue: 12000 },
  { month: 'Feb', revenue: null }, // missing
  { month: 'Mar', revenue: 18000 },
];

Schema

data.columns

Column[]

required

Array of column definitions. Each column defines the structure and metadata for a data field.

columns[].key

string

required

Unique, stable identifier for the column. Must match the keys used in rows objects, and is what a spec’s mapping references.

columns[].label

string

Human-readable label shown in the UI (axis labels, legends, tooltips). Defaults to the key if not provided.

data.rows

Row[]

required

Array of data rows. Each row is an object with keys matching the column keys. Values can be a string, number, Date or null.

data._metadata

object

Optional metadata for parsing and advanced data processing.

Show properties

parsingLocale

'en-GB' | 'en-US'

Locale used to infer column types and parse values (dates, numbers). Defaults to 'en-GB'.

'en-GB': DD/MM/YYYY date format
'en-US': MM/DD/YYYY date format

sortBy

object

Sort configuration: { columnKey: string; direction: 'asc' | 'desc' }.

groupByTimeUnit

'year' | 'quarter' | 'month' | 'week' | 'day'

Time unit for grouping time-based data.

rollingDateFilter

object

Rolling date filter: { timeUnit: 'year' | 'quarter' | 'month' | 'week' | 'day'; value: number } — e.g. the last 30 days is { timeUnit: 'day', value: 30 }.

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Basic structure

Referencing columns from a spec

Value format detection

Numbers

Dates

Percentages

Currencies

Text

How formats reach scales

Missing values

Schema

​Basic structure

​Referencing columns from a spec

​Value format detection

​Numbers

​Dates

​Percentages

​Currencies

​Text

​How formats reach scales

​Missing values

​Schema

Basic structure

Referencing columns from a spec

Value format detection

Numbers

Dates

Percentages

Currencies

Text

How formats reach scales

Missing values

Schema