Skip to main content

expression

The value of any layout property, paint property or filter can be defined as an expression.

Expressions define calculation formulas for attribute values. Operators that can be used include:

  • Mathematical operators for arithmetic and other numerical operations
  • Boolean operations and logical operators defined by conditions
  • String operators for string operations
  • Data operator to get data source feature attributes
  • Get the camera operator that defines the parameters of the current map view

The expression is a JSON array. The first element is the expression operator, such as "*" or "case", and the following elements (if any) are the parameters of the expression. Each argument can be a text value (string, number, Boolean, or null) or another expression array.

[expression_name, argument_0, argument_1, ...]

Camera expressions​

Camera expressions are expressions using the zoom operator. These expressions change the representation style of the layer based on the map zoom level.

{
    "circle-radius": [
        "interpolate", ["linear"], ["zoom"],
        // zoom is less than or equal to 5 -> the radius of the circle is 1px
        5, 1,
        // zoom is greater than or equal to 10 -> the radius of the circle is 5px
        10, 5
    ]
}

This example uses the interpolate operator, using a set of input-outputs to define a linear relationship between zoom level and circle size. In this example, the expression means that when the map level is 5 or less, the radius of the circle will be 1 pixel, when the map level is 10 or greater, the radius of the circle should be 5 pixels, and between the two zoom levels, the radius of the circle will be a linear interpolation between 1 and 5 pixels.

You can use camera expressions wherever expressions can be used. When you use a camera expression as the value of the paint and layout properties, it must be one of the following forms:

[ "interpolate", interpolation, ["zoom"], ... ]

or:

[ "step", ["zoom"], ... ]

or:

[
    "let",
    ... variable bindings...,
    [ "interpolate", interpolation, ["zoom"], ... ]
]

or:

[
    "let",
    ... variable bindings...,
    [ "step", ["zoom"], ... ]
]

That is, in the paint or layout attribute, ["zoom"] can only be used as input to an external interpolate or step expression, or an expression in a let expression.

For on-the-fly evaluation of camera expressions, there is an important difference between the paint and layout properties:

  • For the paint property, when the map hierarchy changes, even a small change, the camera expression of the paint property will be re-evaluated. For example, when the map is zoomed between levels 4.1 and 4.6, the camera expression of the paint property will be continuously re-evaluated.
  • For the layout attribute, camera expressions are only evaluated at integer map levels. For example, when the map level changes from 4.1 to 4.6, it will not be recalculated. It will only be recalculated when it exceeds 5 or falls below 4.

Composite expression (Composition)​

A single expression can mix data operators, camera operators, and other operators. Such compound expressions allow the layer’s style to be determined by combining map-level and individual feature attribute values.

{
    "circle-radius": [
        "interpolate", ["linear"], ["zoom"],
        // When zoom is 0, set the circle radius of each feature to the value of the attribute "rating"
        0, ["get", "rating"],
        // When zoom is 10, set the circle radius of each feature to 4 times the attribute "rating"
        10, ["*", 4, ["get", "rating"]]
    ]
}

Expressions that use both data and camera operators are considered both data and camera expressions, and so must adhere to the rules above for both.

Data expressions​

A data expression is an expression that accesses feature data, that is, any expression that uses get, has, id, geometry-type, properties or feature-state. Data expressions define the style of features based on their attributes or status, and can be used to distinguish features on the same layer to achieve data visualization.

Data expressions can be used as the value of filter and most paint and layout attributes. Please confirm whether the paint and layout attributes have the data-driven styling flag. In addition, the data expression of the feature-state operator is only allowed to be used on the paint attribute.

{
    "circle-color": [
        "rgb",
        // When the value of feature.properties.count is higher, the red value is higher
        ["get", "count"],
        // green is always zero
        0,
        // When the value of feature.properties.count is lower, the blue value is higher
        ["-", 100, ["get", "count"]]
    ]
}

This example uses the get operator to obtain the count value of each feature, and uses this value as the parameter of the rgb operator to define the red, green, and blue values ​​respectively.

Expression reference (Expression reference)​

type​

You can use type expressions to test and convert different data types (such as strings, numbers, and Boolean values).

Normally such tests and conversions are unnecessary in type expressions, but they may be necessary in expressions where the types of certain subexpressions are ambiguous. They are also useful in situations where feature data types are inconsistent, for example you can use to-number to ensure that a value like "1.5" (instead of 1.5) is treated as a numeric value.

array​

Assert that the input is an array (optional, with specific item types and length). If, when the input expression is evaluated, it is not of an asserted type, this assertion will cause the entire expression to be aborted.

Grammar Rules

["array", value]: array
["array", type: "string" | "number" | "boolean", value]: array<type>
["array",
    type: "string" | "number" | "boolean",
    N: number (literal),
    value
]: array<type, N>

boolean​

Assert that the input value is a Boolean value. If multiple values ​​are provided, they are evaluated sequentially until a Boolean value is obtained. If none of the input values ​​are Boolean, the expression is incorrect.

Grammar Rules

["boolean", value]: boolean
["boolean", value, fallback: value, fallback: value, ...]: boolean

collator​

Returns a sorter for locale-dependent comparison operations. The case-sensitive and diacritic-sensitive options default to false. This parameter specifies the IETF language tag of the locale to use. If not provided, the default language setting is used. If the requested language is not available, the system-defined fallback locale will be used. The result of setting locale fallback behavior using resolved-locale.

Grammar Rules

["collator",
    { "case-sensitive": boolean, "diacritic-sensitive": boolean, "locale": string }
]: collator

format​

Applied to the text-field attribute, returns a formatted string of mixed format text. The input can contain a string literal or expression, including an `image' expression. The string can be followed by an overridden style object. Style attributes that support overriding include:

  • "text-font": Override the font specified by the layout attribute.
  • "text-color": Overrides the color specified by the paint attribute.
  • "font-scale": applies the scaling factor to the text-size specified by the layout attribute.

Grammar Rules

["format",
    input_1: string | image, options_1: { "font-scale": number, "text-font": array<string>, "text-color": color },
    ...,
    input_n: string | image, options_n: { "font-scale": number, "text-font": array<string>, "text-color": color }
]: formatted

image​

Returns a ResolvedImage, which can be used as part of icon-image, *-pattern and 'format' expressions. A 'coalesce' expression containing an 'image' will evaluate to the first image in the current style. This validation process is synchronous and requires that the image be added to the style before an 'image' request is made.

Grammar Rules

["image", value]: image

literal​

Provides a literal array or object value.

Grammar Rules

["literal", [...] (JSON array literal)]: array<T, N>
["literal", [...] (JSON array literal)]: array<T, N>

number​

Assert that the input value is a number. If multiple values ​​are provided, each value is evaluated in turn until a number is obtained. If there are no numbers in the input value, the expression is wrong.

Grammar Rules

["number", value]: number
["number", value, fallback: value, fallback: value, ...]: number

number-format​

Converts the entered number to a string representation using the provided formatting rules. If the locale parameter is set specifies the locale to be used as the BCP 47 language tag. If the currency parameter is set specifies the ISO 4217 code used for currency style formatting. If set, the min-fraction-digits and max-fraction-digits parameters specify the minimum and maximum number of fractional digits to include.

Grammar Rules

["number-format",
    input: number,
    options: { "locale": string, "currency": string, "min-fraction-digits": number, "max-fraction-digits": number }
]: string

object​

Assert that the input value is an object. If multiple values ​​are provided, they are evaluated sequentially until an object is obtained. If none of the input values ​​are objects, the expression is wrong.

Grammar Rules

["object", value]: object
["object", value, fallback: value, fallback: value, ...]: object

string​

Assert that the input value is a string. If multiple values ​​are provided, each value is evaluated in turn until a string is obtained. If none of the input values ​​are strings, the expression is wrong.

Grammar Rules

["string", value]: string
["string", value, fallback: value, fallback: value, ...]: string

to-boolean​

Convert input value to Boolean value. When the input is an empty string, 0, false, null or NaN, the result is false, otherwise it is true.

Grammar Rules

["to-boolean", value]: boolean

to-color​

Convert input value to color. If multiple values ​​are provided, each value is evaluated in turn until the first successful conversion is obtained. If any input value cannot be converted, the expression is incorrect.

Grammar Rules

["to-color", value, fallback: value, fallback: value, ...]: color

to-number​

Convert input value to number. If the input is null or false, the result is 0. If the input is true, the result is 1. If the input is a string, it will be converted into the specified value according to the algorithm in the ECMAScript language specification. If multiple values ​​are provided, each value is evaluated in turn until the first successful conversion is obtained. If any input value cannot be converted, the expression is incorrect.

Grammar Rules

["to-number", value, fallback: value, fallback: value, ...]: number

to-string​

Convert input value to string. If the input is null, the result is "". If the input is a Boolean value, the result is "true" or "false". If the input is a number, it will be converted into the specified string according to the algorithm in the ECMAScript language specification. If the input is a color, it will be converted to a string of the form "rgba(r,g,b,a)", where r,g,b are numbers from 0 to 255 and a is a number from 0 to 1. If the input is an 'image' expression, 'to-string' returns the image name. Otherwise, the input will be converted to a string in the format specified by the JSON.stringify function of the ECMAScript language specification.

Grammar Rules

["to-string", value]: string

typeof​

Returns the type of the given value.

Grammar Rules

["typeof", value]: string

Feature data​

accumulated​

Returns the value of an aggregate property accumulated so far. Can only be used in the clusterProperties option of aggregated GeoJSON sources.

Grammar Rules

["accumulated"]: value

feature-state​

Gets the attribute value from the current feature state. If the requested attribute does not belong to the feature state, null is returned. The state of features is not part of the GeoJSON or vector tile data and must be set programmatically for each feature. Features are identified by their id attribute, which must be an integer or a string that can be converted to an integer. Note that ["feature-state"] can only be used with the paint attribute that supports data-driven styles.

Grammar Rules

["feature-state", string]: value

geometry-type​

Returns the geometric type of the feature: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon. Multi* feature types will only appear in GeoJSON data sources, and when using vector tile sources, there is only a single form.

Grammar Rules

["geometry-type"]: string

id​

Returns the attribute’s id (if any).

Grammar Rules

["id"]: value

line-progress​

Return progress along the gradient line. Can only be used within the line-gradient attribute.

Grammar Rules

["line-progress"]: number

properties​

Returns the attribute attribute object. Note that in some cases it may be more efficient to use ["get", "property_name"] directly.

Grammar Rules

["properties"]: object

Find​

at​

Query items from an array.

Grammar Rules

["at", number, array]: ItemType

get​

Gets the attribute value from the current feature’s attributes, or from another object if the second argument is set. If the requested attribute is missing, null is returned.

Grammar Rules

["get", string]: value
["get", string, object]: value

has​

Tests for the presence of an attribute value in the current feature’s attributes, or from another object if the second argument is set.

Grammar Rules

["has", string]: boolean
["has", string, object]: boolean

in​

Determine whether an item exists in an array, or whether a substring exists in a string. In the specific case where the second and third arguments are string literals, at least one of them must be wrapped in a literal expression in order to provide the correct interpretation to the type system.

Grammar Rules

["in",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: boolean

index-of​

Returns the first position in an array where an item can be found, or in a string where a substring can be found, or -1 if not found. Accepts an optional index to start searching from anywhere.

Grammar Rules

["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: number
["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string),
    index: number
]: number

length​

Returns the length of an array or string.

Grammar Rules

["length", string | array | value]: number

slice​

Extracts an item from an array or string, or returns a substring from a string at a specified starting index, or if an ending index is set, returns a substring between the starting and ending indexes. The return value includes the starting index but not the ending index.

Grammar Rules

["slice",
    input: InputType (array or string),
    index: number
]: OutputType (ItemType or string)
["slice",
    input: InputType (array or string),
    index: number,
    index: number
]: OutputType (ItemType or string)

Camera​

distance-from-center​

Returns the distance from the symbol to the center of the map. Distance is measured in pixels divided by the height of the map container. It has a value of 0 at the center, decreases as you get closer to the camera, and increases as you move away from the camera. For example, if the height of the map is 1000px, a value of -1 means that the distance from the center to the camera is 1000px, and a value of 1 means that the distance from the camera to the center is 1000px. ["distance-from-center"] can only be used in filter expressions at the symbol level.

Grammar Rules

["distance-from-center"]: number

Color​

rgb​

Create red, green, and blue color values, which must range from 0 to 255 and have an alpha of 1. If any value is out of range, the expression will error.

Grammar Rules

["rgb", number, number, number]: color

rgba​

Create red, green, and blue color values ​​that must range from 0 to 255, and alpha must range from 0 to 1. If any value is out of range, the expression will error.

Grammar Rules

["rgba", number, number, number, number]: color

to-rgba​

Returns a four-element array containing the red, green, blue, and alpha elements of the input color.

Grammar Rules

["to-rgba", color]: array<number, 4>

Decision​

You can add conditional logic to your styles using decision expressions. For example, a case expression provides "if/then/else" logic, while a match allows you to map specific values ​​of an input expression to a different output expression.

!

logical negation. Returns true if the input is false, and returns false if the input is true.

Grammar Rules

["!", boolean]: boolean

!=​

Returns true if the input values ​​are not equal, otherwise returns false. Strictly typed comparison: Values ​​of different runtime types are always considered unequal. Cases where the types are known to be different at parse time are considered invalid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

["!=", value, value]: boolean
["!=", value, value, collator]: boolean

<​

Returns true if the first input is strictly less than the second input, otherwise returns false. The input values ​​must be two strings or two numbers; if they are not strings or numbers during evaluation, expression evaluation will produce an error. Constraints that are known not to exist at parse time are considered valid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

["<", value, value]: boolean
["<", value, value, collator]: boolean

<=​

Returns true if the first input is less than or equal to the second input, otherwise returns false. The input values ​​must be two strings or two numbers; if they are not strings or numbers during evaluation, expression evaluation will produce an error. Constraints that are known not to exist at parse time are considered valid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

["<=", value, value]: boolean
["<=", value, value, collator]: boolean

==​

Returns true if the input values ​​are equal, otherwise returns false. Strictly typed comparison: Values ​​of different runtime types are always considered unequal. Cases where the types are known to be different at parse time are considered invalid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

["==", value, value]: boolean
["==", value, value, collator]: boolean

>​

Returns true if the first input is strictly greater than the second input, otherwise returns false. The input values ​​must be two strings or two numbers; if they are not strings or numbers during evaluation, expression evaluation will produce an error. Constraints that are known not to exist at parse time are considered valid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

[">", value, value]: boolean
[">", value, value, collator]: boolean

>=​

Returns true if the first input is greater than or equal to the second input, otherwise returns false. The input values ​​must be two strings or two numbers; if they are not strings or numbers during evaluation, expression evaluation will produce an error. Constraints that are known not to exist at parse time are considered valid and will generate a parse error. Accepts an optional collator parameter to facilitate control of setting-related string comparisons.

Grammar Rules

[">=", value, value]: boolean
[">=", value, value, collator]: boolean

all​

Returns true if all input conditions are true, otherwise returns false. The evaluation is performed in the order of the conditional inputs, and the evaluation is short-circuited: when one of the input expressions evaluates to false, the result is false, and the other input expressions are no longer evaluated.

Grammar Rules

["all", boolean, boolean]: boolean
["all", boolean, boolean, ...]: boolean

any​

If any of the input conditions is true, return true, otherwise return false. The evaluation is performed in the order of the conditional input, and the evaluation is short-circuited: when one of the input expressions evaluates to true, the result is true, and other input expressions are no longer evaluated.

Grammar Rules

["any", boolean, boolean]: boolean
["any", boolean, boolean, ...]: boolean

case​

Selects the first output corresponding to the test condition that evaluates to true, otherwise selects the fallback value.

Grammar Rules

["case",
    condition: boolean, output: OutputType,
    condition: boolean, output: OutputType,
    ...,
    fallback: OutputType
]: OutputType

coalesce​

Each expression is evaluated in turn until the first valid value is obtained. Invalid values ​​are null and the 'image' expression, which is not available in the style. If all values ​​are invalid, coalesce returns the first value listed.

Grammar Rules

["coalesce", OutputType, OutputType, ...]: OutputType

match​

Selects the output whose tag value matches the input value, or a fallback value if no match is found. The input value can be any expression (for example, ["get", "building_type"]). Each tag must be unique and must be any of the following:

  • a single literal value;
  • Array of literal values ​​whose values ​​must be all strings or all numbers (e.g. [100,101] or ["c", "b"]).

The input matches if any value in the array uses strict equality matching, similar to the "in" operator. If the input type does not match the label type, the output result is a fallback value.

Grammar Rules

["match",
    input: InputType (number or string),
    label: InputType | [InputType, InputType, ...], output: OutputType,
    label: InputType | [InputType, InputType, ...], output: OutputType,
    ...,
    fallback: OutputType
]: OutputType

within​

Returns true if the feature being evaluated is completely contained within the bounds of the input geometry, false otherwise. The input value can be a valid GeoJSON of type Polygon, MultiPolygon, Feature or FeatureCollection. Supported functions are:

  • Point: Returns false if a point is on or outside the boundary.
  • LineString: Returns false if any part of the line falls outside the boundary, or the line intersects the boundary, or the endpoint of the line is on the boundary.

Grammar Rules

["within", object]: boolean

Heatmap​

heatmap-density​

Returns the kernel density estimate of the pixels in the heat map, which is a relative measure of the number of data points that are crowded around a specific pixel. Can only be used in heatmap color properties.

Grammar Rules

["heatmap-density"]: number

Math​

-​

For two inputs, returns the first input minus the second input. For a single input, return the result of subtracting it from 0.

Grammar Rules

["-", number, number]: number
["-", number]: number

*​

Returns the product of the inputs.

Grammar Rules

["*", number, number, ...]: number

/​

Returns the floating-point division result of the first input divided by the second input.

Grammar Rules

["/", number, number]: number

%​

Returns the remainder after the first input is divided by the second input.

Grammar Rules

["%", number, number]: number

^​

Returns the specified number (first input) raised to the specified power (second input)

Grammar Rules

["^", number, number]: number

+​

Returns the sum of input values

Grammar Rules

["+", number, number, ...]: number

abs​

Returns the absolute value of the input.

Grammar Rules

["abs", number]: number

acos​

Returns the arc cosine of the input.

Grammar Rules

["acos", number]: number

asin​

Returns the arcsine of the input.

Grammar Rules

["asin", number]: number

atan​

Returns the arctangent of the input.

Grammar Rules

["atan", number]: number

ceil​

Returns the smallest integer greater than or equal to the input.

Grammar Rules

["ceil", number]: number

cos​

Returns the cosine of the input.

Grammar Rules

["cos", number]: number

distance​

Returns the shortest distance (in meters) between the calculated feature and the input geometry. The input value can be a valid GeoJSON of type Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, Feature or FeatureCollection. Due to the reduced precision of the encoded geometry, the precision of the returned distance values ​​may vary, especially below zoom level 13.

Grammar Rules

["distance", object]: number

e​

Returns the mathematical constant e.

Grammar Rules

["e"]: number

floor​

Returns the largest integer less than or equal to the input.

Grammar Rules

["floor", number]: number

ln​

Returns the natural logarithm of the input.

Grammar Rules

["ln", number]: number

ln2​

Returns the mathematical constant ln(2).

Grammar Rules

["ln2"]: number

log10​

Returns the base 10 logarithm of the input.

Grammar Rules

["log10", number]: number

log2​

Returns the base 2 logarithm of the input.

Grammar Rules

["log2", number]: number

max​

Returns the maximum value of the input.

Grammar Rules

["max", number, number, ...]: number

min​

Returns the minimum value of the input.

Grammar Rules

["min", number, number, ...]: number

pi​

Returns the mathematical constant pi.

Grammar Rules

["pi"]: number

round​

Rounds the input to the nearest integer. Intermediate values ​​are rounded from zero. For example, ["round", -1.5] evaluates to -2.

Grammar Rules

["round", number]: number

sin​

Returns the sine value of the input.

Grammar Rules

["sin", number]: number

sqrt​

Returns the square root of the input.

Grammar Rules

["sqrt", number]: number

tan​

Returns the tangent value of the input.

Grammar Rules

["tan", number]: number

pitch​

Returns the current tilt in degrees. ["pitch"] can only be used in symbol filter expressions.

Grammar Rules

["pitch"]: number

zoom​

Returns the current zoom level. Note that in style layout and drawing properties, ["zoom"] can only be used as input to the top-level "step" or "interpolate" expression

Grammar Rules

["zoom"]: number

Ramps, scales, curves​

interpolate​

Produces continuous, smooth results by interpolating between input values ​​and output values ​​("stop"). The input can be any numeric expression (for example, ["get", "population"]). Stop input values ​​must be strictly ascending numeric literals. The output type must be number, array<number> or color.

Interpolation type:

  • ["linear"]: Linear interpolation between a pair of dead points just smaller than and just larger than the input.
  • ["exponential", base]: Exponential interpolation between points smaller than and larger than the input. Base controls the rate at which the output grows: the higher the value, the closer the output grows to the high end of the range. As the value approaches 1, the output increases linearly.
  • ["cubic-bezier", x1, y1, x2, y2]: Interpolate using a cubic bezier curve defined by the given control points.

Grammar Rules

["interpolate",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2],
    input: number,
    stop_input_1: number, stop_output_1: OutputType,
    stop_input_n: number, stop_output_n: OutputType, ...
]: OutputType (number, array<number>, or Color)

interpolate-hcl​

Produces continuous, smooth results by interpolating input and output values ​​("stations"). Works like interpolation, but the output type must be color and the interpolation is done in the Hue-Chroma-Luminance color space.

Grammar Rules

["interpolate-hcl",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2],
    input: number,
    stop_input_1: number, stop_output_1: Color,
    stop_input_n: number, stop_output_n: Color, ...
]: Color

interpolate-lab​

Produces continuous, smooth results by interpolating between input values ​​and output values ​​("stop"). Works like interpolate, but the output type must be color and interpolation is performed in CIELAB color space.

Grammar Rules

["interpolate-lab",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2 ],
    input: number,
    stop_input_1: number, stop_output_1: Color,
    stop_input_n: number, stop_output_n: Color, ...
]: Color

step​

Produces a discrete step result by evaluating a piecewise constant function defined by input and output values ​​("stop"). The input can be any numeric expression (for example, ["get", "population"]). Stop input values ​​must be strictly ascending numeric literals. Returns the output value of stop that is just less than the input value, or the first output value if the input is less than the first stop.

Grammar Rules

["step",
    input: number,
    stop_output_0: OutputType,
    stop_input_1: number, stop_output_1: OutputType,
    stop_input_n: number, stop_output_n: OutputType, ...
]: OutputType

String​

concat​

Returns a string consisting of the concatenation of the input values. Each input is converted to a string as if via to-string.

Grammar Rules

["concat", value, value, ...]: string

downcase​

Returns the input string converted to lowercase. Follows the Unicode default case conversion algorithm and the locale-insensitive case mapping in the Unicode character database.

Grammar Rules

["downcase", string]: string

is-supported-script​

Returns true if the expected input string can be rendered clearly. Returns false if the input string contains parts that cannot be rendered without loss of meaning (e.g. Indic scripts that require complex text shaping, or right-to-left scripts if the mapmost-gl-rtl-text plugin is not used in Mapmost GL JS).

Grammar Rules

["is-supported-script", string]: boolean

resolved-locale​

Returns the regional IETF language tag being used by the provided collator. This can be used to determine the system’s default language, or to determine whether a requested language was successfully loaded.

Grammar Rules

["resolved-locale", collator]: string

upcase​

Returns the input string converted to uppercase. Follow Unicode’s default case conversion algorithm and the case-insensitive native mapping in the Unicode character library.

Grammar Rules

["upcase", string]: string

Variable binding​

let​

Bind an expression to a named variable, which can then be referenced in the resulting expression using ["var", "variable_name"].

Grammar Rules

["let",
    string (alphanumeric literal), any, string (alphanumeric literal), any, ...,
    OutputType
]: OutputType

var​

Use "let" to reference variable bindings.

Grammar Rules

["var", previously bound variable name]: the type of the bound expression

##Type system The set of types used for the input parameters and result values ​​of expressions include: boolean, string, number, color and arrays of these types. In addition, the expression needs to be type-safe: the expression has a known result type and required parameter types, and the SDK will verify whether the result type of the expression is suitable for the context in which it is used. For example, the expression result type of the filter attribute must be boolean, and the parameter of the ± operator must be number.

Typically, the SDK does not know the type of feature attribute values ​​before processing the feature data. To ensure type safety, when evaluating data expressions, the SDK will check whether the attribute value is suitable for the context. For example, if you set the circle-color attribute to the expression ["get", "feature-color"], the SDK will verify that the feature-color value of each feature is a valid color string. If this check fails, an error will be output in an SDK-specific manner (usually a log message), and the default value of the property will be used.

In most cases, this verification will occur automatically wherever needed. However, in some cases the SDK may not be able to automatically determine the expected result type of a data expression from the surrounding context. For example, it is not clear whether the expression ["<", ["get", "a"], ["get", "b"]] compares strings or numeric values. In this case, you can use one of the type assertion expression operators to indicate the expected type of the data expression: ["<", ["number", ["get", "a"]], ["number", ["get", "b"]]. Type assertions check whether the feature data matches the expected type of the data expression. If this check fails, it will output an error and cause the entire expression to return the default value of the defined property. Assertion operators include array, boolean, number and string.

The expression performs only one implicit type conversion: when a color is required, the data expression converts the color expressed as a string into a color value. In all other cases, if you want to convert a type, you must use one of the type conversion expression operators: to-boolean, to-number, to-string, or to-color. For example, if you have a feature attribute that stores numeric values ​​in string format, and you want to use those values ​​as numeric values ​​instead of strings, you can use an expression such as ["to-number", ["get", "property-name"]].

If an expression accepts an array parameter and the user supplies an array literal, the array must be wrapped in a literal expression (see example below). When the SDK encounters an array in a style specification attribute value, it assumes the array is an expression and attempts to parse it; the SDK has no way to distinguish between expressions that fail validation and array literals unless the developer explicitly makes the distinction using the literal operator. If the array is returned by a subexpression, such as ["in", 1, ["get", "myArrayProp"]], the literal operator is not required.

// will throw an error
{
    "circle-color": ["in", 1, [1, 2, 3]]
}

// will run as expected
{
    "circle-color": ["in", 1, ["literal", [1, 2, 3]]]
}