Project: QGIS

Version: 3.0.0

Feature: New expression functions

Atlas expressions

  • atlas_layerid and atlas_layername: Returns layer ID and layer name of the current layer in the atlas.

Aggregate expressions

  • array_agg(expression, group_by, filter): Returns an array of aggregated values from a field or expression.

Array expressions

New group that contains expression functions for the creation and manipulation of arrays (also known as list data structures). The order of values within the array matters, in contrary to the 'map' data structure, where the order of key-value pairs is irrelevant and values are identified by their keys.

  • array(value1, value2, …) : Returns an array containing all the values passed as parameter.
  • array_append(array, value): Returns an array with the given value added at the end.
  • array_cat(array1, array2, …): Returns an array containing all the given arrays concatenated.
  • array_contains(array, value): Returns true if an array contains the given value.
  • array_distinct(array): Returns an array containing distinct values of the given array.
  • array_find(array, value): Returns the index (0 for the first one) of a value within an array. Returns -1 if the value is not found.
  • array_first(array): Returns the first value of an array.
  • array_get(array, index): Returns the Nth value (0 for the first one) of an array.
  • array_insert(array, pos, value): Returns an array with the given value added at the given position.
  • array_intersect(array1, array2): Returns true if any element of array1 exists in array2.
  • array_last(array): Returns the last value of an array.
  • array_length(array): Returns the number of elements of an array.
  • array_prepend(array, value): Returns an array with the given value added at the beginning.
  • array_remove_all(array, value): Returns an array with all the entries of the given value removed.
  • array_remove_at(array, pos): Returns an array with the given index removed.
  • array_reverse(array): Returns the given array with array values in reversed order.
  • array_slice(array, start_pos, end_pos): Returns a portion of the array. The slice is defined by the start_pos and end_pos arguments.
  • array_to_string(array, delimiter, empty_value): Concatenates array elements into a string separated by a delimiter using and optional string for empty values.
  • regexp_matches(string, regex, empty_value): Returns an array of all strings captured by capturing groups, in the order the groups themselves appear in the supplied regular expression against a string.
  • string_to_array(string, delimiter, empty_value): Splits string into an array using supplied delimiter and optional string for empty values.

Color expressions

  • create_ramp(map, discrete): Returns a gradient ramp from a map of color strings and steps.

Date and Time expressions

  • epoch(date): Return the interval in milliseconds between the unix epoch and a given date value.

General expressions

  • env(name): Gets an environment variable and returns its content as a string. If the variable is not found, NULL will be returned.
  • raster_statistic(layer, band, property): Returns statistics from a raster layer. Properties: min/max/avg/range/stdev/sum
  • with_variable(name, value, node): This function sets a variable for any expression code that will be provided as 3rd argument. This is only useful for complicated expressions, where the same calculated value needs to be used in different places.

Geometry expressions

  • extend(geometry, start_distance, end_distance): Extends linestrings by a specified amount at the start and end of the line
  • hausdorff_distance(geometry a, geometry b, densify_fraction): Returns the Hausdorff distance between two geometries. This is basically a measure of how similar or dissimilar 2 geometries are, with a lower distance indicating more similar geometries.
  • inclination(inclination(point_a, point_b): Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.
  • make_circle(center, radius, segment): Creates a circular, segmentized, polygon.
  • make_ellipse(center, semi_major_axis, semi_minor_axis, azimuth, segment): Creates an elliptical, segmentized, polygon.
  • make_regular_polygon(center, radius, number_sides, circle): Creates a regular polygon.
  • make_triangle(): help still missing
  • minimal_circle(geometry, segment): Returns the minimal enclosing circle of a geometry. It represents the minimum circle that encloses all geometries within the set.
  • offset_curve(geometry, distance, segments, join, miter_limit): Returns a geometry formed by offsetting a linestring geometry to the side. Distances are in the Spatial Reference System of this geometry.
  • oriented_bbox(geom): Returns a geometry which represents the minimal oriented bounding box of an input geometry.
  • pole_of_inaccessibility(geometry, tolerance): Calculates the approximate pole of inaccessibility for a surface, which is the most distant internal point from the boundary of the surface. This function uses the 'polylabel' algorithm (Vladimir Agafonkin, 2016), which is an iterative approach guaranteed to find the true pole of inaccessibility within a specified tolerance.
  • simplify(geometry, tolerance): Simplifies a geometry by removing nodes using a distance based threshold (ie, the Douglas Peucker algorithm). The algorithm preserves large deviations in geometries and reduces the number of vertices in nearly straight segments.
  • simplify_vw(geometry, tolerance): Simplifies a geometry by removing nodes using an area based threshold (the Visvalingam-Whyatt algorithm). The algorithm removes vertices which create small areas in geometries, e.g., narrow spikes or nearly straight segments.
  • smooth(geometry, iterations, offset, min_length, max_angle): Smooths a geometry by adding extra nodes which round off corners in the geometry.
  • single_sided_buffer(geometry, distance, segments, join, miter_limit): Returns a geometry formed by buffering out just one side of a linestring geometry. Distances are in the Spatial Reference System of this geometry.

Layer Property

  • crs_description returns the CRS description of the layer.

Map Expressions

This group contains expression functions for the creation and manipulation of 'map' data structures (also known as dictionary objects, key-value pairs, or associative arrays). One can assign values to given keys. The order of the key-value pairs in the map object is not relevant.

  • map(key1, value1, key2, value2, , …): Returns a map containing all the keys and values passed as pair of parameters.
  • map_akeys(map): Returns all the keys of a map as an array.
  • map_avals(map): Returns all the values of a map as an array.
  • map_concat(map1, map2, …): Returns a map containing all the entries of the given maps. If two maps contain the same key, the value of the second map is taken.
  • map_delete(map, key): Returns a map with the given key and its corresponding value deleted.
  • map_exist(map, key): Returns true if the given key exists in the map.
  • map_get(map, key): Returns the value of a map, given it's key.
  • map_insert(map, key, value): Returns a map with an added key/value.

Map Layers

New group that contains a list of map layers available in the current project. Returns internal map layer ids. This is used in many other expression functions that reference map layers.

Math expressions

  • inclination(point_a, point_b): Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.

Operators

  • ~: Performs a regular expression match on a string value.

Record and Attributes Expressions

renamed from just "Record"

  • get_feature_by_id(layer, feature_id): Returns the feature with an id on a layer.
  • is_selected(feature, layer): Returns if a feature is selected. If called with no parameters checks the current feature.
  • num_selected(layer): Returns the number of selected features on a given layer. By default works on the layer on which the expression is evaluated.
  • represent_value(value, fieldName): Returns the configured representation value for a field value. It depends on the configured widget type. Often, this is useful for 'Value Map' widgets.
  • uuid(): Generates a Universally Unique Identifier (UUID) for each row using the Qt QUuid::createUuid method. Each UUID is 38 characters long.

Relations

New group listing all available table relations in a project. Useful for relation_aggregate functions.

Deprecated

  • $scale: old variable to get current map scale. Replaced by maps_scale

Changes

  • Change in substr() function
    • support negative start value (e.g. substr('hello',-2) returns 'lo')
    • support negative length value (e.g. substr('hello',3,-1) returns 'll')
    • length parameter now optional, defaults to end of string (e.g. substr('hello world',7) returns 'world')
  • strpos() now relies on a simple string within a string search
  • regexp_match() now returns pos of a matching regular expression

This feature was developed by numerous developers