14.3. List of functions

The functions, operators and variables available in QGIS are listed below, grouped by categories.

14.3.1. Aggregates Functions

This group contains functions which aggregate values over layers and fields.

14.3.1.1. aggregate

Returns an aggregate value calculated using features from another layer.

Syntax

aggregate(layer, aggregate, expression, [filter], [concatenator=’’], [order_by])

[] marks optional arguments

Arguments

  • layer - a string, representing either a layer name or layer ID

  • aggregate - a string corresponding to the aggregate to calculate. Valid options are:

    • count

    • count_distinct

    • count_missing

    • min

    • max

    • sum

    • mean

    • median

    • stdev

    • stdevsample

    • range

    • minority

    • majority

    • q1: first quartile

    • q3: third quartile

    • iqr: inter quartile range

    • min_length: minimum string length

    • max_length: maximum string length

    • concatenate: join strings with a concatenator

    • concatenate_unique: join unique strings with a concatenator

    • collect: create an aggregated multipart geometry

    • array_agg: create an array of aggregated values

  • expression - sub expression or field name to aggregate

  • filter - optional filter expression to limit the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. The source feature can be accessed with the variable @parent.

  • concatenator - optional string to use to join values for ‘concatenate’ aggregate

  • order_by - optional filter expression to order the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. By default, the features will be returned in an unspecified order.

Examples

  • aggregate(layer:='rail_stations',aggregate:='sum',expression:="passengers") → sum of all values from the passengers field in the rail_stations layer

  • aggregate('rail_stations','sum', "passengers"/7) → calculates a daily average of “passengers” by dividing the “passengers” field by 7 before summing the values

  • aggregate(layer:='rail_stations',aggregate:='sum',expression:="passengers",filter:="class">3) → sums up all values from the “passengers” field from features where the “class” attribute is greater than 3 only

  • aggregate(layer:='rail_stations',aggregate:='concatenate', expression:="name", concatenator:=',') → comma separated list of the name field for all features in the rail_stations layer

  • aggregate(layer:='countries', aggregate:='max', expression:="code", filter:=intersects( $geometry, geometry(@parent) ) ) → The country code of an intersecting country on the layer ‘countries’

  • aggregate(layer:='rail_stations',aggregate:='sum',expression:="passengers",filter:=contains( @atlas_geometry, $geometry ) ) → sum of all values from the passengers field in the rail_stations within the current atlas feature

  • aggregate(layer:='rail_stations', aggregate:='collect', expression:=centroid($geometry), filter:="region_name" = attribute(@parent,'name') ) → aggregates centroid geometries of the rail_stations of the same region as current feature

14.3.1.2. array_agg

Returns an array of aggregated values from a field or expression.

Syntax

array_agg(expression, [group_by], [filter], [order_by])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

  • order_by - optional expression to use to order features used to calculate aggregate. By default, the features will be returned in an unspecified order.

Examples

  • array_agg("name",group_by:="state") → list of name values, grouped by state field

14.3.1.3. collect

Returns the multipart geometry of aggregated geometries from an expression

Syntax

collect(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - geometry expression to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • collect( $geometry ) → multipart geometry of aggregated geometries

  • collect( centroid($geometry), group_by:="region", filter:= "use" = 'civilian' ) → aggregated centroids of the civilian features based on their region value

14.3.1.4. concatenate

Returns all aggregated strings from a field or expression joined by a delimiter.

Syntax

concatenate(expression, [group_by], [filter], [concatenator], [order_by])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

  • concatenator - optional string to use to join values. Empty by default.

  • order_by - optional expression to use to order features used to calculate aggregate. By default, the features will be returned in an unspecified order.

Examples

  • concatenate("town_name",group_by:="state",concatenator:=',') → comma separated list of town_names, grouped by state field

14.3.1.5. concatenate_unique

Returns all unique strings from a field or expression joined by a delimiter.

Syntax

concatenate_unique(expression, [group_by], [filter], [concatenator], [order_by])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

  • concatenator - optional string to use to join values. Empty by default.

  • order_by - optional expression to use to order features used to calculate aggregate. By default, the features will be returned in an unspecified order.

Examples

  • concatenate_unique("town_name",group_by:="state",concatenator:=',') → comma separated list of unique town_names, grouped by state field

14.3.1.6. count

Returns the count of matching features.

Syntax

count(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • count("stations",group_by:="state") → count of stations, grouped by state field

14.3.1.7. count_distinct

Returns the count of distinct values.

Syntax

count_distinct(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • count_distinct("stations",group_by:="state") → count of distinct stations values, grouped by state field

14.3.1.8. count_missing

Returns the count of missing (NULL) values.

Syntax

count_missing(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • count_missing("stations",group_by:="state") → count of missing (NULL) station values, grouped by state field

14.3.1.9. iqr

Returns the calculated inter quartile range from a field or expression.

Syntax

iqr(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • iqr("population",group_by:="state") → inter quartile range of population value, grouped by state field

14.3.1.10. majority

Returns the aggregate majority of values (most commonly occurring value) from a field or expression.

Syntax

majority(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • majority("class",group_by:="state") → most commonly occurring class value, grouped by state field

14.3.1.11. max_length

Returns the maximum length of strings from a field or expression.

Syntax

max_length(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • max_length("town_name",group_by:="state") → maximum length of town_name, grouped by state field

14.3.1.12. maximum

Returns the aggregate maximum value from a field or expression.

Syntax

maximum(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • maximum("population",group_by:="state") → maximum population value, grouped by state field

14.3.1.13. mean

Returns the aggregate mean value from a field or expression.

Syntax

mean(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • mean("population",group_by:="state") → mean population value, grouped by state field

14.3.1.14. median

Returns the aggregate median value from a field or expression.

Syntax

median(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • median("population",group_by:="state") → median population value, grouped by state field

14.3.1.15. min_length

Returns the minimum length of strings from a field or expression.

Syntax

min_length(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • min_length("town_name",group_by:="state") → minimum length of town_name, grouped by state field

14.3.1.16. minimum

Returns the aggregate minimum value from a field or expression.

Syntax

minimum(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • minimum("population",group_by:="state") → minimum population value, grouped by state field

14.3.1.17. minority

Returns the aggregate minority of values (least occurring value) from a field or expression.

Syntax

minority(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • minority("class",group_by:="state") → least occurring class value, grouped by state field

14.3.1.18. q1

Returns the calculated first quartile from a field or expression.

Syntax

q1(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • q1("population",group_by:="state") → first quartile of population value, grouped by state field

14.3.1.19. q3

Returns the calculated third quartile from a field or expression.

Syntax

q3(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • q3("population",group_by:="state") → third quartile of population value, grouped by state field

14.3.1.20. range

Returns the aggregate range of values (maximum - minimum) from a field or expression.

Syntax

range(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • range("population",group_by:="state") → range of population values, grouped by state field

14.3.1.21. relation_aggregate

Returns an aggregate value calculated using all matching child features from a layer relation.

Syntax

relation_aggregate(relation, aggregate, expression, [concatenator=’’], [order_by])

[] marks optional arguments

Arguments

  • relation - a string, representing a relation ID

  • aggregate - a string corresponding to the aggregate to calculate. Valid options are:

    • count

    • count_distinct

    • count_missing

    • min

    • max

    • sum

    • mean

    • median

    • stdev

    • stdevsample

    • range

    • minority

    • majority

    • q1: first quartile

    • q3: third quartile

    • iqr: inter quartile range

    • min_length: minimum string length

    • max_length: maximum string length

    • concatenate: join strings with a concatenator

    • concatenate_unique: join unique strings with a concatenator

    • collect: create an aggregated multipart geometry

    • array_agg: create an array of aggregated values

  • expression - sub expression or field name to aggregate

  • concatenator - optional string to use to join values for ‘concatenate’ aggregate

  • order_by - optional expression to order the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. By default, the features will be returned in an unspecified order.

Examples

  • relation_aggregate(relation:='my_relation',aggregate:='mean',expression:="passengers") → mean value of all matching child features using the ‘my_relation’ relation

  • relation_aggregate('my_relation','sum', "passengers"/7) → sum of the passengers field divided by 7 for all matching child features using the ‘my_relation’ relation

  • relation_aggregate('my_relation','concatenate', "towns", concatenator:=',') → comma separated list of the towns field for all matching child features using the ‘my_relation’ relation

  • relation_aggregate('my_relation','array_agg', "id") → array of the id field from all matching child features using the ‘my_relation’ relation

Further reading: Creating one or many to many relations

14.3.1.22. stdev

Returns the aggregate standard deviation value from a field or expression.

Syntax

stdev(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • stdev("population",group_by:="state") → standard deviation of population value, grouped by state field

14.3.1.23. sum

Returns the aggregate summed value from a field or expression.

Syntax

sum(expression, [group_by], [filter])

[] marks optional arguments

Arguments

  • expression - sub expression of field to aggregate

  • group_by - optional expression to use to group aggregate calculations

  • filter - optional expression to use to filter features used to calculate aggregate

Examples

  • sum("population",group_by:="state") → summed population value, grouped by state field

14.3.2. Array Functions

This group contains functions to create and manipulate arrays (also known as list data structures). The order of values within the array matters, unlike the ‘map’ data structure, where the order of key-value pairs is irrelevant and values are identified by their keys.

14.3.2.1. array

Returns an array containing all the values passed as parameter.

Syntax

array(value1, value2, …)

Arguments

  • value - a value

Examples

  • array(2,10) → [ 2, 10 ]

14.3.2.2. array_all

Returns true if an array contains all the values of a given array.

Syntax

array_all(array_a, array_b)

Arguments

  • array_a - an array

  • array_b - the array of values to search

Examples

  • array_all(array(1,2,3),array(2,3)) → true

  • array_all(array(1,2,3),array(1,2,4)) → false

14.3.2.3. array_append

Returns an array with the given value added at the end.

Syntax

array_append(array, value)

Arguments

  • array - an array

  • value - the value to add

Examples

  • array_append(array(1,2,3),4) → [ 1, 2, 3, 4 ]

14.3.2.4. array_cat

Returns an array containing all the given arrays concatenated.

Syntax

array_cat(array1, array2, …)

Arguments

  • array - an array

Examples

  • array_cat(array(1,2),array(2,3)) → [ 1, 2, 2, 3 ]

14.3.2.5. array_contains

Returns true if an array contains the given value.

Syntax

array_contains(array, value)

Arguments

  • array - an array

  • value - the value to search

Examples

  • array_contains(array(1,2,3),2) → true

14.3.2.6. array_distinct

Returns an array containing distinct values of the given array.

Syntax

array_distinct(array)

Arguments

  • array - an array

Examples

  • array_distinct(array(1,2,3,2,1)) → [ 1, 2, 3 ]

14.3.2.7. array_filter

Returns an array with only the items for which the expression evaluates to true.

Syntax

array_filter(array, expression)

Arguments

  • array - an array

  • expression - an expression to evaluate on each item. The variable @element will be replaced by the current value.

Examples

  • array_filter(array(1,2,3),@element < 3) → [ 1, 2 ]

14.3.2.8. array_find

Returns the index (0 for the first one) of a value within an array. Returns -1 if the value is not found.

Syntax

array_find(array, value)

Arguments

  • array - an array

  • value - the value to search

Examples

  • array_find(array(1,2,3),2) → 1

14.3.2.9. array_first

Returns the first value of an array.

Syntax

array_first(array)

Arguments

  • array - an array

Examples

  • array_first(array('a','b','c')) → ‘a’

14.3.2.10. array_foreach

Returns an array with the given expression evaluated on each item.

Syntax

array_foreach(array, expression)

Arguments

  • array - an array

  • expression - an expression to evaluate on each item. The variable @element will be replaced by the current value.

Examples

  • array_foreach(array('a','b','c'),upper(@element)) → [ ‘A’, ‘B’, ‘C’ ]

  • array_foreach(array(1,2,3),@element + 10) → [ 11, 12, 13 ]

14.3.2.11. array_get

Returns the Nth value (0 for the first one) of an array.

Syntax

array_get(array, index)

Arguments

  • array - an array

  • index - the index to get (0 based)

Examples

  • array_get(array('a','b','c'),1) → ‘b’

14.3.2.12. array_insert

Returns an array with the given value added at the given position.

Syntax

array_insert(array, pos, value)

Arguments

  • array - an array

  • pos - the position where to add (0 based)

  • value - the value to add

Examples

  • array_insert(array(1,2,3),1,100) → [ 1, 100, 2, 3 ]

14.3.2.13. array_intersect

Returns true if at least one element of array1 exists in array2.

Syntax

array_intersect(array1, array2)

Arguments

  • array1 - an array

  • array2 - another array

Examples

  • array_intersect(array(1,2,3,4),array(4,0,2,5)) → true

14.3.2.14. array_last

Returns the last value of an array.

Syntax

array_last(array)

Arguments

  • array - an array

Examples

  • array_last(array('a','b','c')) → ‘c’

14.3.2.15. array_length

Returns the number of elements of an array.

Syntax

array_length(array)

Arguments

  • array - an array

Examples

  • array_length(array(1,2,3)) → 3

14.3.2.16. array_prepend

Returns an array with the given value added at the beginning.

Syntax

array_prepend(array, value)

Arguments

  • array - an array

  • value - the value to add

Examples

  • array_prepend(array(1,2,3),0) → [ 0, 1, 2, 3 ]

14.3.2.17. array_remove_all

Returns an array with all the entries of the given value removed.

Syntax

array_remove_all(array, value)

Arguments

  • array - an array

  • value - the values to remove

Examples

  • array_remove_all(array('a','b','c','b'),'b') → [ ‘a’, ‘c’ ]

14.3.2.18. array_remove_at

Returns an array with the given index removed.

Syntax

array_remove_at(array, pos)

Arguments

  • array - an array

  • pos - the position to remove (0 based)

Examples

  • array_remove_at(array(1,2,3),1) → [ 1, 3 ]

14.3.2.19. array_reverse

Returns the given array with array values in reversed order.

Syntax

array_reverse(array)

Arguments

  • array - an array

Examples

  • array_reverse(array(2,4,0,10)) → [ 10, 0, 4, 2 ]

14.3.2.20. array_slice

Returns a portion of the array. The slice is defined by the start_pos and end_pos arguments.

Syntax

array_slice(array, start_pos, end_pos)

Arguments

  • array - an array

  • start_pos - the index of the start position of the slice (0 based). The start_pos index is included in the slice. If you use a negative start_pos, the index is counted from the end of the list (-1 based).

  • end_pos - the index of the end position of the slice (0 based). The end_pos index is included in the slice. If you use a negative end_pos, the index is counted from the end of the list (-1 based).

Examples

  • array_slice(array(1,2,3,4,5),0,3) → [ 1, 2, 3, 4 ]

  • array_slice(array(1,2,3,4,5),0,-1) → [ 1, 2, 3, 4, 5 ]

  • array_slice(array(1,2,3,4,5),-5,-1) → [ 1, 2, 3, 4, 5 ]

  • array_slice(array(1,2,3,4,5),0,0) → [ 1 ]

  • array_slice(array(1,2,3,4,5),-2,-1) → [ 4, 5 ]

  • array_slice(array(1,2,3,4,5),-1,-1) → [ 5 ]

  • array_slice(array('Dufour','Valmiera','Chugiak','Brighton'),1,2) → [ ‘Valmiera’, ‘Chugiak’ ]

  • array_slice(array('Dufour','Valmiera','Chugiak','Brighton'),-2,-1) → [ ‘Chugiak’, ‘Brighton’ ]

14.3.2.21. array_sort

Returns the provided array with its elements sorted.

Syntax

array_sort(array, [ascending=true])

[] marks optional arguments

Arguments

  • array - an array

  • ascending - set this parameter to false to sort the array in descending order

Examples

  • array_sort(array(3,2,1)) → [ 1, 2, 3 ]

14.3.2.22. array_to_string

Concatenates array elements into a string separated by a delimiter and using optional string for empty values.

Syntax

array_to_string(array, [delimiter=’,’], [empty_value=’’])

[] marks optional arguments

Arguments

  • array - the input array

  • delimiter - the string delimiter used to separate concatenated array elements

  • empty_value - the optional string to use as replacement for empty (zero length) matches

Examples

  • array_to_string(array('1','2','3')) → ‘1,2,3’

  • array_to_string(array(1,2,3),'-') → ‘1-2-3’

  • array_to_string(array('1','','3'),',','0') → ‘1,0,3’

14.3.2.23. generate_series

Creates an array containing a sequence of numbers.

Syntax

generate_series(start, stop, [step=1])

[] marks optional arguments

Arguments

  • start - first value of the sequence

  • stop - value that ends the sequence once reached

  • step - value used as the increment between values

Examples

  • generate_series(1,5) → [ 1, 2, 3, 4, 5 ]

  • generate_series(5,1,-1) → [ 5, 4, 3, 2, 1 ]

14.3.2.24. regexp_matches

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.

Syntax

regexp_matches(string, regex, [empty_value=’’])

[] marks optional arguments

Arguments

  • string - the string to capture groups from against the regular expression

  • regex - the regular expression used to capture groups

  • empty_value - the optional string to use as replacement for empty (zero length) matches

Examples

  • regexp_matches('QGIS=>rocks','(.*)=>(.*)') → [ ‘QGIS’, ‘rocks’ ]

  • regexp_matches('key=>','(.*)=>(.*)','empty value') → [ ‘key’, ‘empty value’ ]

14.3.2.25. string_to_array

Splits string into an array using supplied delimiter and optional string for empty values.

Syntax

string_to_array(string, [delimiter=’,’], [empty_value=’’])

[] marks optional arguments

Arguments

  • string - the input string

  • delimiter - the string delimiter used to split the input string

  • empty_value - the optional string to use as replacement for empty (zero length) matches

Examples

  • string_to_array('1,2,3',',') → [ ‘1’, ‘2’, ‘3’ ]

  • string_to_array('1,,3',',','0') → [ ‘1’, ‘0’, ‘3’ ]

14.3.3. Color Functions

This group contains functions for manipulating colors.

14.3.3.1. color_cmyk

Returns a string representation of a color based on its cyan, magenta, yellow and black components

Syntax

color_cmyk(cyan, magenta, yellow, black)

Arguments

  • cyan - cyan component of the color, as a percentage integer value from 0 to 100

  • magenta - magenta component of the color, as a percentage integer value from 0 to 100

  • yellow - yellow component of the color, as a percentage integer value from 0 to 100

  • black - black component of the color, as a percentage integer value from 0 to 100

Examples

  • color_cmyk(100,50,0,10) → ‘0,115,230’

14.3.3.2. color_cmyka

Returns a string representation of a color based on its cyan, magenta, yellow, black and alpha (transparency) components

Syntax

color_cmyka(cyan, magenta, yellow, black, alpha)

Arguments

  • cyan - cyan component of the color, as a percentage integer value from 0 to 100

  • magenta - magenta component of the color, as a percentage integer value from 0 to 100

  • yellow - yellow component of the color, as a percentage integer value from 0 to 100

  • black - black component of the color, as a percentage integer value from 0 to 100

  • alpha - alpha component as an integer value from 0 (completely transparent) to 255 (opaque).

Examples

  • color_cmyk(100,50,0,10,200) → ‘0,115,230,200’

14.3.3.3. color_grayscale_average

Applies a grayscale filter and returns a string representation from a provided color.

Syntax

color_grayscale_average(color)

Arguments

  • color - a color string

Examples

  • color_grayscale_average('255,100,50') → ‘135,135,135,255’

14.3.3.4. color_hsl

Returns a string representation of a color based on its hue, saturation, and lightness attributes.

Syntax

color_hsl(hue, saturation, lightness)

Arguments

  • hue - hue of the color, as an integer value from 0 to 360

  • saturation - saturation percentage of the color as an integer value from 0 to 100

  • lightness - lightness percentage of the color as an integer value from 0 to 100

Examples

  • color_hsl(100,50,70) → ‘166,217,140’

14.3.3.5. color_hsla

Returns a string representation of a color based on its hue, saturation, lightness and alpha (transparency) attributes

Syntax

color_hsla(hue, saturation, lightness, alpha)

Arguments

  • hue - hue of the color, as an integer value from 0 to 360

  • saturation - saturation percentage of the color as an integer value from 0 to 100

  • lightness - lightness percentage of the color as an integer value from 0 to 100

  • alpha - alpha component as an integer value from 0 (completely transparent) to 255 (opaque).

Examples

  • color_hsla(100,50,70,200) → ‘166,217,140,200’

14.3.3.6. color_hsv

Returns a string representation of a color based on its hue, saturation, and value attributes.

Syntax

color_hsv(hue, saturation, value)

Arguments

  • hue - hue of the color, as an integer value from 0 to 360

  • saturation - saturation percentage of the color as an integer value from 0 to 100

  • value - value percentage of the color as an integer from 0 to 100

Examples

  • color_hsv(40,100,100) → ‘255,170,0’

14.3.3.7. color_hsva

Returns a string representation of a color based on its hue, saturation, value and alpha (transparency) attributes.

Syntax

color_hsva(hue, saturation, value, alpha)

Arguments

  • hue - hue of the color, as an integer value from 0 to 360

  • saturation - saturation percentage of the color as an integer value from 0 to 100

  • value - value percentage of the color as an integer from 0 to 100

  • alpha - alpha component as an integer value from 0 (completely transparent) to 255 (opaque)

Examples

  • color_hsva(40,100,100,200) → ‘255,170,0,200’

14.3.3.8. color_mix_rgb

Returns a string representing a color mixing the red, green, blue, and alpha values of two provided colors based on a given ratio.

Syntax

color_mix_rgb(color1, color2, ratio)

Arguments

  • color1 - a color string

  • color2 - a color string

  • ratio - a ratio

Examples

  • color_mix_rgb('0,0,0','255,255,255',0.5) → ‘127,127,127,255’

14.3.3.9. color_part

Returns a specific component from a color string, e.g., the red component or alpha component.

Syntax

color_part(color, component)

Arguments

  • color - a color string

  • component - a string corresponding to the color component to return. Valid options are:

    • red: RGB red component (0-255)

    • green: RGB green component (0-255)

    • blue: RGB blue component (0-255)

    • alpha: alpha (transparency) value (0-255)

    • hue: HSV hue (0-360)

    • saturation: HSV saturation (0-100)

    • value: HSV value (0-100)

    • hsl_hue: HSL hue (0-360)

    • hsl_saturation: HSL saturation (0-100)

    • lightness: HSL lightness (0-100)

    • cyan: CMYK cyan component (0-100)

    • magenta: CMYK magenta component (0-100)

    • yellow: CMYK yellow component (0-100)

    • black: CMYK black component (0-100)

Examples

  • color_part('200,10,30','green') → 10

14.3.3.10. color_rgb

Returns a string representation of a color based on its red, green, and blue components.

Syntax

color_rgb(red, green, blue)

Arguments

  • red - red component as an integer value from 0 to 255

  • green - green component as an integer value from 0 to 255

  • blue - blue component as an integer value from 0 to 255

Examples

  • color_rgb(255,127,0) → ‘255,127,0’

14.3.3.11. color_rgba

Returns a string representation of a color based on its red, green, blue, and alpha (transparency) components.

Syntax

color_rgba(red, green, blue, alpha)

Arguments

  • red - red component as an integer value from 0 to 255

  • green - green component as an integer value from 0 to 255

  • blue - blue component as an integer value from 0 to 255

  • alpha - alpha component as an integer value from 0 (completely transparent) to 255 (opaque).

Examples

  • color_rgba(255,127,0,200) → ‘255,127,0,200’

14.3.3.12. create_ramp

Returns a gradient ramp from a map of color strings and steps.

Syntax

create_ramp(map, [discrete=false])

[] marks optional arguments

Arguments

  • map - a map of color strings and steps

  • discrete - set this parameter to true to create a discrete color ramp

Examples

  • ramp_color(create_ramp(map(0,'0,0,0',1,'255,0,0')),1) → ‘255,0,0,255’

14.3.3.13. darker

Returns a darker (or lighter) color string

Syntax

darker(color, factor)

Arguments

  • color - a color string

  • factor - an integer corresponding to the darkening factor:

    • if the factor is greater than 100, this function returns a darker color (e.g., setting factor to 200 returns a color that is half the brightness);

    • if the factor is less than 100, the return color is lighter, but using the lighter() function for this purpose is recommended;

    • if the factor is 0 or negative, the return value is unspecified.

Examples

  • darker('200,10,30', 200) → ‘100,5,15,255’

Further reading: lighter

14.3.3.14. lighter

Returns a lighter (or darker) color string

Syntax

lighter(color, factor)

Arguments

  • color - a color string

  • factor - an integer corresponding to the lightening factor:

    • if the factor is greater than 100, this function returns a lighter color (e.g., setting factor to 150 returns a color that is 50% brighter);

    • if the factor is less than 100, the return color is darker, but using the darker() function for this purpose is recommended;

    • if the factor is 0 or negative, the return value is unspecified.

Examples

  • lighter('200,10,30', 200) → ‘255,158,168,255’

Further reading: darker

14.3.3.15. project_color

Returns a color from the project’s color scheme.

Syntax

project_color(name)

Arguments

  • name - a color name

Examples

  • project_color('Logo color') → ‘20,140,50’

Further reading: setting project colors

14.3.3.16. ramp_color

Returns a string representing a color from a color ramp.

Saved ramp variant

Returns a string representing a color from a saved ramp

Syntax

ramp_color(ramp_name, value)

Arguments

  • ramp_name - the name of the color ramp as a string, for example ‘Spectral’

  • value - the position on the ramp to select the color from as a real number between 0 and 1

Examples

  • ramp_color('Spectral',0.3) → ‘253,190,115,255’

Note

The color ramps available vary between QGIS installations. This function may not give the expected results if you move your QGIS project between installations.

Expression-created ramp variant

Returns a string representing a color from an expression-created ramp

Syntax

ramp_color(ramp, value)

Arguments

  • ramp - the color ramp

  • value - the position on the ramp to select the color from as a real number between 0 and 1

Examples

  • ramp_color(create_ramp(map(0,'0,0,0',1,'255,0,0')),1) → ‘255,0,0,255’

Further reading: Setting a Color Ramp, The color ramp drop-down shortcut

14.3.3.17. set_color_part

Sets a specific color component for a color string, e.g., the red component or alpha component.

Syntax

set_color_part(color, component, value)

Arguments

  • color - a color string

  • component - a string corresponding to the color component to set. Valid options are:

    • red: RGB red component (0-255)

    • green: RGB green component (0-255)

    • blue: RGB blue component (0-255)

    • alpha: alpha (transparency) value (0-255)

    • hue: HSV hue (0-360)

    • saturation: HSV saturation (0-100)

    • value: HSV value (0-100)

    • hsl_hue: HSL hue (0-360)

    • hsl_saturation: HSL saturation (0-100)

    • lightness: HSL lightness (0-100)

    • cyan: CMYK cyan component (0-100)

    • magenta: CMYK magenta component (0-100)

    • yellow: CMYK yellow component (0-100)

    • black: CMYK black component (0-100)

  • value - new value for color component, respecting the ranges listed above

Examples

  • set_color_part('200,10,30','green',50) → ‘200,50,30,255’

14.3.4. Conditional Functions

This group contains functions to handle conditional checks in expressions.

14.3.4.1. CASE

CASE is used to evaluate a series of conditions and return a result for the first condition met. The conditions are evaluated sequentially, and if a condition is true, the evaluation stops, and the corresponding result is returned. If none of the conditions are true, the value in the ELSE clause is returned. Furthermore, if no ELSE clause is set and none of the conditions are met, NULL is returned.

CASE

WHEN condition THEN result

[ …n ]

[ ELSE result ]

END

[ ] marks optional components

Arguments

  • WHEN condition - A condition expression to evaluate

  • THEN result - If condition evaluates to True then result is evaluated and returned.

  • ELSE result - If none of the above conditions evaluated to True then result is evaluated and returned.

Examples

  • CASE WHEN "name" IS NULL THEN 'None' END → Returns the string ‘None’ if the “name” field is NULL

  • CASE WHEN $area > 10000 THEN 'Big property' WHEN $area > 5000 THEN 'Medium property' ELSE 'Small property' END → Returns the string ‘Big property’ if the area is bigger than 10000, ‘Medium property’ if the area is between 5000 and 10000, and ‘Small property’ for others

14.3.4.2. coalesce

Returns the first non-NULL value from the expression list.

This function can take any number of arguments.

Syntax

coalesce(expression1, expression2, …)

Arguments

  • expression - any valid expression or value, regardless of type.

Examples

  • coalesce(NULL, 2) → 2

  • coalesce(NULL, 2, 3) → 2

  • coalesce(7, NULL, 3*2) → 7

  • coalesce("fieldA", "fallbackField", 'ERROR') → value of fieldA if it is non-NULL else the value of “fallbackField” or the string ‘ERROR’ if both are NULL

14.3.4.3. if

Tests a condition and returns a different result depending on the conditional check.

Syntax

if(condition, result_when_true, result_when_false)

Arguments

  • condition - the condition which should be checked

  • result_when_true - the result which will be returned when the condition is true or another value that does not convert to false.

  • result_when_false - the result which will be returned when the condition is false or another value that converts to false like 0 or ‘’. NULL will also be converted to false.

Examples

  • if( 1+1=2, 'Yes', 'No' ) → ‘Yes’

  • if( 1+1=3, 'Yes', 'No' ) → ‘No’

  • if( 5 > 3, 1, 0) → 1

  • if( '', 'It is true (not empty)', 'It is false (empty)' ) → ‘It is false (empty)’

  • if( ' ', 'It is true (not empty)', 'It is false (empty)' ) → ‘It is true (not empty)’

  • if( 0, 'One', 'Zero' ) → ‘Zero’

  • if( 10, 'One', 'Zero' ) → ‘One’

14.3.4.4. nullif

Returns a NULL value if value1 equals value2; otherwise it returns value1. This can be used to conditionally substitute values with NULL.

Syntax

nullif(value1, value2)

Arguments

  • value1 - The value that should either be used or substituted with NULL.

  • value2 - The control value that will trigger the NULL substitution.

Examples

  • nullif('(none)', '(none)') → NULL

  • nullif('text', '(none)') → ‘text’

  • nullif("name", '') → NULL, if name is an empty string (or already NULL), the name in any other case.

14.3.4.5. regexp_match

Return the first matching position matching a regular expression within an unicode string, or 0 if the substring is not found.

Syntax

regexp_match(input_string, regex)

Arguments

  • input_string - the string to test against the regular expression

  • regex - The regular expression to test against. Backslash characters must be double escaped (e.g., “\\s” to match a white space character or “\\b” to match a word boundary).

Examples

  • regexp_match('QGIS ROCKS','\\sROCKS') → 5

  • regexp_match('Budač','udač\\b') → 2

14.3.4.6. try

Tries an expression and returns its value if error-free. If the expression returns an error, an alternative value will be returned when provided otherwise the function will return NULL.

Syntax

try(expression, [alternative])

[] marks optional arguments

Arguments

  • expression - the expression which should be run

  • alternative - the result which will be returned if the expression returns an error.

Examples

  • try( to_int( '1' ), 0 ) → 1

  • try( to_int( 'a' ), 0 ) → 0

  • try( to_date( 'invalid_date' ) ) → NULL

14.3.5. Conversions Functions

This group contains functions to convert one data type to another (e.g., string from/to integer, binary from/to string, string to date, …).

14.3.5.1. from_base64

Decodes a string in the Base64 encoding into a binary value.

Syntax

from_base64(string)

Arguments

  • string - the string to decode

Examples

  • from_base64('UUdJUw==') → ‘QGIS’

14.3.5.2. hash

Creates a hash from a string with a given method. One byte (8 bits) is represented with two hex ‘’digits’’, so ‘md4’ (16 bytes) produces a 16 * 2 = 32 character long hex string and ‘keccak_512’ (64 bytes) produces a 64 * 2 = 128 character long hex string.

Syntax

hash(string, method)

Arguments

  • string - the string to hash

  • method - The hash method among ‘md4’, ‘md5’, ‘sha1’, ‘sha224’, ‘sha384’, ‘sha512’, ‘sha3_224’, ‘sha3_256’, ‘sha3_384’, ‘sha3_512’, ‘keccak_224’, ‘keccak_256’, ‘keccak_384’, ‘keccak_512’

Examples

  • hash('QGIS', 'md4') → ‘c0fc71c241cdebb6e888cbac0e2b68eb’

  • hash('QGIS', 'md5') → ‘57470aaa9e22adaefac7f5f342f1c6da’

  • hash('QGIS', 'sha1') → ‘f87cfb2b74cdd5867db913237024e7001e62b114’

  • hash('QGIS', 'sha224') → ‘4093a619ada631c770f44bc643ead18fb393b93d6a6af1861fcfece0’

  • hash('QGIS', 'sha256') → ‘eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309’

  • hash('QGIS', 'sha384') → ‘91c1de038cc3d09fdd512e99f9dd9922efadc39ed21d3922e69a4305cc25506033aee388e554b78714c8734f9cd7e610’

  • hash('QGIS', 'sha512') → ‘c2c092f2ab743bf8edbeb6d028a745f30fc720408465ed369421f0a4e20fa5e27f0c90ad72d3f1d836eaa5d25cd39897d4cf77e19984668ef58da6e3159f18ac’

  • hash('QGIS', 'sha3_224') → ‘467f49a5039e7280d5d42fd433e80d203439e338eaabd701f0d6c17d’

  • hash('QGIS', 'sha3_256') → ‘540f7354b6b8a6e735f2845250f15f4f3ba4f666c55574d9e9354575de0e980f’

  • hash('QGIS', 'sha3_384') → ‘96052da1e77679e9a65f60d7ead961b287977823144786386eb43647b0901fd8516fa6f1b9d243fb3f28775e6dde6107’

  • hash('QGIS', 'sha3_512') → ‘900d079dc69761da113980253aa8ac0414a8bd6d09879a916228f8743707c4758051c98445d6b8945ec854ff90655005e02aceb0a2ffc6a0ebf818745d665349’

  • hash('QGIS', 'keccak_224') → ‘5b0ce6acef8b0a121d4ac4f3eaa8503c799ad4e26a3392d1fb201478’

  • hash('QGIS', 'keccak_256') → ‘991c520aa6815392de24087f61b2ae0fd56abbfeee4a8ca019c1011d327c577e’

  • hash('QGIS', 'keccak_384') → ‘c57a3aed9d856fa04e5eeee9b62b6e027cca81ba574116d3cc1f0d48a1ef9e5886ff463ea8d0fac772ee473bf92f810d’

14.3.5.3. md5

Creates a md5 hash from a string.

Syntax

md5(string)

Arguments

  • string - the string to hash

Examples

  • md5('QGIS') → ‘57470aaa9e22adaefac7f5f342f1c6da’

14.3.5.4. sha256

Creates a sha256 hash from a string.

Syntax

sha256(string)

Arguments

  • string - the string to hash

Examples

  • sha256('QGIS') → ‘eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309’

14.3.5.5. to_base64

Encodes a binary value into a string, using the Base64 encoding.

Syntax

to_base64(value)

Arguments

  • value - the binary value to encode

Examples

  • to_base64('QGIS') → ‘UUdJUw==’

14.3.5.6. to_date

Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.

Syntax

to_date(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a date value

  • format - format used to convert the string into a date

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a date

Examples

  • to_date('2012-05-04') → 2012-05-04

  • to_date('June 29, 2019','MMMM d, yyyy') → 2019-06-29

  • to_date('29 juin, 2019','d MMMM, yyyy','fr') → 2019-06-29

14.3.5.7. to_datetime

Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDate::fromString and QTime::fromString for additional documentation on the format.

Syntax

to_datetime(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a datetime value

  • format - format used to convert the string into a datetime

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a datetime

Examples

  • to_datetime('2012-05-04 12:50:00') → 2012-05-04T12:50:00

  • to_datetime('June 29, 2019 @ 12:34','MMMM d, yyyy @ HH:mm') → 2019-06-29T12:34

  • to_datetime('29 juin, 2019 @ 12:34','d MMMM, yyyy @ HH:mm','fr') → 2019-06-29T12:34

14.3.5.8. to_decimal

Converts a degree, minute, second coordinate to its decimal equivalent.

Syntax

to_decimal(value)

Arguments

  • value - A degree, minute, second string.

Examples

  • to_decimal('6°21\'16.445') → 6.3545680555

14.3.5.9. to_dm

Converts a coordinate to degree, minute.

Syntax

to_dm(coordinate, axis, precision, [formatting=])

[] marks optional arguments

Arguments

  • coordinate - A latitude or longitude value.

  • axis - The axis of the coordinate. Either ‘x’ or ‘y’.

  • precision - Number of decimals.

  • formatting - Designates the formatting type. Acceptable values are NULL (default), ‘aligned’ or ‘suffix’.

Examples

  • to_dm(6.1545681, 'x', 3) → 6°9.274′

  • to_dm(6.1545681, 'y', 4, 'aligned') → 6°09.2741′N

  • to_dm(6.1545681, 'y', 4, 'suffix') → 6°9.2741′N

14.3.5.10. to_dms

Converts a coordinate to degree, minute, second.

Syntax

to_dms(coordinate, axis, precision, [formatting=])

[] marks optional arguments

Arguments

  • coordinate - A latitude or longitude value.

  • axis - The axis of the coordinate. Either ‘x’ or ‘y’.

  • precision - Number of decimals.

  • formatting - Designates the formatting type. Acceptable values are NULL (default), ‘aligned’ or ‘suffix’.

Examples

  • to_dms(6.1545681, 'x', 3) → 6°9′16.445″

  • to_dms(6.1545681, 'y', 4, 'aligned') → 6°09′16.4452″N

  • to_dms(6.1545681, 'y', 4, 'suffix') → 6°9′16.4452″N

14.3.5.11. to_int

Converts a string to integer number. Nothing is returned if a value cannot be converted to integer (e.g ‘123asd’ is invalid).

Syntax

to_int(string)

Arguments

  • string - string to convert to integer number

Examples

  • to_int('123') → 123

14.3.5.12. to_interval

Converts a string to an interval type. Can be used to take days, hours, month, etc of a date.

Syntax

to_interval(string)

Arguments

  • string - a string representing an interval. Allowable formats include {n} days {n} hours {n} months.

Examples

  • to_interval('1 day 2 hours') → interval: 1.08333 days

  • to_interval( '0.5 hours' ) → interval: 30 minutes

  • to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours') → 2012-05-04T10:00:00

14.3.5.13. to_real

Converts a string to a real number. Nothing is returned if a value cannot be converted to real (e.g ‘123.56asd’ is invalid). Numbers are rounded after saving changes if the precision is smaller than the result of the conversion.

Syntax

to_real(string)

Arguments

  • string - string to convert to real number

Examples

  • to_real('123.45') → 123.45

14.3.5.14. to_string

Converts a number to string.

Syntax

to_string(number)

Arguments

  • number - Integer or real value. The number to convert to string.

Examples

  • to_string(123) → ‘123’

14.3.5.15. to_time

Converts a string into a time object. An optional format string can be provided to parse the string; see QTime::fromString for additional documentation on the format.

Syntax

to_time(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a time value

  • format - format used to convert the string into a time

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a time

Examples

  • to_time('12:30:01') → 12:30:01

  • to_time('12:34','HH:mm') → 12:34:00

  • to_time('12:34','HH:mm','fr') → 12:34:00

14.3.6. Custom Functions

This group contains functions created by the user. See Function Editor for more details.

14.3.7. Date and Time Functions

This group contains functions for handling date and time data. This group shares several functions with the Conversions Functions (to_date, to_time, to_datetime, to_interval) and String Functions (format_date) groups.

Note

Storing date, datetime and intervals on fields

The ability to store date, time and datetime values directly on fields depends on the data source’s provider (e.g., Shapefile accepts date format, but not datetime or time format). The following are some suggestions to overcome this limitation:

  • date, datetime and time can be converted and stored in text type fields using the format_date() function.

  • Intervals can be stored in integer or decimal type fields after using one of the date extraction functions (e.g., day() to get the interval expressed in days)

14.3.7.1. age

Returns the difference between two dates or datetimes.

The difference is returned as an Interval and needs to be used with one of the following functions in order to extract useful information:

  • year

  • month

  • week

  • day

  • hour

  • minute

  • second

Syntax

age(datetime1, datetime2)

Arguments

  • datetime1 - a string, date or datetime representing the later date

  • datetime2 - a string, date or datetime representing the earlier date

Examples

  • day(age('2012-05-12','2012-05-02')) → 10

  • hour(age('2012-05-12','2012-05-02')) → 240

14.3.7.2. datetime_from_epoch

Returns a datetime whose date and time are the number of milliseconds, msecs, that have passed since 1970-01-01T00:00:00.000, Coordinated Universal Time (Qt.UTC), and converted to Qt.LocalTime.

Syntax

datetime_from_epoch(int)

Arguments

  • int - number (milliseconds)

Examples

  • datetime_from_epoch(1483225200000) → 2017-01-01T00:00:00

14.3.7.3. day

Extracts the day from a date, or the number of days from an interval.

Date variant

Extracts the day from a date or datetime.

Syntax

day(date)

Arguments

  • date - a date or datetime value

Examples

  • day('2012-05-12') → 12

Interval variant

Calculates the length in days of an interval.

Syntax

day(interval)

Arguments

  • interval - interval value to return number of days from

Examples

  • day(to_interval('3 days')) → 3

  • day(to_interval('3 weeks 2 days')) → 23

  • day(age('2012-01-01','2010-01-01')) → 730

14.3.7.4. day_of_week

Returns the day of the week for a specified date or datetime. The returned value ranges from 0 to 6, where 0 corresponds to a Sunday and 6 to a Saturday.

Syntax

day_of_week(date)

Arguments

  • date - date or datetime value

Examples

  • day_of_week(to_date('2015-09-21')) → 1

14.3.7.5. epoch

Returns the interval in milliseconds between the unix epoch and a given date value.

Syntax

epoch(date)

Arguments

  • date - a date or datetime value

Examples

  • epoch(to_date('2017-01-01')) → 1483203600000

14.3.7.6. format_date

Formats a date type or string into a custom string format. Uses Qt date/time format strings. See QDateTime::toString.

Syntax

format_date(datetime, format, [language])

[] marks optional arguments

Arguments

  • datetime - date, time or datetime value

  • format - String template used to format the string.

    Expression

    Output

    d

    the day as number without a leading zero (1 to 31)

    dd

    the day as number with a leading zero (01 to 31)

    ddd

    the abbreviated localized day name (e.g. ‘Mon’ to ‘Sun’)

    dddd

    the long localized day name (e.g. ‘Monday’ to ‘Sunday’)

    M

    the month as number without a leading zero (1-12)

    MM

    the month as number with a leading zero (01-12)

    MMM

    the abbreviated localized month name (e.g. ‘Jan’ to ‘Dec’)

    MMMM

    the long localized month name (e.g. ‘January’ to ‘December’)

    yy

    the year as two digit number (00-99)

    yyyy

    the year as four digit number

    These expressions may be used for the time part of the format string:

    Expression

    Output

    h

    the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)

    hh

    the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)

    H

    the hour without a leading zero (0 to 23, even with AM/PM display)

    HH

    the hour with a leading zero (00 to 23, even with AM/PM display)

    m

    the minute without a leading zero (0 to 59)

    mm

    the minute with a leading zero (00 to 59)

    s

    the second without a leading zero (0 to 59)

    ss

    the second with a leading zero (00 to 59)

    z

    the milliseconds without trailing zeroes (0 to 999)

    zzz

    the milliseconds with trailing zeroes (000 to 999)

    AP or A

    interpret as an AM/PM time. AP must be either ‘AM’ or ‘PM’.

    ap or a

    Interpret as an AM/PM time. ap must be either ‘am’ or ‘pm’.

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to format the date into a custom string

Examples

  • format_date('2012-05-15','dd.MM.yyyy') → ‘15.05.2012’

  • format_date('2012-05-15','d MMMM yyyy','fr') → ‘15 mai 2012’

  • format_date('2012-05-15','dddd') → ‘Tuesday’

  • format_date('2012-05-15 13:54:20','dd.MM.yy') → ‘15.05.12’

  • format_date('13:54:20','hh:mm AP') → ‘01:54 PM’

14.3.7.7. hour

Extracts the hour part from a datetime or time, or the number of hours from an interval.

Time variant

Extracts the hour part from a time or datetime.

Syntax

hour(datetime)

Arguments

  • datetime - a time or datetime value

Examples

  • hour( to_datetime('2012-07-22 13:24:57') ) → 13

Interval variant

Calculates the length in hours of an interval.

Syntax

hour(interval)

Arguments

  • interval - interval value to return number of hours from

Examples

  • hour(to_interval('3 hours')) → 3

  • hour(age('2012-07-22T13:00:00','2012-07-22T10:00:00')) → 3

  • hour(age('2012-01-01','2010-01-01')) → 17520

14.3.7.8. make_date

Creates a date value from year, month and day numbers.

Syntax

make_date(year, month, day)

Arguments

  • year - Year number. Years 1 to 99 are interpreted as is. Year 0 is invalid.

  • month - Month number, where 1=January

  • day - Day number, beginning with 1 for the first day in the month

Examples

  • make_date(2020,5,4) → date value 2020-05-04

14.3.7.9. make_datetime

Creates a datetime value from year, month, day, hour, minute and second numbers.

Syntax

make_datetime(year, month, day, hour, minute, second)

Arguments

  • year - Year number. Years 1 to 99 are interpreted as is. Year 0 is invalid.

  • month - Month number, where 1=January

  • day - Day number, beginning with 1 for the first day in the month

  • hour - Hour number

  • minute - Minutes

  • second - Seconds (fractional values include milliseconds)

Examples

  • make_datetime(2020,5,4,13,45,30.5) → datetime value 2020-05-04 13:45:30.500

14.3.7.10. make_interval

Creates an interval value from year, month, weeks, days, hours, minute and seconds values.

Syntax

make_interval([years=0], [months=0], [weeks=0], [days=0], [hours=0], [minutes=0], [seconds=0])

[] marks optional arguments

Arguments

  • years - Number of years (assumes a 365.25 day year length).

  • months - Number of months (assumes a 30 day month length)

  • weeks - Number of weeks

  • days - Number of days

  • hours - Number of hours

  • minutes - Number of minutes

  • seconds - Number of seconds

Examples

  • make_interval(hours:=3) → interval: 3 hours

  • make_interval(days:=2, hours:=3) → interval: 2.125 days

  • make_interval(minutes:=0.5, seconds:=5) → interval: 35 seconds

14.3.7.11. make_time

Creates a time value from hour, minute and second numbers.

Syntax

make_time(hour, minute, second)

Arguments

  • hour - Hour number

  • minute - Minutes

  • second - Seconds (fractional values include milliseconds)

Examples

  • make_time(13,45,30.5) → time value 13:45:30.500

14.3.7.12. minute

Extracts the minutes part from a datetime or time, or the number of minutes from an interval.

Time variant

Extracts the minutes part from a time or datetime.

Syntax

minute(datetime)

Arguments

  • datetime - a time or datetime value

Examples

  • minute( to_datetime('2012-07-22 13:24:57') ) → 24

Interval variant

Calculates the length in minutes of an interval.

Syntax

minute(interval)

Arguments

  • interval - interval value to return number of minutes from

Examples

  • minute(to_interval('3 minutes')) → 3

  • minute(age('2012-07-22T00:20:00','2012-07-22T00:00:00')) → 20

  • minute(age('2012-01-01','2010-01-01')) → 1051200

14.3.7.13. month

Extracts the month part from a date, or the number of months from an interval.

Date variant

Extracts the month part from a date or datetime.

Syntax

month(date)

Arguments

  • date - a date or datetime value

Examples

  • month('2012-05-12') → 05

Interval variant

Calculates the length in months of an interval.

Syntax

month(interval)

Arguments

  • interval - interval value to return number of months from

Examples

  • month(to_interval('3 months')) → 3

  • month(age('2012-01-01','2010-01-01')) → 4.03333

14.3.7.14. now

Returns the current date and time. The function is static and will return consistent results while evaluating. The time returned is the time when the expression is prepared.

Syntax

now()

Examples

  • now() → 2012-07-22T13:24:57

14.3.7.15. second

Extracts the seconds part from a datetime or time, or the number of seconds from an interval.

Time variant

Extracts the seconds part from a time or datetime.

Syntax

second(datetime)

Arguments

  • datetime - a time or datetime value

Examples

  • second( to_datetime('2012-07-22 13:24:57') ) → 57

Interval variant

Calculates the length in seconds of an interval.

Syntax

second(interval)

Arguments

  • interval - interval value to return number of seconds from

Examples

  • second(to_interval('3 minutes')) → 180

  • second(age('2012-07-22T00:20:00','2012-07-22T00:00:00')) → 1200

  • second(age('2012-01-01','2010-01-01')) → 63072000

14.3.7.16. to_date

Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.

Syntax

to_date(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a date value

  • format - format used to convert the string into a date

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a date

Examples

  • to_date('2012-05-04') → 2012-05-04

  • to_date('June 29, 2019','MMMM d, yyyy') → 2019-06-29

  • to_date('29 juin, 2019','d MMMM, yyyy','fr') → 2019-06-29

14.3.7.17. to_datetime

Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDate::fromString and QTime::fromString for additional documentation on the format.

Syntax

to_datetime(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a datetime value

  • format - format used to convert the string into a datetime

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a datetime

Examples

  • to_datetime('2012-05-04 12:50:00') → 2012-05-04T12:50:00

  • to_datetime('June 29, 2019 @ 12:34','MMMM d, yyyy @ HH:mm') → 2019-06-29T12:34

  • to_datetime('29 juin, 2019 @ 12:34','d MMMM, yyyy @ HH:mm','fr') → 2019-06-29T12:34

14.3.7.18. to_interval

Converts a string to an interval type. Can be used to take days, hours, month, etc of a date.

Syntax

to_interval(string)

Arguments

  • string - a string representing an interval. Allowable formats include {n} days {n} hours {n} months.

Examples

  • to_interval('1 day 2 hours') → interval: 1.08333 days

  • to_interval( '0.5 hours' ) → interval: 30 minutes

  • to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours') → 2012-05-04T10:00:00

14.3.7.19. to_time

Converts a string into a time object. An optional format string can be provided to parse the string; see QTime::fromString for additional documentation on the format.

Syntax

to_time(string, [format], [language])

[] marks optional arguments

Arguments

  • string - string representing a time value

  • format - format used to convert the string into a time

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a time

Examples

  • to_time('12:30:01') → 12:30:01

  • to_time('12:34','HH:mm') → 12:34:00

  • to_time('12:34','HH:mm','fr') → 12:34:00

14.3.7.20. week

Extracts the week number from a date, or the number of weeks from an interval.

Date variant

Extracts the week number from a date or datetime.

Syntax

week(date)

Arguments

  • date - a date or datetime value

Examples

  • week('2012-05-12') → 19

Interval variant

Calculates the length in weeks of an interval.

Syntax

week(interval)

Arguments

  • interval - interval value to return number of months from

Examples

  • week(to_interval('3 weeks')) → 3

  • week(age('2012-01-01','2010-01-01')) → 104.285

14.3.7.21. year

Extracts the year part from a date, or the number of years from an interval.

Date variant

Extracts the year part from a date or datetime.

Syntax

year(date)

Arguments

  • date - a date or datetime value

Examples

  • year('2012-05-12') → 2012

Interval variant

Calculates the length in years of an interval.

Syntax

year(interval)

Arguments

  • interval - interval value to return number of years from

Examples

  • year(to_interval('3 years')) → 3

  • year(age('2012-01-01','2010-01-01')) → 1.9986

Some examples:

Besides these functions, subtracting dates, datetimes or times using the - (minus) operator will return an interval.

Adding or subtracting an interval to dates, datetimes or times, using the + (plus) and - (minus) operators, will return a datetime.

  • Get the number of days until QGIS 3.0 release:

    to_date('2017-09-29') - to_date(now())
    -- Returns <interval: 203 days>
    
  • The same with time:

    to_datetime('2017-09-29 12:00:00') - now()
    -- Returns <interval: 202.49 days>
    
  • Get the datetime of 100 days from now:

    now() + to_interval('100 days')
    -- Returns <datetime: 2017-06-18 01:00:00>
    

14.3.8. Fields and Values

Contains a list of fields from the layer.

Double-click a field name to have it added to your expression. You can also type the field name (preferably inside double quotes) or its alias.

To retrieve fields values to use in an expression, select the appropriate field and, in the shown widget, choose between 10 Samples and All Unique. Requested values are then displayed and you can use the Search box at the top of the list to filter the result. Sample values can also be accessed via right-clicking on a field.

To add a value to the expression you are writing, double-click on it in the list. If the value is of a string type, it should be simple quoted, otherwise no quote is needed.

14.3.9. Files and Paths Functions

This group contains functions which manipulate file and path names.

14.3.9.1. base_file_name

Returns the base name of the file without the directory or file suffix.

Syntax

base_file_name(path)

Arguments

  • path - a file path

Examples

  • base_file_name('/home/qgis/data/country_boundaries.shp') → ‘country_boundaries’

14.3.9.2. file_exists

Returns true if a file path exists.

Syntax

file_exists(path)

Arguments

  • path - a file path

Examples

  • file_exists('/home/qgis/data/country_boundaries.shp') → true

14.3.9.3. file_name

Returns the name of a file (including the file extension), excluding the directory.

Syntax

file_name(path)

Arguments

  • path - a file path

Examples

  • file_name('/home/qgis/data/country_boundaries.shp') → ‘country_boundaries.shp’

14.3.9.4. file_path

Returns the directory component of a file path. This does not include the file name.

Syntax

file_path(path)

Arguments

  • path - a file path

Examples

  • file_path('/home/qgis/data/country_boundaries.shp') → ‘/home/qgis/data’

14.3.9.5. file_size

Returns the size (in bytes) of a file.

Syntax

file_size(path)

Arguments

  • path - a file path

Examples

  • file_size('/home/qgis/data/country_boundaries.geojson') → 5674

14.3.9.6. file_suffix

Returns the file suffix (extension) from a file path.

Syntax

file_suffix(path)

Arguments

  • path - a file path

Examples

  • file_suffix('/home/qgis/data/country_boundaries.shp') → ‘shp’

14.3.9.7. is_directory

Returns true if a path corresponds to a directory.

Syntax

is_directory(path)

Arguments

  • path - a file path

Examples

  • is_directory('/home/qgis/data/country_boundaries.shp') → false

  • is_directory('/home/qgis/data/') → true

14.3.9.8. is_file

Returns true if a path corresponds to a file.

Syntax

is_file(path)

Arguments

  • path - a file path

Examples

  • is_file('/home/qgis/data/country_boundaries.shp') → true

  • is_file('/home/qgis/data/') → false

14.3.10. Form Functions

This group contains functions that operate exclusively under the attribute form context. For example, in field’s widgets settings.

14.3.10.1. current_parent_value

Only usable in an embedded form context, this function returns the current, unsaved value of a field in the parent form currently being edited. This will differ from the parent feature’s actual attribute values for features which are currently being edited or have not yet been added to a parent layer. When used in a value-relation widget filter expression, this function should be wrapped into a ‘coalesce()’ that can retrieve the actual parent feature from the layer when the form is not used in an embedded context.

Syntax

current_parent_value(field_name)

Arguments

  • field_name - a field name in the current parent form

Examples

  • current_parent_value( 'FIELD_NAME' ) → The current value of a field ‘FIELD_NAME’ in the parent form.

14.3.10.2. current_value

Returns the current, unsaved value of a field in the form or table row currently being edited. This will differ from the feature’s actual attribute values for features which are currently being edited or have not yet been added to a layer.

Syntax

current_value(field_name)

Arguments

  • field_name - a field name in the current form or table row

Examples

  • current_value( 'FIELD_NAME' ) → The current value of field ‘FIELD_NAME’.

14.3.11. Fuzzy Matching Functions

This group contains functions for fuzzy comparisons between values.

14.3.11.1. hamming_distance

Returns the Hamming distance between two strings. This equates to the number of characters at corresponding positions within the input strings where the characters are different. The input strings must be the same length, and the comparison is case-sensitive.

Syntax

hamming_distance(string1, string2)

Arguments

  • string1 - a string

  • string2 - a string

Examples

  • hamming_distance('abc','xec') → 2

  • hamming_distance('abc','ABc') → 2

  • hamming_distance(upper('abc'),upper('ABC')) → 0

14.3.11.2. levenshtein

Returns the Levenshtein edit distance between two strings. This equates to the minimum number of character edits (insertions, deletions or substitutions) required to change one string to another.

The Levenshtein distance is a measure of the similarity between two strings. Smaller distances mean the strings are more similar, and larger distances indicate more different strings. The distance is case sensitive.

Syntax

levenshtein(string1, string2)

Arguments

  • string1 - a string

  • string2 - a string

Examples

  • levenshtein('kittens','mitten') → 2

  • levenshtein('Kitten','kitten') → 1

  • levenshtein(upper('Kitten'),upper('kitten')) → 0

14.3.11.3. longest_common_substring

Returns the longest common substring between two strings. This substring is the longest string that is a substring of the two input strings. For example, the longest common substring of “ABABC” and “BABCA” is “BABC”. The substring is case sensitive.

Syntax

longest_common_substring(string1, string2)

Arguments

  • string1 - a string

  • string2 - a string

Examples

  • longest_common_substring('ABABC','BABCA') → ‘BABC’

  • longest_common_substring('abcDeF','abcdef') → ‘abc’

  • longest_common_substring(upper('abcDeF'),upper('abcdex')) → ‘ABCDE’

14.3.11.4. soundex

Returns the Soundex representation of a string. Soundex is a phonetic matching algorithm, so strings with similar sounds should be represented by the same Soundex code.

Syntax

soundex(string)

Arguments

  • string - a string

Examples

  • soundex('robert') → ‘R163’

  • soundex('rupert') → ‘R163’

  • soundex('rubin') → ‘R150’

14.3.12. General Functions

This group contains general assorted functions.

14.3.12.1. env

Gets an environment variable and returns its content as a string. If the variable is not found, NULL will be returned. This is handy to inject system specific configuration like drive letters or path prefixes. Definition of environment variables depends on the operating system, please check with your system administrator or the operating system documentation how this can be set.

Syntax

env(name)

Arguments

  • name - The name of the environment variable which should be retrieved.

Examples

  • env( 'LANG' ) → ‘en_US.UTF-8’

  • env( 'MY_OWN_PREFIX_VAR' ) → ‘Z:’

  • env( 'I_DO_NOT_EXIST' ) → NULL

14.3.12.2. eval

Evaluates an expression which is passed in a string. Useful to expand dynamic parameters passed as context variables or fields.

Syntax

eval(expression)

Arguments

  • expression - an expression string

Examples

  • eval('\'nice\'') → ‘nice’

  • eval(@expression_var) → [whatever the result of evaluating @expression_var might be…]

14.3.12.3. eval_template

Evaluates a template which is passed in a string. Useful to expand dynamic parameters passed as context variables or fields.

Syntax

eval_template(template)

Arguments

  • template - a template string

Examples

  • eval_template('QGIS [% upper(\'rocks\') %]') → QGIS ROCKS

14.3.12.4. is_layer_visible

Returns true if a specified layer is visible.

Syntax

is_layer_visible(layer)

Arguments

  • layer - a string, representing either a layer name or layer ID

Examples

  • is_layer_visible('baseraster') → True

14.3.12.5. layer_property

Returns a matching layer property or metadata value.

Syntax

layer_property(layer, property)

Arguments

  • layer - a string, representing either a layer name or layer ID

  • property - a string corresponding to the property to return. Valid options are:

    • name: layer name

    • id: layer ID

    • title: metadata title string

    • abstract: metadata abstract string

    • keywords: metadata keywords

    • data_url: metadata URL

    • attribution: metadata attribution string

    • attribution_url: metadata attribution URL

    • source: layer source

    • min_scale: minimum display scale for layer

    • max_scale: maximum display scale for layer

    • is_editable: if layer is in edit mode

    • crs: layer CRS

    • crs_definition: layer CRS full definition

    • crs_description: layer CRS description

    • extent: layer extent (as a geometry object)

    • distance_units: layer distance units

    • type: layer type, e.g., Vector or Raster

    • storage_type: storage format (vector layers only)

    • geometry_type: geometry type, e.g., Point (vector layers only)

    • feature_count: approximate feature count for layer (vector layers only)

    • path: File path to the layer data source. Only available for file based layers.

Examples

  • layer_property('streets','title') → ‘Basemap Streets’

  • layer_property('airports','feature_count') → 120

  • layer_property('landsat','crs') → ‘EPSG:4326’

Further reading: vector, raster and mesh layer properties

14.3.12.6. var

Returns the value stored within a specified variable.

Syntax

var(name)

Arguments

  • name - a variable name

Examples

  • var('qgis_version') → ‘2.12’

Further reading: List of default variables

14.3.12.7. with_variable

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.

Syntax

with_variable(name, value, expression)

Arguments

  • name - the name of the variable to set

  • value - the value to set

  • expression - the expression for which the variable will be available

Examples

  • with_variable('my_sum', 1 + 2 + 3, @my_sum * 2 + @my_sum * 5) → 42

14.3.13. Geometry Functions

This group contains functions that operate on geometry objects (e.g. buffer, transform, $area).

14.3.13.1. angle_at_vertex

Returns the bisector angle (average angle) to the geometry for a specified vertex on a linestring geometry. Angles are in degrees clockwise from north.

Syntax

angle_at_vertex(geometry, vertex)

Arguments

  • geometry - a linestring geometry

  • vertex - vertex index, starting from 0; if the value is negative, the selected vertex index will be its total count minus the absolute value

Examples

  • angle_at_vertex(geometry:=geom_from_wkt('LineString(0 0, 10 0, 10 10)'),vertex:=1) → 45.0

14.3.13.2. $area

Returns the area of the current feature. The area calculated by this function respects both the current project’s ellipsoid setting and area unit settings. For example, if an ellipsoid has been set for the project then the calculated area will be ellipsoidal, and if no ellipsoid is set then the calculated area will be planimetric.

Syntax

$area

Examples

  • $area → 42

14.3.13.3. area

Returns the area of a geometry polygon object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned area will match the units for the SRS. This differs from the calculations performed by the $area function, which will perform ellipsoidal calculations based on the project’s ellipsoid and area unit settings.

Syntax

area(geometry)

Arguments

  • geometry - polygon geometry object

Examples

  • area(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))')) → 8.0

14.3.13.4. azimuth

Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.

Syntax

azimuth(point_a, point_b)

Arguments

  • point_a - point geometry

  • point_b - point geometry

Examples

  • degrees( azimuth( make_point(25, 45), make_point(75, 100) ) ) → 42.273689

  • degrees( azimuth( make_point(75, 100), make_point(25,45) ) ) → 222.273689

14.3.13.5. boundary

Returns the closure of the combinatorial boundary of the geometry (ie the topological boundary of the geometry). For instance, a polygon geometry will have a boundary consisting of the linestrings for each ring in the polygon. Some geometry types do not have a defined boundary, e.g., points or geometry collections, and will return NULL.

Syntax

boundary(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt(boundary(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))'))) → ‘LineString(1 1,0 0,-1 1,1 1)’

  • geom_to_wkt(boundary(geom_from_wkt('LineString(1 1,0 0,-1 1)'))) → ‘MultiPoint ((1 1),(-1 1))’

Further reading: Boundary algorithm

14.3.13.6. bounds

Returns a geometry which represents the bounding box of an input geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax

bounds(geometry)

Arguments

  • geometry - a geometry

Examples

  • bounds($geometry) → bounding box of the current feature’s geometry

  • geom_to_wkt(bounds(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))'))) → ‘Polygon ((-1 0, 1 0, 1 1, -1 1, -1 0))’

Further reading: Bounding boxes algorithm

14.3.13.7. bounds_height

Returns the height of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax

bounds_height(geometry)

Arguments

  • geometry - a geometry

Examples

  • bounds_height($geometry) → height of bounding box of the current feature’s geometry

  • bounds_height(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))')) → 1

14.3.13.8. bounds_width

Returns the width of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax

bounds_width(geometry)

Arguments

  • geometry - a geometry

Examples

  • bounds_width($geometry) → width of bounding box of the current feature’s geometry

  • bounds_width(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))')) → 2

14.3.13.9. buffer

Returns a geometry that represents all points whose distance from this geometry is less than or equal to distance. Calculations are in the Spatial Reference System of this geometry.

Syntax

buffer(geometry, distance, [segments=8])

[] marks optional arguments

Arguments

  • geometry - a geometry

  • distance - buffer distance in layer units

  • segments - number of segments to use to represent a quarter circle when a round join style is used. A larger number results in a smoother buffer with more nodes.

Examples

  • buffer($geometry, 10.5) → polygon of the current feature’s geometry buffered by 10.5 units

Further reading: Buffer algorithm

14.3.13.10. buffer_by_m

Creates a buffer along a line geometry where the buffer diameter varies according to the m-values at the line vertices.

Syntax

buffer_by_m(geometry, [segments=8])

[] marks optional arguments

Arguments

  • geometry - input geometry. Must be a (multi)line geometry with m values.

  • segments - number of segments to approximate quarter-circle curves in the buffer.

Examples

  • buffer_by_m(geometry:=geom_from_wkt('LINESTRINGM(1 2 0.5, 4 2 0.2)'),segments:=8) → A variable width buffer starting with a diameter of 0.5 and ending with a diameter of 0.2 along the linestring geometry.

Further reading: Variable width buffer (by M value) algorithm

14.3.13.11. centroid

Returns the geometric center of a geometry.

Syntax

centroid(geometry)

Arguments

  • geometry - a geometry

Examples

  • centroid($geometry) → a point geometry

Further reading: Centroids algorithm

14.3.13.12. close_line

Returns a closed line string of the input line string by appending the first point to the end of the line, if it is not already closed. If the geometry is not a line string or multi line string then the result will be NULL.

Syntax

close_line(geometry)

Arguments

  • geometry - a line string geometry

Examples

  • geom_to_wkt(close_line(geom_from_wkt('LINESTRING(0 0, 1 0, 1 1)'))) → ‘LineString (0 0, 1 0, 1 1, 0 0)’

  • geom_to_wkt(close_line(geom_from_wkt('LINESTRING(0 0, 1 0, 1 1, 0 0)'))) → ‘LineString (0 0, 1 0, 1 1, 0 0)’

14.3.13.13. closest_point

Returns the point on geometry1 that is closest to geometry2.

Syntax

closest_point(geometry1, geometry2)

Arguments

  • geometry1 - geometry to find closest point on

  • geometry2 - geometry to find closest point to

Examples

  • geom_to_wkt(closest_point(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75 )'),geom_from_wkt('POINT(100 100)'))) → ‘Point(73.0769 115.384)’

14.3.13.14. collect_geometries

Collects a set of geometries into a multi-part geometry object.

List of arguments variant

Geometry parts are specified as separate arguments to the function.

Syntax

collect_geometries(geometry1, geometry2, …)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt(collect_geometries(make_point(1,2), make_point(3,4), make_point(5,6))) → ‘MultiPoint ((1 2),(3 4),(5 6))’

Array variant

Geometry parts are specified as an array of geometry parts.

Syntax

collect_geometries(array)

Arguments

  • array - array of geometry objects

Examples

  • geom_to_wkt(collect_geometries(array(make_point(1,2), make_point(3,4), make_point(5,6)))) → ‘MultiPoint ((1 2),(3 4),(5 6))’

Further reading: Collect geometries algorithm

14.3.13.15. combine

Returns the combination of two geometries.

Syntax

combine(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • geom_to_wkt( combine( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 2 1)' ) ) ) → ‘MULTILINESTRING((4 4, 2 1), (3 3, 4 4), (4 4, 5 5))’

  • geom_to_wkt( combine( geom_from_wkt( 'LINESTRING(3 3, 4 4)' ), geom_from_wkt( 'LINESTRING(3 3, 6 6, 2 1)' ) ) ) → ‘LINESTRING(3 3, 4 4, 6 6, 2 1)’

14.3.13.16. contains

Tests whether a geometry contains another. Returns true if and only if no points of geometry2 lie in the exterior of geometry1, and at least one point of the interior of geometry2 lies in the interior of geometry1.

Syntax

contains(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • contains( geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))' ), geom_from_wkt( 'POINT(0.5 0.5 )' ) ) → true

  • contains( geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → false

Further reading: overlay_contains

14.3.13.17. convex_hull

Returns the convex hull of a geometry. It represents the minimum convex geometry that encloses all geometries within the set.

Syntax

convex_hull(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt( convex_hull( geom_from_wkt( 'LINESTRING(3 3, 4 4, 4 10)' ) ) ) → ‘POLYGON((3 3, 4 10, 4 4, 3 3))’

Further reading: Convex hull algorithm

14.3.13.18. crosses

Tests whether a geometry crosses another. Returns true if the supplied geometries have some, but not all, interior points in common.

Syntax

crosses(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • crosses( geom_from_wkt( 'LINESTRING(3 5, 4 4, 5 3)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • crosses( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → false

Further reading: overlay_crosses

14.3.13.19. difference

Returns a geometry that represents that part of geometry1 that does not intersect with geometry2.

Syntax

difference(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • geom_to_wkt( difference( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4)' ) ) ) → ‘LINESTRING(4 4, 5 5)’

Further reading: Difference algorithm

14.3.13.20. disjoint

Tests whether geometries do not spatially intersect. Returns true if the geometries do not share any space together.

Syntax

disjoint(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • disjoint( geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0 ))' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • disjoint( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'POINT(4 4)' )) → false

Further reading: overlay_disjoint

14.3.13.21. distance

Returns the minimum distance (based on spatial ref) between two geometries in projected units.

Syntax

distance(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • distance( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(4 8)' ) ) → 4

14.3.13.22. distance_to_vertex

Returns the distance along the geometry to a specified vertex.

Syntax

distance_to_vertex(geometry, vertex)

Arguments

  • geometry - a linestring geometry

  • vertex - vertex index, starting from 0; if the value is negative, the selected vertex index will be its total count minus the absolute value

Examples

  • distance_to_vertex(geometry:=geom_from_wkt('LineString(0 0, 10 0, 10 10)'),vertex:=1) → 10.0

14.3.13.23. end_point

Returns the last node from a geometry.

Syntax

end_point(geometry)

Arguments

  • geometry - geometry object

Examples

  • geom_to_wkt(end_point(geom_from_wkt('LINESTRING(4 0, 4 2, 0 2)'))) → ‘Point (0 2)’

Further reading: Extract specific vertices algorithm

14.3.13.24. extend

Extends the start and end of a linestring geometry by a specified amount. Lines are extended using the bearing of the first and last segment in the line. For a multilinestring, all the parts are extended. Distances are in the Spatial Reference System of this geometry.

Syntax

extend(geometry, start_distance, end_distance)

Arguments

  • geometry - a (multi)linestring geometry

  • start_distance - distance to extend the start of the line

  • end_distance - distance to extend the end of the line.

Examples

  • geom_to_wkt(extend(geom_from_wkt('LineString(0 0, 1 0, 1 1)'),1,2)) → ‘LineString (-1 0, 1 0, 1 3)’

  • geom_to_wkt(extend(geom_from_wkt('MultiLineString((0 0, 1 0, 1 1), (2 2, 0 2, 0 5))'),1,2)) → ‘MultiLineString ((-1 0, 1 0, 1 3),(3 2, 0 2, 0 7))’

Further reading: Extend lines algorithm

14.3.13.25. exterior_ring

Returns a line string representing the exterior ring of a polygon geometry. If the geometry is not a polygon then the result will be NULL.

Syntax

exterior_ring(geometry)

Arguments

  • geometry - a polygon geometry

Examples

  • geom_to_wkt(exterior_ring(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),( 0.1 0.1, 0.1 0.2, 0.2 0.2, 0.2, 0.1, 0.1 0.1))'))) → ‘LineString (-1 -1, 4 0, 4 2, 0 2, -1 -1)’

14.3.13.26. extrude

Returns an extruded version of the input (Multi-)Curve or (Multi-)Linestring geometry with an extension specified by x and y.

Syntax

extrude(geometry, x, y)

Arguments

  • geometry - a polygon geometry

  • x - x extension, numeric value

  • y - y extension, numeric value

Examples

  • geom_to_wkt(extrude(geom_from_wkt('LineString(1 2, 3 2, 4 3)'), 1, 2)) → ‘Polygon ((1 2, 3 2, 4 3, 5 5, 4 4, 2 4, 1 2))’

  • geom_to_wkt(extrude(geom_from_wkt('MultiLineString((1 2, 3 2), (4 3, 8 3))'), 1, 2)) → ‘MultiPolygon (((1 2, 3 2, 4 4, 2 4, 1 2)),((4 3, 8 3, 9 5, 5 5, 4 3)))’

14.3.13.27. flip_coordinates

Returns a copy of the geometry with the x and y coordinates swapped. Useful for repairing geometries which have had their latitude and longitude values reversed.

Syntax

flip_coordinates(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt(flip_coordinates(make_point(1, 2))) → ‘Point (2 1)’

Further reading: Swap X and Y coordinates algorithm

14.3.13.28. force_rhr

Forces a geometry to respect the Right-Hand-Rule, in which the area that is bounded by a polygon is to the right of the boundary. In particular, the exterior ring is oriented in a clockwise direction and the interior rings in a counter-clockwise direction.

Syntax

force_rhr(geometry)

Arguments

  • geometry - a geometry. Any non-polygon geometries are returned unchanged.

Examples

  • geom_to_wkt(force_rhr(geometry:=geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1))'))) → ‘Polygon ((-1 -1, 0 2, 4 2, 4 0, -1 -1))’

Further reading: Force right-hand-rule algorithm

14.3.13.29. geom_from_gml

Returns a geometry from a GML representation of geometry.

Syntax

geom_from_gml(gml)

Arguments

  • gml - GML representation of a geometry as a string

Examples

  • geom_from_gml('<gml:LineString srsName="EPSG:4326"><gml:coordinates>4,4 5,5 6,6</gml:coordinates></gml:LineString>') → a line geometry object

14.3.13.30. geom_from_wkb

Returns a geometry created from a Well-Known Binary (WKB) representation.

Syntax

geom_from_wkb(binary)

Arguments

  • binary - Well-Known Binary (WKB) representation of a geometry (as a binary blob)

Examples

  • geom_from_wkb( geom_to_wkb( make_point(4,5) ) ) → a point geometry object

14.3.13.31. geom_from_wkt

Returns a geometry created from a Well-Known Text (WKT) representation.

Syntax

geom_from_wkt(text)

Arguments

  • text - Well-Known Text (WKT) representation of a geometry

Examples

  • geom_from_wkt( 'POINT(4 5)' ) → a geometry object

14.3.13.32. geom_to_wkb

Returns the Well-Known Binary (WKB) representation of a geometry

Syntax

geom_to_wkb(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkb( $geometry ) → binary blob containing a geometry object

14.3.13.33. geom_to_wkt

Returns the Well-Known Text (WKT) representation of the geometry without SRID metadata.

Syntax

geom_to_wkt(geometry, [precision=8])

[] marks optional arguments

Arguments

  • geometry - a geometry

  • precision - numeric precision

Examples

  • geom_to_wkt( make_point(6, 50) ) → ‘POINT(6 50)’

  • geom_to_wkt(centroid(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))'))) → ‘POINT(0 0.66666667)’

  • geom_to_wkt(centroid(geom_from_wkt('Polygon((1 1, 0 0, -1 1, 1 1))')), 2) → ‘POINT(0 0.67)’

14.3.13.34. $geometry

Returns the geometry of the current feature. Can be used for processing with other functions.

Syntax

$geometry

Examples

  • geom_to_wkt( $geometry ) → ‘POINT(6 50)’

14.3.13.35. geometry

Returns a feature’s geometry.

Syntax

geometry(feature)

Arguments

  • feature - a feature object

Examples

  • geom_to_wkt( geometry( get_feature( layer, attributeField, value ) ) ) → ‘POINT(6 50)’

  • intersects( $geometry, geometry( get_feature( layer, attributeField, value ) ) ) → true

14.3.13.36. geometry_n

Returns a specific geometry from a geometry collection, or NULL if the input geometry is not a collection.

Syntax

geometry_n(geometry, index)

Arguments

  • geometry - geometry collection

  • index - index of geometry to return, where 1 is the first geometry in the collection

Examples

  • geom_to_wkt(geometry_n(geom_from_wkt('GEOMETRYCOLLECTION(POINT(0 1), POINT(0 0), POINT(1 0), POINT(1 1))'),3)) → ‘Point (1 0)’

14.3.13.37. hausdorff_distance

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.

The function can be executed with an optional densify fraction argument. If not specified, an approximation to the standard Hausdorff distance is used. This approximation is exact or close enough for a large subset of useful cases. Examples of these are:

  • computing distance between Linestrings that are roughly parallel to each other, and roughly equal in length. This occurs in matching linear networks.

  • Testing similarity of geometries.

If the default approximate provided by this method is insufficient, specify the optional densify fraction argument. Specifying this argument performs a segment densification before computing the discrete Hausdorff distance. The parameter sets the fraction by which to densify each segment. Each segment will be split into a number of equal-length subsegments, whose fraction of the total length is closest to the given fraction. Decreasing the densify fraction parameter will make the distance returned approach the true Hausdorff distance for the geometries.

Syntax

hausdorff_distance(geometry1, geometry2, [densify_fraction])

[] marks optional arguments

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

  • densify_fraction - densify fraction amount

Examples

  • hausdorff_distance( geometry1:= geom_from_wkt('LINESTRING (0 0, 2 1)'),geometry2:=geom_from_wkt('LINESTRING (0 0, 2 0)')) → 2

  • hausdorff_distance( geom_from_wkt('LINESTRING (130 0, 0 0, 0 150)'),geom_from_wkt('LINESTRING (10 10, 10 150, 130 10)')) → 14.142135623

  • hausdorff_distance( geom_from_wkt('LINESTRING (130 0, 0 0, 0 150)'),geom_from_wkt('LINESTRING (10 10, 10 150, 130 10)'),0.5) → 70.0

14.3.13.38. inclination

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

Syntax

inclination(point_a, point_b)

Arguments

  • point_a - point geometry

  • point_b - point geometry

Examples

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, 5 ) ) → 0.0

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, 0 ) ) → 90.0

  • inclination( make_point( 5, 10, 0 ), make_point( 50, 100, 0 ) ) → 90.0

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, -5 ) ) → 180.0

14.3.13.39. interior_ring_n

Returns a specific interior ring from a polygon geometry, or NULL if the geometry is not a polygon.

Syntax

interior_ring_n(geometry, index)

Arguments

  • geometry - polygon geometry

  • index - index of interior to return, where 1 is the first interior ring

Examples

  • geom_to_wkt(interior_ring_n(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),(-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1),(-1 -1, 4 0, 4 2, 0 2, -1 -1))'),1)) → ‘LineString (-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))’

14.3.13.40. intersection

Returns a geometry that represents the shared portion of two geometries.

Syntax

intersection(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • geom_to_wkt( intersection( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4)' ) ) ) → ‘LINESTRING(3 3, 4 4)’

  • geom_to_wkt( intersection( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'MULTIPOINT(3.5 3.5, 4 5)' ) ) ) → ‘POINT(3.5 3.5)’

Further reading: Intersection algorithm

14.3.13.41. intersects

Tests whether a geometry intersects another. Returns true if the geometries spatially intersect (share any portion of space) and false if they do not.

Syntax

intersects(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • intersects( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • intersects( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'POINT(5 5)' ) ) → false

Further reading: overlay_intersects

14.3.13.42. intersects_bbox

Tests whether a geometry’s bounding box overlaps another geometry’s bounding box. Returns true if the geometries spatially intersect the bounding box defined and false if they do not.

Syntax

intersects_bbox(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • intersects_bbox( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • intersects_bbox( geom_from_wkt( 'POINT(6 5)' ), geom_from_wkt( 'POLYGON((3 3, 4 4, 5 5, 3 3))' ) ) → false

14.3.13.43. is_closed

Returns true if a line string is closed (start and end points are coincident), or false if a line string is not closed. If the geometry is not a line string then the result will be NULL.

Syntax

is_closed(geometry)

Arguments

  • geometry - a line string geometry

Examples

  • is_closed(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')) → false

  • is_closed(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2, 0 0)')) → true

14.3.13.44. is_empty

Returns true if a geometry is empty (without coordinates), false if the geometry is not empty and NULL if there is no geometry. See also is_empty_or_null.

Syntax

is_empty(geometry)

Arguments

  • geometry - a geometry

Examples

  • is_empty(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')) → false

  • is_empty(geom_from_wkt('LINESTRING EMPTY')) → true

  • is_empty(geom_from_wkt('POINT(7 4)')) → false

  • is_empty(geom_from_wkt('POINT EMPTY')) → true

14.3.13.45. is_empty_or_null

Returns true if a geometry is NULL or empty (without coordinates) or false otherwise. This function is like the expression ‘$geometry IS NULL or is_empty($geometry)’

Syntax

is_empty_or_null(geometry)

Arguments

  • geometry - a geometry

Examples

  • is_empty_or_null(NULL) → true

  • is_empty_or_null(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')) → false

  • is_empty_or_null(geom_from_wkt('LINESTRING EMPTY')) → true

  • is_empty_or_null(geom_from_wkt('POINT(7 4)')) → false

  • is_empty_or_null(geom_from_wkt('POINT EMPTY')) → true

14.3.13.46. is_multipart

Returns true if the geometry is of Multi type.

Syntax

is_multipart(geometry)

Arguments

  • geometry - a geometry

Examples

  • is_multipart(geom_from_wkt('MULTIPOINT ((0 0),(1 1),(2 2))')) → true

  • is_multipart(geom_from_wkt('POINT (0 0)')) → false

14.3.13.47. is_valid

Returns true if a geometry is valid; if it is well-formed in 2D according to the OGC rules.

Syntax

is_valid(geometry)

Arguments

  • geometry - a geometry

Examples

  • is_valid(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2, 0 0)')) → true

  • is_valid(geom_from_wkt('LINESTRING(0 0)')) → false

14.3.13.48. $length

Returns the length of a linestring. If you need the length of a border of a polygon, use $perimeter instead. The length calculated by this function respects both the current project’s ellipsoid setting and distance unit settings. For example, if an ellipsoid has been set for the project then the calculated length will be ellipsoidal, and if no ellipsoid is set then the calculated length will be planimetric.

Syntax

$length

Examples

  • $length → 42.4711

14.3.13.49. length

Returns the number of characters in a string or the length of a geometry linestring.

String variant

Returns the number of characters in a string.

Syntax

length(string)

Arguments

  • string - string to count length of

Examples

  • length('hello') → 5

Geometry variant

Calculate the length of a geometry line object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned length will match the units for the SRS. This differs from the calculations performed by the $length function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.

Syntax

length(geometry)

Arguments

  • geometry - line geometry object

Examples

  • length(geom_from_wkt('LINESTRING(0 0, 4 0)')) → 4.0

14.3.13.50. line_interpolate_angle

Returns the angle parallel to the geometry at a specified distance along a linestring geometry. Angles are in degrees clockwise from north.

Syntax

line_interpolate_angle(geometry, distance)

Arguments

  • geometry - a linestring geometry

  • distance - distance along line to interpolate angle at

Examples

  • line_interpolate_angle(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),distance:=5) → 90.0

14.3.13.51. line_interpolate_point

Returns the point interpolated by a specified distance along a linestring geometry.

Syntax

line_interpolate_point(geometry, distance)

Arguments

  • geometry - a linestring geometry

  • distance - distance along line to interpolate

Examples

  • geom_to_wkt(line_interpolate_point(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),distance:=5)) → ‘Point (5 0)’

Further reading: Interpolate point on line algorithm

14.3.13.52. line_locate_point

Returns the distance along a linestring corresponding to the closest position the linestring comes to a specified point geometry.

Syntax

line_locate_point(geometry, point)

Arguments

  • geometry - a linestring geometry

  • point - point geometry to locate closest position on linestring to

Examples

  • line_locate_point(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),point:=geom_from_wkt('Point(5 0)')) → 5.0

14.3.13.53. line_merge

Returns a LineString or MultiLineString geometry, where any connected LineStrings from the input geometry have been merged into a single linestring. This function will return NULL if passed a geometry which is not a LineString/MultiLineString.

Syntax

line_merge(geometry)

Arguments

  • geometry - a LineString/MultiLineString geometry

Examples

  • geom_to_wkt(line_merge(geom_from_wkt('MULTILINESTRING((0 0, 1 1),(1 1, 2 2))'))) → ‘LineString(0 0,1 1,2 2)’

  • geom_to_wkt(line_merge(geom_from_wkt('MULTILINESTRING((0 0, 1 1),(11 1, 21 2))'))) → ‘MultiLineString((0 0, 1 1),(11 1, 21 2)’

14.3.13.54. line_substring

Returns the portion of a line (or curve) geometry which falls between the specified start and end distances (measured from the beginning of the line). Z and M values are linearly interpolated from existing values.

Syntax

line_substring(geometry, start_distance, end_distance)

Arguments

  • geometry - a linestring or curve geometry

  • start_distance - distance to start of substring

  • end_distance - distance to end of substring

Examples

  • geom_to_wkt(line_substring(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),start_distance:=2,end_distance=6)) → ‘LineString (2 0,6 0)’

Further reading: Line substring algorithm

14.3.13.55. m

Returns the m value of a point geometry.

Syntax

m(geometry)

Arguments

  • geometry - a point geometry

Examples

  • m( geom_from_wkt( 'POINTM(2 5 4)' ) ) → 4

14.3.13.56. m_max

Returns the maximum m (measure) value of a geometry.

Syntax

m_max(geometry)

Arguments

  • geometry - a geometry containing m values

Examples

  • m_max( make_point_m( 0,0,1 ) ) → 1

  • m_max(make_line( make_point_m( 0,0,1 ), make_point_m( -1,-1,2 ), make_point_m( -2,-2,0 ) ) ) → 2

14.3.13.57. m_min

Returns the minimum m (measure) value of a geometry.

Syntax

m_min(geometry)

Arguments

  • geometry - a geometry containing m values

Examples

  • m_min( make_point_m( 0,0,1 ) ) → 1

  • m_min(make_line( make_point_m( 0,0,1 ), make_point_m( -1,-1,2 ), make_point_m( -2,-2,0 ) ) ) → 0

14.3.13.58. main_angle

Returns the main angle of a geometry (clockwise, in degrees from North), which represents the angle of the oriented minimal bounding rectangle which completely covers the geometry.

Syntax

main_angle(geometry)

Arguments

  • geometry - a geometry

Examples

  • main_angle(geom_from_wkt('Polygon ((321577 129614, 321581 129618, 321585 129615, 321581 129610, 321577 129614))')) → 38.66

14.3.13.59. make_circle

Creates a circular polygon.

Syntax

make_circle(center, radius, [segments=36])

[] marks optional arguments

Arguments

  • center - center point of the circle

  • radius - radius of the circle

  • segments - optional argument for polygon segmentation. By default this value is 36

Examples

  • geom_to_wkt(make_circle(make_point(10,10), 5, 4)) → ‘Polygon ((10 15, 15 10, 10 5, 5 10, 10 15))’

  • geom_to_wkt(make_circle(make_point(10,10,5), 5, 4)) → ‘PolygonZ ((10 15 5, 15 10 5, 10 5 5, 5 10 5, 10 15 5))’

  • geom_to_wkt(make_circle(make_point(10,10,5,30), 5, 4)) → ‘PolygonZM ((10 15 5 30, 15 10 5 30, 10 5 5 30, 5 10 5 30, 10 15 5 30))’

14.3.13.60. make_ellipse

Creates an elliptical polygon.

Syntax

make_ellipse(center, semi_major_axis, semi_minor_axis, azimuth, [segments=36])

[] marks optional arguments

Arguments

  • center - center point of the ellipse

  • semi_major_axis - semi-major axis of the ellipse

  • semi_minor_axis - semi-minor axis of the ellipse

  • azimuth - orientation of the ellipse

  • segments - optional argument for polygon segmentation. By default this value is 36

Examples

  • geom_to_wkt(make_ellipse(make_point(10,10), 5, 2, 90, 4)) → ‘Polygon ((15 10, 10 8, 5 10, 10 12, 15 10))’

  • geom_to_wkt(make_ellipse(make_point(10,10,5), 5, 2, 90, 4)) → ‘PolygonZ ((15 10 5, 10 8 5, 5 10 5, 10 12 5, 15 10 5))’

  • geom_to_wkt(make_ellipse(make_point(10,10,5,30), 5, 2, 90, 4)) → ‘PolygonZM ((15 10 5 30, 10 8 5 30, 5 10 5 30, 10 12 5 30, 15 10 5 30))’

14.3.13.61. make_line

Creates a line geometry from a series of point geometries.

List of arguments variant

Line vertices are specified as separate arguments to the function.

Syntax

make_line(point1, point2, …)

Arguments

  • point - a point geometry (or array of points)

Examples

  • geom_to_wkt(make_line(make_point(2,4),make_point(3,5))) → ‘LineString (2 4, 3 5)’

  • geom_to_wkt(make_line(make_point(2,4),make_point(3,5),make_point(9,7))) → ‘LineString (2 4, 3 5, 9 7)’

Array variant

Line vertices are specified as an array of points.

Syntax

make_line(array)

Arguments

  • array - array of points

Examples

  • geom_to_wkt(make_line(array(make_point(2,4),make_point(3,5),make_point(9,7)))) → ‘LineString (2 4, 3 5, 9 7)’

14.3.13.62. make_point

Creates a point geometry from an x and y (and optional z and m) value.

Syntax

make_point(x, y, [z], [m])

[] marks optional arguments

Arguments

  • x - x coordinate of point

  • y - y coordinate of point

  • z - optional z coordinate of point

  • m - optional m value of point

Examples

  • geom_to_wkt(make_point(2,4)) → ‘Point (2 4)’

  • geom_to_wkt(make_point(2,4,6)) → ‘PointZ (2 4 6)’

  • geom_to_wkt(make_point(2,4,6,8)) → ‘PointZM (2 4 6 8)’

14.3.13.63. make_point_m

Creates a point geometry from an x, y coordinate and m value.

Syntax

make_point_m(x, y, m)

Arguments

  • x - x coordinate of point

  • y - y coordinate of point

  • m - m value of point

Examples

  • geom_to_wkt(make_point_m(2,4,6)) → ‘PointM (2 4 6)’

14.3.13.64. make_polygon

Creates a polygon geometry from an outer ring and optional series of inner ring geometries.

Syntax

make_polygon(outerRing, [innerRing1], [innerRing2], …)

[] marks optional arguments

Arguments

  • outerRing - closed line geometry for polygon’s outer ring

  • innerRing - optional closed line geometry for inner ring

Examples

  • geom_to_wkt(make_polygon(geom_from_wkt('LINESTRING( 0 0, 0 1, 1 1, 1 0, 0 0 )'))) → ‘Polygon ((0 0, 0 1, 1 1, 1 0, 0 0))’

  • geom_to_wkt(make_polygon(geom_from_wkt('LINESTRING( 0 0, 0 1, 1 1, 1 0, 0 0 )'),geom_from_wkt('LINESTRING( 0.1 0.1, 0.1 0.2, 0.2 0.2, 0.2 0.1, 0.1 0.1 )'),geom_from_wkt('LINESTRING( 0.8 0.8, 0.8 0.9, 0.9 0.9, 0.9 0.8, 0.8 0.8 )'))) → ‘Polygon ((0 0, 0 1, 1 1, 1 0, 0 0),(0.1 0.1, 0.1 0.2, 0.2 0.2, 0.2 0.1, 0.1 0.1),(0.8 0.8, 0.8 0.9, 0.9 0.9, 0.9 0.8, 0.8 0.8))’

14.3.13.65. make_rectangle_3points

Creates a rectangle from 3 points.

Syntax

make_rectangle_3points(point1, point2, point3, [option=0])

[] marks optional arguments

Arguments

  • point1 - First point.

  • point2 - Second point.

  • point3 - Third point.

  • option - An optional argument to construct the rectangle. By default this value is 0. Value can be 0 (distance) or 1 (projected). Option distance: Second distance is equal to the distance between 2nd and 3rd point. Option projected: Second distance is equal to the distance of the perpendicular projection of the 3rd point on the segment or its extension.

Examples

  • geom_to_wkt(make_rectangle(make_point(0, 0), make_point(0,5), make_point(5, 5), 0))) → ‘Polygon ((0 0, 0 5, 5 5, 5 0, 0 0))’

  • geom_to_wkt(make_rectangle(make_point(0, 0), make_point(0,5), make_point(5, 3), 1))) → ‘Polygon ((0 0, 0 5, 5 5, 5 0, 0 0))’

14.3.13.66. make_regular_polygon

Creates a regular polygon.

Syntax

make_regular_polygon(center, radius, number_sides, [circle=0])

[] marks optional arguments

Arguments

  • center - center of the regular polygon

  • radius - second point. The first if the regular polygon is inscribed. The midpoint of the first side if the regular polygon is circumscribed.

  • number_sides - Number of sides/edges of the regular polygon

  • circle - Optional argument to construct the regular polygon. By default this value is 0. Value can be 0 (inscribed) or 1 (circumscribed)

Examples

  • geom_to_wkt(make_regular_polygon(make_point(0,0), make_point(0,5), 5)) → ‘Polygon ((0 5, 4.76 1.55, 2.94 -4.05, -2.94 -4.05, -4.76 1.55, 0 5))’

  • geom_to_wkt(make_regular_polygon(make_point(0,0), project(make_point(0,0), 4.0451, radians(36)), 5)) → ‘Polygon ((0 5, 4.76 1.55, 2.94 -4.05, -2.94 -4.05, -4.76 1.55, 0 5))’

14.3.13.67. make_square

Creates a square from a diagonal.

Syntax

make_square(point1, point2)

Arguments

  • point1 - First point of the diagonal

  • point2 - Last point of the diagonal

Examples

  • geom_to_wkt(make_square( make_point(0,0), make_point(5,5))) → ‘Polygon ((0 0, -0 5, 5 5, 5 0, 0 0))’

  • geom_to_wkt(make_square( make_point(5,0), make_point(5,5))) → ‘Polygon ((5 0, 2.5 2.5, 5 5, 7.5 2.5, 5 0))’

14.3.13.68. make_triangle

Creates a triangle polygon.

Syntax

make_triangle(point1, point2, point3)

Arguments

  • point1 - first point of the triangle

  • point2 - second point of the triangle

  • point3 - third point of the triangle

Examples

  • geom_to_wkt(make_triangle(make_point(0,0), make_point(5,5), make_point(0,10))) → ‘Triangle ((0 0, 5 5, 0 10, 0 0))’

  • geom_to_wkt(boundary(make_triangle(make_point(0,0), make_point(5,5), make_point(0,10)))) → ‘LineString (0 0, 5 5, 0 10, 0 0)’

14.3.13.69. minimal_circle

Returns the minimal enclosing circle of a geometry. It represents the minimum circle that encloses all geometries within the set.

Syntax

minimal_circle(geometry, [segments=36])

[] marks optional arguments

Arguments

  • geometry - a geometry

  • segments - optional argument for polygon segmentation. By default this value is 36

Examples

  • geom_to_wkt( minimal_circle( geom_from_wkt( 'LINESTRING(0 5, 0 -5, 2 1)' ), 4 ) ) → ‘Polygon ((0 5, 5 -0, -0 -5, -5 0, 0 5))’

  • geom_to_wkt( minimal_circle( geom_from_wkt( 'MULTIPOINT(1 2, 3 4, 3 2)' ), 4 ) ) → ‘Polygon ((3 4, 3 2, 1 2, 1 4, 3 4))’

Further reading: Minimum enclosing circles algorithm

14.3.13.70. nodes_to_points

Returns a multipoint geometry consisting of every node in the input geometry.

Syntax

nodes_to_points(geometry, [ignore_closing_nodes=false])

[] marks optional arguments

Arguments

  • geometry - geometry object

  • ignore_closing_nodes - optional argument specifying whether to include duplicate nodes which close lines or polygons rings. Defaults to false, set to true to avoid including these duplicate nodes in the output collection.

Examples

  • geom_to_wkt(nodes_to_points(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) → ‘MultiPoint ((0 0),(1 1),(2 2))’

  • geom_to_wkt(nodes_to_points(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1))'),true)) → ‘MultiPoint ((-1 -1),(4 0),(4 2),(0 2))’

Further reading: Extract vertices algorithm

14.3.13.71. num_geometries

Returns the number of geometries in a geometry collection, or NULL if the input geometry is not a collection.

Syntax

num_geometries(geometry)

Arguments

  • geometry - geometry collection

Examples

  • num_geometries(geom_from_wkt('GEOMETRYCOLLECTION(POINT(0 1), POINT(0 0), POINT(1 0), POINT(1 1))')) → 4

14.3.13.72. num_interior_rings

Returns the number of interior rings in a polygon or geometry collection, or NULL if the input geometry is not a polygon or collection.

Syntax

num_interior_rings(geometry)

Arguments

  • geometry - input geometry

Examples

  • num_interior_rings(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),(-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))')) → 1

14.3.13.73. num_points

Returns the number of vertices in a geometry.

Syntax

num_points(geometry)

Arguments

  • geometry - a geometry

Examples

  • num_points($geometry) → number of vertices in the current feature’s geometry

14.3.13.74. num_rings

Returns the number of rings (including exterior rings) in a polygon or geometry collection, or NULL if the input geometry is not a polygon or collection.

Syntax

num_rings(geometry)

Arguments

  • geometry - input geometry

Examples

  • num_rings(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),(-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))')) → 2

14.3.13.75. offset_curve

Returns a geometry formed by offsetting a linestring geometry to the side. Distances are in the Spatial Reference System of this geometry.

Syntax

offset_curve(geometry, distance, [segments=8], [join=1], [miter_limit=2.0])

[] marks optional arguments

Arguments

  • geometry - a (multi)linestring geometry

  • distance - offset distance. Positive values will be buffered to the left of lines, negative values to the right

  • segments - number of segments to use to represent a quarter circle when a round join style is used. A larger number results in a smoother line with more nodes.

  • join - join style for corners, where 1 = round, 2 = miter and 3 = bevel

  • miter_limit - limit on the miter ratio used for very sharp corners (when using miter joins only)

Examples

  • offset_curve($geometry, 10.5) → line offset to the left by 10.5 units

  • offset_curve($geometry, -10.5) → line offset to the right by 10.5 units

  • offset_curve($geometry, 10.5, segments=16, join=1) → line offset to the left by 10.5 units, using more segments to result in a smoother curve

  • offset_curve($geometry, 10.5, join=3) → line offset to the left by 10.5 units, using a beveled join

Further reading: Offset lines algorithm

14.3.13.76. order_parts

Orders the parts of a MultiGeometry by a given criteria

Syntax

order_parts(geometry, orderby, ascending)

Arguments

  • geometry - a multi-type geometry

  • orderby - an expression string defining the order criteria

  • ascending - boolean, True for ascending, False for descending

Examples

  • geom_to_wkt(order_parts(geom_from_wkt('MultiPolygon (((1 1, 5 1, 5 5, 1 5, 1 1)),((1 1, 9 1, 9 9, 1 9, 1 1)))'), 'area($geometry)', False)) → ‘MultiPolygon (((1 1, 9 1, 9 9, 1 9, 1 1)),((1 1, 5 1, 5 5, 1 5, 1 1)))’

  • geom_to_wkt(order_parts(geom_from_wkt('LineString(1 2, 3 2, 4 3)'), '1', True)) → ‘LineString(1 2, 3 2, 4 3)’

14.3.13.77. oriented_bbox

Returns a geometry which represents the minimal oriented bounding box of an input geometry.

Syntax

oriented_bbox(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt( oriented_bbox( geom_from_wkt( 'MULTIPOINT(1 2, 3 4, 3 2)' ) ) ) → ‘Polygon ((3 2, 3 4, 1 4, 1 2, 3 2))’

Further reading: Oriented minimum bounding box algorithm

14.3.13.78. overlaps

Tests whether a geometry overlaps another. Returns true if the geometries share space, are of the same dimension, but are not completely contained by each other.

Syntax

overlaps(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • overlaps( geom_from_wkt( 'LINESTRING(3 5, 4 4, 5 5, 5 3)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • overlaps( geom_from_wkt( 'LINESTRING(0 0, 1 1)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → false

14.3.13.79. overlay_contains

Returns whether the current feature spatially contains at least one feature from a target layer, or an array of expression-based results for the features in the target layer contained in the current feature.

Read more on the underlying GEOS “Contains” predicate, as described in PostGIS ST_Contains function.

Syntax

overlay_contains(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_contains('regions') → true if the current feature spatially contains a region

  • overlay_contains('regions', filter:= population > 10000) → true if the current feature spatially contains a region with a population greater than 10000

  • overlay_contains('regions', name) → an array of names, for the regions contained in the current feature

  • array_to_string(overlay_contains('regions', name)) → a string as a comma separated list of names, for the regions contained in the current feature

  • array_length(overlay_contains('regions', name)) → the number of regions contained in the current feature

  • array_sort(overlay_contains(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions contained in the current feature and with a population greater than 10000

  • overlay_contains(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions contained in the current feature

Further reading: contains, array manipulation, Select by location algorithm

14.3.13.80. overlay_crosses

Returns whether the current feature spatially crosses at least one feature from a target layer, or an array of expression-based results for the features in the target layer crossed by the current feature.

Read more on the underlying GEOS “Crosses” predicate, as described in PostGIS ST_Crosses function.

Syntax

overlay_crosses(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_crosses('regions') → true if the current feature spatially crosses a region

  • overlay_crosses('regions', filter:= population > 10000) → true if the current feature spatially crosses a region with a population greater than 10000

  • overlay_crosses('regions', name) → an array of names, for the regions crossed by the current feature

  • array_to_string(overlay_crosses('regions', name)) → a string as a comma separated list of names, for the regions crossed by the current feature

  • array_sort(overlay_crosses(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions crossed by the current feature and with a population greater than 10000

  • overlay_crosses(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions crossed by the current feature

Further reading: crosses, array manipulation, Select by location algorithm

14.3.13.81. overlay_disjoint

Returns whether the current feature is spatially disjoint from all the features of a target layer, or an array of expression-based results for the features in the target layer that are disjoint from the current feature.

Read more on the underlying GEOS “Disjoint” predicate, as described in PostGIS ST_Disjoint function.

Syntax

overlay_disjoint(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_disjoint('regions') → true if the current feature is spatially disjoint from all the regions

  • overlay_disjoint('regions', filter:= population > 10000) → true if the current feature is spatially disjoint from all the regions with a population greater than 10000

  • overlay_disjoint('regions', name) → an array of names, for the regions spatially disjoint from the current feature

  • array_to_string(overlay_disjoint('regions', name)) → a string as a comma separated list of names, for the regions spatially disjoint from the current feature

  • array_sort(overlay_disjoint(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions spatially disjoint from the current feature and with a population greater than 10000

  • overlay_disjoint(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions spatially disjoint from the current feature

Further reading: disjoint, array manipulation, Select by location algorithm

14.3.13.82. overlay_equals

Returns whether the current feature spatially equals to at least one feature from a target layer, or an array of expression-based results for the features in the target layer that are spatially equal to the current feature.

Read more on the underlying GEOS “Equals” predicate, as described in PostGIS ST_Equals function.

Syntax

overlay_equals(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_equals('regions') → true if the current feature is spatially equal to a region

  • overlay_equals('regions', filter:= population > 10000) → true if the current feature is spatially equal to a region with a population greater than 10000

  • overlay_equals('regions', name) → an array of names, for the regions spatially equal to the current feature

  • array_to_string(overlay_equals('regions', name)) → a string as a comma separated list of names, for the regions spatially equal to the current feature

  • array_sort(overlay_equals(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions spatially equal to the current feature and with a population greater than 10000

  • overlay_equals(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions spatially equal to the current feature

Further reading: array manipulation, Select by location algorithm

14.3.13.83. overlay_intersects

Returns whether the current feature spatially intersects at least one feature from a target layer, or an array of expression-based results for the features in the target layer intersected by the current feature.

Read more on the underlying GEOS “Intersects” predicate, as described in PostGIS ST_Intersects function.

Syntax

overlay_intersects(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_intersects('regions') → true if the current feature spatially intersects a region

  • overlay_intersects('regions', filter:= population > 10000) → true if the current feature spatially intersects a region with a population greater than 10000

  • overlay_intersects('regions', name) → an array of names, for the regions intersected by the current feature

  • array_to_string(overlay_intersects('regions', name)) → a string as a comma separated list of names, for the regions intersected by the current feature

  • array_sort(overlay_intersects(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions intersected by the current feature and with a population greater than 10000

  • overlay_intersects(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions intersected by the current feature

Further reading: intersects, array manipulation, Select by location algorithm

14.3.13.84. overlay_nearest

Returns whether the current feature has feature(s) from a target layer within a given distance, or an array of expression-based results for the features in the target layer within a distance from the current feature.

Note: This function can be slow and consume a lot of memory for large layers.

Syntax

overlay_nearest(layer, [expression], [filter], [limit=1], [max_distance], [cache=false])

[] marks optional arguments

Arguments

  • layer - the target layer

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features in the target layer will be used.

  • limit - an optional integer to limit the number of matching features. If not set, only the nearest feature will be returned. If set to -1, returns all the matching features.

  • max_distance - an optional distance to limit the search of matching features. If not set, all the features in the target layer will be used.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_nearest('airports') → true if the “airports” layer has at least one feature

  • overlay_nearest('airports', max_distance:= 5000) → true if there is an airport within a distance of 5000 map units from the current feature

  • overlay_nearest('airports', name) → the name of the closest airport to the current feature, as an array

  • array_to_string(overlay_nearest('airports', name)) → the name of the closest airport to the current feature, as a string

  • overlay_nearest(layer:='airports', expression:= name, max_distance:= 5000) → the name of the closest airport within a distance of 5000 map units from the current feature, as an array

  • overlay_nearest(layer:='airports', expression:="name", filter:= "Use"='Civilian', limit:=3) → an array of names, for up to the three closest civilian airports ordered by distance

  • overlay_nearest(layer:='airports', expression:="name", limit:= -1, max_distance:= 5000) → an array of names, for all the airports within a distance of 5000 map units from the current feature, ordered by distance

Further reading: array manipulation, Join attributes by nearest algorithm

14.3.13.85. overlay_touches

Returns whether the current feature spatially touches at least one feature from a target layer, or an array of expression-based results for the features in the target layer touched by the current feature.

Read more on the underlying GEOS “Touches” predicate, as described in PostGIS ST_Touches function.

Syntax

overlay_touches(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_touches('regions') → true if the current feature spatially touches a region

  • overlay_touches('regions', filter:= population > 10000) → true if the current feature spatially touches a region with a population greater than 10000

  • overlay_touches('regions', name) → an array of names, for the regions touched by the current feature

  • string_to_array(overlay_touches('regions', name)) → a string as a comma separated list of names, for the regions touched by the current feature

  • array_sort(overlay_touches(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions touched by the current feature and with a population greater than 10000

  • overlay_touches(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions touched by the current feature

Further reading: touches, array manipulation, Select by location algorithm

14.3.13.86. overlay_within

Returns whether the current feature is spatially within at least one feature from a target layer, or an array of expression-based results for the features in the target layer that contain the current feature.

Read more on the underlying GEOS “Within” predicate, as described in PostGIS ST_Within function.

Syntax

overlay_within(layer, [expression], [filter], [limit], [cache=false])

[] marks optional arguments

Arguments

  • layer - the layer whose overlay is checked

  • expression - an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.

  • filter - an optional expression to filter the target features to check. If not set, all the features will be checked.

  • limit - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.

  • cache - set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)

Examples

  • overlay_within('regions') → true if the current feature is spatially within a region

  • overlay_within('regions', filter:= population > 10000) → true if the current feature is spatially within a region with a population greater than 10000

  • overlay_within('regions', name) → an array of names, for the regions containing the current feature

  • array_to_string(overlay_within('regions', name)) → a string as a comma separated list of names, for the regions containing the current feature

  • array_sort(overlay_within(layer:='regions', expression:="name", filter:= population > 10000)) → an ordered array of names, for the regions containing the current feature and with a population greater than 10000

  • overlay_within(layer:='regions', expression:= geom_to_wkt($geometry), limit:=2) → an array of geometries (in WKT), for up to two regions containing the current feature

Further reading: within, array manipulation, Select by location algorithm

14.3.13.87. $perimeter

Returns the perimeter length of the current feature. The perimeter calculated by this function respects both the current project’s ellipsoid setting and distance unit settings. For example, if an ellipsoid has been set for the project then the calculated perimeter will be ellipsoidal, and if no ellipsoid is set then the calculated perimeter will be planimetric.

Syntax

$perimeter

Examples

  • $perimeter → 42

14.3.13.88. perimeter

Returns the perimeter of a geometry polygon object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned perimeter will match the units for the SRS. This differs from the calculations performed by the $perimeter function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.

Syntax

perimeter(geometry)

Arguments

  • geometry - polygon geometry object

Examples

  • perimeter(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))')) → 12.0

14.3.13.89. point_n

Returns a specific node from a geometry.

Syntax

point_n(geometry, index)

Arguments

  • geometry - geometry object

  • index - index of node to return, where 1 is the first node; if the value is negative, the selected vertex index will be its total count minus the absolute value

Examples

  • geom_to_wkt(point_n(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))'),2)) → ‘Point (4 0)’

Further reading: Extract specific vertices algorithm

14.3.13.90. point_on_surface

Returns a point guaranteed to lie on the surface of a geometry.

Syntax

point_on_surface(geometry)

Arguments

  • geometry - a geometry

Examples

  • point_on_surface($geometry) → a point geometry

Further reading: Point on Surface algorithm

14.3.13.91. pole_of_inaccessibility

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. More precise tolerances require more iterations and will take longer to calculate.

Syntax

pole_of_inaccessibility(geometry, tolerance)

Arguments

  • geometry - a geometry

  • tolerance - maximum distance between the returned point and the true pole location

Examples

  • geom_to_wkt(pole_of_inaccessibility( geom_from_wkt('POLYGON((0 1, 0 9, 3 10, 3 3, 10 3, 10 1, 0 1))'), 0.1))' → ‘Point(1.546875 2.546875)’

Further reading: Pole of inaccessibility algorithm

14.3.13.92. project

Returns a point projected from a start point using a distance, a bearing (azimuth) and an elevation in radians.

Syntax

project(point, distance, azimuth, [elevation])

[] marks optional arguments

Arguments

  • point - start point

  • distance - distance to project

  • azimuth - azimuth in radians clockwise, where 0 corresponds to north

  • elevation - angle of inclination in radians

Examples

  • geom_to_wkt(project(make_point(1, 2), 3, radians(270))) → ‘Point(-2, 2)’

Further reading: Project points (Cartesian) algorithm

14.3.13.93. relate

Tests the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between two geometries.

Relationship variant

Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between two geometries.

Syntax

relate(geometry, geometry)

Arguments

  • geometry - a geometry

  • geometry - a geometry

Examples

  • relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt( 'LINESTRING(40 40,60 120)' ) ) → ‘FF1F00102’

Pattern match variant

Tests whether the DE-9IM relationship between two geometries matches a specified pattern.

Syntax

relate(geometry, geometry, pattern)

Arguments

  • geometry - a geometry

  • geometry - a geometry

  • pattern - DE-9IM pattern to match

Examples

  • relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt( 'LINESTRING(40 40,60 120)' ), '**1F001**' ) → True

14.3.13.94. reverse

Reverses the direction of a line string by reversing the order of its vertices.

Syntax

reverse(geometry)

Arguments

  • geometry - a geometry

Examples

  • geom_to_wkt(reverse(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) → ‘LINESTRING(2 2, 1 1, 0 0)’

Further reading: Reverse line direction algorithm

14.3.13.95. rotate

Returns a rotated version of a geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax

rotate(geometry, rotation, [center])

[] marks optional arguments

Arguments

  • geometry - a geometry

  • rotation - clockwise rotation in degrees

  • center - rotation center point. If not specified, the center of the geometry’s bounding box is used.

Examples

  • rotate($geometry, 45, make_point(4, 5)) → geometry rotated 45 degrees clockwise around the (4, 5) point

  • rotate($geometry, 45) → geometry rotated 45 degrees clockwise around the center of its bounding box

14.3.13.96. segments_to_lines

Returns a multi line geometry consisting of a line for every segment in the input geometry.

Syntax

segments_to_lines(geometry)

Arguments

  • geometry - geometry object

Examples

  • geom_to_wkt(segments_to_lines(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) → ‘MultiLineString ((0 0, 1 1),(1 1, 2 2))’

Further reading: Explode lines algorithm

14.3.13.97. shortest_line

Returns the shortest line joining geometry1 to geometry2. The resultant line will start at geometry1 and end at geometry2.

Syntax

shortest_line(geometry1, geometry2)

Arguments

  • geometry1 - geometry to find shortest line from

  • geometry2 - geometry to find shortest line to

Examples

  • geom_to_wkt(shortest_line(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75 )'),geom_from_wkt('POINT(100 100)'))) → ‘LineString(73.0769 115.384, 100 100)’

14.3.13.98. simplify

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.

Syntax

simplify(geometry, tolerance)

Arguments

  • geometry - a geometry

  • tolerance - maximum deviation from straight segments for points to be removed

Examples

  • geom_to_wkt(simplify(geometry:=geom_from_wkt('LineString(0 0, 5 0.1, 10 0)'),tolerance:=5)) → ‘LineString(0 0, 10 0)’

Further reading: Simplify algorithm

14.3.13.99. simplify_vw

Simplifies a geometry by removing nodes using an area based threshold (ie, the Visvalingam-Whyatt algorithm). The algorithm removes vertices which create small areas in geometries, e.g., narrow spikes or nearly straight segments.

Syntax

simplify_vw(geometry, tolerance)

Arguments

  • geometry - a geometry

  • tolerance - a measure of the maximum area created by a node for the node to be removed

Examples

  • geom_to_wkt(simplify_vw(geometry:=geom_from_wkt('LineString(0 0, 5 0, 5.01 10, 5.02 0, 10 0)'),tolerance:=5)) → ‘LineString(0 0, 10 0)’

Further reading: Simplify algorithm

14.3.13.100. single_sided_buffer

Returns a geometry formed by buffering out just one side of a linestring geometry. Distances are in the Spatial Reference System of this geometry.

Syntax

single_sided_buffer(geometry, distance, [segments=8], [join=1], [miter_limit=2.0])

[] marks optional arguments

Arguments

  • geometry - a (multi)linestring geometry

  • distance - buffer distance. Positive values will be buffered to the left of lines, negative values to the right

  • segments - number of segments to use to represent a quarter circle when a round join style is used. A larger number results in a smoother buffer with more nodes.

  • join - join style for corners, where 1 = round, 2 = miter and 3 = bevel

  • miter_limit - limit on the miter ratio used for very sharp corners (when using miter joins only)

Examples

  • single_sided_buffer($geometry, 10.5) → line buffered to the left by 10.5 units

  • single_sided_buffer($geometry, -10.5) → line buffered to the right by 10.5 units

  • single_sided_buffer($geometry, 10.5, segments=16, join=1) → line buffered to the left by 10.5 units, using more segments to result in a smoother buffer

  • single_sided_buffer($geometry, 10.5, join=3) → line buffered to the left by 10.5 units, using a beveled join

Further reading: Single sided buffer algorithm

14.3.13.101. smooth

Smooths a geometry by adding extra nodes which round off corners in the geometry. If input geometries contain Z or M values, these will also be smoothed and the output geometry will retain the same dimensionality as the input geometry.

Syntax

smooth(geometry, [iterations=1], [offset=0.25], [min_length=-1], [max_angle=180])

[] marks optional arguments

Arguments

  • geometry - a geometry

  • iterations - number of smoothing iterations to apply. Larger numbers result in smoother but more complex geometries.

  • offset - value between 0 and 0.5 which controls how tightly the smoothed geometry follow the original geometry. Smaller values result in a tighter smoothing, larger values result in looser smoothing.

  • min_length - minimum length of segments to apply smoothing to. This parameter can be used to avoid placing excessive additional nodes in shorter segments of the geometry.

  • max_angle - maximum angle at node for smoothing to be applied (0-180). By lowering the maximum angle intentionally sharp corners in the geometry can be preserved. For instance, a value of 80 degrees will retain right angles in the geometry.

Examples

  • geom_to_wkt(smooth(geometry:=geom_from_wkt('LineString(0 0, 5 0, 5 5)'),iterations:=1,offset:=0.2,min_length:=-1,max_angle:=180)) → ‘LineString (0 0, 4 0, 5 1, 5 5)’

Further reading: Smooth algorithm

14.3.13.102. start_point

Returns the first node from a geometry.

Syntax

start_point(geometry)

Arguments

  • geometry - geometry object

Examples

  • geom_to_wkt(start_point(geom_from_wkt('LINESTRING(4 0, 4 2, 0 2)'))) → ‘Point (4 0)’

Further reading: Extract specific vertices algorithm

14.3.13.103. sym_difference

Returns a geometry that represents the portions of two geometries that do not intersect.

Syntax

sym_difference(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • geom_to_wkt( sym_difference( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 8 8)' ) ) ) → ‘LINESTRING(5 5, 8 8)’

Further reading: Symmetrical difference algorithm

14.3.13.104. tapered_buffer

Creates a buffer along a line geometry where the buffer diameter varies evenly over the length of the line.

Syntax

tapered_buffer(geometry, start_width, end_width, [segments=8])

[] marks optional arguments

Arguments

  • geometry - input geometry. Must be a (multi)line geometry.

  • start_width - width of buffer at start of line,

  • end_width - width of buffer at end of line.

  • segments - number of segments to approximate quarter-circle curves in the buffer.

Examples

  • tapered_buffer(geometry:=geom_from_wkt('LINESTRING(1 2, 4 2)'),start_width:=1,end_width:=2,segments:=8) → A tapered buffer starting with a diameter of 1 and ending with a diameter of 2 along the linestring geometry.

Further reading: Tapered buffers algorithm

14.3.13.105. touches

Tests whether a geometry touches another. Returns true if the geometries have at least one point in common, but their interiors do not intersect.

Syntax

touches(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • touches( geom_from_wkt( 'LINESTRING(5 3, 4 4)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) ) → true

  • touches( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(5 5)' ) ) → false

Further reading: overlay_touches

14.3.13.106. transform

Returns the geometry transformed from a source CRS to a destination CRS.

Syntax

transform(geometry, source_auth_id, dest_auth_id)

Arguments

  • geometry - a geometry

  • source_auth_id - the source auth CRS ID

  • dest_auth_id - the destination auth CRS ID

Examples

  • geom_to_wkt( transform( make_point(488995.53240249, 7104473.38600835), 'EPSG:2154', 'EPSG:4326' ) ) → ‘POINT(0 51)’

Further reading: Reproject layer algorithm

14.3.13.107. translate

Returns a translated version of a geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax

translate(geometry, dx, dy)

Arguments

  • geometry - a geometry

  • dx - delta x

  • dy - delta y

Examples

  • translate($geometry, 5, 10) → a geometry of the same type like the original one

Further reading: Translate algorithm

14.3.13.108. union

Returns a geometry that represents the point set union of the geometries.

Syntax

union(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • geom_to_wkt( union( make_point(4, 4), make_point(5, 5) ) ) → ‘MULTIPOINT(4 4, 5 5)’

14.3.13.109. wedge_buffer

Returns a wedge shaped buffer originating from a point geometry.

Syntax

wedge_buffer(center, azimuth, width, outer_radius, [inner_radius=0.0])

[] marks optional arguments

Arguments

  • center - center point (origin) of buffer. Must be a point geometry.

  • azimuth - angle (in degrees) for the middle of the wedge to point.

  • width - buffer width (in degrees). Note that the wedge will extend to half of the angular width either side of the azimuth direction.

  • outer_radius - outer radius for buffers

  • inner_radius - optional inner radius for buffers

Examples

  • wedge_buffer(center:=geom_from_wkt('POINT(1 2)'),azimuth:=90,width:=180,outer_radius:=1) → A wedge shaped buffer centered on the point (1,2), facing to the East, with a width of 180 degrees and outer radius of 1.

Further reading: Create wedge buffers algorithm

14.3.13.110. within

Tests whether a geometry is within another. Returns true if the geometry1 is completely within geometry2.

Syntax

within(geometry1, geometry2)

Arguments

  • geometry1 - a geometry

  • geometry2 - a geometry

Examples

  • within( geom_from_wkt( 'POINT( 0.5 0.5)' ), geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))' ) ) → true

  • within( geom_from_wkt( 'POINT( 5 5 )' ), geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0 ))' ) ) → false

Further reading: overlay_within

14.3.13.111. $x

Returns the x coordinate of the current point feature. If the feature is a multipoint feature, then the x-coordinate of the first point will be returned.

Syntax

$x

Examples

  • $x → 42

14.3.13.112. x

Returns the x coordinate of a point geometry, or the x coordinate of the centroid for a non-point geometry.

Syntax

x(geometry)

Arguments

  • geometry - a geometry

Examples

  • x( geom_from_wkt( 'POINT(2 5)' ) ) → 2

  • x( $geometry ) → x coordinate of the current feature’s centroid

14.3.13.113. $x_at

Retrieves a x coordinate of the current feature’s geometry.

Syntax

$x_at(i)

Arguments

  • i - index of point of a line (indices start at 0; negative values apply from the last index, starting at -1)

Examples

  • $x_at(1) → 5

14.3.13.114. x_max

Returns the maximum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax

x_max(geometry)

Arguments

  • geometry - a geometry

Examples

  • x_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) → 4

14.3.13.115. x_min

Returns the minimum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax

x_min(geometry)

Arguments

  • geometry - a geometry

Examples

  • x_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) → 2

14.3.13.116. $y

Returns the y coordinate of the current point feature. If the feature is a multipoint feature, then the y-coordinate of the first point will be returned.

Syntax

$y

Examples

  • $y → 42

14.3.13.117. y

Returns the y coordinate of a point geometry, or the y coordinate of the centroid for a non-point geometry.

Syntax

y(geometry)

Arguments

  • geometry - a geometry

Examples

  • y( geom_from_wkt( 'POINT(2 5)' ) ) → 5

  • y( $geometry ) → y coordinate of the current feature’s centroid

14.3.13.118. $y_at

Retrieves a y coordinate of the current feature’s geometry.

Syntax

$y_at(i)

Arguments

  • i - index of point of a line (indices start at 0; negative values apply from the last index, starting at -1)

Examples

  • $y_at(1) → 2

14.3.13.119. y_max

Returns the maximum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax

y_max(geometry)

Arguments

  • geometry - a geometry

Examples

  • y_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) → 8

14.3.13.120. y_min

Returns the minimum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax

y_min(geometry)

Arguments

  • geometry - a geometry

Examples

  • y_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) → 5

14.3.13.121. z

Returns the z coordinate of a point geometry, or NULL if the geometry has no z value.

Syntax

z(geometry)

Arguments

  • geometry - a point geometry

Examples

  • z( geom_from_wkt( 'POINTZ(2 5 7)' ) ) → 7

14.3.13.122. z_max

Returns the maximum z coordinate of a geometry, or NULL if the geometry has no z value.

Syntax

z_max(geometry)

Arguments

  • geometry - a geometry with z coordinate

Examples

  • z_max( geom_from_wkt( 'POINT ( 0 0 1 )' ) ) → 1

  • z_max( geom_from_wkt( 'MULTIPOINT ( 0 0 1 , 1 1 3 )' ) ) → 3

  • z_max( make_line( make_point( 0,0,0 ), make_point( -1,-1,-2 ) ) ) → 0

  • z_max( geom_from_wkt( 'LINESTRING( 0 0 0, 1 0 2, 1 1 -1 )' ) ) → 2

  • z_max( geom_from_wkt( 'POINT ( 0 0 )' ) ) → NULL

14.3.13.123. z_min

Returns the minimum z coordinate of a geometry, or NULL if the geometry has no z value.

Syntax

z_min(geometry)

Arguments

  • geometry - a geometry with z coordinate

Examples

  • z_min( geom_from_wkt( 'POINT ( 0 0 1 )' ) ) → 1

  • z_min( geom_from_wkt( 'MULTIPOINT ( 0 0 1 , 1 1 3 )' ) ) → 1

  • z_min( make_line( make_point( 0,0,0 ), make_point( -1,-1,-2 ) ) ) → -2

  • z_min( geom_from_wkt( 'LINESTRING( 0 0 0, 1 0 2, 1 1 -1 )' ) ) → -1

  • z_min( geom_from_wkt( 'POINT ( 0 0 )' ) ) → NULL

14.3.14. Layout Functions

This group contains functions to manipulate print layout items properties.

14.3.14.1. item_variables

Returns a map of variables from a layout item inside this print layout.

Syntax

item_variables(id)

Arguments

  • id - layout item ID

Examples

  • map_get( item_variables('Map 0'), 'map_scale') → scale of the item ‘Map 0’ in the current print layout

Further reading: List of default variables

14.3.15. Map Layers

This group contains a list of the available layers in the current project. This offers a convenient way to write expressions referring to multiple layers, such as when performing aggregates, attribute or spatial queries.

It also provides some convenient functions to manipulate layers.

14.3.15.1. decode_uri

Takes a layer and decodes the uri of the underlying data provider. It depends on the dataprovider, which data is available.

Syntax

decode_uri(layer, [part])

[] marks optional arguments

Arguments

  • layer - The layer for which the uri should be decoded.

  • part - The part of the uri to return. If unspecified, a map with all uri parts will be returned.

Examples

  • decode_uri(@layer) → {‘layerId’: ‘0’, ‘layerName’: ‘’, ‘path’: ‘/home/qgis/shapefile.shp’}

  • decode_uri(@layer) → {‘layerId’: NULL, ‘layerName’: ‘layer’, ‘path’: ‘/home/qgis/geopackage.gpkg’}

  • decode_uri(@layer, 'path') → ‘C:\my_data\qgis\shape.shp’

14.3.16. Maps Functions

This group contains functions to create or manipulate keys and values of map data structures (also known as dictionary objects, key-value pairs, or associative arrays). Unlike the list data structure where values order matters, the order of the key-value pairs in the map object is not relevant and values are identified by their keys.

14.3.16.1. from_json

Loads a JSON formatted string.

Syntax

from_json(string)

Arguments

  • string - JSON string

Examples

  • from_json('{"qgis":"rocks"}') → { ‘qgis’: ‘rocks’ }

  • from_json('[1,2,3]') → [1,2,3]

14.3.16.2. hstore_to_map

Creates a map from a hstore-formatted string.

Syntax

hstore_to_map(string)

Arguments

  • string - the input string

Examples

  • hstore_to_map('qgis=>rocks') → { ‘qgis’: ‘rocks’ }

14.3.16.3. json_to_map

Creates a map from a json-formatted string.

Syntax

json_to_map(string)

Arguments

  • string - the input string

Examples

  • json_to_map('{"qgis":"rocks"}') → { ‘qgis’: ‘rocks’ }

14.3.16.4. map

Returns a map containing all the keys and values passed as pair of parameters.

Syntax

map(key1, value1, key2, value2, …)

Arguments

  • key - a key (string)

  • value - a value

Examples

  • map('1','one','2', 'two') → { ‘1’: ‘one’, ‘2’: ‘two’ }

14.3.16.5. map_akeys

Returns all the keys of a map as an array.

Syntax

map_akeys(map)

Arguments

  • map - a map

Examples

  • map_akeys(map('1','one','2','two')) → [ ‘1’, ‘2’ ]

14.3.16.6. map_avals

Returns all the values of a map as an array.

Syntax

map_avals(map)

Arguments

  • map - a map

Examples

  • map_avals(map('1','one','2','two')) → [ ‘one’, ‘two’ ]

14.3.16.7. map_concat

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.

Syntax

map_concat(map1, map2, …)

Arguments

  • map - a map

Examples

  • map_concat(map('1','one', '2','overridden'),map('2','two', '3','three')) → { ‘1’: ‘one’, ‘2’: ‘two’, ‘3’: ‘three’ }

14.3.16.8. map_delete

Returns a map with the given key and its corresponding value deleted.

Syntax

map_delete(map, key)

Arguments

  • map - a map

  • key - the key to delete

Examples

  • map_delete(map('1','one','2','two'),'2') → { ‘1’: ‘one’ }

14.3.16.9. map_exist

Returns true if the given key exists in the map.

Syntax

map_exist(map, key)

Arguments

  • map - a map

  • key - the key to lookup

Examples

  • map_exist(map('1','one','2','two'),'3') → false

14.3.16.10. map_get

Returns the value of a map, given its key. Returns NULL if the key does not exist.

Syntax

map_get(map, key)

Arguments

  • map - a map

  • key - the key to lookup

Examples

  • map_get(map('1','one','2','two'),'2') → ‘two’

  • map_get( item_variables('Map 0'), 'map_scale') → scale of the item ‘Map 0’ (if it exists) in the current print layout

14.3.16.11. map_insert

Returns a map with an added key/value. If the key already exists, its value is overridden.

Syntax

map_insert(map, key, value)

Arguments

  • map - a map

  • key - the key to add

  • value - the value to add

Examples

  • map_insert(map('1','one'),'3','three') → { ‘1’: ‘one’, ‘3’: ‘three’ }

  • map_insert(map('1','one','2','overridden'),'2','two') → { ‘1’: ‘one’, ‘2’: ‘two’ }

14.3.16.12. map_to_hstore

Merge map elements into a hstore-formatted string.

Syntax

map_to_hstore(map)

Arguments

  • map - the input map

Examples

  • map_to_hstore(map('qgis','rocks')) → ‘“qgis”=>”rocks”’

14.3.16.13. map_to_json

Merge map elements into a json-formatted string.

Syntax

map_to_json(map)

Arguments

  • map - the input map

Examples

  • map_to_json(map('qgis','rocks')) → {“qgis”:”rocks”}

14.3.16.14. to_json

Create a JSON formatted string from a map, array or other value.

Syntax

to_json(value)

Arguments

  • value - The input value

Examples

  • to_json(map('qgis','rocks')) → {“qgis”:”rocks”}

  • to_json(array(1,2,3)) → [1,2,3]

14.3.17. Mathematical Functions

This group contains math functions (e.g., square root, sin and cos).

14.3.17.1. abs

Returns the absolute value of a number.

Syntax

abs(value)

Arguments

  • value - a number

Examples

  • abs(-2) → 2

14.3.17.2. acos

Returns the inverse cosine of a value in radians.

Syntax

acos(value)

Arguments

  • value - cosine of an angle in radians

Examples

  • acos(0.5) → 1.0471975511966

14.3.17.3. asin

Returns the inverse sine of a value in radians.

Syntax

asin(value)

Arguments

  • value - sine of an angle in radians

Examples

  • asin(1.0) → 1.5707963267949

14.3.17.4. atan

Returns the inverse tangent of a value in radians.

Syntax

atan(value)

Arguments

  • value - tan of an angle in radians

Examples

  • atan(0.5) → 0.463647609000806

14.3.17.5. atan2

Returns the inverse tangent of dy/dx by using the signs of the two arguments to determine the quadrant of the result.

Syntax

atan2(dy, dx)

Arguments

  • dy - y coordinate difference

  • dx - x coordinate difference

Examples

  • atan2(1.0, 1.732) → 0.523611477769969

14.3.17.6. azimuth

Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.

Syntax

azimuth(point_a, point_b)

Arguments

  • point_a - point geometry

  • point_b - point geometry

Examples

  • degrees( azimuth( make_point(25, 45), make_point(75, 100) ) ) → 42.273689

  • degrees( azimuth( make_point(75, 100), make_point(25,45) ) ) → 222.273689

14.3.17.7. ceil

Rounds a number upwards.

Syntax

ceil(value)

Arguments

  • value - a number

Examples

  • ceil(4.9) → 5

  • ceil(-4.9) → -4

14.3.17.8. clamp

Restricts an input value to a specified range.

Syntax

clamp(minimum, input, maximum)

Arguments

  • minimum - the smallest value input is allowed to take.

  • input - a value which will be restricted to the range specified by minimum and maximum

  • maximum - the largest value input is allowed to take

Examples

  • clamp(1,5,10) → 5

    input is between 1 and 10 so is returned unchanged

  • clamp(1,0,10) → 1

    input is less than minimum value of 1, so function returns 1

  • clamp(1,11,10) → 10

    input is greater than maximum value of 10, so function returns 10

14.3.17.9. cos

Returns cosine of an angle.

Syntax

cos(angle)

Arguments

  • angle - angle in radians

Examples

  • cos(1.571) → 0.000796326710733263

14.3.17.10. degrees

Converts from radians to degrees.

Syntax

degrees(radians)

Arguments

  • radians - numeric value

Examples

  • degrees(3.14159) → 180

  • degrees(1) → 57.2958

14.3.17.11. exp

Returns exponential of an value.

Syntax

exp(value)

Arguments

  • value - number to return exponent of

Examples

  • exp(1.0) → 2.71828182845905

14.3.17.12. floor

Rounds a number downwards.

Syntax

floor(value)

Arguments

  • value - a number

Examples

  • floor(4.9) → 4

  • floor(-4.9) → -5

14.3.17.13. inclination

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

Syntax

inclination(point_a, point_b)

Arguments

  • point_a - point geometry

  • point_b - point geometry

Examples

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, 5 ) ) → 0.0

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, 0 ) ) → 90.0

  • inclination( make_point( 5, 10, 0 ), make_point( 50, 100, 0 ) ) → 90.0

  • inclination( make_point( 5, 10, 0 ), make_point( 5, 10, -5 ) ) → 180.0

14.3.17.14. ln

Returns the natural logarithm of a value.

Syntax

ln(value)

Arguments

  • value - numeric value

Examples

  • ln(1) → 0

  • ln(2.7182818284590452354) → 1

14.3.17.15. log

Returns the value of the logarithm of the passed value and base.

Syntax

log(base, value)

Arguments

  • base - any positive number

  • value - any positive number

Examples

  • log(2, 32) → 5

  • log(0.5, 32) → -5

14.3.17.16. log10

Returns the value of the base 10 logarithm of the passed expression.

Syntax

log10(value)

Arguments

  • value - any positive number

Examples

  • log10(1) → 0

  • log10(100) → 2

14.3.17.17. max

Returns the largest value in a set of values.

Syntax

max(value1, value2, …)

Arguments

  • value - a number

Examples

  • max(2,10.2,5.5) → 10.2

  • max(20.5,NULL,6.2) → 20.5

14.3.17.18. min

Returns the smallest value in a set of values.

Syntax

min(value1, value2, …)

Arguments

  • value - a number

Examples

  • min(20.5,10,6.2) → 6.2

  • min(2,-10.3,NULL) → -10.3

14.3.17.19. pi

Returns value of pi for calculations.

Syntax

pi()

Examples

  • pi() → 3.14159265358979

14.3.17.20. radians

Converts from degrees to radians.

Syntax

radians(degrees)

Arguments

  • degrees - numeric value

Examples

  • radians(180) → 3.14159

  • radians(57.2958) → 1

14.3.17.21. rand

Returns a random integer within the range specified by the minimum and maximum argument (inclusive). If a seed is provided, the returned will always be the same, depending on the seed.

Syntax

rand(min, max, [seed=NULL])

[] marks optional arguments

Arguments

  • min - an integer representing the smallest possible random number desired

  • max - an integer representing the largest possible random number desired

  • seed - any value to use as seed

Examples

  • rand(1, 10) → 8

14.3.17.22. randf

Returns a random float within the range specified by the minimum and maximum argument (inclusive). If a seed is provided, the returned will always be the same, depending on the seed.

Syntax

randf([min=0.0], [max=1.0], [seed=NULL])

[] marks optional arguments

Arguments

  • min - an float representing the smallest possible random number desired

  • max - an float representing the largest possible random number desired

  • seed - any value to use as seed

Examples

  • randf(1, 10) → 4.59258286403147

14.3.17.23. round

Rounds a number to number of decimal places.

Syntax

round(value, [places=0])

[] marks optional arguments

Arguments

  • value - decimal number to be rounded

  • places - Optional integer representing number of places to round decimals to. Can be negative.

Examples

  • round(1234.567, 2) → 1234.57

  • round(1234.567) → 1235

14.3.17.24. scale_exp

Transforms a given value from an input domain to an output range using an exponential curve. This function can be used to ease values in or out of the specified output range.

Syntax

scale_exp(value, domain_min, domain_max, range_min, range_max, exponent)

Arguments

  • value - A value in the input domain. The function will return a corresponding scaled value in the output range.

  • domain_min - Specifies the minimum value in the input domain, the smallest value the input value should take.

  • domain_max - Specifies the maximum value in the input domain, the largest value the input value should take.

  • range_min - Specifies the minimum value in the output range, the smallest value which should be output by the function.

  • range_max - Specifies the maximum value in the output range, the largest value which should be output by the function.

  • exponent - A positive value (greater than 0), which dictates the way input values are mapped to the output range. Large exponents will cause the output values to ‘ease in’, starting slowly before accelerating as the input values approach the domain maximum. Smaller exponents (less than 1) will cause output values to ‘ease out’, where the mapping starts quickly but slows as it approaches the domain maximum.

Examples

  • scale_exp(5,0,10,0,100,2) → 25

    easing in, using an exponent of 2

  • scale_exp(3,0,10,0,100,0.5) → 54.772

    easing out, using an exponent of 0.5

14.3.17.25. scale_linear

Transforms a given value from an input domain to an output range using linear interpolation.

Syntax

scale_linear(value, domain_min, domain_max, range_min, range_max)

Arguments

  • value - A value in the input domain. The function will return a corresponding scaled value in the output range.

  • domain_min - Specifies the minimum value in the input domain, the smallest value the input value should take.

  • domain_max - Specifies the maximum value in the input domain, the largest value the input value should take.

  • range_min - Specifies the minimum value in the output range, the smallest value which should be output by the function.

  • range_max - Specifies the maximum value in the output range, the largest value which should be output by the function.

Examples

  • scale_linear(5,0,10,0,100) → 50

  • scale_linear(0.2,0,1,0,360) → 72

    scaling a value between 0 and 1 to an angle between 0 and 360

  • scale_linear(1500,1000,10000,9,20) → 9.6111111

    scaling a population which varies between 1000 and 10000 to a font size between 9 and 20

14.3.17.26. sin

Returns the sine of an angle.

Syntax

sin(angle)

Arguments

  • angle - angle in radians

Examples

  • sin(1.571) → 0.999999682931835

14.3.17.27. sqrt

Returns square root of a value.

Syntax

sqrt(value)

Arguments

  • value - a number

Examples

  • sqrt(9) → 3

14.3.17.28. tan

Returns the tangent of an angle.

Syntax

tan(angle)

Arguments

  • angle - angle in radians

Examples

  • tan(1.0) → 1.5574077246549

14.3.18. Operators

This group contains operators (e.g., +, -, *). Note that for most of the mathematical functions below, if one of the inputs is NULL then the result is NULL.

Function

Description

a + b

Addition of two values (a plus b)

a - b

Subtraction of two values (a minus b).

a * b

Multiplication of two values (a multiplied by b)

a / b

Division of two values (a divided by b)

a % b

Remainder of division of a by b (eg, 7 % 2 = 1, or 2 fits into 7 three times with remainder 1)

a ^ b

Power of two values (for example, 2^2=4 or 2^3=8)

a < b

Compares two values and evaluates to 1 if the left value is less than the right value (a is smaller than b)

a <= b

Compares two values and evaluates to 1 if the left value is less than or equal to the right value

a <> b

Compares two values and evaluates to 1 if they are not equal

a = b

Compares two values and evaluates to 1 if they are equal

a != b

a and b are not equal

a > b

Compares two values and evaluates to 1 if the left value is greater than the right value (a is larger than b)

a >= b

Compares two values and evaluates to 1 if the left value is greater than or equal to the right value

a ~ b

a matches the regular expression b

||

Joins two values together into a string. If one of the values is NULL the result will be NULL

‘\n’

Inserts a new line in a string

LIKE

Returns 1 if the first parameter matches the supplied pattern

ILIKE

Returns 1 if the first parameter matches case-insensitive the supplied pattern (ILIKE can be used instead of LIKE to make the match case-insensitive)

a IS b

Tests whether two values are identical. Returns 1 if a is the same as b

a OR b

Returns 1 when condition a or condition b is true

a AND b

Returns 1 when conditions a and b are true

NOT

Negates a condition

“Column_name”

Value of the field Column_name, take care to not be confused with simple quote, see below

‘string’

a string value, take care to not be confused with double quote, see above

NULL

null value

a IS NULL

a has no value

a IS NOT NULL

a has a value

a IN (value[,value])

a is below the values listed

a NOT IN (value[,value])

a is not below the values listed

Some examples:

  • Joins a string and a value from a column name:

    'My feature''s id is: ' || "gid"
    
  • Test if the “description” attribute field starts with the ‘Hello’ string in the value (note the position of the % character):

    "description" LIKE 'Hello%'
    

14.3.19. Processing Functions

This group contains functions that operate on processing algorithms.

14.3.19.1. parameter

Returns the value of a processing algorithm input parameter.

Syntax

parameter(name)

Arguments

  • name - name of the corresponding input parameter

Examples

  • parameter('BUFFER_SIZE') → 5.6

14.3.20. Rasters Functions

This group contains functions to operate on raster layer.

14.3.20.1. raster_statistic

Returns statistics from a raster layer.

Syntax

raster_statistic(layer, band, property)

Arguments

  • layer - a string, representing either a raster layer name or layer ID

  • band - integer representing the band number from the raster layer, starting at 1

  • property - a string corresponding to the property to return. Valid options are:

    • min: minimum value

    • max: maximum value

    • avg: average (mean) value

    • stdev: standard deviation of values

    • range: range of values (max - min)

    • sum: sum of all values from raster

Examples

  • raster_statistic('lc',1,'avg') → Average value from band 1 from ‘lc’ raster layer

  • raster_statistic('ac2010',3,'min') → Minimum value from band 3 from ‘ac2010’ raster layer

14.3.20.2. raster_value

Returns the raster value found at the provided point.

Syntax

raster_value(layer, band, point)

Arguments

  • layer - the name or id of a raster layer

  • band - the band number to sample the value from.

  • point - point geometry (for multipart geometries having more than one part, a NULL value will be returned)

Examples

  • raster_value('dem', 1, make_point(1,1)) → 25

14.3.21. Record and Attributes Functions

This group contains functions that operate on record identifiers.

14.3.21.1. attribute

Returns an attribute from a feature.

Variant 1

Returns the value of an attribute from the current feature.

Syntax

attribute(attribute_name)

Arguments

  • attribute_name - name of attribute to be returned

Examples

  • attribute( 'name' ) → value stored in ‘name’ attribute for the current feature

Variant 2

Allows the target feature and attribute name to be specified.

Syntax

attribute(feature, attribute_name)

Arguments

  • feature - a feature

  • attribute_name - name of attribute to be returned

Examples

  • attribute( @atlas_feature, 'name' ) → value stored in ‘name’ attribute for the current atlas feature

14.3.21.2. attributes

Returns a map containing all attributes from a feature, with field names as map keys.

Variant 1

Returns a map of all attributes from the current feature.

Syntax

attributes()

Examples

  • attributes()['name'] → value stored in ‘name’ attribute for the current feature

Variant 2

Allows the target feature to be specified.

Syntax

attributes(feature)

Arguments

  • feature - a feature

Examples

  • attributes( @atlas_feature )['name'] → value stored in ‘name’ attribute for the current atlas feature

Further reading: Maps Functions

14.3.21.3. $currentfeature

Returns the current feature being evaluated. This can be used with the ‘attribute’ function to evaluate attribute values from the current feature.

Syntax

$currentfeature

Examples

  • attribute( $currentfeature, 'name' ) → value stored in ‘name’ attribute for the current feature

14.3.21.4. display_expression

Returns the display expression for a given feature in a layer. The expression is evaluated by default. Can be used with zero, one or more arguments, see below for details.

No parameters

If called with no parameters, the function will evaluate the display expression of the current feature in the current layer.

Syntax

display_expression()

Examples

  • display_expression() → The display expression of the current feature in the current layer.

One ‘feature’ parameter

If called with a ‘feature’ parameter only, the function will evaluate the specified feature from the current layer.

Syntax

display_expression(feature)

Arguments

  • feature - The feature which should be evaluated.

Examples

  • display_expression(@atlas_feature) → The display expression of the current atlas feature.

Layer and feature parameters

If the function is called with both a layer and a feature, it will evaluate the specified feature from the specified layer.

Syntax

display_expression(layer, feature, [evaluate=true])

[] marks optional arguments

Arguments

  • layer - The layer (or its ID or name)

  • feature - The feature which should be evaluated.

  • evaluate - If the expression must be evaluated. If false, the expression will be returned as a string literal only (which could potentially be later evaluated using the ‘eval’ function).

Examples

  • display_expression( 'streets', get_feature_by_id('streets', 1)) → The display expression of the feature with the ID 1 on the layer ‘streets’.

  • display_expression('a_layer_id', $currentfeature, 'False') → The display expression of the given feature not evaluated.

14.3.21.5. get_feature

Returns the first feature of a layer matching a given attribute value.

Syntax

get_feature(layer, attribute, value)

Arguments

  • layer - layer name or ID

  • attribute - attribute name

  • value - attribute value to match

Examples

  • get_feature('streets','name','main st') → first feature found in “streets” layer with “main st” value in the “name” field

14.3.21.6. get_feature_by_id

Returns the feature with an id on a layer.

Syntax

get_feature_by_id(layer, feature_id)

Arguments

  • layer - layer, layer name or layer id

  • feature_id - the id of the feature which should be returned

Examples

  • get_feature_by_id('streets', 1) → the feature with the id 1 on the layer “streets”

Further reading: $id

14.3.21.7. $id

Returns the feature id of the current row.

Syntax

$id

Examples

  • $id → 42

14.3.21.8. is_selected

Returns True if a feature is selected. Can be used with zero, one or two arguments, see below for details.

No parameters

If called with no parameters, the function will return true if the current feature in the current layer is selected.

Syntax

is_selected()

Examples

  • is_selected() → True if the current feature in the current layer is selected.

One ‘feature’ parameter

If called with a ‘feature’ parameter only, the function returns true if the specified feature from the current layer is selected.

Syntax

is_selected(feature)

Arguments

  • feature - The feature which should be checked for selection.

Examples

  • is_selected(@atlas_feature) → True if a selected feature on the current layer is the active atlas feature.

  • is_selected(get_feature(@layer, 'name', 'Main St.'))) → True if the unique named “Main St.” feature on the current layer is selected.

  • is_selected(get_feature_by_id(@layer, 1)) → True if the feature with the id 1 on the current layer is selected.

Two parameters

If the function is called with both a layer and a feature, it will return true if the specified feature from the specified layer is selected.

Syntax

is_selected(layer, feature)

Arguments

  • layer - The layer (its ID or name) on which the selection will be checked.

  • feature - The feature which should be checked for selection.

Examples

  • is_selected( 'streets', get_feature('streets', 'name', "street_name")) → True if the current building’s street is selected (assuming the building layer has a field named ‘street_name’ and the ‘streets’ layer has a field called ‘name’ with unique values).

  • is_selected( 'streets', get_feature_by_id('streets', 1)) → True if the feature with the id 1 on the “streets” layer is selected.

14.3.21.9. maptip

Returns the maptip for a given feature in a layer. The expression is evaluated by default. Can be used with zero, one or more arguments, see below for details.

No parameters

If called with no parameters, the function will evaluate the maptip of the current feature in the current layer.

Syntax

maptip()

Examples

  • maptip() → The maptip of the current feature in the current layer.

One ‘feature’ parameter

If called with a ‘feature’ parameter only, the function will evaluate the specified feature from the current layer.

Syntax

maptip(feature)

Arguments

  • feature - The feature which should be evaluated.

Examples

  • maptip(@atlas_feature) → The maptip of the current atlas feature.

Layer and feature parameters

If the function is called with both a layer and a feature, it will evaluate the specified feature from the specified layer.

Syntax

maptip(layer, feature, [evaluate=true])

[] marks optional arguments

Arguments

  • layer - The layer (or its ID or name)

  • feature - The feature which should be evaluated.

  • evaluate - If the expression must be evaluated. If false, the expression will be returned as a string literal only (which could potentially be later evaluated using the ‘eval_template’ function).

Examples

  • maptip('streets', get_feature_by_id('streets', 1)) → The maptip of the feature with the ID 1 on the layer ‘streets’.

  • maptip('a_layer_id', $currentfeature, 'False') → The maptip of the given feature not evaluated.

14.3.21.10. num_selected

Returns the number of selected features on a given layer. By default works on the layer on which the expression is evaluated.

Syntax

num_selected([layer=current layer])

[] marks optional arguments

Arguments

  • layer - The layer (or its id or name) on which the selection will be checked.

Examples

  • num_selected() → The number of selected features on the current layer.

  • num_selected('streets') → The number of selected features on the layer streets

14.3.21.11. represent_value

Returns the configured representation value for a field value. It depends on the configured widget type. Often, this is useful for ‘Value Map’ widgets.

Syntax

represent_value(value, fieldName)

Arguments

  • value - The value which should be resolved. Most likely a field.

  • fieldName - The field name for which the widget configuration should be loaded. (Optional)

Examples

  • represent_value("field_with_value_map") → Description for value

  • represent_value('static value', 'field_name') → Description for static value

Further reading: widget types

14.3.21.12. sqlite_fetch_and_increment

Manage autoincrementing values in sqlite databases.

SQlite default values can only be applied on insert and not prefetched.

This makes it impossible to acquire an incremented primary key via AUTO_INCREMENT before creating the row in the database. Sidenote: with postgres, this works via the option evaluate default values.

When adding new features with relations, it is really nice to be able to already add children for a parent, while the parents form is still open and hence the parent feature uncommitted.

To get around this limitation, this function can be used to manage sequence values in a separate table on sqlite based formats like gpkg.

The sequence table will be filtered for a sequence id (filter_attribute and filter_value) and the current value of the id_field will be incremented by 1 and the incremented value returned.

If additional columns require values to be specified, the default_values map can be used for this purpose.

Note

This function modifies the target sqlite table. It is intended for usage with default value configurations for attributes.

When the database parameter is a layer and the layer is in transaction mode, the value will only be retrieved once during the lifetime of a transaction and cached and incremented. This makes it unsafe to work on the same database from several processes in parallel.

Syntax

sqlite_fetch_and_increment(database, table, id_field, filter_attribute, filter_value, [default_values])

[] marks optional arguments

Arguments

  • database - Path to the sqlite file or geopackage layer

  • table - Name of the table that manages the sequences

  • id_field - Name of the field that contains the current value

  • filter_attribute - Name the field that contains a unique identifier for this sequence. Must have a UNIQUE index.

  • filter_value - Name of the sequence to use.

  • default_values - Map with default values for additional columns on the table. The values need to be fully quoted. Functions are allowed.

Examples

  • sqlite_fetch_and_increment(@layer, 'sequence_table', 'last_unique_id', 'sequence_id', 'global', map('last_change', 'date(''now'')', 'user', '''' || @user_account_name || '''')) → 0

  • sqlite_fetch_and_increment(layer_property(@layer, 'path'), 'sequence_table', 'last_unique_id', 'sequence_id', 'global', map('last_change', 'date(''now'')', 'user', '''' || @user_account_name || '''')) → 0

Further reading: Data Sources Properties, Creating one or many to many relations

14.3.21.13. uuid

Generates a Universally Unique Identifier (UUID) for each row using the Qt QUuid::createUuid method. Each UUID is 38 characters long.

Syntax

uuid()

Examples

  • uuid() → ‘{0bd2f60f-f157-4a6d-96af-d4ba4cb366a1}’

14.3.22. Relations

This group contains the list of the relations available in the current project, with their description. It provides a quick access to the relation ID for writing an expression (with e.g. the relation_aggregate function) or customizing a form.

14.3.23. String Functions

This group contains functions that operate on strings (e.g., that replace, convert to upper case).

14.3.23.1. ascii

Returns the unicode code associated with the first character of a string.

Syntax

ascii(string)

Arguments

  • string - the string to convert to unicode code

Examples

  • ascii('Q') → 81

14.3.23.2. char

Returns the character associated with a unicode code.

Syntax

char(code)

Arguments

  • code - a unicode code number

Examples

  • char(81) → ‘Q’

14.3.23.3. concat

Concatenates several strings to one. NULL values are converted to empty strings. Other values (like numbers) are converted to strings.

Syntax

concat(string1, string2, …)

Arguments

  • string - a string value

Examples

  • concat('sun', 'set') → ‘sunset’

  • concat('a','b','c','d','e') → ‘abcde’

  • concat('Anno ', 1984) → ‘Anno 1984’

  • concat('The Wall', NULL) → ‘The Wall’

About fields concatenation

You can also concatenate strings or field values using either || or + operators, with some special characteristics:

  • The + operator also means sum up expression, so if you have an integer (field or numeric value) operand, this can be error prone and you better use the others:

    'My feature id is: ' + "gid" => triggers an error as gid returns an integer
    
  • When any of the arguments is a NULL value, either || or + will return a NULL value. To return the other arguments regardless the NULL value, you may want to use the concat function:

    'My feature id is: ' + NULL ==> NULL
    'My feature id is: ' || NULL => NULL
    concat('My feature id is: ', NULL) => 'My feature id is: '
    

14.3.23.4. format

Format a string using supplied arguments.

Syntax

format(string, arg1, arg2, …)

Arguments

  • string - A string with place holders for the arguments. Use %1, %2, etc for placeholders. Placeholders can be repeated.

  • arg - any type. Any number of arguments.

Examples

  • format('This %1 a %2','is', 'test') → ‘This is a test’

14.3.23.5. format_date

Formats a date type or string into a custom string format. Uses Qt date/time format strings. See QDateTime::toString.

Syntax

format_date(datetime, format, [language])

[] marks optional arguments

Arguments

  • datetime - date, time or datetime value

  • format - String template used to format the string.

    Expression

    Output

    d

    the day as number without a leading zero (1 to 31)

    dd

    the day as number with a leading zero (01 to 31)

    ddd

    the abbreviated localized day name (e.g. ‘Mon’ to ‘Sun’)

    dddd

    the long localized day name (e.g. ‘Monday’ to ‘Sunday’)

    M

    the month as number without a leading zero (1-12)

    MM

    the month as number with a leading zero (01-12)

    MMM

    the abbreviated localized month name (e.g. ‘Jan’ to ‘Dec’)

    MMMM

    the long localized month name (e.g. ‘January’ to ‘December’)

    yy

    the year as two digit number (00-99)

    yyyy

    the year as four digit number

    These expressions may be used for the time part of the format string:

    Expression

    Output

    h

    the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)

    hh

    the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)

    H

    the hour without a leading zero (0 to 23, even with AM/PM display)

    HH

    the hour with a leading zero (00 to 23, even with AM/PM display)

    m

    the minute without a leading zero (0 to 59)

    mm

    the minute with a leading zero (00 to 59)

    s

    the second without a leading zero (0 to 59)

    ss

    the second with a leading zero (00 to 59)

    z

    the milliseconds without trailing zeroes (0 to 999)

    zzz

    the milliseconds with trailing zeroes (000 to 999)

    AP or A

    interpret as an AM/PM time. AP must be either ‘AM’ or ‘PM’.

    ap or a

    Interpret as an AM/PM time. ap must be either ‘am’ or ‘pm’.

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to format the date into a custom string

Examples

  • format_date('2012-05-15','dd.MM.yyyy') → ‘15.05.2012’

  • format_date('2012-05-15','d MMMM yyyy','fr') → ‘15 mai 2012’

  • format_date('2012-05-15','dddd') → ‘Tuesday’

  • format_date('2012-05-15 13:54:20','dd.MM.yy') → ‘15.05.12’

  • format_date('13:54:20','hh:mm AP') → ‘01:54 PM’

14.3.23.6. format_number

Returns a number formatted with the locale separator for thousands. Also truncates the decimal places to the number of supplied places.

Syntax

format_number(number, places, [language])

[] marks optional arguments

Arguments

  • number - number to be formatted

  • places - integer representing the number of decimal places to truncate the string to.

  • language - language (lowercase, two- or three-letter, ISO 639 language code) used to format the number into a string

Examples

  • format_number(10000000.332,2) → ‘10,000,000.33’

  • format_number(10000000.332,2,'fr') → ‘10 000 000,33’

14.3.23.7. left

Returns a substring that contains the n leftmost characters of the string.

Syntax

left(string, length)

Arguments

  • string - a string

  • length - integer. The number of characters from the left of the string to return.

Examples

  • left('Hello World',5) → ‘Hello’

14.3.23.8. length

Returns the number of characters in a string or the length of a geometry linestring.

String variant

Returns the number of characters in a string.

Syntax

length(string)

Arguments

  • string - string to count length of

Examples

  • length('hello') → 5

Geometry variant

Calculate the length of a geometry line object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned length will match the units for the SRS. This differs from the calculations performed by the $length function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.

Syntax

length(geometry)

Arguments

  • geometry - line geometry object

Examples

  • length(geom_from_wkt('LINESTRING(0 0, 4 0)')) → 4.0

14.3.23.9. lower

Converts a string to lower case letters.

Syntax

lower(string)

Arguments

  • string - the string to convert to lower case

Examples

  • lower('HELLO World') → ‘hello world’

14.3.23.10. lpad

Returns a string padded on the left to the specified width, using a fill character. If the target width is smaller than the string’s length, the string is truncated.

Syntax

lpad(string, width, fill)

Arguments

  • string - string to pad

  • width - length of new string

  • fill - character to pad the remaining space with

Examples

  • lpad('Hello', 10, 'x') → ‘xxxxxHello’

  • lpad('Hello', 3, 'x') → ‘Hel’

14.3.23.11. regexp_match

Return the first matching position matching a regular expression within an unicode string, or 0 if the substring is not found.

Syntax

regexp_match(input_string, regex)

Arguments

  • input_string - the string to test against the regular expression

  • regex - The regular expression to test against. Backslash characters must be double escaped (e.g., “\\s” to match a white space character or “\\b” to match a word boundary).

Examples

  • regexp_match('QGIS ROCKS','\\sROCKS') → 5

  • regexp_match('Budač','udač\\b') → 2

14.3.23.12. regexp_replace

Returns a string with the supplied regular expression replaced.

Syntax

regexp_replace(input_string, regex, replacement)

Arguments

  • input_string - the string to replace matches in

  • regex - The regular expression to replace. Backslash characters must be double escaped (e.g., “\\s” to match a white space character).

  • replacement - The string that will replace any matching occurrences of the supplied regular expression. Captured groups can be inserted into the replacement string using \\1, \\2, etc.

Examples

  • regexp_replace('QGIS SHOULD ROCK','\\sSHOULD\\s',' DOES ') → ‘QGIS DOES ROCK’

  • regexp_replace('ABC123','\\d+','') → ‘ABC’

  • regexp_replace('my name is John','(.*) is (.*)','\\2 is \\1') → ‘John is my name’

14.3.23.13. regexp_substr

Returns the portion of a string which matches a supplied regular expression.

Syntax

regexp_substr(input_string, regex)

Arguments

  • input_string - the string to find matches in

  • regex - The regular expression to match against. Backslash characters must be double escaped (e.g., “\\s” to match a white space character).

Examples

  • regexp_substr('abc123','(\\d+)') → ‘123’

14.3.23.14. replace

Returns a string with the supplied string, array, or map of strings replaced.

String & array variant

Returns a string with the supplied string or array of strings replaced by a string or an array of strings.

Syntax

replace(string, before, after)

Arguments

  • string - the input string

  • before - the string or array of strings to replace

  • after - the string or array of strings to use as a replacement

Examples

  • replace('QGIS SHOULD ROCK','SHOULD','DOES') → ‘QGIS DOES ROCK’

  • replace('QGIS ABC',array('A','B','C'),array('X','Y','Z')) → ‘QGIS XYZ’

  • replace('QGIS',array('Q','S'),'') → ‘GI’

Map variant

Returns a string with the supplied map keys replaced by paired values.

Syntax

replace(string, map)

Arguments

  • string - the input string

  • map - the map containing keys and values

Examples

  • replace('APP SHOULD ROCK',map('APP','QGIS','SHOULD','DOES')) → ‘QGIS DOES ROCK’

14.3.23.16. rpad

Returns a string padded on the right to the specified width, using a fill character. If the target width is smaller than the string’s length, the string is truncated.

Syntax

rpad(string, width, fill)

Arguments

  • string - string to pad

  • width - length of new string

  • fill - character to pad the remaining space with

Examples

  • rpad('Hello', 10, 'x') → ‘Helloxxxxx’

  • rpad('Hello', 3, 'x') → ‘Hel’

14.3.23.17. strpos

Return the first matching position of a substring within another string, or 0 if the substring is not found.

Syntax

strpos(haystack, needle)

Arguments

  • haystack - string that is to be searched

  • needle - string to search for

Examples

  • strpos('HELLO WORLD','WORLD') → 7

  • strpos('HELLO WORLD','GOODBYE') → 0

14.3.23.18. substr

Returns a part of a string.

Syntax

substr(string, start, [length])

[] marks optional arguments

Arguments

  • string - the full input string

  • start - integer representing start position to extract beginning with 1; if start is negative, the return string will begin at the end of the string minus the start value

  • length - integer representing length of string to extract; if length is negative, the return string will omit the given length of characters from the end of the string

Examples

  • substr('HELLO WORLD',3,5) → ‘LLO W’

  • substr('HELLO WORLD',6) → ‘ WORLD’

  • substr('HELLO WORLD',-5) → ‘WORLD’

  • substr('HELLO',3,-1) → ‘LL’

  • substr('HELLO WORLD',-5,2) → ‘WO’

  • substr('HELLO WORLD',-5,-1) → ‘WORL’

14.3.23.19. title

Converts all words of a string to title case (all words lower case with leading capital letter).

Syntax

title(string)

Arguments

  • string - the string to convert to title case

Examples

  • title('hello WOrld') → ‘Hello World’

14.3.23.20. to_string

Converts a number to string.

Syntax

to_string(number)

Arguments

  • number - Integer or real value. The number to convert to string.

Examples

  • to_string(123) → ‘123’

14.3.23.21. trim

Removes all leading and trailing whitespace (spaces, tabs, etc) from a string.

Syntax

trim(string)

Arguments

  • string - string to trim

Examples

  • trim('   hello world    ') → ‘hello world’

14.3.23.22. upper

Converts a string to upper case letters.

Syntax

upper(string)

Arguments

  • string - the string to convert to upper case

Examples

  • upper('hello WOrld') → ‘HELLO WORLD’

14.3.23.23. wordwrap

Returns a string wrapped to a maximum/minimum number of characters.

Syntax

wordwrap(string, wrap_length, [delimiter_string])

[] marks optional arguments

Arguments

  • string - the string to be wrapped

  • wrap_length - an integer. If wrap_length is positive the number represents the ideal maximum number of characters to wrap; if negative, the number represents the minimum number of characters to wrap.

  • delimiter_string - Optional delimiter string to wrap to a new line.

Examples

  • wordwrap('UNIVERSITY OF QGIS',13) → ‘UNIVERSITY OF<br>QGIS’

  • wordwrap('UNIVERSITY OF QGIS',-3) → ‘UNIVERSITY<br>OF QGIS’

14.3.24. User Expressions

This group contains the expressions saved as user expressions.

14.3.25. Variables

This group contains dynamic variables related to the application, the project file and other settings. The availability of variables depends on the context:

  • from the expressionSelect Select by expression dialog

  • from the calculateField Field calculator dialog

  • from the layer properties dialog

  • from the print layout

To use these variables in an expression, they should be preceded by the @ character (e.g, @row_number).

Variable

Description

algorithm_id

The unique ID of an algorithm

animation_end_time

End of the animation’s overall temporal time range (as a datetime value)

animation_interval

Duration of the animation’s overall temporal time range (as an interval value)

animation_start_time

Start of the animation’s overall temporal time range (as a datetime value)

atlas_feature

The current atlas feature (as feature object)

atlas_featureid

The current atlas feature ID

atlas_featurenumber

The current atlas feature number in the layout

atlas_filename

The current atlas file name

atlas_geometry

The current atlas feature geometry

atlas_layerid

The current atlas coverage layer ID

atlas_layername

The current atlas coverage layer name

atlas_pagename

The current atlas page name

atlas_totalfeatures

The total number of features in atlas

canvas_cursor_point

The last cursor position on the canvas in the project’s geographical coordinates

cluster_color

The color of symbols within a cluster, or NULL if symbols have mixed colors

cluster_size

The number of symbols contained within a cluster

current_feature

The feature currently being edited in the attribute form or table row

current_geometry

The geometry of the feature currently being edited in the form or the table row

current_parent_feature

represents the feature currently being edited in the parent form. Only usable in an embedded form context.

current_parent_geometry

represents the geometry of the feature currently being edited in the parent form. Only usable in an embedded form context.

form_mode

What the form is used for, like AddFeatureMode, SingleEditMode, MultiEditMode, SearchMode, AggregateSearchMode or IdentifyMode as string.

frame_duration

Temporal duration of each animation frame (as an interval value)

frame_number

Current frame number during animation playback

frame_rate

Number of frames per second during animation playback

fullextent_maxx

Maximum x value from full canvas extent (including all layers)

fullextent_maxy

Maximum y value from full canvas extent (including all layers)

fullextent_minx

Minimum x value from full canvas extent (including all layers)

fullextent_miny

Minimum y value from full canvas extent (including all layers)

geometry_part_count

The number of parts in rendered feature’s geometry

geometry_part_num

The current geometry part number for feature being rendered

geometry_point_count

The number of points in the rendered geometry’s part

geometry_point_num

The current point number in the rendered geometry’s part

grid_axis

The current grid annotation axis (eg, ‘x’ for longitude, ‘y’ for latitude)

grid_number

The current grid annotation value

item_id

The layout item user ID (not necessarily unique)

item_uuid

The layout item unique ID

layer

The current layer

layer_id

The ID of current layer

layer_ids

The IDs of all the map layers in the current project as a list

layer_name

The name of current layer

layers

All the map layers in the current project as a list

layout_dpi

The composition resolution (DPI)

layout_name

The layout name

layout_numpages

The number of pages in the layout

layout_page

The page number of the current item in the layout

layout_pageheight

The active page height in the layout (in mm)

layout_pagewidth

The active page width in the layout (in mm)

legend_column_count

The number of columns in the legend

legend_filter_by_map

Indicates if the content of the legend is filtered by the map

legend_filter_out_atlas

Indicates if the atlas is filtered out of the legend

legend_split_layers

Indicates if layers can be split in the legend

legend_title

The title of the legend

legend_wrap_string

The character(s) used to wrap the legend text

map_crs

The Coordinate reference system of the current map

map_crs_acronym

The acronym of the Coordinate reference system of the current map

map_crs_definition

The full definition of the Coordinate reference system of the current map

map_crs_description

The name of the Coordinate reference system of the current map

map_crs_ellipsoid

The acronym of the ellipsoid of the Coordinate reference system of the current map

map_crs_proj4

The Proj4 definition of the Coordinate reference system of the current map

map_crs_wkt

The WKT definition of the Coordinate reference system of the current map

map_end_time

The end of the map’s temporal time range (as a datetime value)

map_extent

The geometry representing the current extent of the map

map_extent_center

The point feature at the center of the map

map_extent_height

The current height of the map

map_extent_width

The current width of the map

map_id

The ID of current map destination. This will be ‘canvas’ for canvas renders, and the item ID for layout map renders

map_interval

The duration of the map’s temporal time range (as an interval value)

map_layer_ids

The list of map layer IDs visible in the map

map_layers

The list of map layers visible in the map

map_rotation

The current rotation of the map

map_scale

The current scale of the map

map_start_time

The start of the map’s temporal time range (as a datetime value)

map_units

The units of map measurements

model_path

Full path (including file name) of current model (or project path if model is embedded in a project).

model_folder

Folder containing current model (or project folder if model is embedded in a project).

model_name

Name of current model

model_group

Group for current model

notification_message

Content of the notification message sent by the provider (available only for actions triggered by provider notifications).

parent

Refers to the current feature in the parent layer, providing access to its attributes and geometry when filtering an aggregate function

project_abstract

The project abstract, taken from project metadata

project_area_units

The area unit for the current project, used when calculating areas of geometries

project_author

The project author, taken from project metadata

project_basename

The basename of current project’s filename (without path and extension)

project_creation_date

The project creation date, taken from project metadata

project_crs

The Coordinate reference system of the project

project_crs_arconym

The acronym of the Coordinate reference system of the project

project_crs_definition

The full definition of the Coordinate reference system of the project

project_crs_description

The description of the Coordinate reference system of the project

project_crs_ellipsoid

The ellipsoid of the Coordinate reference system of the project

project_crs_proj4

The Proj4 representation of the Coordinate reference system of the project

project_crs_wkt

The WKT (well known text) representation of the coordinate reference system of the project

project_distance_units

The distance unit for the current project, used when calculating lengths of geometries and distances

project_ellipsoid

The name of the ellipsoid of the current project, used when calculating geodetic areas or lengths of geometries

project_filename

The filename of the current project

project_folder

The folder of the current project

project_home

The home path of the current project

project_identifier

The project identifier, taken from the project’s metadata

project_keywords

The project keywords, taken from the project’s metadata

project_last_saved

Date/time when project was last saved.

project_path

The full path (including file name) of the current project

project_title

The title of current project

project_units

The units of the project’s CRS

qgis_locale

The current language of QGIS

qgis_os_name

The current Operating system name, eg ‘windows’, ‘linux’ or ‘osx’

qgis_platform

The QGIS platform, eg ‘desktop’ or ‘server’

qgis_release_name

The current QGIS release name

qgis_short_version

The current QGIS version short string

qgis_version

The current QGIS version string

qgis_version_no

The current QGIS version number

row_number

Stores the number of the current row

snapping_results

Gives access to snapping results while digitizing a feature (only available in add feature)

scale_value

The current scale bar distance value

symbol_angle

The angle of the symbol used to render the feature (valid for marker symbols only)

symbol_color

The color of the symbol used to render the feature

symbol_count

The number of features represented by the symbol (in the layout legend)

symbol_id

The Internal ID of the symbol (in the layout legend)

symbol_label

The label for the symbol (either a user defined label or the default autogenerated label - in the layout legend)

symbol_layer_count

Total number of symbol layers in the symbol

symbol_layer_index

Current symbol layer index

symbol_marker_column

Column number for marker (valid for point pattern fills only).

symbol_marker_row

Row number for marker (valid for point pattern fills only).

user_account_name

The current user’s operating system account name

user_full_name

The current user’s operating system user name

value

The current value

with_variable

Allows setting a variable for usage within an expression and avoid recalculating the same value repeatedly

zoom_level

Zoom level of the tile that is being rendered (derived from the current map scale). Normally in interval [0, 20].

Some examples:

  • Return the X coordinate of a map item center in layout:

    x( map_get( item_variables( 'map1'), 'map_extent_center' ) )
    
  • Return, for each feature in the current layer, the number of overlapping airport features:

    aggregate( layer:='airport', aggregate:='count', expression:="code",
                   filter:=intersects( $geometry, geometry( @parent ) ) )
    
  • Get the object_id of the first snapped point of a line:

    with_variable(
      'first_snapped_point',
      array_first( @snapping_results ),
      attribute(
        get_feature_by_id(
          map_get( @first_snapped_point, 'layer' ),
          map_get( @first_snapped_point, 'feature_id' )
        ),
        'object_id'
      )
    )
    

14.3.26. Recent Functions

This group contains recently used functions. Depending on the context of its usage (feature selection, field calculator, generic), recently applied expressions are added to the corresponding list (up to ten expressions), sorted from more to less recent. This makes it easy to quickly retrieve and reapply previously used expressions.