CARTO VL

Introduction to Expressions

Expressions are functions used to define the style properties of a layer. The main types of expressions are: number, string, color and, date. CARTO VL also includes arrays to define lists of string categories or custom color schemes.

Types of Expressions

Number

Number expressions allow you to work with numeric values in your data (e.g. 1, 2 + 3, 4 * 5) or by defining numeric constants (e.g. TRUE, FALSE, PI, E). Numeric expressions can be evaluated to get the result:

1
2
3
4
const viz = new carto.Viz(`
  @var: sqrt(2)
`);
viz.variables.var.eval();  // 1.4142135623730951

String

This is the equivalent to the JavaScript string type, e.g. 'a', "b". They could be used to define lists of categories.

1
2
3
const viz = new carto.Viz(`
  @categories: ['a', 'b', 'c']
`);

Color

This is a composed type to define the colors. It is defined as a JavaScript object with the following RGBA structure:

1
{ r: 255, g: 0, b: 0, a: 1 }

In the language there are several ways to define a color, e.g. red, #AAA, hsv(0.67, 1.0, 1.0) (see supported Color Spaces). They can be used directly, or within an array to define a custom palette.

1
2
3
4
const viz = new carto.Viz(`
  @color: rgba(127, 100, 10, 0.7)
  @customPalette: [red, green, blue]
`);

Date

This is the equivalent to the JavaScript Date type. It is used for animations and can be defined by time or date, e.g. date('2022-03-09T00:00:00Z').

1
2
3
4
const viz = new carto.Viz(`
  @begin: date('1970-01-01T00:00:00Z')
  @end: date('2022-03-09T00:00:00Z')
`);

Basic expressions

Operations

Unary

This is the list of the available unary operations: log, sqrt, sin, cos, tan, sign, abs, isNaN, not, floor and, ceil.

1
2
3
4
const viz = new carto.Viz(`
  width: sqrt($population)
  strokeWidth: not($nat)
`);

Binary

These are the available binary arithmetic operations: mul, div, add, sub, mod and pow. And these are the binary comparison operators: or, and, gt, gte, lt, lte, eq and, neq.

1
2
3
4
5
const viz = new carto.Viz(`
  color: red + blue
  width: $population / 100
  strokeWidth: ($population > 10^5) * 5
`);

Colors

This is the list of the supported color spaces: rgb, rgba, hsl, hsla, hsv, hsva, cielab, opacity, hex and, namedColor.

1
2
3
4
5
const viz = new carto.Viz(`
  @myColor: #FABADA
  color: @myColor
  strokeColor: opacity(@myColor, 0.7)
`);

In addition to these, you can also use our CARTOcolors schemes. They are shipped under the namespace carto.expressions.palettes in the JavaScript API or directly by using the palette’s name in the String API.

1
2
3
const viz = new carto.Viz(`
  @palette: PRISM
`);

Aggregations

Viewport

These aggregations evaluate the provided expression with the features showed within the current viewport. These are: viewportAvg, viewportMax, viewportMin, viewportSum, viewportCount, viewportPercentile and viewportHistogram.

1
2
3
4
5
const viz = new carto.Viz(`
  @view_total: viewportCount($cities)
`);
[...]
viz.variables.view_total.eval();

Global

Global aggregations evaluate a property for all the features in the source data. These are: globalAvg, globalMax, globalMin, globalSum, globalCount and, globalPercentile.

1
2
3
4
5
const viz = new carto.Viz(`
  @total: globalCount($cities)
`);
[...]
viz.variables.total.eval();

Cluster

An operation-based cluster generated by a defined property with a specific resolution. These are: clusterAvg, clusterMax, clusterMin, clusterMode and, clusterSum.

1
2
3
4
const viz = new carto.Viz(`
  width: clusterAvg($population)
  resolution: 2.5
`);

Note: These operations disable the access to the property except within other cluster aggregate functions and they are not available for GeoJSON sources.