Data

Data set definitions and transforms define the data to load and how to process it.

The basic data model used by Vega is tabular data, similar to a spreadsheet or database table. Individual data sets are assumed to contain a collection of records (or “rows”), which may contain any number of named data attributes (fields, or “columns”). Records are modeled using standard JavaScript objects.

If the input data is simply an array of primitive values, Vega maps each value to the data property of a new object. For example [5, 3, 8, 1] is loaded as:

[ {"data": 5}, {"data": 3}, {"data": 8}, {"data": 1} ]

Upon ingest, Vega also assigns each data object a unique id property, accessible via a custom Symbol. As a result, the id property is not accessible via a string key and is not enumerable, though you can observe the id value when inspecting data objects in a JavaScript console.

Data sets can be specified directly by defining data inline or providing a URL from which to load the data. Alternatively, data can be bound dynamically at runtime by using the View API to provide data when a chart is instantiated or issue streaming updates. Loading data from a URL will be subject to the policies of your runtime environment (e.g., cross-origin request rules).

Documentation Overview

• Data Properties
• Data Formats
• Examples

Data Properties

Properties for specifying a data set. At most one of the source, url, or values properties should be defined.

Dynamic Data Loading

≥ 4.2 For Vega version 4.2 and higher, the data url parameter and (when used with URL-loading) the format parameter may include signal references. This feature allows either the source url or one or more formatting parameters to be dynamically changed at runtime, causing the data to be reloaded. For example, a single spec might load a different dataset based on user input, or the data might be polled at a regular interval in conjunction with a timer event stream.

If no signals are used (the traditional configuration), external data sources are loaded immediately upon view construction and the first dataflow evaluation is delayed until data loading is complete. For dynamic loading, the dataflow must first be evaluated in order to determine the signal values, and then data can be loaded. As a result of this, downstream transforms and encodings may initially be evaluated with empty datasets: be sure any signal expressions behave appropriately with empty data, including downstream concerns such as empty scale domains.

Format

The format object describes the data format and additional parsing instructions.

json

Loads a JavaScript Object Notation (JSON) file. Assumes row-oriented data, where each row is an object with named attributes. This is the default file format, and so will be used if no format parameter is provided. If specified, the format parameter should have a type property of "json", and can also accept the following:

csv

Load a comma-separated values (CSV) file.

tsv

Load a tab-separated values (TSV) file.

dsv

Load a delimited text file with a custom delimiter.

topojson

Load a JavaScript Object Notation (JSON) file using the TopoJSON format. The input file must contain valid TopoJSON data. The TopoJSON input is then converted into a GeoJSON format for use within Vega. There are two mutually exclusive properties that can be used to specify the conversion process:

Examples

Here is an example defining data directly in a specification:

{"name": "table", "values": [12, 23, 47, 6, 52, 19]}

One can also load data from an external file (in this case, a JSON file):

{"name": "points", "url": "data/points.json"}

Or, one can simply declare the existence of a data set. The data can then be dynamically provided when the visualization is instantiated. See the View API documentation for more.

{"name": "table"}

Finally, one can draw from an existing data set and apply new data transforms. In this case, we create a new data set ("stats") by computing aggregate statistics for groups drawn from the source "table" data set:

{
  "name": "stats",
  "source": "table",
  "transform": [
    {
      "type": "aggregate",
      "groupby": ["x"],
      "ops": ["average", "sum", "min", "max"],
      "fields": ["y", "y", "y", "y"]
    }
  ]
}