The CARTO VL functionality is exposed through the carto namespace including:
Current version:
Setup:
CARTO Basemaps:
Source:
Layer:
Viz:
Expressions:
Interactivity:
The version of CARTO VL in use as specified in
package.json
and the GitHub release.
Remove an event handler for the given event name, layer list and callback.
eventName 
String
event 
layerList 
carto.Layer
List of layers 
callback 
function
Handler function to unregister 
Register an event handler for the given event name and for the given list of layers. Valid names are:
loaded
,
updated
.
The 'loaded' event will be fired when all the layers are loaded (and their 'loaded' events are fired).
The 'updated' event will be fired whenever one of the layers fired an 'updated' event, but throttled by requestAnimationFrame to return a maximum of one event per frame.
eventName 
String
Supported event names are 'loaded' and 'updated' 
layerList 
carto.Layer
Array
List of layers 
callback 
Set default authentication parameters: [user or username] and apiKey.
auth 

Set default configuration parameters
config 

Use CARTO basemaps for your map visualization. Here you have more information about our basemaps .
DarkMatter vector basemap
Example
Use DarkMatter vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.darkmatter
})
Example
Use DarkMatter vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.darkmatter
})
Positron vector basemap
Example
Use Positron vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.positron
})
Example
Use Positron vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.positron
})
Voyager vector basemap
Example
Use Voyager vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.voyager
})
Example
Use Voyager vector basemap.
1
2
3
4
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.voyager
})
Expressions are used to define visualizations, a visualization (viz) is a set named properties and variables and its corresponding values: expressions. A viz has the following properties:
color : fill color of points and polygons and color of lines
strokeColor : stroke/border color of points and polygons, not applicable to lines
width : fill diameter of points, thickness of lines, not applicable to polygons
strokeWidth : stroke width of points and polygons, not applicable to lines
filter : filter features by removing from rendering and interactivity all the features that don't pass the test.
symbol  show an image instead in the place of points
symbolPlacement
 when using
symbol
, offset to apply to the image
order :  rendering order of the features, only applicable to points. See carto.expressions.asc , carto.expressions.desc and carto.expressions.noOrder
resolution :  resolution of the propertyaggregation functions, only applicable to points. Default resolution is 1. Custom values must be greater than 0 and lower than 256. A resolution of N means points are aggregated to grid cells NxN pixels. Unlinke Torque resolution , the aggregated points are placed in the centroid of the cluster, not in the center of the grid cell.
For example the point diameter could be using the
add
expression:
You can use dataset properties inside expressions. Imagine we are representing cities in a map,
we can make the point width proportional to the population using the
property
/
prop
expression.
Multiple expressions can be combined to form more powerful ones,
for example lets divide the population between a number using the
div
expression to make points smaller:
All these expressions can be used also in a String API form. This API is a more compact way to create and use expressions.
It has shortcut notation to access your feature properties using the
$
symbol. It also allows inline comments using the JavaScript syntax.
Although the combination of expressions is very powerful, you must be aware of the different types to produce valid combinations. For example, the previous example is valid since we assumed that 'population' is a numeric property, it won't be valid if it was a categorical property. Each expression defines some restrictions regarding their parameters, particularly, the type of their parameters.
The most important types are:
Number expression. Expressions that contains numbers, both integers and floating point numbers. Boolean types are emulated by this type, being 0 false, and 1 true.
Category expression. Expressions that contains categories. Categories can have a limited set of values, like the country or the region of a feature.
Color expression. Expressions that contains colors. An alpha or transparency channel is included in this type.
Color palettes.
Palettes are constants that allow to use CARTOColors and ColorBrewer palettes easily. Use them with a ramp .
The following palettes are available in the namespace carto.expressions .
Example
Using a color scheme.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.prop('type'), s.palettes.PRISM);
});
Example
Using a color scheme.
1
2
3
const viz = new carto.Viz(`
color: ramp($type, PRISM)
`);
Example
Abs.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.abs(100) // 100
});
Example
Abs.
1
2
3
const viz = new carto.Viz(`
width: abs(100) // 100
`);
Example
Number addition.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.add(10, 2) // 12
});
Example
Number addition.
1
2
3
const viz = new carto.Viz(`
width: 10 + 2 // Equivalent to add(10, 2)
`);
Override the opacity (alpha channel) of a color to normalize the input color by a normalizer property.
This is implemented as `opacity(input, normalizer/globalMax(normalizer))
input 
Color
input color to normalize 
normalizer 
Number
numeric property that will be used to normalize the input color 
Color
Example
Normalize an input property ($winner_party) by a second property ($voters).
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
color: s.alphaNormalize(
s.ramp(s.prop('winner_party'), [red, blue]),
s.prop('voters')
)
});
Example
Normalize an input property ($winner_party) by a second property ($voters).
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
color: alphaNormalize(
ramp($winner_party, [red, blue]),
$voters
)
});
Perform a binary AND between two numeric expressions. If the numbers are different from 0 or 1 this performs a fuzzy and operation . This fuzzy behavior will allow transitions to work in a continuos, nondiscrete, fashion.
This returns a number expression where 0 means
false
and 1 means
true
.
Result of the expression
Number
Example
Show only elements with price < 30 AND category === 'fruit'.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.and(
s.lt(s.prop('price'), 30),
s.eq(s.prop('category'), 'fruit')
)
});
Example
Show only elements with price < 30 AND category === 'fruit'.
1
2
3
const viz = new carto.Viz(`
filter: $price < 30 and $category === 'fruit' // Equivalent to and(lt($price, 30), eq($category, 'fruit'))
`);
Create an animated temporal filter (animation). Read more about the Animation Class
input 
Number
input to base the temporal filter,
if input is a property, the beginning and end of the animation will be determined by the minimum and maximum timestamps of the property on the dataset,
this can be problematic if outliers are present. Otherwise input must be a number expression in which 0 means beginning of the animation and 1 means end.
If
It can be combined with linear and time expressions. 
duration 
Number
duration of the animation in seconds, optional, defaults to 10 seconds 
fade 
Fade
fadeIn/fadeOut configuration, optional, defaults to 0.15 seconds of fadeIn and 0.15 seconds of fadeOut 
Number
Example
Temporal map by $day (of numeric type), with a duration of 40 seconds, fadeIn of 0.1 seconds and fadeOut of 0.3 seconds.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
width: 2,
color: s.ramp(s.linear(s.clusterAvg(s.prop('temp'), 0, 30)), s.palettes.TEALROSE),
filter: s.animation(s.prop('day'), 40, s.fade(0.1, 0.3))
});
Example
Temporal map by $day (of numeric type), with a duration of 40 seconds, fadeIn of 0.1 seconds and fadeOut of 0.3 seconds.
1
2
3
4
5
const viz = new carto.Viz(`
width: 2
color: ramp(linear(clusterAvg($temp), 0,30), tealrose)
filter: animation($day, 40, fade(0.1, 0.3))
`);
Example
Temporal map by $date (of date type), with a duration of 40 seconds, fadeIn of 0.1 seconds and fadeOut of 0.3 seconds.
1
2
3
4
5
const viz = new carto.Viz({
width: 2,
color: s.ramp(s.linear(s.clusterAvg(s.prop('temp'), 0, 30)), s.palettes.TEALROSE),
filter: s.animation(s.linear(s.prop('date'), s.time('20220309T00:00:00Z'), s.time('20330812T00:00:00Z')), 40, s.fade(0.1, 0.3))
});
Example
Temporal map by $date (of date type), with a duration of 40 seconds, fadeIn of 0.1 seconds and fadeOut of 0.3 seconds.
1
2
3
4
5
6
7
8
const viz = new carto.Viz(`
width: 2
color: ramp(linear(clusterAvg($temp), 0,30), tealrose)
filter: animation(linear($date, time('20220309T00:00:00Z'), time('20330812T00:00:00Z')), 40, fade(0.1, 0.3))
`);
Animation class
This class is instanced automatically by using the `animation` function. It is documented for its methods.
Order ascending input a provided expression. NOTE: only works with
width()
.
Note: ordering expressions won't assure a perfect ordering.
Features will be distributed in different buckets with the original order, and those buckets will be ordered.
This guarantees a maximum error, but not a perfect order.
For most operations this is imperceptible, but usage of
order
in combination with animation or multiscale expressions (
zoomrange
and
scaled
)
may result in artifacts.
input 
carto.expressions.Width
must be

Order
Example
Ascending order based on width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
order: s.asc(s.width())
});
Example
Ascending order based on width.
1
2
3
const viz = new carto.Viz(`
order: asc(width())
`);
Check if a given value is contained within an inclusive range (including the limits).
This returns a numeric expression where 0 means
false
and 1 means
true
.
input 
Number
Numeric expression that is going to be tested against the [lowerLimit, upperLimit] range 
lowerLimit 
Number
Numeric expression with the lower limit of the range 
upperLimit 
Number
Numeric expression with the upper limit of the range 
Numeric expression with the result of the check
Number
Example
Display only cities where the population density is within the [50,100] range.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.between(s.prop('dn'), 50, 100);
});
Example
Display only cities where the population density is within the [50,100] range.
1
2
3
const viz = new carto.Viz(`
filter: between($dn, 50, 100)
`);
Linearly interpolate from
a
to
b
based on
mix
.
a 
Number

Color
Numeric or color expression,

b 
Number

Color
Numeric or color expression,

mix 
Number
Numeric expression with the interpolation parameter in the [0,1] range 
Numeric or color expression with the same type as
a
and
b
Number

Color
Example
Blend based on the zoom level to display a bubble map at high zoom levels and display fixedsized points at low zoom levels.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
width: s.blend(3,
s.prop('dn'),
s.linear(s.zoom(), 10, 14))
);
});
Example
Blend based on the zoom level to display a bubble map at high zoom levels and display fixedsized points at low zoom levels.
1
2
3
4
5
6
const viz = new carto.Viz(`
width: blend(3,
$dn,
linear(zoom(), 10, 14)
)
`);
Given a property create "subgroups" based on the given breakpoints.
This returns a number or category expression depending on the input values. The "others" label is by default CARTO_VL_OTHERS. This can be overwriten by setting the "others" label as the third parameter.
property 
Number

Category
The property to be evaluated and interpolated 
breakpoints 
Number Array

Category Array
Expression containing the different breakpoints. 
othersLabel 
string
Custom label for "others" 
Number

Category
Example
Display a traffic dataset in 4 colors depending on the numeric speed.
1
2
3
4
5
6
7
8
9
10
11
12
13
// Using the buckets `expression` we divide the dataset into 4 buckets according to the speed
//  From inf to 29
//  From 30 to 79
//  From 80 to 119
//  From 120 to +inf
// Values lower than 0 will be in the first bucket and values higher than 120 will be in the last one.
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(
s.buckets(s.prop('speed'), [30, 80, 120]),
s.palettes.PRISM
)
});
Example
Display a traffic dataset in 4 colors depending on the numeric speed.
1
2
3
4
5
6
7
8
9
// Using the buckets `expression` we divide the dataset into 4 buckets according to the speed
//  From inf to 29
//  From 30 to 79
//  From 80 to 119
//  From 120 to +inf
// Values lower than 0 will be in the first bucket and values higher than 120 will be in the last one.
const viz = new carto.Viz(`
color: ramp(buckets($speed, [30, 80, 120]), PRISM)
`);
Example
Display a traffic dataset is 3 colors depending on the category procesedSpeed.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(
s.buckets(s.prop('procesedSpeed'), ['slow', 'medium', 'high']),
s.palettes.PRISM)
)
});
Example
Display a traffic dataset is 3 colors depending on the category procesedSpeed.
1
2
3
const viz = new carto.Viz(`
color: ramp(buckets($procesedSpeed, ['slow', 'medium', 'high']), PRISM)
`);
Example
Set custom "others" label.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(
s.buckets(s.prop('procesedSpeed'), ['slow', 'medium', 'high'], 'Others'),
s.palettes.PRISM)
)
});
Example
Set custom "others" label.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz(`
color: ramp(buckets($procesedSpeed, ['slow', 'medium', 'high'], 'Others'), PRISM)
`);
Example
Color by $city using the CARTOColor Prism by assigning different color in Prism to each category.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.categoryIndex(s.prop('city')), s.palettes.PRISM)
});
Example
Color by $city using the CARTOColor Prism by assigning different color in Prism to each category.
1
2
3
const viz = new carto.Viz(`
color: ramp(categoryIndex($city), PRISM)
`);
Example
Ceil.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.ceil(5.1); // 6
});
Example
Ceil.
1
2
3
const viz = new carto.Viz(`
width: ceil(5.1)
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.cielab(32.3, 79.2, 107.86)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: cielab(32.3, 79.2, 107.86)
`);
Aggregate using the average. This operation disables the access to the property except within other cluster aggregate functions.
Note:
clusterAvg
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
Column of the table to be aggregated 
Aggregated column
Number
Example
Use cluster average of the population as width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.clusterAvg(s.prop('population'))
});
Example
Use cluster average of the population as width.
1
2
3
const viz = new carto.Viz(`
width: clusterAvg($population)
`);
Count of features per cluster.
The
clusterCount
expression has no input parameters and if data is not aggregated, it always returns 1.
It is not possible to use it as an input in global aggregations such as
globalMin
or
globalQuantiles
.
Cluster feature count
Number
Example
Use cluster count for width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.clusterCount() / 50
});
Example
Use cluster count for width.
1
2
3
const viz = new carto.Viz(`
width: clusterCount() / 50
`);
Example
Use cluster count with viewportQuantiles in a ramp for width and color.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.viewportQuantiles(s.clusterCount(), 5), [1, 20])
width: s.ramp(s.viewportQuantiles(s.clusterCount(), 5), s.palettes.PINKYL))
});
// Note: this is not possible with globalQuantiles
Example
Use cluster count with viewportQuantiles in a ramp for width and color.
1
2
3
4
5
const viz = new carto.Viz(`
width: ramp(viewportQuantiles(clusterCount(), 5), [1, 20])
color: ramp(viewportQuantiles(clusterCount(), 5), Pinkyl)
`);
// Note: this is not possible with globalQuantiles
Aggregate using the maximum. This operation disables the access to the property except within other cluster aggregate functions.
Note:
clusterMax
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
Column of the table to be aggregated 
Aggregated column
Number
Example
Use cluster maximum of the population as width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.clusterMax(s.prop('population'))
});
Example
Use cluster maximum of the population as width.
1
2
3
const viz = new carto.Viz(`
width: clusterMax($population)
`);
Aggregate using the minimum. This operation disables the access to the property except within other cluster aggregate functions.
Note:
clusterMin
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
Column of the table to be aggregated 
Aggregated column
Number
Example
Use cluster minimum of the population as width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.clusterMin(s.prop('population'))
});
Example
Use cluster minimum of the population as width.
1
2
3
const viz = new carto.Viz(`
width: clusterMin($population)
`);
Aggregate using the mode. This operation disables the access to the property except within other cluster aggregate functions.
Note:
clusterMode
can only be created by
carto.expressions.prop
, not other expressions.
property 
Category
Column of the table to be aggregated 
Aggregated column
Category
Example
Use cluster mode of the population in a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.clusterMode(s.prop('category')), s.palettes.PRISM)
});
Example
Use cluster mode of the population in a color ramp.
1
2
3
const viz = new carto.Viz(`
color: ramp(clusterMode($category), PRISM)
`);
Aggregate using the sum. This operation disables the access to the property except within other cluster aggregate functions.
Note:
clusterSum
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
Column of the table to be aggregated 
Aggregated column
Number
Example
Use cluster sum of the population as width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.clusterSum(s.prop('population'))
});
Example
Use cluster sum of the population as width.
1
2
3
const viz = new carto.Viz(`
width: clusterSum($population)
`);
Use discretised property as aggregate dimension. This operation disables the access to the property
except within
clusterTime
expressions with the same parameters.
Note:
clusterTime
can only be created with a
carto.expressions.prop
,
as the first parameter, not other expressions.
When the units of resolution are cyclic periods such as 'dayOfWeek' (day of the week) or 'monthOfYear' (month of the year), the resulting expression takes a numeric value to represent the period, e.g. 1 for Monday or January.
When the units are not cyclic (e.g. 'week' or 'month'), the resulting expression is a
TimeRange
that
encompass each individual calendar period, for example week 2018W03 (third week of 2018 from 20180115 to 20180121)
or 201803 (March 2018, from 20180301 to 20180401).
Accepted values for cyclic resolution periods are:
semesterOfYear
(6month term) takes values from 1 to 2
trimesterOfYear
(4month term) takes values from 1 to 3
quarterOfYear
(3month term) takes values from 1 to 4
monthOfYear
takes values from 1 (January) to 12 (December)
weekOfYear
follows
ISO 8601 numbering
taking values from 1 up to 53
dayOfWeek
(as per ISO 8601, 1 = Monday, to 7 = Sunday
dayOfMonth
takes values from 1 to 31
dayOfYear
takes values from 1 to 366
hourOfDay
takes values from 0 to 23
minuteOfHour
takes values from 0 to 59
Accepted values for serial resolution units are:
year
, e.g. '2017'
month
, e.g. '201703'
day
, e.g. '20170301'
hour
, e.g. '20170301T13'
minute
, e.g. '20170301T13:22'
second
, e.g. '20170301T13:22:31'
week
represented as '2018W03' (third week of 2018:, 20180115 to 20180121)
quarter
as '2018Q2' (second quarter of 2018, i.e. 201804 to 201806)
semester
as '2018S2' (second semester of 2018, i.e. 201807 to 201812)
trimester
as '2018t2' (second trimester of 2018, i.e. 201805 to 201808)
decade
as 'D201' (decade 201, i.e. 2010 to 2019)
century
as 'C21' (21st century, ie. 2001 to 2100)
millennium
as 'M3' (3rd millennium: 2001 to 3000)
The time zone is optional. By default UTC time will be used.
It admits a fixed offset from UTC as a signed number of seconds,
or
IANA
timezone
names
such as
America/New_York
or
Europe/Madrid
, which not only define a time offset,
but also rules for DST (daylight savings time).
property 
Date
Column of the table to be discretised as dimension 
units 
String
Units of resolution for the discretization 
timezone 
String
Time zone in which the dates are discretised. UTC by default. 
Dimension column; takes time range values (intervals) for serial units of resolutions and numbers for recurrent units.
TimeRange

Number
Example
Use months as a dimension of the cluster aggregations as `month`.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
month: s.clusterTime(s.prop('date', 'month', 'America/New_York'))
});
Example
Use months as a dimension of the cluster aggregations as `month`.
1
2
3
const viz = new carto.Viz(`
month: clusterTime($date, 'month', 'America/New_York')
`);
Wraps a constant number. Implies a GPU optimization vs number expression .
x 
number
A number to be warped in a constant numeric expression 
Numeric expression
Number
Example
Creating a constant number expression.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.constant(15)
});
Example
Creating a constant number expression.
1
2
3
const viz = new carto.Viz(`
width: constant(15)
`);
Example
Cos.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.cos(0) // 1
});
Example
Cos.
1
2
3
const viz = new carto.Viz(`
width: cos(0)
`);
Order descending input a provided expression. NOTE: only works with
width()
.
Note: ordering expressions won't assure a perfect ordering.
Features will be distributed in different buckets with the original order, and those buckets will be ordered.
This guarantees a maximum error, but not a perfect order.
For most operations this is imperceptible, but usage of
order
in combination with animation or multiscale expressions (
zoomrange
and
scaled
)
may result in artifacts.
input 
carto.expressions.Width
must be

Order
Example
Descending order based on width.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
order: s.desc(s.width())
});
Example
Descending order based on width.
1
2
3
const viz = new carto.Viz(`
order: desc(width())
`);
Example
Number division.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.div(10, 2) // 5
});
Example
Number division.
1
2
3
const viz = new carto.Viz(`
width: 10 / 2 // Equivalent to div(10, 2)
`);
Example
Compare two numbers to show only elements with price equal to 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.eq(s.prop('price'), 30)
});
Example
Compare two numbers to show only elements with price equal to 30.
1
2
3
const viz = new carto.Viz(`
filter: $price == 30 // Equivalent to eq($price, 30)
`);
Example
Fade in of 0.1 seconds, fade out of 0.3 seconds.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.animation(s.prop('day'), 40, s.fade(0.1, 0.3))
});
Example
Fade in of 0.1 seconds, fade out of 0.3 seconds.
1
2
3
const viz = new carto.Viz(`
filter: animation($day, 40, fade(0.1, 0.3))
`);
Example
Fade in and fade out of 0.5 seconds.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.animation(s.prop('day'), 40, s.fade(0.5))
});
Example
Fade in and fade out of 0.5 seconds.
1
2
3
const viz = new carto.Viz(`
filter: animation($day, 40, fade(0.5))
`);
Example
Fade in of 0.3 seconds without fading out.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.animation(s.prop('day'), 40, s.fade(0.1, s.HOLD))
});
Example
Fade in of 0.3 seconds without fading out.
1
2
3
const viz = new carto.Viz(`
filter: animation($day, 40, fade(0.3, HOLD))
`);
Example
Floor.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.floor(5.9) // 5
});
Example
Floor.
1
2
3
const viz = new carto.Viz(`
width: floor(5.9)
`);
Return the average of the feature property for the entire source data.
Note:
globalAvg
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
property expression of number type 
Result of the aggregation
Number
Example
Assign the global average of the `amount` property to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
g_avg: s.globalAvg(s.prop('amount'))
}
});
Example
Assign the global average of the `amount` property to a variable.
1
2
3
const viz = new carto.Viz(`
@g_avg: globalAvg($amount)
`);
Example
Assign the global count of features to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
g_count: s.globalCount()
}
});
No String example available
Example
Assign the global count of features.
1
2
3
const viz = new carto.Viz(`
@g_count: globalCount()
`);
Example
Use global equal intervals to define a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.globalEqIntervals(s.prop('density'), 5), s.palettes.PRISM)
});
Example
Use global equal intervals to define a color ramp.
1
2
3
const viz = new carto.Viz(`
color: ramp(globalEqIntervals($density, 5), PRISM)
`);
Generates a histogram based on a representative sample of the data.
The histogram can be based on a categorical expression, in which case each category will correspond to a histogram bar.
The histogram can be based on a numeric expression, the buckets for the histogram is controllable through the
sizeOrBuckets
parameter.
For numeric values of sizeOrBuckets, the minimum and maximum will be computed automatically and bars will be generated at regular intervals between the minimum and maximum.
When providing sizeOrBuckets as a list of buckets, the values will get assigned to the first bucket matching the criteria [bucketMin <= value < bucketMax].
The globalHistogram can also be combined with the
top()
expression.
Histograms are useful to get insights and create widgets outside the scope of CARTO VL, see the following example for more info.
input 
Number
expression to base the histogram 
sizeOrBuckets 
Number

Array
Optional (defaults to 20). Number of bars to use if

GlobalHistogram
GlobalHistogram
Example
Create and use an histogram.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const s = carto.expressions;
const viz = new carto.Viz(
variables: {
categoryHistogram: s.globalHistogram(s.prop('type')),
numericHistogram: s.globalHistogram(s.prop('amount'), 3, 1),
userDefinedHistogram: s.globalHistogram(s.prop('amount', [[0, 10], [10, 20], [20, 30]], 1),
topCategoryHistogram: s.globalHistogram(s.top(s.prop('type'), 3))
}
);
// ...
console.log(viz.variables.categoryHistogram.value);
// [{x: 'typeA', y: 10}, {x: 'typeB', y: 20}]
// There are 10 features of type A and 20 of type B
console.log(viz.variables.numericHistogram.value);
// [{x: [0,10], y: 20}, {x: [10,20], y: 7}, {x: [20, 30], y: 3}]
// There are 20 features with an amount between 0 and 10, 7 features with an amount between 10 and 20, and 3 features with an amount between 20 and 30
Example
Create and use an histogram.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const viz = new carto.Viz(`
@categoryHistogram: globalHistogram($type)
@numericHistogram: globalHistogram($amount, 3, 1)
@userDefinedHistogram: globalHistogram($amount, [[0, 10], [10, 20], [20, 30]], 1)
@topCategoryHistogram: globalHistogram(top($type, 3))
`);
// ...
console.log(viz.variables.categoryHistogram.value);
// [{x: 'typeA', y: 10}, {x: 'typeB', y: 20}]
// There are 10 features of type A and 20 of type B
console.log(viz.variables.numericHistogram.value);
// [{x: [0,10], y: 20}, {x: [10,20], y: 7}, {x: [20, 30], y: 3}]
// There are 20 features with an amount between 0 and 10, 7 features with an amount between 10 and 20, and 3 features with an amount between 20 and 30
Return the maximum of the feature property for the entire source data.
Note:
globalMax
can only be created by
carto.expressions.prop
, not other expressions.
Result of the aggregation
Number

Date
Example
Assign the global maximum of the `amount` property to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
g_max: s.globalMax(s.prop('amount'))
}
});
Example
Assign the global maximum of the `amount` property to a variable.
1
2
3
const viz = new carto.Viz(`
@g_max: globalMax($amount)
`);
Return the minimum of the feature property for the entire source data.
Note:
globalMin
can only be created by
carto.expressions.prop
, not other expressions.
Result of the aggregation
Number

Date
Example
Assign the global minimum of the `amount` property to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
g_min: s.globalMin(s.prop('amount'))
}
});
Example
Assign the global minimum of the `amount` property to a variable.
1
2
3
const viz = new carto.Viz(`
@g_min: globalMin($amount)
`);
Example
Assign the 90th percentile of the `amount` property for the entire dataset to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
v_percentile: s.globalPercentile(s.prop('amount'), 90)
}
});
Example
Assign the 90th percentile of the `amount` property for the entire dataset to a variable.
1
2
3
const viz = new carto.Viz(`
@v_percentile: globalPercentile($amount, 90)
`);
Example
Use global quantiles to define a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.globalQuantiles(s.prop('density'), 5), s.palettes.CB_REDS)
});
Example
Use global quantiles to define a color ramp.
1
2
3
const viz = new carto.Viz(`
color: ramp(globalQuantiles($density, 5), CB_REDS)
`);
Classify
input
by using the MeanStandard Deviation method with
n
buckets.
It will classify the input based on the entire dataset without filtering by viewport or by
filter
.
It uses average and standard deviation (population formula) to classify the dataset. When using an odd number of buckets, the central class has a double size (classSize * 2), to honour the number of required buckets
This method is suitable if data are normally (or near normal) distributed, and it is specially appropiated for diverging datasets, which can be well displayed using a diverging color scheme like TEALROSE
input 
Number
The input expression to classify 
n 
number
Number of buckets 
classSize 
Optional. The class size, defaults to 1.0 standard deviation (usual values are also 0.5 or 0.25) 
Category
Example
Use global meanstandard deviation to define a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.globalStandardDev(s.prop('density'), 5), s.palettes.TEALROSE)
});
Example
Use global meanstandard deviation to define a color ramp.
1
2
3
const viz = new carto.Viz(`
color: ramp(globalStandardDev($density, 5), TEALROSE)
`);
Example
Use global custom meanstandard deviation to define a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.globalStandardDev(s.prop('density'), 7, 0.5), s.palettes.TEALROSE)
});
Example
Use global custom meanstandard deviation to define a color ramp.
1
2
3
const viz = new carto.Viz(`
color: ramp(globalStandardDev($density, 7, 0.5), TEALROSE)
`);
Return the sum of the feature property for the entire source data.
Note:
globalSum
can only be created by
carto.expressions.prop
, not other expressions.
property 
Number
property expression of number type 
Result of the aggregation
Number
Example
Assign the global sum of the `amount` property to a variable.
1
2
3
4
5
6
const s = carto.expressions;
const viz = new carto.Viz({
variables: {
g_sum: s.globalSum(s.prop('amount'))
}
});
Example
Assign the global sum of the `amount` property to a variable.
1
2
3
const viz = new carto.Viz(`
@g_sum: globalSum($amount)
`);
Example
Compare two numbers to show only elements with price greater than 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.gt(s.prop('price'), 30)
});
Example
Compare two numbers to show only elements with price greater than 30.
1
2
3
const viz = new carto.Viz(`
filter: $price > 30 // Equivalent to gt($price, 30)
`);
Example
Compare two numbers to show only elements with price greater than or equal to 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.gte(s.prop('price'), 30)
});
Example
Compare two numbers to show only elements with price greater than or equal to 30.
1
2
3
const viz = new carto.Viz(`
filter: $price >= 30 // Equivalent to gte($price, 30)
`);
Create a color from its hexadecimal description.
hexadecimalColor 
String
Color in the #RGB, #RGBA, #RRGGBB or #RRGGBBAA format 
Color
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.hex('#00F'); // Equivalent to `color: '#00F'`
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: #00F // Equivalent to hex('#00F')
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.hsl(0.67, 1.0, 0.5)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: hsl(0.67, 1.0, 0.5)
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.hsla(0.67, 1.0, 0.5, 1.0)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: hsla(0.67, 1.0, 0.5, 1.0)
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.hsv(0.67, 1.0, 1.0)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: hsv(0.67, 1.0, 1.0)
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.hsva(0.67, 1.0, 1.0, 1.0)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: hsva(0.67, 1.0, 1.0, 1.0)
`);
Image. Load an image and use it as a symbol.
Note: image RGB color will be overridden if the viz
color
property is set.
url 
String
Image path 
Example
Load a svg image.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
symbol: s.image('./marker.svg')
});
Example
Load a svg image.
1
2
3
const viz = new carto.Viz(`
symbol: image('./marker.svg')
`);
Example
Display only cities where $type is 'metropolis' or 'capital'.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.in(s.prop('type'), ['metropolis', 'capital'])
});
Example
Display only cities where $type is 'metropolis' or 'capital'.
1
2
3
const viz = new carto.Viz(`
filter: $type in ['metropolis', 'capital']
`);
Example
Filter NULL values of the `numeric` property.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.not(s.isNull(s.prop('numeric')))
});
Example
Filter NULL values of the `numeric` property.
1
2
3
const viz = new carto.Viz(`
filter: not(isNull($numeric))
`);
Linearly interpolates the value of a given input between a minimum and a maximum. If
min
and
max
are not defined they will
default to
globalMin(input)
and
globalMax(input)
.
input 
Number

Date
The input to be evaluated and interpolated, can be a numeric property or a date property 
min 
Number

Date
Numeric or date expression pointing to the lower limit 
max 
Number

Date
Numeric or date expression pointing to the higher limit 
max 
Number

Date
Numeric or date expression to set a timerange 
samples 
Number
Number of samples, which is 10 by default 
Number

Date
Example
Color by $speed using the CARTOColor Prism by assigning the first color in Prism to features with speeds of 10 or less, the last color in Prism to features with speeds of 100 or more and a interpolated value for the speeds in between.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.linear(s.prop('speed'), 10, 100), s.palettes.PRISM)
});
Example
Color by $speed using the CARTOColor Prism by assigning the first color in Prism to features with speeds of 10 or less, the last color in Prism to features with speeds of 100 or more and a interpolated value for the speeds in between.
1
2
3
const viz = new carto.Viz(`
color: ramp(linear($speed, 10, 100), PRISM)
`);
Example
Set custom number of samples.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.linear(s.prop('speed'), 10, 100, null, 10), s.palettes.PRISM)
});
Example
Set custom number of samples.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz(`
color: ramp(linear($speed, 10, 100, null, 10), PRISM)
`);
Wrapper around arrays. Explicit usage is unnecessary since CARTO VL will wrap implicitly all arrays using this function.
When used with Transformation expressions, the returned value will be a Transformation that will chain each single transformation one after another.
elements 
Number Array

Category Array

Color Array

Date Array

Image Array

Transform Array

List

Transform
Example
Rotate then translate.
1
2
3
4
5
const s = carto.expressions;
const viz = new carto.Viz({
symbol: s.CROSS
transform: [s.rotate(90), s.translate(10, 20)]
});
Example
Rotate then translate.
1
2
3
4
const viz = new carto.Viz(`
symbol: cross
transform: [rotate(90), translate(10, 20)]
`);
Example
Natural Logarithm.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.log(10) // 2.302585092994046
});
Example
Natural Logarithm.
1
2
3
const viz = new carto.Viz(`
width: log(10)
`);
Example
Compare two numbers to show only elements with price less than 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.lt(s.prop('price'), 30)
});
Example
Compare two numbers to show only elements with price less than 30.
1
2
3
const viz = new carto.Viz(`
filter: $price < 30 // Equivalent to lt($price, 30)
`);
Example
Compare two numbers to show only elements with price less than or equal to 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.lte(s.prop('price'), 30)
});
Example
Compare two numbers to show only elements with price less than or equal to 30.
1
2
3
const viz = new carto.Viz(`
filter: $price <= 30 // Equivalent to lte($price, 30)
`);
Example
Number modulus.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.mod(10, 6) // 4
});
Example
Number modulus.
1
2
3
const viz = new carto.Viz(`
width: 10 % 6 // Equivalent to mod(10, 6)
`);
Example
Number multiplication.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.mul(5, 5) // 25
});
Example
Number multiplication.
1
2
3
const viz = new carto.Viz(`
width: 5 * 5 // Equivalent to mul(5, 5)
`);
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.namedColor('blue') // Equivalent to `color: 'blue'`
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: blue // Equivalent to namedColor('blue')
`);
Example
Compare two numbers to show only elements with price not equal to 30.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.neq(s.prop('price'), 30);
});
Example
Compare two numbers to show only elements with price not equal to 30.
1
2
3
const viz = new carto.Viz(`
filter: $price != 30 // Equivalent to neq($price, 30)
`);
Example
Display only cities where $type is not 'metropolis' or 'capital'.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.nin(s.prop('type'), ['metropolis', 'capital'])
});
Example
Display only cities where $type is not 'metropolis' or 'capital'.
1
2
3
const viz = new carto.Viz(`
filter: $type nin ['metropolis', 'capital']
`);
Example
No order.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
order: s.noOrder()
});
Example
No order.
1
2
3
const viz = new carto.Viz(`
order: noOrder()
`);
Compute the logical negation of the given expression. This is internally computed as 1  x preserving boolean behavior and allowing fuzzy logic.
When x is equal to 1 not(x) will be evaluated to 0
When x is equal to 0 not(x) will be evaluated to 1
x 
Number
Number to compute the not value 
Number
Example
Not.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.not(0) // 1
});
Example
Not.
1
2
3
const viz = new carto.Viz(`
width: not(0)
`);
Get the current timestamp. This is an advanced form of animation,
animation
expression is preferred.
Number
Example
Update width during the time.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.mod(s.now(), 10)
});
Example
Update width during the time.
1
2
3
const viz = new carto.Viz(`
width: now() % 10
`);
Example
Display blue points with 50% opacity.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.opacity(s.rgb(0,0,255), 0.5) // Equivalent to `s.rgba(0,0,255,0.5)`
});
Example
Display blue points with 50% opacity.
1
2
3
const viz = new carto.Viz(`
color: opacity(rgb(0,0,255), 0.5) // Equivalent to `rgba(0,0,255,0.5)`
`);
Perform a binary OR between two numeric expressions. If the numbers are different from 0 or 1 this performs a fuzzy or operation . This fuzzy behavior will allow transitions to work in a continuos, nondiscrete, fashion.
This returns a number expression where 0 means
false
and 1 means
true
.
Result of the expression
Number
Example
Show only elements with price < 30 OR price > 1000.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.or(
s.lt(s.prop('price'), 30),
s.gt(s.prop('price'), 1000)
)
});
Example
Show only elements with price < 30 OR price > 1000.
1
2
3
const viz = new carto.Viz(`
filter: $price < 30 or $price > 1000 // Equivalent to or(lt($price, 30), gt($price, 1000))
`);
Placement. Define an image offset relative to its size. Where:
symbolPlacement: placement(1,1)
means to align the bottom left corner of the image with the point center.
symbolPlacement: placement(0,0)
means to align the center of the image with the point center.
symbolPlacement: placement(1,1)
means to align the top right corner of the image with the point center.
You can also use
align_center
and
align_bottom
to set the simbol placement as follows:
symbolPlacement: align_bottom
is equivalent to
symbolPlacement: placement(0, 1)
symbolPlacement: align_center
is equivalent to
symbolPlacement: placement(0, 0)
x 
number
first numeric expression that indicates the image offset in the X direction. 
y 
number
second numeric expression that indicates the image offset in the Y direction. 
Numeric expression
Placement
Example
Setting the aligment to the top corner of the image.
1
2
3
4
5
const s = carto.expressions;
const viz = new carto.Viz({
symbol: s.image('./marker.svg').
symbolPlacement: s.placement(1, 0)
});
Example
Setting the aligment to the top corner of the image.
1
2
3
4
const viz = new carto.Viz(`
symbol: image('./marker.svg')
symbolPlacement: placement(1, 0)
`);
Compute the base to the exponent power, return a numeric expression with the value of the first parameter raised to the power of the second. The result is undefined if x<0 or if x=0 and y≤0.
Result of the power
Number
Example
Number power.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.pow(2, 3) // 8
});
Example
Number power.
1
2
3
const viz = new carto.Viz(`
width: 2 ^ 3 // Equivalent to pow(2, 3)
`);
Evaluates the value of a column for every row in the dataset.
For example think about a dataset containing 3 cities: Barcelona, Paris and London.
The
prop('name')
will return the name of the current city for every point in the dataset.
name 
String
The property in the dataset that is going to be evaluated 
Number

Category

Date
Example
Display only cities with name different from "London".
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.neq(s.prop('name'), 'london')
});
Example
Display only cities with name different from "London".
1
2
3
4
5
6
7
const viz = new carto.Viz(`
filter: neq(prop('name'), 'london')
`);
const viz = new carto.Viz(`
filter: $name != 'london'
`);
Create a ramp: a mapping between an input (numeric or categorical) and an output (number, colors and/or images)
When the input has the same number of categories (without taking the "others" category into account). Then, each input category will have a one to one match with an output value.
Some case examples:
ramp(buckets($product, ['A, 'B', 'C']), [house, car, bus])
ramp(buckets($price, [20, 50, 120]), [1, 10, 4, 12])
ramp(top($product, 3), [blue, yellow, green])
ramp(globalQuantiles($price, 3), [red, yellow, green])
When the input has different number of categories or the input is a linear expression. Then it will interpolate the output values (Note: this is not supported if output values are images)
Some case examples:
ramp(linear($price, 1, 10) [green, yellow, red])
`ramp(buckets($product, ['A, 'B', 'C'], [red, blue]))
When the input is a categorical property, we wrap it automatically in a CategoryIndex expression
ramp($product, Prism)
(equivalent to
ramp($categoryIndex($product)), Prism)
When the input is a numeric property, we wrap it automatically in a Linear expression.
ramp($price, Prism)
(equivalent to
ramp($linear($price)), Prism)
The "others" value is setted by default, depending on the output type:
If it is "Number", the "others" value is 1.
If it is "Color" from a color array (i.e: [red, yellow, green]), the "others" value is the gray color.
If it is "Color" from a cartocolor palette (i.e: Prism), the "others" value is the last color of the palette.
If it is "Image", the "others" value is a circle.
If we add a third parameter, the "others" default value will be overridden by this one
input 
Number

Category
The input expression to give a color 
palette 
Palette

Color Array

Number Array
The color palette that is going to be used 
others 
(Optional) Value that overrides the default value for "others" 
Number

Color

Image
Example
Mapping categories to numbers, colors and images.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
width: s.ramp(s.buckets(s.prop('product'), ['A, 'B', 'C']), [1, 2, 3])
color: s.ramp(s.buckets(s.prop('product'), ['A, 'B', 'C']), s.palettes.PRISM)
strokeColor: s.ramp(s.buckets(s.prop('product'), ['A, 'B', 'C']), [s.namedColor('red'), s.namedColor('yellow'), s.namedColor('green')])
symbol: s.ramp(s.buckets(s.prop('product'), ['A, 'B', 'C']), [s.HOUSE, s.CAR, s.BUS])
});
Example
Mapping categories to numbers, colors and images.
1
2
3
4
5
6
const viz = new carto.Viz(`
width: ramp(buckets($product), ['A, 'B', 'C']), [1, 2, 3])
color: ramp(buckets($product), ['A, 'B', 'C']), Prism)
strokeColor: ramp(buckets($product), ['A, 'B', 'C']), [red, yellow, green])
symbol: ramp(buckets($product), ['A, 'B', 'C']), [house, car, bus])
`);
Example
Mapping classified numeric properties to numbers, colors and images.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
width: s.ramp(s.buckets(s.prop('price'), [40, 100]), [1, 2, 3])
color: s.ramp(s.buckets(s.prop('price'), [40, 100]), s.palettes.PRISM)
strokeColor: s.ramp(s.buckets(s.prop('price'), [40, 100]), [s.namedColor('red'), s.namedColor('yellow'), s.namedColor(green)])
symbol: s.ramp(s.buckets(s.prop('price'), [40, 100]), [s.HOUSE), s.CAR, s.BUS])
});
Example
Mapping classified numeric properties to numbers, colors and images.
1
2
3
4
5
6
const viz = new carto.Viz(`
width: ramp(buckets($price, [40, 100]), [1, 2, 3])
color: ramp(buckets($price, [40, 100]), Prism)
strokeColor: ramp(buckets($price, [40, 100]), [red, yellow, green])
symbol: ramp(buckets($price, [40, 100]), [house, car, bus])
`);
Example
Override default values.
1
2
3
4
5
6
7
const s = carto.expressions;
const viz = new carto.Viz({
width: s.ramp(s.top(s.prop('price'), 3), [1, 2, 3], 0)
strokeColor: s.ramp(s.top(s.prop('price'), 3), Prism, s.namedColor('red'))
color: s.ramp(s.top(s.prop('price'), 3), [s.namedColor('blue'), s.namedColor('red'), s.namedColor('yellow')], s.namedColor(black))
symbol: s.ramp(s.top(s.prop('price'), 3), [s.HOUSE, s.CAR, s.BUS], s.CROSS)
});
Example
Override default values.
1
2
3
4
5
6
const viz = new carto.Viz(`
width: ramp(top($price, 3), [1, 2, 3], 0)
strokeColor: ramp(top($price, 3), Prism, red)
color: ramp(top($price, 3), [blue, red, yellow], black)
symbol: ramp(top($price, 3), [house, car, bus], cross)
`);
Example
Invert a Palette.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.prop('type'), s.reverse(s.palettes.PRISM));
});
No String example available
Example
Invert a Palette .
1
2
3
const viz = new carto.Viz(`
color: ramp($type, reverse(PRISM))
`);
Example
Invert a List.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.prop('count'), s.reverse([s.namedColor('red'), s.namedColor('blue')]));
});
No String example available
Example
Invert a List .
1
2
3
const viz = new carto.Viz(`
color: ramp($count, reverse([red, blue]))
`);
Evaluates to a rgb color.
r 
Number
The amount of red in the color in the [0, 255] range. Numeric expression. 
g 
Number
The amount of green in the color in the [0, 255] range. Numeric expression. 
b 
Number
The amount of blue in the color in the [0, 255] range. Numeric expression. 
Color
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.rgb(0, 0, 255)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: rgb(0, 0, 255)
`);
Evaluates to a rgba color.
r 
Number
The amount of red in the color in the [0, 255] range. Numeric expression. 
g 
Number
The amount of green in the color in the [0, 255] range. Numeric expression. 
b 
Number
The amount of blue in the color in the [0, 255] range. Numeric expression. 
a 
Number
The alpha value of the color in the [0, 1] range. Numeric expression. 
Color
Example
Display blue points.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.rgba(0, 0, 255, 1)
});
Example
Display blue points.
1
2
3
const viz = new carto.Viz(`
color: rgba(0, 0, 255, 1)
`);
Rotate. Define a rotation in degrees.
Limitation: only supported in combination with
symbol:
.
angle 
Number
angle to rotate in degrees in clockwise direction 
Transform
Example
Rotate 30 degrees in clockwise direction.
1
2
3
4
5
const s = carto.expressions;
const viz = new carto.Viz({
symbol: s.CROSS
transform: s.rotate(30)
});
Example
Rotate 30 degrees in clockwise direction.
1
2
3
4
const viz = new carto.Viz(`
symbol: cross
transform: rotate(30)
`);
Example
Rotate 30 degrees in counterclockwise direction.
1
2
3
4
5
const s = carto.expressions;
const viz = new carto.Viz({
symbol: s.CROSS
transform: s.rotate(30)
});
Example
Rotate 30 degrees in counterclockwise direction.
1
2
3
4
const viz = new carto.Viz(`
symbol: cross
transform: rotate(30)
`);
Scale a width value to keep feature width constant in real space (meters). This will change the width in pixels at different zoom levels to enforce the previous condition.
width 
Number
pixel width at zoom level

zoomlevel 
Number
zoomlevel at which

Number
Example
Keep feature width in meters constant with 25 pixels at zoom level 7.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.scaled(25, 7)
});
Example
Keep feature width in meters constant with 25 pixels at zoom level 7.
1
2
3
const viz = new carto.Viz(`
width: s.scaled(25, 7)
`);
Compute the sign of a number x, indicating whether the number is positive, negative or zero This means this function will return 1 if the number is positive, 1 if the number is negative 0 if the number is 0 and 0 if the number is 0.
x 
Number
Numeric expression to compute the sign 
Number
Example
Sign.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.sign(100) // 1
});
Example
Sign.
1
2
3
const viz = new carto.Viz(`
width: sign(100)
`);
Example
Sin.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.sin(Math.PI/2) // 1
});
Example
Sin.
1
2
3
const viz = new carto.Viz(`
width: sin(PI/2)
`);
Example
Square root.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.sqrt(4) // 2
});
Example
Square root.
1
2
3
const viz = new carto.Viz(`
width: sqrt(4)
`);
Example
Number subtraction.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.sub(10, 2) // 8
});
Example
Number subtraction.
1
2
3
const viz = new carto.Viz(`
width: 10  2 // Equivalent to sub(10, 2)
`);
Example
Tan.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
width: s.tan(0) // 0
});
Example
Tan.
1
2
3
const viz = new carto.Viz(`
width: tan(0)
`);
Example
Filter by a date between dates.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
filter: s.between(s.prop('date'), s.time('20220309T00:00:00Z'), s.time('20330812T00:00:00Z')
});
Example
Filter by a date between dates.
1
2
3
const viz = new carto.Viz(`
filter: time('20220309T00:00:00Z') < $date < time('20330812T00:00:00Z')
`);
Define a time range: an interval between two time points.
ISOformatted strings (based on ISO 8601) are used to define ranges.
Since
timeRange
doesn't support arbitrary intervals, but only
intervals based on single units of time (e.g. a month, an hour),
we don't use the general ISO interval format, but simply an
abbreviated form of the date point format, so that '201803' represents
the month of March, 2018 (i.e. the interval 20180301T00:00:00/20180401T00:00:00).
value 
String
abbreviated ISOformatted interval 
It retuns a TimeRange object.
TimeRange
Get the top
n
properties, aggregating the rest into an "others" bucket category. The "others" label is by default CARTO_VL_OTHERS.
This can be overwriten by setting the "others" label as the third parameter.
property 
Category
Column of the table 
n 
number
Number of top properties to be returned, the maximum value is 16, values higher than that will result in an error 
othersLabel 
string
Custom label for "others" 
Category
Example
Use top 3 categories to define a color ramp.
1
2
3
4
const s = carto.expressions;
const viz = new carto.Viz({
color: s.ramp(s.top(s.prop(