All pages
Powered by GitBook
1 of 5

Vega Reference Overview

A Vega specification is a JSON-formatted structure that describes a visualization, which can be sent to the back end for rendering. This document introduces the the Vega specification syntax and provides links to topics that provide more details about each Vega property.

For examples of using Vega, see Tutorials. You can also see and edit examples in Try Vega.

Specification Language Syntax

The Vega specification includes properties for describing the source data, mapping the data to the visualization area, and visual encoding. The root Vega specification supported by OmniSci has the following JSON structure and top-level properties:

{
  "width": <number>,
  "height": <number>,
  "data": [],
  "projections": [],
  "scales": [],
  "marks": []
}
Property
Type
Description

width and height

unsigned integer

Visualization area width and height, in pixels. Both properties are required. Example: Set the viewing area width to 384 pixels and the height to 564 pixels:

array

Source data. The Vega data model uses tabular data, similar to a spreadsheet. Organized in rows with any number of named columns. JSON format:

array

Projection data. Maps longitude and latitude data to projected x and y coordinates. JSON format:

array

Data-to-visualization area mapping. Maps visually encoded data values to pixel positions with attributes, such as color. JSON format:

array

Geometric primitive used to visually encode data. JSON format:

Format Rules

  • Property names are case-sensitive.

  • Property values are typed.

  • Unsupported properties are ignored by the rendering engine.

data Property

Use the Vega data property to specify the visualization data sources by providing an array of one or more data definitions. A data definition must be an object identified by a unique name, which can be referenced in other areas of the specification. Data can be statically defined inline ("values":), can reference columns from a database table using a SQL statement ("SQL":), or can be loaded from an existing data set ("source":).

JSON format:

"data": [
  {
    "name": <dataID>,
    "format": {
      "type": "lines" | "polys",
      "coords": {
        "x": <array>
        "y": <array>
      }
      "layout": "interleaved" | "sequential"
    "values": <valueSet> | "SQL": <dataSource> | "source": <dataSource>,
    "transform": [
      {
        "type": "aggregate"
         "fields": ["string":"string"]
         "ops": ["keyword":"keyword"]
         "as": ["string":"string"]
      }  
  },
  {
     ...
  }
]

The data specification has the following properties:

Property
Data Type
Required
Description

string

X

User-assigned database table name.

string/object

How the data are parsed. polys and lines are the only supported format mark types and are for rendering purposes only. Use the single string "short form" for polygon and simple linestring renders. Use the JSON object "long form" to provide more information for rendering more complex line types.

string

Data source:

values: Embedded, static data values defined inline as JSON.

sql: A SQL query that loads the data.

string

An array of transforms to perform on the input data. The output of the transform pipeline then becomes the value of this data set. Currently, can only be used with source data set types.

boolean

If true, automatically adds rowid column(s) to the SQL statement, which is required for hit-testing using the get_result_row_for_pixel endpoint.

Examples

Load discrete x- and y column values using the values database table type:

vegaSpec = {
    width: 384,
    height: 564,
    data: [
        {
          name: "coordinates",
          values: [ {"x":0, "y":3}, {"x":1, "y":5} ],
    scales: [ ... elided ... ],
    marks: [ ... elided ... ]
};

Use the sql database table type to load latitude and longitude coordinates from the tweets_data database table:

vegaSpec = {
    width: 384,
    height: 564,
    data: [
        {
          name: "tweets",
          sql: "SELECT lon as x, lat as y FROM tweets_data WHERE (lon >= -32 AND lon < 66) AND (lat >= -45 AND lat < 68)"
        }
    ],
    scales: [ ... elided ... ],
    marks: [ ... elided ... ]
};

Use the source type to use the data set defined in the sql data section and perform aggregation transforms:

vegaSpec = {
      width: 384,
      height: 564,
      data: [
              {
                      name: "tweets",
                      sql: "SELECT lon as x, lat as y FROM tweets_data WHERE (lon >= -32 AND lon < 66) AND (lat >= -45 AND lat < 68)"
              },
              {
                      name: "tweets_stats",
                      source: "tweets",
                      transform: [
                              {
                                      type: "aggregate",
                                      fields: ["x", "x"],
                                      ops: ["min", "max"],
                                      as: ["minx", "maxx"]
                              }
                      ]
              },
      ],
      scales: [ ... elided ... ],
      marks: [ ... elided ... ]
}

Data Properties

name

The name property uniquely identifies a data set, and is used for reference by other Vega properties, such as the Marks property.

format

The format property indicates that data preprocessing is needed before rendering the query result. If this property is not specified, data is assumed to be in row-oriented JSON format.

This property is required for Polys and Lines mark types. The property has one of two forms:

  • The "short form", where format is a single string, which must be either polys or lines. This form is used for all polygon rendering, and for fast ‘in-situ’ rendering of LINESTRING data.

  • The "long form", where format is an object containing other properties, as follows:

Format Property
Description

type

Marks property type:

coords

Applies to type: lines.

Specifies x and y arrays, which must both be the same size.

This permits column extraction pertaining to line rendering and place them in a rendering buffer. The coords property also dictates the ordering of points in the line.

Separate x- and y-array columns are also supported.

layout

(optional) Applies to type: lines.

Specifies how vertices are packed in the vertices column. All arrays must have the same layout:

  • interleaved: (default) All elements corresponding to a single vertex are ordered in adjacent pairs. For example, x0, y0, x1, y1, x2, y2.

  • sequential: All elements of the same axis are adjacent. For example, x0, x1, x2, y0, y1, y2.

For lines, each row in the query corresponds to a single line.

This lines format example of interleaved data renders ten lines, all of the same length.

"data": [
  {
    "name": "table",
    "sql": "select lineArrayTest.rowid as rowid, vertices, color from lineArrayTest order by color desc limit 10;",
    "format": {
      "type": "lines",
      "coords": {
        "x": ["vertices"],
        "y": [
          {"from": "vertices" }
        ]
      },
      "layout": "interleaved"
    }
  }
]

In this lines format example of sequential data, x only stores points corresponding to the x coordinate and y only stores points corresponding to the y coordinate. Make sure that columns only contain a single coordinate if using multiple columns in sequential layout.

"data": [
  {
    "name": "table",
    "sql": "select lineArrayTestSeq.rowid as rowid, x, y, color from lineArrayTestSeq order by color desc limit 10;",
    "format": {
      "type": "lines",
      "coords": {
        "x": ["x"],
        "y": ["y"]
      },
    "layout": "sequential"
    }
  }
],

The following example shows a fast "in-situ" LINESTRING format:

"data": [
  {
    "name": "table",
    "format": "lines",
    "sql": "SELECT rowid, linestring_column, ... FROM ..."
  }
]

The following example shows a polys format:

"data": [
  {
    "name": "polys",
    "format": "polys",
    "sql": "SELECT ... elided ..."
  }
]

Data Source

The database table source property key-value pair specifies the location of the data and defines how the data is loaded:

Key
Value
Description

source

String

Data is loaded from an existing data set.

sql

SQL statement

Data is loaded using a SQL statement.

values

JSON data

Data is loaded from static, key-value pair data definitions.

transform

Transforms process a data stream to calculate new aggregated statistic fields and derive new data streams from them. Currently, transforms are specified only as part of a source data definition. Transforms are defined as an array of specific transform types that are executed in sequential order. Each element of the array must be an object and must contain a type property. Currently, two transform types are supported: aggregate and formula.

Type
Description and Properties

aggregate

Performs aggregation operations on input data columns to calculate new aggregated statistic fields and derive new data streams from them. The following properties are required:

fields: An array of strings referencing columns from the sourced data table.

ops: An array of keyword strings and objects indicating the predefined operation to perform. For objects, the type property is required to name the type of the aggregation function. Supported operators:

  • count: The total count of data objects in the group.

  • countdistinct: The number of distinct values in an input data column; operates only on numeric or dictionary-encoded string columns.

  • distinct: An array of distinct values from an input data column; operates only on numeric or dictionary-encoded string columns.

  • max: The maximum field value.

  • mean / average / avg: The mean (average) field value.

  • median: The median of an input data column; operates only on numeric columns.

  • min: The minimum field value.

  • missing: The count of field values that are null or undefined.

  • quantile: An array of quantile separators; see https://en.wikipedia.org/wiki/Quantile. Operates only on numeric columns:

    • numQuantiles: The number of contiguous intervals to create; returns the separators for the intervals. The number of separators equals numQuantiles - 1. Range: 1-100. Default: 4

    • includeExtrema: Whether to include min and max values (extrema) in the resulting separator array. When true, the resulting array size is numQuantiles + 1. Values: true or false. Default: false

  • sum: The sum of field values.

  • stddev: The sample standard deviation of field values.

  • stddevp: The population standard deviation of field values.

  • valid: The count of field values that are not null nor undefined.

  • variance: The sample variance of field values.

  • variancep: The population variance of field values.

as: An array of strings used as output names of the operations for later reference.

formula

Evaluates a user-defined expression. The following properties are required:

as: A string used as an output name for later reference.

Note: Currently, expressions can only be performed against outputs (as values) from prior aggregate transforms.

See Tutorial: Using Transforms for more detailed examples.

enableHitTesting

If true, automatically adds rowid column(s) to the SQL statement where appropriate, enabling the data block for hit-testing using the get_result_row_for_pixel endpoint.

If false, the data block is not automatically hit-test enabled, and any later get_result_row_for_pixel calls return empty hit-test results.

If the enableHitTesting property is not present, the following legacy behavior is used as the default:

  • If the SQL statement represents a projection query, hit-testing is enabled if a rowid column is explicitly projected.

  • If the SQL statement represents an aggregate query, hit-testing is always enabled.

This legacy behavior will likely be deprecated and removed in an upcoming version of OmniSci. At that point, the enableHitTesting property will be required for activating hit-test support for the data.

projections Property

Vega projections map longitude and latitude data to projected x and y coordinates. When working with geospatial data in OmniSci, you can use projections to define geographic points and regions.

General projections property JSON format:

"projections": [
       {
         "name": "<projectionName>",
         "type": "<projectionType>",
         "bounds": {
               "x": [<minLong>,<maxLong>],
               "y": [<minLat>,<maxLat>]
         }
       }
]

When you specify a projection, you must reference it in the Marks Property using the transform object. For example, if you define the projection my_mercator_projection:

"projections": [
{
   "name": "my_mercator_projection",
   "type": "mercator",
   "bounds": {
     "x": [-120.0, 120.0],
     "y": [-20.0,20.0]
   }
 }
 ]

you then reference it as follows:

"marks": [
{
   "type": "symbol",
   "from": { "data": "fec_contributions_oct" },
   "properties": { ... elided ... }
   "transform": {
      "projection": "my_mercator_projection"
   }
 }
 ]

The projections specification has the following properties:

Property
Data Type
Required
Description

name

string

X

User-assigned name of the projection.

type

string

X

Projection type. Currently supported types:

  • mercator: Mercator map projection.

bounds

object

Specifies the longitude and latitude bounding box for the projection. Default values:

  • x: [-180.0, 180.0]

  • y: [-85.0, 85.0]

Example

Use Vega projection projection alongside array columns:

{
      "width": 1024,
      "height": 1024,
      "data": [
              {
                      "name": "table",
                      "sql": "SELECT rowid, coords[1] as x, coords[2] as y FROM cities WHERE coords[1] BETWEEN $minLon AND $maxLon AND coords[2] BETWEEN $minLat AND $maxLat"
              }
      ],
      "projections": [
      {
              "name": "projection",
              "type": "mercator",
              "bounds": {
              "x": [-120.0, 120.0],
              "y": [-20.0, 20.0]
              }
      }
      ],
      "scales": [
      ],
      "marks": [
              {
                      "type": "symbol",
                      "from": {"data": "table"},
                      "properties": {
                              "shape": "circle",
                              "xc": {
                                      "field": "x"
                              },
                              "yc": {
                                      "field": "y"
                              },
                              "fillColor": "darkblue",
                              "width": 25,
                              "height": 25
                      },
                      "transform": {
                              "projection": "projection"
                      }
              }
      ]
}

scales Property

The Vega scales property maps visually encoded data values to pixel positions with attributes, such as color. See the D3 scales documentation for additional background information about scales.

General scales property JSON format:

"scales": [
  {
    "name": <scaleID>,
    "type": <scaleType>,
    "domain": <inputValues>,
    "range": <outputValues>"
    "accumulator": <accumulatorType>
    "default": <defaultOutputValue>,
    "nullValue": <nullDataValue>
  },
  {
     ...
  }
],

The scales specification is one or more arrays with the following properties:

Property Field
Data Type
Required
Description

name<code></code>

string

X

User-defined scale name.

type<code></code>

string

Scale type, which specifies the domain-to-range transform:

  • linear: Quantitative, continuous scale that preserves proportion among data items.

  • log: Quantitative scale that applies a logarithmic transform to the data.

  • ordinal: Discrete domain and range scale.

  • pow: Quantitative scale that applies an exponential transform to the input data.

  • quantize: Quantitative, discrete scale that divides input data into segments.

  • sqrt: Quantitative scale that applies an square root transform to the input data.

  • threshold: Discrete scale that maps arbitrary domain subsets to discrete range values.

domain<code></code>

array

Domain. Array of input interval data values.

range<code></code>

string or array

Range. Array of output interval visual data values.

default<code></code>

number

Default output value to use when domain value does not map to range value.

accumulator<code></code>

string

Accumulation rendering type:

blend: Blends colors by category. Works only for discrete output scales (ordinal, quantize, and threshold).

density: Performs count aggregation per pixel and applies the supplied color based on the normalization of the per-pixel aggregated counts over a specified range. The range is determined by the required minDensityCnt and maxDensityCnt properties. minDensityCnt and maxDensityCnt can be explicit integer values or one of the following keywords that automatically compute statistical information about the per-pixel counts:

  • min

  • max

  • -1stStdDev

  • -2ndStdDev

  • 1stStdDev

  • 2ndStdDev

pct: Apply a color range based on percentage accumulation for a specific category.

nullValue

number

Specify the output value to use when the input value is null.

Note: As a general rule, limit the total number of domain and range values used to a maximum of 1000. Exceeding this limit can cause an error.

Example

Define two scales, x and y. For the x scale, linearly transform input data values between -100 and 999 to the visualization area width. For the y scale, linearly transform input data values between 0 and 500 to the visualization area height. The width and height range values are pre-defined literals that reference the width and height properties.

vegaSpec = {
    width: 384,
    height: 564,
    data: [ ... elided ... ],
    scales: [
        {
            name: "x",
            type: "linear",
            domain: [ -100, 999 ],
            range: "width"
        },
        {
            name: "y",
            type: "linear",
            domain: [ 0, 500 ],
            range: "height"
        }
    ],
    marks: [ ... elided ... ]
};

Scales Properties

name

The name property uniquely identifies the scale for reference by other properties.

type

The type property specifies how to transform the input, domain data to output, range visual values. Vega supports the following transforms, categorized by quantitative, discrete, and discretizing scales:

Quantitative Scales

Type
Description
Additional Information

linear

Preserves proportional differences, where range value y can be expressed as a linear function of the domain value x: y = mx + b.

D3 linear scale

log

Applies a logarithmic transform to the input domain value before the output range value is computed. The mapping to the range value y can be expressed as a logarithmic function of the domain value x: y = m log(x) + b.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative. The domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values. A log scale with a negative domain has a well-defined behavior for negative values. For a negative domain, input and output values are implicitly multiplied by -1. The behavior of the scale is undefined if you compute a negative value for a log scale with a positive domain, and vice versa.

log scale values must be positive. Default = base 10.

D3 logarithmic scale

pow

Applies an exponential transform to the input domain value before the output range value is computed. Range value y can be expressed as a polynomial function of the domain value x: y = mx^k + b, where k is the exponent. Power scales also support negative domain values, and input value and resulting output value are then multiplied by -1.

Default exponent = 1.

D3 power scale

sqrt

A shorthand for power scales with an exponent of 0.5, indicating a square root transform.

sqrt scale values must be positive.

D3 sqrt scale

Discrete Scales

Type
Description
Resource

ordinal

Applies a discrete domain-to-range transform, and functions as a lookup table from a domain value to a range value.

Specify a default value for domain values that do not map to a range.

D3 ordinal scale

Discretizing Scales

Type
Description
Resource

quantize

Divides input domain values into uniform segments based on the number of values in, or the cardinality of, the output range, where range value y can be expressed as a quantized linear function of the domain value x: y = m round(x) + b.

D3 quantize scale

threshold

Maps arbitrary, non-uniform subsets of the domain to discrete range values. The input domain is continuous but divided into slices based on a set of domain threshold values. The range must have N+1 elements, where N is the number of domain threshold boundaries.

D3 threshold scale

domain

The domain field specifies the domain of input data values. For quantitative data, this can take the form of a two-element array.

Example:

Specify minimum and maximum input values.

domain: [ -100, 999 ]

For ordinal or categorical data, the domain can be an array of valid input values.

Example

Specify valid input data languages.

"domain": ["en",  "es", "fr"]

range

Scale range specifies the set of visual values. For numeric values, the range can take the form of a two-element array with minimum and maximum values. For ordinal or quantized data, the range can be an array of desired output values, which are mapped to elements in the specified domain.

Scale ranges can be specified in the following ways:

  • As an array of static values: "range": [0, 500] or "range": ['a', 'b', 'c'].

  • Using pre-defined literals: "range": "width" or "range": "height".

Example

Specify a color scale that quantizes input values between 0 and 100 among five visual output colors.

{
  name: "color",
  type: "quantize",
  domain: [ 0, 100 ],
  range: [ "#115f9a", "#1984c5", "#c9e52f", "#d0ee11", "#d0f400"
  ]
}

Scale ranges can accept width and height string literals that map to the Width and Height Properties.

Value
Description

width

A spatial range that is the value of t``width``.

height

A spatial range that is the value of height. The direction of the range, top-to-bottom or bottom-to-top, is determined by to the scale type.

Example

Specify a y scale that linearly maps input values between 0 and 500 to the height of the visualization area.

{
    name: "y",
    type: "linear",
    domain: [ 0, 500 ],
    range: "height"
}

default

The default scales property specifies the output value to use when the input domain value does not map to the range.

The default property is not applicable to the threshold scale type, which maps domain values outside of the range to either the lowest or highest range value.

accumulator

The accumulator property enables you to identify regional density of data in a layer of a backend render and apply pixel coloring based on the accumulation mode that you have defined. Each data point is rendered individually, providing an accurate representation of data distribution in a spatial setting.

Mode
Description

density

Perform count aggregation per pixel and define a color for a pixel by normalizing the count and applying a color to it based on a color scale.

You can activate density accumulation for any scale that takes as input a continuous domain (linear, sqrt, pow, log, threshold scales) and outputs a color range. The range is determined by the required minDensityCnt and maxDensityCnt properties. minDensityCnt and maxDensityCnt can be explicit integer values or one of the following keywords that automatically compute statistical information about the per-pixel counts:

  • min

  • max

  • -1stStdDev

  • -2ndStdDev

  • 1stStdDev

  • 2ndStdDev

Note: Domain values of density accumulators must be between 0 and 1 inclusive.

blend

Blend by category (ultimately an ordinal scale). You can provide a color to a category and blend those colors to show the density of the distinct categorical values at a pixel.

pct

For a specific category, apply color based on the percentage of the category in a region.

Example

Apply a density accumulator to a linear scale named pointcolor:

{
  "name": "pointcolor",
  "type": "linear",
  "domain": [0.0,1.0],
  "range": ["blue","red"],
  "clamp": true,
  "accumulator": "density",
  "minDensityCnt": 1,
  "maxDensityCnt": 100
}

The color at a pixel is determined by normalizing per-pixel aggregated counts and using that value in the scale function to calculate a color. Normalization is performed according to the required minDensityCnt and maxDensityCnt properties. After normalization, minDensityCnt == 0 and maxDensityCnt == 1.

minDensityCnt and maxDensityCnt can have explicit integer values or use one of the following keywords to compute statistical information about per-pixel counts: min, max, -1stStdDev, -2ndStdDev, 1stStdDev, 2ndStdDev.

For more detailed examples of using accumulators, see Tutorial: Vega Accumulator.

marks Property

Marks visually encode data using geometric primitives.

General JSON format:

"marks": [
  {
    "type": points | line | polys | symbol,
    "from": { data: <dataSourceID> },
    "properties": { <propName>: <propVal> }, ... { <propName>: <propVal> }
    "transform": { <transformType>: <transformName> }
  },
  {
    ...
  }
],

A Vega marks specification includes the following properties:

Property
Data Type
Required
Description

type

string

X

Graphical marks type or shape:

  • points

  • lines

  • polys

  • symbol

from

object

Database table associated with the marks.

properties

object

X

Visual encoding rules. Valid properties depend on marks type.

transform

object

Transforms applied to a mark.

Each marks property is associated with the specified data property.

Marks are rendered in marks property array order.

Marks property values can be constants or as data references. You can use the scales property to transform marks property values to the visualization area.

Apply the x and y scales to the x and y database table columns to scale the data to the visualization area width and height. For example:

const exampleVega = {
  "width:" 384,
  "height:" 564,
  "data:" [ ... elided ... ],
  "scales:" [
    {
      "name:" "x",
      "type:" "linear",
      "domain:" [-3650484.1235206556,7413325.514451755],
      "range:" "width"
    },
    {
      "name:" "y",
      "type:" "linear",
      "domain:" [-5778161.9183506705, 10471808.487466192],
      "range:" "height"
    }
  ],
  "marks:" [
    {
      "type:" "points",
      "from:" { "data:" "tweets" },
      "properties:" {
        "x:" { "scale:" "x", "field:" "x" },
        "y:" { "scale:" "y","field:" "y"}
      }
    }
  ]
};

marks Properties

type

Marks must include a type property that specifies the geometric primitive to use to render the data.

Marks Type
Description

points``

Render marks as points.

lines``

Render marks as lines.

polys``

Render marks as a polygon.

symbol``

Render marks as a shape.

points Type

Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.

points Examples

Define a point with size, color, and opacity:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
    {
      "name" : "table",
        "values": [
          {"x": 412, "y": 512, "val": 0.9,"color": "red"},
          {"x": 512, "y": 512, "val": 0.3, "color": "violet"},
          {"x": 612, "y": 512, "val": 0.5,"color": "green"}
        ]
     }
      ],
  "marks" : [
    {
      "type" : "points",
      "from" : {"data" : "table"},
        "properties" : {
          "x" : { "field" : "x" },
          "y" : { "field" : "y" },
          "fillColor" : {
              "field" : "color"
                      },
                      "size" : 150.0,
                      "fillOpacity" : {
                              "field" : "val"
                      },
                      "opacity" : 0.8
               }
             }
       ]
     }

Associate the points geometric primitive with tweets data items.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
            "name": "tweets",
            "sql": "SELECT  ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "points",
            "from": { data: "tweets" },
            "properties": { ... elided ... }
        },
        { ... elided ... }
    ]
};

lines Type

Specifying the data format property as lines causes the rendering engine to assume a lines database table layout and to extract line-related columns from the table.

Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.

lines Example

{
  "type": "lines",
  "from": {"data": "table"},
  "properties": {
    "x": {
      "field": "x",
      "scale": "x"
    },
    "y": {
      "field": "y",
      "scale": "y"
    },
    "strokeColor": {
      "scale": "strokeColor",
      "field": "color"
    },
    "strokeWidth": 2,
    "lineJoin": "miter",
    "miterLimit": 10
  }
}

polys Type

The polys type renders data as a polygon. When the data format property is polys, the rendering engine assumes a polys database table layout and extracts the poly-related columns from the table. A polys database table layout implies that the first data column is the vertex x- and y-positions. The vertices are interleaved x and y values, such that vertex[0] = vert0.x, vertex[1] = vert0.y, vertex[2] = vert1.x, and vertex[3] = vert1.y, for example. The next three positions of a polys database table are the triangulated indices, and line loop and drawing information for unpacking multiple, associated polygons that can be packed as a single data item.

polys Example

const exampleVega = {
  "width": 1004,
  "height": 336,
  "data": [
    {
      "name": "polys",
      "format": "polys",
      "sql": "SELECT ... elided ..."
    }
  ],
  "scales": [ ... elided ... ]
  "marks": [
    {
      "type": "polys",
      "from": {
        "data": "polys"
      },
      "properties": {
        "x": {
          "scale": "x",
          "field": "x"
        },
        "y": {
          "scale": "y",
          "field": "y"
        },
        "fillColor": {
          "scale": "polys_fillColor",
          "field": "avgContrib"
        },
        "strokeColor": "white",
        "strokeWidth": 0,
        "lineJoin": "miter",
        "miterLimit": 10
      }
    }
  ]
}

symbol Type

The symbol marks type renders data as one of the supported shapes.

Currently, in symbol mark types, strokes are not visible beneath other marks, regardless of opacity settings.

Specify x and y coordinate values using either constants or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be specified using constant values.

symbol Examples

const exampleVega = {
  "width": 733,
  "height": 530,
  "data": [
    {
      "name": "heatmap_query",
      "sql": "SELECT ... elided ... "
    }
  ],
  "scales": [ ... elided ... ],
  ],
  "marks": [
    {
      "type": "symbol",
      "from": {
        "data": "heatmap_query"
      },
      "properties": {
        "shape": "square",
        "x": { "field": "x" },
        "y": { "field": "y" },
        "width": 1,
        "height": 1,
        "fillColor": { "scale": "heat_color", "field": "cnt" }
      }
    }
  ]
};

The following example defines symbol mark types including fill, stroke, and general opacity properties:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
      {
          "name" : "table",
          "values": [
              {"x": 200,  "x2": 0.0, "y": 200.0, "y2": 0.0, "val" : 0, "color" : "red", "color2": "yellow", "opacity": 1.0, "fillOpacity":0.75, "strokeOpacity": 0.25},
              {"x": 220.806,  "x2": 0.0, "y": 263.75, "y2": 0.0, "val" : 1, "color" : "blue", "color2": "green", "opacity": 0.5, "fillOpacity": 0.5, "strokeOpacity": 0.5},
              {"x": 240.61216,  "x2": 0.0, "y": 327.5, "y2": 0.0, "val" : 0, "color" : "maroon", "color2": "magenta", "opacity": 0.1, "fillOpacity": 0.25, "strokeOpacity": 0.75}
          ]
      }
  ],
  "marks" : [
      {
          "type" : "symbol",
          "from" : {"data" : "table"},
          "properties" : {
                      "shape" : "circle",
              "xc" : { "field" : "x" },
              "yc" : { "field" : "y" },
                      "width": 150.0,
                  "height": 150.0,
              "opacity": 0.9,
              "fillOpacity": {
                  "field": "fillOpacity"
              },
              "fillColor" : {
                  "field": "color2"
              },
                      "strokeWidth" : 10.0,
                      "strokeColor" : {
                  "field": "color"
              },
              "strokeOpacity": {
                  "field": "strokeOpacity"
              }
          }
      }
   ]
}

from

The from field specifies the input database table to use.

Data Source Field
Data Type
Description

data

string

Name of the data source. The data name must be defined in the data property.

Example

Use the tweets database table for marks input data.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
          "name": "tweets",
          "sql": "SELECT ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "polys",
            "from": {"data": "tweets"},
            "properties": { ... elided ... }
        }
    ]
};

If from is not specified, the data source is implicitly a single point with the value defined in the points properties.

properties

The properties property specifies type-dependent visual encoding that define the position and appearance of mark instances. The property value is specified using one of the Value Reference options.

Typically, a single mark instance is generated per input data element, except for polys, which uses multiple data elements to represent a line or area shape.

The following table describes the various marks properties and lists the types for which the property is valid.

Property
Data Type
Valid Primitive Types
Description

angle

number

symbol

Amount of rotation about the defined center of rotation. The center of rotation depends on the properties that specify the symbol location:

  • x and y: Lower-left corner.

  • x and yc: Left center.

  • xc and y: Bottom center.

  • xc and yc: Center.

Must be a numerical constant or a scale that provides numerical values.

In the following example, the triangle-down symbol is rotated 30 degrees about the downward point:

angleUnit

string

symbol

Optional. Unit of measure for the rotation of a symbol around the center of rotation, defined in angle. Either degrees (default) or radians.

fillColor

color

points, polys, symbol

Fill color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.

fillOpacity

number

points, polys, symbol

The fill opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.

height

number

symbol

Mark height, in pixels.

lineJoin

string

line, polys, symbol

Line join method:

  • bevel - Extension of a line end

  • miter - Clipped extension of a line end

  • round - Semi-circle at a line end

miterLimit

number

line, polys, symbol

The miter limit at which to bevel a line join, in pixels.

Must be a positive number. Default = 10.0

opacity

number

all

The line opacity as a whole, from transparent (0) to opaque (1). If used with fillOpacity (points, polys, symbol) or strokeOpacity (lines), the values are multiplied together to determine final opacity.

shape

string

symbol

Shape name:

  • circle

  • cross

  • diamond

  • hexagon-horiz

  • hexagon-vert

  • square

  • triangle-down

  • triangle-left

  • triangle-right

  • triangle-up

  • wedge

size

number

points

Graphical primitive size, in pixels. Must be a scale/data reference or a number.

stroke

color

symbol

Stroke color.

strokeColor

color

line, polys

Stroke color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.

Default color = white

strokeOpacity

number

line, polys, symbol

Stroke opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.

strokeWidth

number

line, polys, symbol

Stroke width, in pixels. Must be a scale/data reference or a number.

width

number

symbol

Mark width, in pixels.

x

number

all

Primary x-coordinate, in pixels. Must be a scale/data reference for polys, or a scale/data reference or a number for points, lines, or symbol. See Value Reference.

x2

number

symbol

Secondary x-coordinate, in pixels. See Value Reference.

xc

number

symbol

Center x-coordinate, in pixels. Incompatible with x and x2. See Value Reference.

y

number

all

Primary y-coordinate, in pixels. Must be a scale/data reference for polys, or a scale/data reference or a number for points, lines, or symbol. See Value Reference.

y2

number

symbol

Secondary y-coordinate, in pixels. See Value Reference.

yc

number

symbol

Center y-coordinate, in pixels. Incompatible with y and y2. See Value Reference.

z

number

points, symbol

Primary depth-coordinate, in pixels. Must be a scale/data reference or a number. See Value Reference.

Value Reference

A value reference describes how to specify marks properties values. The value can be a constant or data object reference:

Name
Type Description

value

Any

Constant value. If field is specified, value is ignored.

field

Field Reference

Perform a lookup on the current data value. The marks from property determines the source data table and the field name must be a column defined in the data property.

scale

Field Reference

Name of a scale transform to apply to the mark. If the input is an object, it indicates a field value from which to dynamically look up the scale name and follows the Field Reference format.

Examples:

Statically set the point fillColor and size.

"marks:" [
  {
    "type:" "points",
    "from:" {
      "data:" "tweets"
    },
    "properties:" {

         ... elided ...

      "fillColor": "blue",
      "size": 3
      }
    }
  }
]

For the x marks property, apply the x scale transform to the implicit x-coordinate data column.

"marks": [
  {
    "type": "polys",
    "from": {
      "data": "polys"
    },
    "properties": {
      "x": {
        "scale": "x",
        "field": "x"
      },

      ... elided ...

    }
  }
]

Field Reference

A field reference is either a string literal or an object. For object values, the following properties are supported:

Property
Type
Description

Property Name

FieldRef

Perform a lookup on the property name. This is the default operation when a field reference is a string.

Color Value Reference

Typically, color values are specified as a single RGB color value. To specify specific color fields or use a different color space, use one of the following color value reference formats:

Property Value Field
Data Type
Description

field

string

Name of the attribute from the data: sql field.

colorSpace

string

Space in which the color is defined:

  • Hue-Chroma-Luminance color space. See HCL color space.

    • Use r, g, and b property names.

  • Hue, saturation, and lightness color space. See HSL and HSV color space.

    • Use h, s, and l property names.

  • Lab color space. A perceptual color space with distances based on human color judgments. The L dimension represents luminance, the A dimension represents green-red opposition and the B dimension represents blue-yellow opposition. See Lab color space.

    • Use l, a, and b property names.

  • RGB color space. A version of LAB, which uses polar coordinates for the AB plane. See RGB color space.

    • Use h, c, and l property names.

Examples

Set the red and blue channels of an RGB color as constants, and uses a scale transform to determine the green channel:

"fill": {
  "r": {"value": 255},
  "g": {"scale": "green", "field": "g"},
  "b": {"value": 0}
}

Use the rgb color space for the color field:

"fillColor": {
    "field": "color",
    "colorSpace": "rgb"
}

transform

The transform object specifies any Vega projections to be applied to the mark. Each transform is specified as a key:value pair in the transform object:

},
"transform": {
      "<key>": "<value>"
}

The value references an existing Vega object by name.

For example, the following transform references the projection my_mercator_projection defined in the top-level Vega projections property.

"projections": [
{
  "name": "my_mercator_projection",
  "type": "mercator",
  "bounds": {
    "x": [-120.0, 120.0],
    "y": [-20.0, 20.0]
  }
}
]
"marks": [
{
  "type": "symbol",
  "from": { "data": "fec_contributions_oct" },
  "properties": { ... elided ... }
  "transform": {
    "projection": "my_mercator_projection"
  }
}
]

Currently, the only supported transform is projection.