Bind Data Source

A Data Chart must be connected to a data source before it can visualize data. In SpreadJS, data is typically managed through the Data Manager, where tables are defined and maintained.

To display data in a Data Chart, you:

1. Bind the chart to a table.

2. Map table fields to chart encodings.

This topic explains how to configure data binding and how encodings control data visualization.

Bind a Chart to a Table

Each Data Chart binds to a table by setting the tableName property in the chart configuration.

dataChart.setChartConfig({
  tableName: 'Sales',
  plots: [...]
});

The table must exist in the Data Manager.

Data Charts can also bind data from multiple related tables. When using multiple tables:

• Relationships must be defined in the Data Manager.

• Fields from related tables can be referenced using tableName.fieldName.

Encodings

Encodings define how data fields are mapped to visual elements in the chart.

Each plot defines its encodings under:

plots[n].encodings

Encodings control:

• What values are aggregated

• How data is grouped

• How colors, tooltips, and filters are applied

Encodings are organized into:

• Value Encoding

• Category Encoding

• Trellis Binding

• Details Encoding

• Color Encoding

• Other Encodings

Value Encoding

Value encoding defines which numeric fields are visualized as measures (typically along the Y-axis).

Single-Field Value Encoding

The most common scenario binds one field per value entry:

encodings: {
  values: [
    {
      field: "Sales",
      aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
    }
  ]
}

When multiple value fields are defined:

• Each field is treated as a separate series.

• The legend is automatically generated from the value fields.

Some chart types (such as Pie and Donut) support only a single value field.

Multi-Field Value Encoding

Supported chart types

• Range value encoding:

  • Range Column

  • Range Bar

  • Range Area

• Stock value encoding:

  • Candlestick

  • OHLC

Some chart types require multiple data fields to represent a single logical value.

Examples:

• Range charts require lower and upper values.

• Candlestick and OHLC charts require open, high, low, and close values.

For these charts, multiple fields are grouped under a single value entry using a vectors structure.

Range Chart Example

encodings: {
  values: [{
    vectors: {
      lower: { field: "Return" },
      upper: { field: "Sales" }
    },
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: { field: "Product" }
}

Stock Chart Example

encodings: {
  values: [{
    vectors: {
      open:  { field: "open" },
      high:  { field: "high" },
      low:   { field: "low" },
      close: { field: "close" }
    }
  }],
  category: { field: "date" }
}

In this structure:

• Each named vector binds to a specific field.

• All required vectors must be provided for the chart type.

Existing configurations that use separate value entries continue to work, but the vector structure is recommended for clarity and consistency.

Category Encoding

Category encoding defines how data is grouped along a dimension (typically the X-axis).

Flat Category

A flat category binds a single field:

encodings: {
  category: {
    field: "timePeriod"
  }
}

Date Category Encoding

When a Date field is bound to Category, you can use dateMode to control how Date values are grouped.

If dateMode is not specified, or if it is set to null or undefined, the chart uses the original Date values. This is the raw date behavior.

You can set dateMode to group Date values by a specific time unit, such as year, quarter, month, day, hour, minute, or second.

encodings: {
  category: {
    field: "orderDate",
    dateMode: GC.Spread.Sheets.DataCharts.DateMode.month
  }
}

In this example, Date values from the orderDate field are grouped by month.

Setting dateMode changes how Date values are grouped. It does not automatically change the axis scale. By default, a Date field bound to Category uses an ordinal axis, where each grouped Date value is treated as a category. To render the Date values on a continuous time axis, configure the category axis to use a Date scale.

Hierarchical Category

Hierarchical Category allows multiple grouping levels within a single plot.

This is useful when working with naturally nested data, such as:

• Year → Quarter → Month

• Region → Country → City

You define hierarchy levels using nested child objects.

Example

encodings: {
  values: [{
    field: "Sales",
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: {
    field: "Year",
    child: {
      field: "Quarter",
      child: {
        field: "Month"
      }
    }
  }
}

Key characteristics:

• Nesting order defines grouping order.

• Each level refines the grouping of its parent.

• All levels share the same aggregation rules.

• If no child is defined, the category behaves as a flat category.

When hierarchical categories include Date fields, each Date level can define its own dateMode.

encodings: {
  category: {
    field: "orderDate",
    dateMode: GC.Spread.Sheets.DataCharts.DateMode.year,
    child: {
      field: "orderDate",
      dateMode: GC.Spread.Sheets.DataCharts.DateMode.month
    }
  }
}

Multi-level Date categories define a grouping hierarchy. Each level is evaluated independently.

Trellis Binding

Trellis Binding, also known as small multiples, partitions one dataset into multiple chart panels based on one or more categorical fields. Each panel displays the same chart type and visual configuration, but shows a subset of the data for a specific row or column value.

Use trellis binding when you want to compare the same measure across dimensions such as region, product category, department, or time period.

Trellis Binding uses the row and column encodings:

• row creates trellis panels organized by rows.

• column creates trellis panels organized by columns.

• row and column can be used together to create a grid of panels.

  Trellis Binding is supported by all Data Chart types. Axis rendering behavior varies by chart type.

Row Binding

Row binding creates a separate trellis row for each unique value in the bound field.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: { field: "Region" }
}

Column Binding

Column binding creates a separate trellis column for each unique value in the bound field.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  column: { field: "Channel" }
}

Row and Column Binding

You can use row and column bindings together to create a two-dimensional trellis layout.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: { field: "Region" },
  column: { field: "Channel" }
}

Multi-Level Trellis Binding

Trellis row and column bindings support hierarchical fields by using nested child objects. Each level further partitions the trellis layout.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: {
    field: "Region",
    child: {
      field: "City"
    }
  },
  column: {
    field: "Quarter",
    child: {
      field: "Month"
    }
  }
}

Trellis Layout Options

By default, Cartesian trellis charts use shared axes outside the trellis cells. You can set includeAxesInCells to true to render axes inside each trellis cell.

config: {
  trellis: {
    includeAxesInCells: true
  }
}

When axes are rendered inside cells, empty trellis cells can be controlled with includeEmptyCells.

By default, includeEmptyCells is false, and an empty trellis cell still renders its plot area and axes.

When includeEmptyCells is set to true, trellis cells without data are not rendered and appear empty.

config: {
  trellis: {
    includeEmptyCells: true
  }
}

Trellis charts use a shared legend for the entire trellis layout. Tooltips include trellis row and column field values to identify the cell context. For bar and column chart families, bar height or column width is kept consistent across trellis cells for comparison.

Detail Encoding

Detail encoding divides data into additional groups within the current chart structure. It is used to slice the data, but it does not assign colors to data points.

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  details: [{ field: "Region" }]
}

Most chart types that support detail encoding allow one detail field. Sunburst and Treemap charts support multiple detail fields, where the field order defines the hierarchy from outer level to inner level.

encodings: {
  values: [{ field: "Sales" }],
  details: [
    { field: "Category" },
    { field: 'Subcategory' },
    { field: 'Product' }
  ]
}

If multiple detail fields are configured for a chart type that supports only one detail field, only the first detail field takes effect.

Color Encoding

Color encoding determines how colors are assigned to data points and how color legend items are generated.

A Data Chart does not assign colors based on detail encoding automatically. If no color encoding is specified, the chart does not apply the previous built-in color strategy and no color legend is generated.

Color encoding supports the following field types, depending on the chart type:

• String fields

• Numeric fields

• Value Names

String Fields

For most chart types, a string field used for color encoding must already be used in Category or Details. This ensures that the data has already been sliced before colors are assigned.

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  details: [{ field: "Region" }],
  color: { field: "Region" }
}

Numeric Fields

For chart types that support numeric color encoding, a numeric field creates a gradient color legend.

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  color: {
    field: "Sales",
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }
}

When the color field is numeric, aggregation can be applied to the color field. If the color field is not numeric, the aggregation setting does not take effect.

Value Names

Use Value Names when a chart has multiple value fields and each value field should be represented by a separate color.

encodings: {
  values: [
    { field: "Sales" },
    { field: "Return" }
  ],
  category: { field: "Product" },
  color: {
    field: GC.Spread.Sheets.DataCharts.EncodingField.valueName
  }
}

When Value Names is used for color encoding, each value field generates a color legend item.

Chart Type Differences for Detail and Color Encoding

Detail and color encoding behavior can vary by chart type.

• Area and Line charts apply color at the series level. They do not support using Category fields as color fields, and they do not support numeric color encoding.

• Radar and Filled Radar charts follow the same color encoding restrictions as Area and Line charts.

• Scatter and Bubble charts do not support detail encoding. Any string field can be used for color encoding, but Value Names color encoding is not supported.

• Sunburst and Treemap charts support multiple detail fields for hierarchical data.

• Funnel charts do not support detail encoding.

Other Encodings

• size - Applies a continuous size scale. Supported only by bubble charts.

• tooltip - Specifies which fields are displayed in tooltips.

• filter - Applies filtering to source data before aggregation. Supports numeric and string filtering and nested logical conditions.

Compatibility

Data Charts now require encodings to be configured explicitly.

If no color encoding is specified, colors are not assigned by the previous built-in color strategy, and no color legend is generated.

For existing .sjs or .ssjson files, compatibility handling is applied automatically based on the file version.

For code-based configurations, you can pass true as the second parameter of setChartConfig to infer missing encodings for compatibility with previous behavior.

dataChart.setChartConfig(config, true);

For details about the method signature, refer to the API reference.

Using Code

DataCharts bind to tables managed by the SpreadJS Data Manager.

Before configuring a chart, you must:

1. Initialize the Data Manager

2. Register tables

3. (Optional) Define relationships between tables

Step 1 – Initialize the Data Manager

const dataManager = spread.dataManager();

Step 2 – Register Tables

Register all required tables before creating charts.

// Sales table
const salesTable = createSalesTable(dataManager);
await salesTable.fetch();

// Orders table
const ordersTable = createOrders(dataManager);
await ordersTable.fetch();

// Order details table
const orderDetailsTable = createOrderDetails(dataManager);
await orderDetailsTable.fetch();

// Hierarchical sales table (used for hierarchical category examples)
const hierarchySalesTable = createHierarchySalesTable(dataManager);
await hierarchySalesTable.fetch();

Step 3 – Define Table Relationships (Optional)

When binding multiple tables, a relationship must be defined between them.

dataManager.addRelationship(
    ordersTable, "orderId",
    "orderDetailsTable",
    orderDetailsTable, "OrderId",
    "ordersTable"
);

Step 4 – Basic Data Binding Example

The following example binds a Column chart to the Sales table.

const sheet = spread.getSheet(0);
sheet.name("Binding Data");

const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 600, 400);

dataChart.setChartConfig({
    tableName: 'Sales',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: "Sales",
                aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
            }],
            category: {
                field: "Product"
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Product"
        }
    }
});

Step 5 – Binding Multiple Tables

When a relationship exists, fields from related tables can be referenced using a path expression.

The following example binds a chart to the Orders table and aggregates data from the related orderDetailsTable.

let sheet2 = spread.getSheet(1);
sheet2.name("Binding Multiple Tables");

const dataChart2 = sheet2.dataCharts.add('data-chart-2', 10, 10, 600, 400);

dataChart2.setChartConfig({
    tableName: 'Orders',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'orderDetailsTable.Sales'
            }],
            category: {
                field: 'shipCountry'
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Country (Multiple Tables)"
        }
    }
});

Step 6 – Hierarchical Category Binding

DataCharts support multi-level category grouping by defining nested child fields within the category encoding.

The following example binds a Column chart using a hierarchical category structure (Year → Quarter → Month).

let sheet3 = spread.getSheet(2);
sheet3.name("Hierarchical Category Binding");

const dataChart3 = sheet3.dataCharts.add('data-chart-3', 10, 10, 600, 400);

dataChart3.setChartConfig({
    tableName: 'HierarchySales',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'sales'
            }],
            category: {
                field: "year",
                    child: {
                        field: "quarter",
                            child: {
                                field: "month"
                            }
                        }
            }
        }
    }],
    config: {
        header: {
            title: "Hierarchical Column Chart"
        }
    }
});

Complete Example

The implementations of the following functions are not shown in this topic:

• createSalesTable

• createOrders

• createOrderDetails

• createHierarchySalesTable

Download the complete runnable example, including all table creation utilities:

BindDataSourceExample.js