0% found this document useful (0 votes)

37 views

List of Functions - QGIS Documentation Documentation

The document describes various aggregate functions available in QGIS for summarizing and aggregating data from features and fields. It provides the syntax and examples of functions like aggregate(), array_agg(), collect(), concatenate(), count(), and others to calculate values like sums, means, medians, ranges, counts and more in an aggregated manner over layers, fields or expressions.

Uploaded by

atom108

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

37 views

List of Functions - QGIS Documentation Documentation

Uploaded by

atom108

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 148

1. 13.2.

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

• Aggregates Functions
• Array Functions
• Color Functions
• Conditional Functions
• Conversions Functions
• Custom Functions
• Date and Time Functions
• Fields and Values
• Files and Paths Functions
• Form Functions
• Fuzzy Matching Functions
• General Functions
• Geometry Functions
• Layout Functions
• Map Layers
• Maps Functions
• Mathematical Functions
• Meshes Functions
• Operators
• Processing Functions
• Rasters Functions
• Record and Attributes Functions
• Relations
• String Functions
• User Expressions
• Variables
• Recent Functions

1. 13.2.1. Aggregates Functions

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

• aggregate
• array_agg
• collect
• concatenate
• concatenate_unique
• count
• count_distinct
• count_missing
• iqr
• majority
• max_length
• maximum
• mean
• median
• min_length
• minimum
• minority
• q1
• q3
• range
• relation_aggregate
• stdev
• sum

2. 13.2.1.1. aggregate

Returns an aggregate value calculated using features from another layer.

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

Syntax
[] marks optional arguments
• layer - a string, representing either a layer name or layer ID
• aggregate - a string corresponding to the aggregate to calculate. Valid options are:
o count
o count_distinct
o count_missing
o min
o max
o sum
o mean
o median
o stdev
o stdevsample
o range
o minority
o majority
o q1: first quartile
Argumen o q3: third quartile
ts o iqr: inter quartile range
o min_length: minimum string length
o max_length: maximum string length
o concatenate: join strings with a concatenator
o concatenate_unique: join unique strings with a concatenator
o collect: create an aggregated multipart geometry
o 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’ and ‘concatenate_unique’
aggregates
• 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.

• 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
Examples “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

3. 13.2.1.2. array_agg

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

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

Syntax
[] marks optional 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
Arguments
• order_by - optional expression to use to order features used to calculate aggregate. By default, the
features will be returned in an unspecified order.

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

Examples

4. 13.2.1.3. collect

Returns the multipart geometry of aggregated geometries from an expression

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

Syntax
[] marks optional arguments
• expression - geometry expression to aggregate
• group_by - optional expression to use to group aggregate calculations
Arguments
• filter - optional expression to use to filter features used to calculate aggregate

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

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

5. 13.2.1.4. concatenate

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

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

Syntax
[] marks optional 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
Arguments • 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.

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

Examples town_names, grouped by state field

6. 13.2.1.5. concatenate_unique

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

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

Syntax
[] marks optional 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
Arguments • 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.

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

7. 13.2.1.6. count

Returns the count of matching features.

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

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

Examples

8. 13.2.1.7. count_distinct

Returns the count of distinct values.

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

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

Examples by state field

9. 13.2.1.8. count_missing

Returns the count of missing (NULL) values.

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

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

Examples grouped by state field

10. 13.2.1.9. iqr

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

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

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

Examples state field

11. 13.2.1.10. majority

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

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

Syntax
[] marks optional arguments
• expression - sub expression of field to aggregate
• group_by - optional expression to use to group aggregate calculations
Arguments
• filter - optional expression to use to filter features used to calculate aggregate
• majority("class",group_by:="state") → most commonly occurring class value, grouped by
Examples state field

12. 13.2.1.11. max_length

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

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

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

Examples state field

13. 13.2.1.12. maximum

Returns the aggregate maximum value from a field or expression.

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

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

Examples field

14. 13.2.1.13. mean

Returns the aggregate mean value from a field or expression.

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

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

Examples

15. 13.2.1.14. median

Returns the aggregate median value from a field or expression.

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

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

Examples

16. 13.2.1.15. min_length

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

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

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

Examples state field

17. 13.2.1.16. minimum

Returns the aggregate minimum value from a field or expression.

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

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

Examples

18. 13.2.1.17. minority

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

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

Syntax
[] marks optional arguments
• expression - sub expression of field to aggregate
Arguments
• group_by - optional expression to use to group aggregate calculations
• filter - optional expression to use to filter features used to calculate aggregate

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

Examples

19. 13.2.1.18. q1

Returns the calculated first quartile from a field or expression.

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

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

Examples

20. 13.2.1.19. q3

Returns the calculated third quartile from a field or expression.

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

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

Examples

21. 13.2.1.20. range

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

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

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

Examples

22. 13.2.1.21. relation_aggregate

Returns an aggregate value calculated using all matching child features from a layer relation.
relation_aggregate(relation, aggregate, expression, [concatenator=’’], [order_by])
Syntax
[] marks optional arguments
• relation - a string, representing a relation ID
• aggregate - a string corresponding to the aggregate to calculate. Valid options are:
o count
o count_distinct
o count_missing
o min
o max
o sum
o mean
o median
o stdev
o stdevsample
o range
o minority
Argument o majority
s o q1: first quartile
o q3: third quartile
o iqr: inter quartile range
o min_length: minimum string length
o max_length: maximum string length
o concatenate: join strings with a concatenator
o concatenate_unique: join unique strings with a concatenator
o collect: create an aggregated multipart geometry
o 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.

• relation_aggregate(relation:='my_relation',aggregate:='mean',expression:="passenger
s") → 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:=',') →
Examples
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

23. 13.2.1.22. stdev

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

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

Syntax
[] 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

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

Examples state field

24. 13.2.1.23. sum

Returns the aggregate summed value from a field or expression.

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

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

Examples

25. 13.2.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.

• array
• array_all
• array_append
• array_cat
• array_contains
• array_count
• array_distinct
• array_filter
• array_find
• array_first
• array_foreach
• array_get
• array_insert
• array_intersect
• array_last
• array_length
• array_majority
• array_max
• array_mean
• array_median
• array_min
• array_minority
• array_prepend
• array_prioritize
• array_remove_all
• array_remove_at
• array_replace
• array_reverse
• array_slice
• array_sort
• array_sum
• array_to_string
• generate_series
• geometries_to_array
• regexp_matches
• string_to_array

26. 13.2.2.1. array

Returns an array containing all the values passed as parameter.

Syntax array(value1, value2, …)

• value - a value
Arguments

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

27. 13.2.2.2. array_all

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

Syntax array_all(array_a, array_b)

• array_a - an array
Arguments • array_b - the array of values to search

• array_all(array(1,2,3),array(2,3)) → TRUE
Examples • array_all(array(1,2,3),array(1,2,4)) → FALSE

28. 13.2.2.3. array_append

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

Syntax array_append(array, value)

• array - an array
Arguments • value - the value to add

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

29. 13.2.2.4. array_cat

Returns an array containing all the given arrays concatenated.

Syntax array_cat(array1, array2, …)

• array - an array
Arguments

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

30. 13.2.2.5. array_contains

Returns TRUE if an array contains the given value.

Syntax array_contains(array, value)

• array - an array
Arguments • value - the value to search

• array_contains(array(1,2,3),2) → TRUE
Examples

31. 13.2.2.6. array_count

Counts the number of occurrences of a given value in an array.

Syntax array_count(array, value)

• array - an array
Arguments • value - the value to count

• array_count(array('a', 'b', 'c', 'b'), 'b') →2

Examples

32. 13.2.2.7. array_distinct

Returns an array containing distinct values of the given array.

Syntax array_distinct(array)
• array - an array
Arguments

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

33. 13.2.2.8. array_filter

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

array_filter(array, expression, [limit=0])

Syntax
[] marks optional arguments
• array - an array
• expression - an expression to evaluate on each item. The variable @element will be replaced by the
Arguments current value.
• limit - maximum number of elements to be returned. Use 0 to return all values.
• array_filter(array(1,2,3),@element < 3) → [ 1, 2 ]
Examples • array_filter(array(1,2,3),@element < 3, 1) → [ 1 ]

34. 13.2.2.9. array_find

Returns the lowest 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)

• array - an array
Arguments • value - the value to search

• array_find(array('a', 'b', 'c'), 'b') → 1

Examples • array_find(array('a', 'b', 'c', 'b'), 'b') →1

35. 13.2.2.10. array_first

Returns the first value of an array.

Syntax array_first(array)
• array - an array
Arguments

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

36. 13.2.2.11. array_foreach

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

Syntax array_foreach(array, expression)

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

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

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

37. 13.2.2.12. array_get

Returns the Nth value (0 for the first one) or the last -Nth value (-1 for the last one) of an array.

Syntax array_get(array, pos)

• array - an array
Arguments • pos - the index to get (0 based)

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

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

Hint

You can also use the index operator ([]) to get a value from an array.

38. 13.2.2.13. array_insert

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

Syntax array_insert(array, pos, value)

• array - an array
• pos - the position where to add (0 based)
Arguments
• value - the value to add

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

39. 13.2.2.14. array_intersect

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

Syntax array_intersect(array1, array2)

• array1 - an array
Arguments • array2 - another array

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

40. 13.2.2.15. array_last

Returns the last value of an array.

Syntax array_last(array)
• array - an array
Arguments

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

41. 13.2.2.16. array_length

Returns the number of elements of an array.

Syntax array_length(array)
• array - an array
Arguments

• array_length(array(1,2,3)) →3
Examples
42. 13.2.2.17. array_majority

Returns the most common values in an array.

array_majority(array, [option=’all’])
Syntax
[] marks optional arguments
• array - an array
• option=’all’ - a string specifying the return values handling. Valid options are:
o all: Default, all most common values are returned in an array.
Arguments o any: Returns one of the most common values.
o median: Returns the median of the most common values. Non arithmetic values are ignored.
o real_majority: Returns the value which occurs more than half the size of the array.

• array_majority(array(0,1,42,42,43), 'all') → [ 42 ]
• array_majority(array(0,1,42,42,43,1), 'all') → [ 42, 1 ]
• array_majority(array(0,1,42,42,43,1), 'any') → 1 or 42
• array_majority(array(0,1,1,2,2), 'median') → 1.5
Examples
• array_majority(array(0,1,42,42,43), 'real_majority') → NULL
• array_majority(array(0,1,42,42,43,42), 'real_majority') → NULL
• array_majority(array(0,1,42,42,43,42,42), 'real_majority') → 42

43. 13.2.2.18. array_max

Returns the maximum value of an array.

Syntax array_max(array)
• array - an array
Arguments

• array_max(array(0,42,4,2)) → 42
Examples

44. 13.2.2.19. array_mean

Returns the mean of arithmetic values in an array. Non numeric values in the array are ignored.

Syntax array_mean(array)
• array - an array
Arguments

• array_mean(array(0,1,7,66.6,135.4)) → 42
Examples • array_mean(array(0,84,'a','b','c')) → 42

45. 13.2.2.20. array_median

Returns the median of arithmetic values in an array. Non arithmetic values in the array are ignored.

Syntax array_median(array)
• array - an array
Arguments

• array_median(array(0,1,42,42,43)) → 42
Examples • array_median(array(0,1,2,42,'a','b')) → 1.5

46. 13.2.2.21. array_min

Returns the minimum value of an array.

Syntax array_min(array)
• array - an array
Arguments

• array_min(array(43,42,54)) → 42
Examples

47. 13.2.2.22. array_minority

Returns the less common values in an array.

array_minority(array, [option=’all’])
Syntax
[] marks optional arguments
• array - an array
• option=’all’ - a string specifying the return values handling. Valid options are:
o all: Default, all less common values are returned in an array.
Arguments o any: Returns one of the less common values.
o median: Returns the median of the less common values. Non arithmetic values are ignored.
o real_minority: Returns values which occur less than half the size of the array.

• array_minority(array(0,42,42), 'all') → [ 0 ]
• array_minority(array(0,1,42,42), 'all') → [ 0, 1 ]
• array_minority(array(0,1,42,42,43,1), 'any') → 0 or 43
• array_minority(array(1,2,3,3), 'median') → 1.5
Examples
• array_minority(array(0,1,42,42,43), 'real_minority') → [ 42, 43, 0, 1 ]
• array_minority(array(0,1,42,42,43,42), 'real_minority') → [ 42, 43, 0, 1 ]
• array_minority(array(0,1,42,42,43,42,42), 'real_minority') → [ 43, 0, 1 ]

48. 13.2.2.23. array_prepend

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

Syntax array_prepend(array, value)

• array - an array
Arguments • value - the value to add

• array_prepend(array(1,2,3),0) → [ 0, 1, 2, 3 ]
Examples
49. 13.2.2.24. array_prioritize

Returns an array sorted using the ordering specified in another array. Values which are present in the first array but are
missing from the second array will be added to the end of the result.

Syntax array_prioritize(array, array_prioritize)

• array - an array
Arguments • array_prioritize - an array with values ordered by priority

• array_prioritize(array(1, 8, 2, 5), array(5, 4, 2, 1, 3, 8)) → [ 5, 2, 1, 8 ]

Examples • array_prioritize(array(5, 4, 2, 1, 3, 8), array(1, 8, 6, 5)) → [ 1, 8, 5, 4, 2, 3 ]

50. 13.2.2.25. array_remove_all

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

Syntax array_remove_all(array, value)

• array - an array
Arguments • value - the values to remove

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

Examples

51. 13.2.2.26. array_remove_at

Returns an array with the item at the given index removed. Supports positive (0 for the first element) and negative (the
last -Nth value, -1 for the last element) index.

Syntax array_remove_at(array, pos)

• array - an array
Arguments • pos - the position to remove (0 based)

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

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

52. 13.2.2.27. array_replace

Returns an array with the supplied value, array, or map of values replaced.

Value & array variant

Returns an array with the supplied value or array of values replaced by another value or an array of values.

Syntax array_replace(array, before, after)

• array - the input array
• before - the value or array of values to replace
Arguments
• after - the value or array of values to use as a replacement
• array_replace(array('QGIS','SHOULD','ROCK'),'SHOULD','DOES') → [ ‘QGIS’, ‘DOES’,
‘ROCK’ ]
Examples • array_replace(array(3,2,1),array(1,2,3),array(7,8,9)) → [ 9, 8, 7 ]
• array_replace(array('Q','G','I','S'),array('Q','S'),'-') → [ ‘-’, ‘G’, ‘I’, ‘-’ ]

Map variant

Returns an array with the supplied map keys replaced by their paired values.

Syntax array_replace(array, map)

• array - the input array
Arguments • map - the map containing keys and values

• array_replace(array('APP', 'SHOULD', 'ROCK'),map('APP','QGIS','SHOULD','DOES')) →[

Examples ‘QGIS’, ‘DOES’, ‘ROCK’ ]

53. 13.2.2.28. array_reverse

Returns the given array with array values in reversed order.

Syntax array_reverse(array)
• array - an array
Arguments

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

54. 13.2.2.29. 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)

• 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).
Arguments
• 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).

• 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 ]
Examples • 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’ ]
55. 13.2.2.30. array_sort

Returns the provided array with its elements sorted.

array_sort(array, [ascending=true])
Syntax
[] marks optional arguments
• array - an array
Arguments • ascending - set this parameter to false to sort the array in descending order

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

56. 13.2.2.31. array_sum

Returns the sum of arithmetic values in an array. Non numeric values in the array are ignored.

Syntax array_sum(array)
• array - an array
Arguments

• array_sum(array(0,1,39.4,1.6,'a')) → 42.0
Examples

57. 13.2.2.32. array_to_string

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

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

Syntax
[] marks optional arguments
• array - the input array
• delimiter - the string delimiter used to separate concatenated array elements
Arguments
• empty_value - the optional string to use as replacement for empty (zero length) matches

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

58. 13.2.2.33. generate_series

Creates an array containing a sequence of numbers.

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

Syntax
[] marks optional arguments
• start - first value of the sequence
• stop - value that ends the sequence once reached
Arguments
• step - value used as the increment between values
• generate_series(1,5) → [ 1, 2, 3, 4, 5 ]
Examples • generate_series(5,1,-1) → [ 5, 4, 3, 2, 1]

59. 13.2.2.34. geometries_to_array

Splits a geometry into simpler geometries in an array.

Syntax geometries_to_array(geometry)
• geometry - the input geometry
Arguments

• geometries_to_array(geom_from_wkt('GeometryCollection (Polygon ((5 8, 4 1, 3 2, 5

8)),LineString (3 2, 4 2))')) → an array of a polygon and a line geometries
• geom_to_wkt(geometries_to_array(geom_from_wkt('GeometryCollection (Polygon ((5 8,
Examples 4 1, 3 2, 5 8)),LineString (3 2, 4 2))'))[0]) → ‘Polygon ((5 8, 4 1, 3 2, 5 8))’
• geometries_to_array(geom_from_wkt('MULTIPOLYGON(((5 5,0 0,0 10,5 5)),((5 5,10
10,10 0,5 5))')) → an array of two polygon geometries

60. 13.2.2.35. 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.

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

Syntax
[] marks optional arguments
• string - the string to capture groups from against the regular expression
• regex - the regular expression used to capture groups
Arguments
• empty_value - the optional string to use as replacement for empty (zero length) matches

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

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

61. 13.2.2.36. string_to_array

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

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

Syntax
[] marks optional arguments
• string - the input string
• delimiter - the string delimiter used to split the input string
Arguments
• empty_value - the optional string to use as replacement for empty (zero length) matches

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

Examples • string_to_array('1,,3',',','0') → [ ‘1’, ‘0’, ‘3’ ]
62. 13.2.3. Color Functions
This group contains functions for manipulating colors.

• color_cmyk
• color_cmyka
• color_grayscale_average
• color_hsl
• color_hsla
• color_hsv
• color_hsva
• color_mix_rgb
• color_part
• color_rgb
• color_rgba
• create_ramp
• darker
• lighter
• project_color
• ramp_color
• set_color_part

63. 13.2.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)

• 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
Arguments • 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

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

64. 13.2.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)

• 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
Arguments
• 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).

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

65. 13.2.3.3. color_grayscale_average

Applies a grayscale filter and returns a string representation from a provided color.
Syntax color_grayscale_average(color)
• color - a color string
Arguments

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

66. 13.2.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)

• 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
Arguments
• lightness - lightness percentage of the color as an integer value from 0 to 100

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

67. 13.2.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)

• 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
Arguments • 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).

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

68. 13.2.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)

• 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
Arguments
• value - value percentage of the color as an integer from 0 to 100

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

69. 13.2.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)

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

70. 13.2.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)

• color1 - a color string
• color2 - a color string
Arguments
• ratio - a ratio

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

71. 13.2.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)

• color - a color string
• component - a string corresponding to the color component to return. Valid options are:
o red: RGB red component (0-255)
o green: RGB green component (0-255)
o blue: RGB blue component (0-255)
o alpha: alpha (transparency) value (0-255)
o hue: HSV hue (0-360)
o saturation: HSV saturation (0-100)
Arguments o value: HSV value (0-100)
o hsl_hue: HSL hue (0-360)
o hsl_saturation: HSL saturation (0-100)
o lightness: HSL lightness (0-100)
o cyan: CMYK cyan component (0-100)
o magenta: CMYK magenta component (0-100)
o yellow: CMYK yellow component (0-100)
o black: CMYK black component (0-100)

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

72. 13.2.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

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

73. 13.2.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)

• red - red component as an integer value from 0 to 255
• green - green component as an integer value from 0 to 255
Arguments • 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).

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

74. 13.2.3.12. create_ramp

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

create_ramp(map, [discrete=false])
Syntax
[] marks optional arguments
• map - a map of color strings and steps
Arguments • discrete - set this parameter to true to create a discrete color ramp

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

75. 13.2.3.13. darker

Returns a darker (or lighter) color string

Syntax darker(color, factor)

• color - a color string
• factor - an integer corresponding to the darkening factor:
o 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);
Arguments
o if the factor is less than 100, the return color is lighter, but using the lighter() function for this
purpose is recommended;
o if the factor is 0 or negative, the return value is unspecified.

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

Examples

Returns a lighter (or darker) color string

Syntax lighter(color, factor)

• color - a color string
• factor - an integer corresponding to the lightening factor:
o 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);
Arguments
o if the factor is less than 100, the return color is darker, but using the darker() function for this
purpose is recommended;
o if the factor is 0 or negative, the return value is unspecified.

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

Examples

77. 13.2.3.15. project_color

Returns a color from the project’s color scheme.

Syntax project_color(name)
• name - a color name
Arguments

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

Examples

78. 13.2.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)

• ramp_name - the name of the color ramp as a string, for example ‘Spectral’
Arguments • value - the position on the ramp to select the color from as a real number between 0 and 1

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

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)

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

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

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

79. 13.2.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)

• color - a color string
• component - a string corresponding to the color component to set. Valid options are:
o red: RGB red component (0-255)
o green: RGB green component (0-255)
o blue: RGB blue component (0-255)
o alpha: alpha (transparency) value (0-255)
o hue: HSV hue (0-360)
o saturation: HSV saturation (0-100)
o value: HSV value (0-100)
Arguments
o hsl_hue: HSL hue (0-360)
o hsl_saturation: HSL saturation (0-100)
o lightness: HSL lightness (0-100)
o cyan: CMYK cyan component (0-100)
o magenta: CMYK magenta component (0-100)
o yellow: CMYK yellow component (0-100)
o black: CMYK black component (0-100)
• value - new value for color component, respecting the ranges listed above

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

80. 13.2.4. Conditional Functions

This group contains functions to handle conditional checks in expressions.

• CASE
• coalesce
• if
• nullif
• regexp_match
• try

81. 13.2.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

• WHEN condition - A condition expression to evaluate

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

• 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
Examples 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

82. 13.2.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, …)

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

• coalesce(NULL, 2) → 2
• coalesce(NULL, 2, 3) → 2
• coalesce(7, NULL, 3*2) → 7
Examples
• 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

83. 13.2.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)

• condition - the condition which should be checked
Arguments • 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.

• 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)’
Examples
• 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’

84. 13.2.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)

• value1 - The value that should either be used or substituted with NULL.
Arguments • value2 - The control value that will trigger the NULL substitution.

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

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

85. 13.2.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)

• 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.,
Arguments
“\\s” to match a white space character or “\\b” to match a word boundary).

• regexp_match('QGIS ROCKS','\\sROCKS') →5
Examples • regexp_match('Budač','udač\\b') → 2

86. 13.2.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.

try(expression, [alternative])
Syntax
[] marks optional arguments
Arguments • expression - the expression which should be run
• alternative - the result which will be returned if the expression returns an error.

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

• try( to_int( 'a' ), 0 ) → 0
Examples
• try( to_date( 'invalid_date' ) ) → NULL

87. 13.2.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, …).

• from_base64
• hash
• md5
• sha256
• to_base64
• to_date
• to_datetime
• to_decimal
• to_dm
• to_dms
• to_int
• to_interval
• to_real
• to_string
• to_time

88. 13.2.5.1. from_base64

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

Syntax from_base64(string)
• string - the string to decode
Arguments

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

89. 13.2.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)

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

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

les • hash('QGIS', 'md5') → ‘57470aaa9e22adaefac7f5f342f1c6da’
• hash('QGIS', 'sha1') → ‘f87cfb2b74cdd5867db913237024e7001e62b114’
• hash('QGIS', 'sha224') → ‘4093a619ada631c770f44bc643ead18fb393b93d6a6af1861fcfece0’
• hash('QGIS', 'sha256') →
‘eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309’
• hash('QGIS', 'sha384') →
‘91c1de038cc3d09fdd512e99f9dd9922efadc39ed21d3922e69a4305cc25506033aee388e554b78714c873
4f9cd7e610’
• hash('QGIS', 'sha512') →
‘c2c092f2ab743bf8edbeb6d028a745f30fc720408465ed369421f0a4e20fa5e27f0c90ad72d3f1d836eaa5d2
5cd39897d4cf77e19984668ef58da6e3159f18ac’
• hash('QGIS', 'sha3_224') → ‘467f49a5039e7280d5d42fd433e80d203439e338eaabd701f0d6c17d’
• hash('QGIS', 'sha3_256') →
‘540f7354b6b8a6e735f2845250f15f4f3ba4f666c55574d9e9354575de0e980f’
• hash('QGIS', 'sha3_384') →
‘96052da1e77679e9a65f60d7ead961b287977823144786386eb43647b0901fd8516fa6f1b9d243fb3f2877
5e6dde6107’
• hash('QGIS', 'sha3_512') →
‘900d079dc69761da113980253aa8ac0414a8bd6d09879a916228f8743707c4758051c98445d6b8945ec85
4ff90655005e02aceb0a2ffc6a0ebf818745d665349’
• hash('QGIS', 'keccak_224') → ‘5b0ce6acef8b0a121d4ac4f3eaa8503c799ad4e26a3392d1fb201478’
• hash('QGIS', 'keccak_256') →
‘991c520aa6815392de24087f61b2ae0fd56abbfeee4a8ca019c1011d327c577e’
• hash('QGIS', 'keccak_384') →
‘c57a3aed9d856fa04e5eeee9b62b6e027cca81ba574116d3cc1f0d48a1ef9e5886ff463ea8d0fac772ee473b
f92f810d’

90. 13.2.5.3. md5

Creates a md5 hash from a string.

Syntax md5(string)
• string - the string to hash
Arguments

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

91. 13.2.5.4. sha256

Creates a sha256 hash from a string.

Syntax sha256(string)
• string - the string to hash
Arguments

• sha256('QGIS') → ‘eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309’
Examples

92. 13.2.5.5. to_base64

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

Syntax to_base64(value)
• value - the binary value to encode
Arguments

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

93. 13.2.5.6. to_date

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

Syntax
[] marks optional arguments
• string - string representing a date value
• format - format used to convert the string into a date
Arguments • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the
string into a date. By default the current QGIS user locale is used.

• to_date('2012-05-04') → 2012-05-04
• to_date('June 29, 2019','MMMM d, yyyy') → 2019-06-29, if the current locale uses the name
Examples ‘June’ for the sixth month, otherwise an error occurs
• to_date('29 juin, 2019','d MMMM, yyyy','fr') → 2019-06-29

94. 13.2.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, QTime::fromString or the documentation of the format_date function for additional documentation on
the format. By default the current QGIS user locale is used.

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

Syntax
[] marks optional arguments
• string - string representing a datetime value
• format - format used to convert the string into a datetime
Arguments • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the
string into a datetime. By default the current QGIS user locale is used.

• 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, if the
Examples current locale uses the name ‘June’ for the sixth month, otherwise an error occurs
• to_datetime('29 juin, 2019 @ 12:34','d MMMM, yyyy @ HH:mm','fr') → 2019-06-29T12:34

95. 13.2.5.8. to_decimal

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

Syntax to_decimal(value)
• value - A degree, minute, second string.
Arguments

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

96. 13.2.5.9. to_dm

Converts a coordinate to degree, minute.

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

Syntax
[] marks optional arguments
• coordinate - A latitude or longitude value.
• axis - The axis of the coordinate. Either ‘x’ or ‘y’.
• precision - Number of decimals.
Arguments
• formatting - Designates the formatting type. Acceptable values are NULL (default), ‘aligned’ or
‘suffix’.

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

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

97. 13.2.5.10. to_dms

Converts a coordinate to degree, minute, second.

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

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

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

98. 13.2.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)
• string - string to convert to integer number
Arguments

• to_int('123') → 123
Examples
99. 13.2.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)
• string - a string representing an interval. Allowable formats include {n} days {n} hours {n} months.
Arguments

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

• to_interval( '0.5 hours' ) → interval: 30 minutes
Examples • to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours') → 2012-05-
04T10:00:00

100. 13.2.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)
• string - string to convert to real number
Arguments

• to_real('123.45') → 123.45
Examples

101. 13.2.5.14. to_string

Converts a number to string.

Syntax to_string(number)
• number - Integer or real value. The number to convert to string.
Arguments

• to_string(123) → ‘123’
Examples

102. 13.2.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.

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

Syntax
[] marks optional arguments
• string - string representing a time value
• format - format used to convert the string into a time
Arguments • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the
string into a time

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

103. 13.2.6. Custom Functions

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

104. 13.2.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)

• age
• datetime_from_epoch
• day
• day_of_week
• epoch
• format_date
• hour
• make_date
• make_datetime
• make_interval
• make_time
• minute
• month
• now
• second
• to_date
• to_datetime
• to_interval
• to_time
• week
• year

105. 13.2.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)

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

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

106. 13.2.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)
• int - number (milliseconds)
Arguments

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

107. 13.2.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)
• date - a date or datetime value
Arguments

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

Interval variant

Calculates the length in days of an interval.

Syntax day(interval)
• interval - interval value to return number of days from
Arguments

• day(to_interval('3 days')) → 3
Examples
• day(to_interval('3 weeks 2 days')) → 23
• day(age('2012-01-01','2010-01-01')) → 730

108. 13.2.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)
• date - date or datetime value
Arguments

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

109. 13.2.7.5. epoch

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

Syntax epoch(date)
• date - a date or datetime value
Arguments

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

110. 13.2.7.6. format_date

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

format_date(datetime, format, [language])

Syntax
[] marks optional 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’)
Arguments 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. By default the current QGIS user locale is used.

• 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’, if the current locale is an English variant
Examples
• 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’

111. 13.2.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)
• datetime - a time or datetime value
Arguments

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

Examples

Interval variant

Calculates the length in hours of an interval.

Syntax hour(interval)
• interval - interval value to return number of hours from
Arguments

• hour(to_interval('3 hours')) → 3
• hour(age('2012-07-22T13:00:00','2012-07-22T10:00:00')) →3
Examples
• hour(age('2012-01-01','2010-01-01')) → 17520
112. 13.2.7.8. make_date

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

Syntax make_date(year, month, day)

• year - Year number. Years 1 to 99 are interpreted as is. Year 0 is invalid.
• month - Month number, where 1=January
Arguments
• day - Day number, beginning with 1 for the first day in the month

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

Examples

113. 13.2.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)

• 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
Arguments • hour - Hour number
• minute - Minutes
• second - Seconds (fractional values include milliseconds)

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

Examples

114. 13.2.7.10. make_interval

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

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

Syntax
[] marks optional 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
Arguments
• hours - Number of hours
• minutes - Number of minutes
• seconds - Number of seconds

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

• make_interval(days:=2, hours:=3) → interval: 2.125 days
Examples
• make_interval(minutes:=0.5, seconds:=5) → interval: 35 seconds

115. 13.2.7.11. make_time

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

Syntax make_time(hour, minute, second)
• hour - Hour number
• minute - Minutes
Arguments
• second - Seconds (fractional values include milliseconds)

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

Examples

116. 13.2.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)
• datetime - a time or datetime value
Arguments

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

Examples

Interval variant

Calculates the length in minutes of an interval.

Syntax minute(interval)
• interval - interval value to return number of minutes from
Arguments

• minute(to_interval('3 minutes')) → 3
• minute(age('2012-07-22T00:20:00','2012-07-22T00:00:00')) → 20
Examples
• minute(age('2012-01-01','2010-01-01')) → 1051200

117. 13.2.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)
• date - a date or datetime value
Arguments

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

Interval variant
Calculates the length in months of an interval.

Syntax month(interval)
• interval - interval value to return number of months from
Arguments

• month(to_interval('3 months')) → 3
Examples • month(age('2012-01-01','2010-01-01')) → 4.03333

118. 13.2.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()
• now() → 2012-07-22T13:24:57
Examples

119. 13.2.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)
• datetime - a time or datetime value
Arguments

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

Examples

Interval variant

Calculates the length in seconds of an interval.

Syntax second(interval)
• interval - interval value to return number of seconds from
Arguments

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

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

120. 13.2.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
or the documentation of the format_date function for additional documentation on the format. By default the current QGIS
user locale is used.
to_date(string, [format], [language])
Syntax
[] marks optional arguments
• string - string representing a date value
• format - format used to convert the string into a date
Arguments • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the
string into a date. By default the current QGIS user locale is used.

121. 13.2.7.17. to_datetime

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

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

122. 13.2.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)
• string - a string representing an interval. Allowable formats include {n} days {n} hours {n} months.
Arguments

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

• to_interval( '0.5 hours' ) → interval: 30 minutes
Examples • to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours') → 2012-05-
04T10:00:00

123. 13.2.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.
to_time(string, [format], [language])
Syntax
[] marks optional arguments
• string - string representing a time value
• format - format used to convert the string into a time
Arguments • language - language (lowercase, two- or three-letter, ISO 639 language code) used to convert the
string into a time

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

124. 13.2.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)
• date - a date or datetime value
Arguments

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

Interval variant

Calculates the length in weeks of an interval.

Syntax week(interval)
• interval - interval value to return number of months from
Arguments

• week(to_interval('3 weeks')) → 3
Examples • week(age('2012-01-01','2010-01-01')) → 104.285

125. 13.2.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)
• date - a date or datetime value
Arguments
• year('2012-05-12') → 2012
Examples

Interval variant

Calculates the length in years of an interval.

Syntax year(interval)
• interval - interval value to return number of years from
Arguments

• year(to_interval('3 years')) → 3
Examples • 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>

126. 13.2.8. Fields and Values

Contains a list of fields from the active layer, and special values. Fields list includes the ones stored in the dataset, virtual
and auxiliary ones as well as from joins.

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.

• NULL
127. 13.2.8.1. NULL

Equates to a NULL value.

Syntax NULL
• NULL → a NULL value
Examples

Note

To test for NULL use an IS NULL or IS NOT NULL expression.

128. 13.2.9. Files and Paths Functions

This group contains functions which manipulate file and path names.

• base_file_name
• exif
• file_exists
• file_name
• file_path
• file_size
• file_suffix
• is_directory
• is_file

129. 13.2.9.1. base_file_name

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

Syntax base_file_name(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

130. 13.2.9.2. exif

Retrieves exif tag values from an image file.

exif(path, [tag])
Syntax
[] marks optional arguments
• path - An image file path or a map layer value. If a map layer value is specified then the file source
of the layer will be used.
Arguments
• tag - The tag to return. If empty, a map with all exif tag values will be returned.

• exif('/my/photo.jpg','Exif.Image.Orientation') →0
Examples
131. 13.2.9.3. file_exists

Returns TRUE if a file path exists.

Syntax file_exists(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

132. 13.2.9.4. file_name

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

Syntax file_name(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

133. 13.2.9.5. file_path

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

Syntax file_path(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

134. 13.2.9.6. file_size

Returns the size (in bytes) of a file.

Syntax file_size(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

135. 13.2.9.7. file_suffix

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

Syntax file_suffix(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

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

136. 13.2.9.8. is_directory

Returns TRUE if a path corresponds to a directory.

Syntax is_directory(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

• is_directory('/home/qgis/data/country_boundaries.shp') → FALSE
Examples • is_directory('/home/qgis/data/') → TRUE

137. 13.2.9.9. is_file

Returns TRUE if a path corresponds to a file.

Syntax is_file(path)
• path - a file path or a map layer value. If a map layer value is specified then the file source of the
Arguments layer will be used.

• is_file('/home/qgis/data/country_boundaries.shp') → TRUE
Examples • is_file('/home/qgis/data/') → FALSE

138. 13.2.10. Form Functions

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

• current_parent_value
• current_value

139. 13.2.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)
• field_name - a field name in the current parent form
Arguments
• current_parent_value( 'FIELD_NAME' ) → The current value of a field ‘FIELD_NAME’ in the
Examples parent form.

140. 13.2.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)
• field_name - a field name in the current form or table row
Arguments

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

Examples

141. 13.2.11. Fuzzy Matching Functions

This group contains functions for fuzzy comparisons between values.

• hamming_distance
• levenshtein
• longest_common_substring
• soundex

142. 13.2.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)

• string1 - a string
Arguments • string2 - a string

• hamming_distance('abc','xec') → 2
• hamming_distance('abc','ABc') → 2
Examples • hamming_distance(upper('abc'),upper('ABC')) →0
• hamming_distance('abc','abcd') → NULL

143. 13.2.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

• levenshtein('kittens','mitten') → 2
• levenshtein('Kitten','kitten') → 1
Examples
• levenshtein(upper('Kitten'),upper('kitten')) →0

144. 13.2.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)

• string1 - a string
Arguments • string2 - a string

• longest_common_substring('ABABC','BABCA') → ‘BABC’
• longest_common_substring('abcDeF','abcdef') → ‘abc’
Examples
• longest_common_substring(upper('abcDeF'),upper('abcdex')) → ‘ABCDE’

145. 13.2.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)
• string - a string
Arguments

• soundex('robert') → ‘R163’
• soundex('rupert') → ‘R163’
Examples
• soundex('rubin') → ‘R150’

146. 13.2.12. General Functions

This group contains general assorted functions.

• env
• eval
• eval_template
• is_layer_visible
• mime_type
• var
• with_variable

147. 13.2.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)
• name - The name of the environment variable which should be retrieved.
Arguments

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

• env( 'MY_OWN_PREFIX_VAR' ) → ‘Z:’
Examples
• env( 'I_DO_NOT_EXIST' ) → NULL

148. 13.2.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)
• expression - an expression string
Arguments

• eval('\'nice\'') → ‘nice’
Examples • eval(@expression_var) → [whatever the result of evaluating @expression_var might be…]

149. 13.2.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)
• template - a template string
Arguments

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

Examples

150. 13.2.12.4. is_layer_visible

Returns TRUE if a specified layer is visible.

Syntax is_layer_visible(layer)
• layer - a string, representing either a layer name or layer ID
Arguments

• is_layer_visible('baseraster') → TRUE
Examples

151. 13.2.12.5. mime_type

Returns the mime type of the binary data.

Syntax mime_type(bytes)
• bytes - the binary data
Arguments

• mime_type('<html><body></body></html>') → text/html
• mime_type(from_base64('R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==')) →
Examples
image/gif

152. 13.2.12.6. var

Returns the value stored within a specified variable.

Syntax var(name)
• name - a variable name
Arguments

• var('qgis_version') → ‘2.12’
Examples

153. 13.2.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)

• name - the name of the variable to set
• value - the value to set
Arguments
• expression - the expression for which the variable will be available

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

Examples

154. 13.2.13. Geometry Functions

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

• affine_transform
• angle_at_vertex
• apply_dash_pattern
• $area
• area
• azimuth
• boundary
• bounds
• bounds_height
• bounds_width
• buffer
• buffer_by_m
• centroid
• close_line
• closest_point
• collect_geometries
• combine
• concave_hull
• contains
• convex_hull
• crosses
• densify_by_count
• densify_by_distance
• difference
• disjoint
• distance
• distance_to_vertex
• end_point
• exif_geotag
• extend
• exterior_ring
• extrude
• flip_coordinates
• force_polygon_ccw
• force_polygon_cw
• force_rhr
• geom_from_gml
• geom_from_wkb
• geom_from_wkt
• geom_to_wkb
• geom_to_wkt
• $geometry
• geometry
• geometry_n
• geometry_type
• hausdorff_distance
• inclination
• interior_ring_n
• intersection
• intersects
• intersects_bbox
• is_closed
• is_empty
• is_empty_or_null
• is_multipart
• is_valid
• $length
• length
• length3D
• line_interpolate_angle
• line_interpolate_point
• line_locate_point
• line_merge
• line_substring
• m
• m_max
• m_min
• main_angle
• make_circle
• make_ellipse
• make_line
• make_point
• make_point_m
• make_polygon
• make_rectangle_3points
• make_regular_polygon
• make_square
• make_triangle
• make_valid
• minimal_circle
• nodes_to_points
• num_geometries
• num_interior_rings
• num_points
• num_rings
• offset_curve
• order_parts
• oriented_bbox
• overlaps
• overlay_contains
• overlay_crosses
• overlay_disjoint
• overlay_equals
• overlay_intersects
• overlay_nearest
• overlay_touches
• overlay_within
• $perimeter
• perimeter
• point_n
• point_on_surface
• pole_of_inaccessibility
• project
• relate
• reverse
• rotate
• roundness
• scale
• segments_to_lines
• shared_paths
• shortest_line
• simplify
• simplify_vw
• single_sided_buffer
• sinuosity
• smooth
• square_wave
• square_wave_randomized
• start_point
• straight_distance_2d
• sym_difference
• tapered_buffer
• touches
• transform
• translate
• triangular_wave
• triangular_wave_randomized
• union
• wave
• wave_randomized
• wedge_buffer
• within
• $x
• x
• $x_at
• x_max
• x_min
• $y
• y
• $y_at
• y_max
• y_min
• $z
• z
• z_max
• z_min

155. 13.2.13.1. affine_transform

Returns the geometry after an affine transformation. Calculations are in the Spatial Reference System of this geometry.
The operations are performed in a scale, rotation, translation order. If there is a Z or M offset but the coordinate is not
present in the geometry, it will be added.

affine_transform(geometry, delta_x, delta_y, rotation_z, scale_x, scale_y, [delta_z=0], [delta_m=0],

[scale_z=1], [scale_m=1])
Syntax
[] marks optional arguments
• geometry - a geometry
• delta_x - x-axis translation
• delta_y - y-axis translation
• rotation_z - rotation around z-axis in degrees counter-clockwise
• scale_x - x-axis scale factor
Arguments • scale_y - y-axis scale factor
• delta_z - z-axis translation
• delta_m - m-axis translation
• scale_z - z-axis scale factor
• scale_m - m-axis scale factor

• geom_to_wkt(affine_transform(geom_from_wkt('LINESTRING(1 1, 2 2)'), 2, 2, 0, 1,
1)) → ‘LineString (3 3, 4 4)’
• geom_to_wkt(affine_transform(geom_from_wkt('POLYGON((0 0, 0 3, 2 2, 0 0))'), 0, 0,
Examples -90, 1, 2)) → ‘Polygon ((0 0, 6 0, 4 -2, 0 0))’
• geom_to_wkt(affine_transform(geom_from_wkt('POINT(3 1)'), 0, 0, 0, 1, 1, 5, 0)) →
‘PointZ (3 1 5)’

156. 13.2.13.2. 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)
• geometry - a linestring geometry
• vertex - vertex index, starting from 0; if the value is negative, the selected vertex index will be its
Arguments
total count minus the absolute value

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

157. 13.2.13.3. apply_dash_pattern

Applies a dash pattern to a geometry, returning a MultiLineString geometry which is the input geometry stroked along
each line/ring with the specified pattern.

apply_dash_pattern(geometry, pattern, [start_rule=no_rule], [end_rule=no_rule], [adjustment=both],

[pattern_offset=0])
Syntax
[] marks optional arguments
• geometry - a geometry (accepts (multi)linestrings or (multi)polygons).
• pattern - dash pattern, as an array of numbers representing dash and gap lengths. Must contain an
even number of elements.
• start_rule - optional rule for constraining the start of the pattern. Valid values are ‘no_rule’,
‘full_dash’, ‘half_dash’, ‘full_gap’, ‘half_gap’.
Arguments • end_rule - optional rule for constraining the end of the pattern. Valid values are ‘no_rule’,
‘full_dash’, ‘half_dash’, ‘full_gap’, ‘half_gap’.
• adjustment - optional rule for specifying which part of patterns are adjusted to fit the desired pattern
rules. Valid values are ‘both’, ‘dash’, ‘gap’.
• pattern_offset - Optional distance specifying a specific distance along the pattern to commence at.

• geom_to_wkt(apply_dash_pattern(geom_from_wkt('LINESTRING(1 1, 10 1)'), array(3,

1))) → MultiLineString ((1 1, 4 1),(5 1, 8 1),(9 1, 10 1, 10 1))
Examples • geom_to_wkt(apply_dash_pattern(geom_from_wkt('LINESTRING(1 1, 10 1)'), array(3,
1), start_rule:='half_dash')) → MultiLineString ((1 1, 2.5 1),(3.5 1, 6.5 1),(7.5 1, 10 1, 10 1))

158. 13.2.13.4. $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
• $area → 42
Examples

159. 13.2.13.5. 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)
• geometry - polygon geometry object
Arguments

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

Examples

160. 13.2.13.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)

• point_a - point geometry
Arguments • point_b - point geometry

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

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

161. 13.2.13.7. 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)
• geometry - a geometry
Arguments

• 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)’
Examples • geom_to_wkt(boundary(geom_from_wkt('LineString(1 1,0 0,-1 1)'))) → ‘MultiPoint ((1
1),(-1 1))’

162. 13.2.13.8. 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)
• geometry - a geometry
Arguments

• 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
Examples
0, 1 0, 1 1, -1 1, -1 0))’
Fig. 13.4 Black lines represent the bounding boxes of each polygon feature

163. 13.2.13.9. 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)
• geometry - a geometry
Arguments

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

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

164. 13.2.13.10. 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)
• geometry - a geometry
Arguments

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

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

165. 13.2.13.11. 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.

buffer(geometry, distance, [segments=8], [cap=’round’], [join=’round’], [miter_limit=2])

Syntax
[] marks optional 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.
Arguments
• cap - end cap style for buffer. Valid values are ‘round’, ‘flat’ or ‘square’
• join - join style for buffer. Valid values are ‘round’, ‘bevel’ or ‘miter’.
• miter_limit - miter distance limit, for use when the join style is set to ‘miter’

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

Fig. 13.5 Buffer (in yellow) of points, line, polygon with positive buffer, and polygon with negative buffer

166. 13.2.13.12. buffer_by_m

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

buffer_by_m(geometry, [segments=8])
Syntax
[] marks optional arguments
• geometry - input geometry. Must be a (multi)line geometry with m values.
Arguments • segments - number of segments to approximate quarter-circle curves in the buffer.
• 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
Examples
linestring geometry.

Fig. 13.6 Buffering line features using the m value on the vertices

167. 13.2.13.13. centroid

Returns the geometric center of a geometry.

Syntax centroid(geometry)
• geometry - a geometry
Arguments

• centroid($geometry) → a point geometry

Examples

168. 13.2.13.14. 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)
• geometry - a line string geometry
Arguments

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

0, 1 0, 1 1, 0 0)’
Examples • 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)’

169. 13.2.13.15. closest_point

Returns the point on geometry1 that is closest to geometry2.

Syntax closest_point(geometry1, geometry2)

• geometry1 - geometry to find closest point on
Arguments • geometry2 - geometry to find closest point to

• geom_to_wkt(closest_point(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75

Examples )'),geom_from_wkt('POINT(100 100)'))) → ‘Point(73.0769 115.384)’

170. 13.2.13.16. 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, …)

• geometry - a geometry
Arguments

• geom_to_wkt(collect_geometries(make_point(1,2), make_point(3,4), make_point(5,6)))

Examples → ‘MultiPoint ((1 2),(3 4),(5 6))’

Array variant

Geometry parts are specified as an array of geometry parts.

Syntax collect_geometries(array)
• array - array of geometry objects
Arguments

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

171. 13.2.13.17. combine

Returns the combination of two geometries.

Syntax combine(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• 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))’
Examples • 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)’

172. 13.2.13.18. concave_hull

Returns a possibly concave polygon that contains all the points in the geometry

concave_hull(geometry, target_percent, [allow_holes=False])

Syntax
[] marks optional arguments
• geometry - a geometry
• target_percent - the percentage of area of the convex hull the solution tries to approach. A
target_percent of 1 gives the same result as the convex hull. A target_percent between 0 and 0.99
Arguments produces a result that should have a smaller area than the convex hull.
• allow_holes - optional argument specifying whether to allow holes within the output geometry.
Defaults to FALSE, set to TRUE to avoid including holes in the output geometry.

• geom_to_wkt(concave_hull(geom_from_wkt('MULTILINESTRING((106 164,30 112,74 70,82

112,130 94,130 62,122 40,156 32,162 76,172 88),(132 178,134 148,128 136,96 128,132
108,150 130,170 142,174 110,156 96,158 90,158 88),(22 64,66 28,94 38,94 68,114
76,112 30,132 10,168 18,178 34,186 52,184 74,190 100,190 122,182 148,178 170,176
Examples 184,156 164,146 178,132 186,92 182,56 158,36 150,62 150,76 128,88 118))'), 0.99))
→ ‘Polygon ((30 112, 36 150, 92 182, 132 186, 176 184, 190 122, 190 100, 186 52, 178 34, 168 18,
132 10, 112 30, 66 28, 22 64, 30 112))’

173. 13.2.13.19. 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)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• contains( geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))' ), geom_from_wkt(

'POINT(0.5 0.5 )' ) ) → TRUE
Examples • 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

174. 13.2.13.20. 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)
• geometry - a geometry
Arguments

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

Examples ‘POLYGON((3 3, 4 10, 4 4, 3 3))’

175. 13.2.13.21. 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)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

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

'LINESTRING(3 3, 4 4, 5 5)' ) ) → TRUE
Examples • crosses( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)'
) ) → FALSE

176. 13.2.13.22. densify_by_count

Takes a polygon or line layer geometry and generates a new one in which the geometries have a larger number of vertices
than the original one.

Syntax densify_by_count(geometry, vertices)

• geometry - a geometry (accepts (multi)linestrings or (multi)polygons).
Arguments • vertices - number of vertices to add (per segment)

• geom_to_wkt(densify_by_count(geom_from_wkt('LINESTRING(1 1, 10 1)'), 3)) →

Examples LineString (1 1, 3.25 1, 5.5 1, 7.75 1, 10 1)

177. 13.2.13.23. densify_by_distance

Takes a polygon or line layer geometry and generates a new one in which the geometries are densified by adding
additional vertices on edges that have a maximum distance of the specified interval distance.

Syntax densify_by_distance(geometry, distance)

• geometry - a geometry (accepts (multi)linestrings or (multi)polygons).
Arguments • distance - maximum interval distance between vertices in output geometry

• geom_to_wkt(densify_by_distance(geom_from_wkt('LINESTRING(1 1, 10 1)'), 4)) →

Examples LineString (1 1, 4 1, 7 1, 10 1)

178. 13.2.13.24. difference

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

Syntax difference(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

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

Examples geom_from_wkt( 'LINESTRING(3 3, 4 4)' ) ) ) → ‘LINESTRING(4 4, 5 5)’

179. 13.2.13.25. disjoint

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

Syntax disjoint(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• 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
Examples • disjoint( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'POINT(4
4)' )) → FALSE

180. 13.2.13.26. distance

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

Syntax distance(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry
• distance( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(4 8)' ) ) →4
Examples

181. 13.2.13.27. distance_to_vertex

Returns the distance along the geometry to a specified vertex.

Syntax distance_to_vertex(geometry, vertex)

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

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

182. 13.2.13.28. end_point

Returns the last node from a geometry.

Syntax end_point(geometry)
• geometry - geometry object
Arguments

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

Examples

183. 13.2.13.29. exif_geotag

Creates a point geometry from the exif geotags of an image file.

Syntax exif_geotag(path)
• path - An image file path or a map layer value. If a map layer value is specified then the file source
Arguments of the layer will be used.

• geom_to_wkt(exif_geotag('/my/photo.jpg')) → ‘Point (2 4)’

Examples

184. 13.2.13.30. 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)

• geometry - a (multi)linestring geometry
• start_distance - distance to extend the start of the line
Arguments
• end_distance - distance to extend the end of the line.
• geom_to_wkt(extend(geom_from_wkt('LineString(0 0, 1 0, 1 1)'),1,2)) → ‘LineString (-1
0, 1 0, 1 3)’
Examples • 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))’

185. 13.2.13.31. 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)
• geometry - a polygon geometry
Arguments

• 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 -
Examples
1)’

186. 13.2.13.32. 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)
• geometry - a curve or linestring geometry
• x - x extension, numeric value
Arguments
• y - y extension, numeric value

• 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))’
Examples • 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)))’

187. 13.2.13.33. 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)
• geometry - a geometry
Arguments

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

• geom_to_wkt(flip_coordinates(geom_from_wkt('LineString(0 2, 1 0, 1 6)'))) →
Examples
‘LineString (2 0, 0 1, 6 1)’

• geom_to_wkt(force_polygon_ccw(geometry:=geom_from_wkt('Polygon ((-1 -1, 0 2, 4 2,

Examples 4 0, -1 -1))'))) → ‘Polygon ((-1 -1, 4 0, 4 2, 0 2, -1 -1))’

189. 13.2.13.35. force_polygon_cw

Forces a geometry to respect the convention where exterior rings are clockwise, interior rings are counter-clockwise.

Syntax force_polygon_cw(geometry)
• geometry - a geometry. Any non-polygon geometries are returned unchanged.
Arguments

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

190. 13.2.13.36. 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. Due to the inconsistency in the definition of the Right-Hand-Rule in some contexts it is recommended to use the
explicit force_polygon_cw function instead.

Syntax force_rhr(geometry)
• geometry - a geometry. Any non-polygon geometries are returned unchanged.
Arguments

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

191. 13.2.13.37. geom_from_gml

Returns a geometry from a GML representation of geometry.

Syntax geom_from_gml(gml)
• gml - GML representation of a geometry as a string
Arguments
• geom_from_gml('<gml:LineString srsName="EPSG:4326"><gml:coordinates>4,4 5,5
Examples 6,6</gml:coordinates></gml:LineString>') → a line geometry object

192. 13.2.13.38. geom_from_wkb

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

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

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

Examples

193. 13.2.13.39. geom_from_wkt

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

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

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

Examples

194. 13.2.13.40. geom_to_wkb

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

Syntax geom_to_wkb(geometry)
• geometry - a geometry
Arguments

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

Examples

195. 13.2.13.41. geom_to_wkt

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

geom_to_wkt(geometry, [precision=8])
Syntax
[] marks optional arguments
• geometry - a geometry
Arguments • precision - numeric precision

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

Examples • 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)’

196. 13.2.13.42. $geometry

Returns the geometry of the current feature. Can be used for processing with other functions. WARNING: This function
is deprecated. It is recommended to use the replacement @geometry variable instead.

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

197. 13.2.13.43. geometry

Returns a feature’s geometry.

Syntax geometry(feature)
• feature - a feature object
Arguments

• `` geometry( $currentfeature )`` → the geometry of the current feature. Prefer using $geometry.
• geom_to_wkt( geometry( get_feature_by_id( 'streets', 1 ) ) ) → the geometry in WKT
of the feature with the id 1 on the layer “streets”, e.g. ‘POINT(6 50)’
Examples
• intersects( $geometry, geometry( get_feature( 'streets', 'name', 'Main St.' ) ) )
→ TRUE if the current feature spatially intersects the ‘Main St.’ named feature in the “streets” layer

198. 13.2.13.44. geometry_n

Returns a specific geometry from a geometry collection, or NULL if the input geometry is not a collection. Also returns a
part from a multipart geometry.

Syntax geometry_n(geometry, index)

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

• geom_to_wkt(geometry_n(geom_from_wkt('GEOMETRYCOLLECTION(POINT(0 1), POINT(0 0),

Examples POINT(1 0), POINT(1 1))'),3)) → ‘Point (1 0)’

199. 13.2.13.45. geometry_type

Returns a string value describing the type of a geometry (Point, Line or Polygon)

Syntax geometry_type(geometry)
• geometry - a geometry
Arguments

• geometry_type( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) → ‘Line’

Examples • geometry_type( geom_from_wkt( 'MULTILINESTRING((2 5, 3 6, 4 8), (1 1, 0 0))') ) →
‘Line’
• geometry_type( geom_from_wkt( 'POINT(2 5)') ) → ‘Point’
• geometry_type( geom_from_wkt( 'POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1))') ) →
‘Polygon’

200. 13.2.13.46. 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.

hausdorff_distance(geometry1, geometry2, [densify_fraction])

Syntax
[] marks optional arguments
• geometry1 - a geometry
• geometry2 - a geometry
Arguments
• densify_fraction - densify fraction amount

• 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
Examples 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

201. 13.2.13.47. 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)

• point_a - point geometry
Arguments • point_b - point geometry

• 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
Examples • 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
202. 13.2.13.48. 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)

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

• 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 -
Examples 1))'),1)) → ‘LineString (-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))’

203. 13.2.13.49. intersection

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

Syntax intersection(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• 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)’
Examples • 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)’

204. 13.2.13.50. 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)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

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

5)' ) ) → TRUE
Examples • intersects( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'POINT(5 5)' ) ) →
FALSE

205. 13.2.13.51. 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)
• geometry1 - a geometry
Arguments • geometry2 - a geometry

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

4, 5 5)' ) ) → TRUE
Examples • intersects_bbox( geom_from_wkt( 'POINT(6 5)' ), geom_from_wkt( 'POLYGON((3 3, 4 4,
5 5, 3 3))' ) ) → FALSE

206. 13.2.13.52. 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)
• geometry - a line string geometry
Arguments

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

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

207. 13.2.13.53. 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)
• geometry - a geometry
Arguments

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

• is_empty(geom_from_wkt('LINESTRING EMPTY')) → TRUE
Examples • is_empty(geom_from_wkt('POINT(7 4)')) → FALSE
• is_empty(geom_from_wkt('POINT EMPTY')) → TRUE

208. 13.2.13.54. 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)
• geometry - a geometry
Arguments

• is_empty_or_null(NULL) → TRUE
• is_empty_or_null(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')) → FALSE
Examples
• 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

209. 13.2.13.55. is_multipart

Returns TRUE if the geometry is of Multi type.

Syntax is_multipart(geometry)
• geometry - a geometry
Arguments

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

Examples • is_multipart(geom_from_wkt('POINT (0 0)')) → FALSE

210. 13.2.13.56. 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)
• geometry - a geometry
Arguments

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

Examples • is_valid(geom_from_wkt('LINESTRING(0 0)')) → FALSE

211. 13.2.13.57. $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
• $length → 42.4711
Examples

212. 13.2.13.58. 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)
• string - string to count length of
Arguments

• length('hello') →5
Examples

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)
• geometry - line geometry object
Arguments

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

Examples

213. 13.2.13.59. length3D

Calculates the 3D length of a geometry line object. If the geometry is not a 3D line object, it returns its 2D length.
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 length3D(geometry)
• geometry - line geometry object
Arguments

• length3D(geom_from_wkt('LINESTRINGZ(0 0 0, 3 0 4)')) → 5.0

Examples

214. 13.2.13.60. 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)

• geometry - a linestring geometry
Arguments • distance - distance along line to interpolate angle at

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

215. 13.2.13.61. line_interpolate_point

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

Syntax line_interpolate_point(geometry, distance)
• geometry - a linestring geometry
Arguments • distance - distance along line to interpolate

• geom_to_wkt(line_interpolate_point(geometry:=geom_from_wkt('LineString(0 0, 8
0)'), distance:=5)) → ‘Point (5 0)’
• geom_to_wkt(line_interpolate_point(geometry:=geom_from_wkt('LineString(0 0, 1 1, 2
Examples 0)'), distance:=2.1)) → ‘Point (1.48492424 0.51507576)’
• geom_to_wkt(line_interpolate_point(geometry:=geom_from_wkt('LineString(0 0, 1
0)'), distance:=2)) → NULL

216. 13.2.13.62. 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)

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

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

217. 13.2.13.63. 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)
• geometry - a LineString/MultiLineString geometry
Arguments

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

‘LineString(0 0,1 1,2 2)’
Examples • 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)’

218. 13.2.13.64. 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)

• geometry - a linestring or curve geometry
Arguments
• start_distance - distance to start of substring
• end_distance - distance to end of substring

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

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

Syntax m(geometry)
• geometry - a point geometry
Arguments

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

Examples

220. 13.2.13.66. m_max

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

Syntax m_max(geometry)
• geometry - a geometry containing m values
Arguments

• 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( -
Examples
2,-2,0 ) ) ) → 2

221. 13.2.13.67. m_min

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

Syntax m_min(geometry)
• geometry - a geometry containing m values
Arguments

• 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( -
Examples
2,-2,0 ) ) ) → 0

222. 13.2.13.68. main_angle

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

Syntax main_angle(geometry)
• geometry - a geometry
Arguments

• main_angle(geom_from_wkt('Polygon ((321577 129614, 321581 129618, 321585 129615,

Examples 321581 129610, 321577 129614))')) → 38.66

223. 13.2.13.69. make_circle

Creates a circular polygon.

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

Syntax
[] marks optional arguments
• center - center point of the circle
• radius - radius of the circle
Arguments
• segments - optional argument for polygon segmentation. By default this value is 36

• 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
Examples 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))’

224. 13.2.13.70. make_ellipse

Creates an elliptical polygon.

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

Syntax
[] marks optional 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
Arguments
• azimuth - orientation of the ellipse
• segments - optional argument for polygon segmentation. By default this value is 36

• 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
Examples 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))’

225. 13.2.13.71. 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, …)

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

• 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))) →
Examples
‘LineString (2 4, 3 5, 9 7)’

Array variant

Line vertices are specified as an array of points.

Syntax make_line(array)
• array - array of points
Arguments

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

226. 13.2.13.72. make_point

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

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

Syntax
[] marks optional arguments
• x - x coordinate of point
• y - y coordinate of point
Arguments • z - optional z coordinate of point
• m - optional m value of point

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

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

227. 13.2.13.73. make_point_m

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

Syntax make_point_m(x, y, m)
• x - x coordinate of point
• y - y coordinate of point
Arguments
• m - m value of point

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

Examples
228. 13.2.13.74. make_polygon

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

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

Syntax
[] marks optional arguments
• outerRing - closed line geometry for polygon’s outer ring
Arguments • innerRing - optional closed line geometry for inner ring

• 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
Examples )'),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))’

229. 13.2.13.75. make_rectangle_3points

Creates a rectangle from 3 points.

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

Syntax
[] marks optional 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
Arguments
(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.

• geom_to_wkt(make_rectangle_3points(make_point(0, 0), make_point(0,5),

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

230. 13.2.13.76. make_regular_polygon

Creates a regular polygon.

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

Syntax
[] marks optional 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
Arguments
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)

• 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))’
Examples • 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))’

231. 13.2.13.77. make_square

Creates a square from a diagonal.

Syntax make_square(point1, point2)

• point1 - First point of the diagonal
Arguments • point2 - Last point of the diagonal

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

5 0, 0 0))’
Examples • 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))’

232. 13.2.13.78. make_triangle

Creates a triangle polygon.

Syntax make_triangle(point1, point2, point3)

• point1 - first point of the triangle
• point2 - second point of the triangle
Arguments
• point3 - third point of the triangle

• 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))’
Examples • 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)’

233. 13.2.13.79. make_valid

Returns a valid geometry or an empty geometry if the geometry could not be made valid.

make_valid(geometry, [method=structure], [keep_collapsed=false])

Syntax
[] marks optional arguments
• geometry - a geometry
• method - repair algorithm. May be either ‘structure’ or ‘linework’. The ‘linework’ option combines
Arguments all rings into a set of noded lines and then extracts valid polygons from that linework. The ‘structure’
method first makes all rings valid and then merges shells and subtracts holes from shells to generate
valid result. Assumes that holes and shells are correctly categorized.
• keep_collapsed - if set to true, then components that have collapsed into a lower dimensionality will
be kept. For example, a ring collapsing to a line, or a line collapsing to a point.

• geom_to_wkt(make_valid(geom_from_wkt('POLYGON((3 2, 4 1, 5 8, 3 2, 4 2))'))) →
‘Polygon ((3 2, 5 8, 4 1, 3 2))’
• geom_to_wkt(make_valid(geom_from_wkt('POLYGON((3 2, 4 1, 5 8, 3 2, 4 2))'),
'linework')) → ‘GeometryCollection (Polygon ((5 8, 4 1, 3 2, 5 8)),LineString (3 2, 4 2))’
Examples • geom_to_wkt(make_valid(geom_from_wkt('POLYGON((3 2, 4 1, 5 8))'),
method:='linework')) → ‘Polygon ((3 2, 4 1, 5 8, 3 2))’
• make_valid(geom_from_wkt('LINESTRING(0 0)')) → An empty geometry

234. 13.2.13.80. minimal_circle

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

minimal_circle(geometry, [segments=36])
Syntax
[] marks optional arguments
• geometry - a geometry
Arguments • segments - optional argument for polygon segmentation. By default this value is 36

• 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))’
Examples • 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))’

235. 13.2.13.81. nodes_to_points

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

nodes_to_points(geometry, [ignore_closing_nodes=false])
Syntax
[] marks optional arguments
• geometry - geometry object
• ignore_closing_nodes - optional argument specifying whether to include duplicate nodes which
Arguments close lines or polygons rings. Defaults to false, set to true to avoid including these duplicate nodes in
the output collection.

• geom_to_wkt(nodes_to_points(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) →
‘MultiPoint ((0 0),(1 1),(2 2))’
Examples • 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))’

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

0), POINT(1 1))')) → 4
Examples
• num_geometries(geom_from_wkt('MULTIPOINT((0 1), (0 0), (1 0))')) → 3

237. 13.2.13.83. 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)
• geometry - input geometry
Arguments

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

Examples 0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))')) → 1

238. 13.2.13.84. num_points

Returns the number of vertices in a geometry.

Syntax num_points(geometry)
• geometry - a geometry
Arguments

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

Examples

239. 13.2.13.85. 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)
• geometry - input geometry
Arguments

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

Examples 0.4 0.2, 0 0.2, -0.1 -0.1))')) → 2

240. 13.2.13.86. offset_curve

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

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

Syntax
[] marks optional 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
Arguments
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)

• 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
Examples 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

241. 13.2.13.87. order_parts

Orders the parts of a MultiGeometry by a given criteria

order_parts(geometry, orderby, [ascending=true])

Syntax
[] marks optional arguments
• geometry - a multi-type geometry
• orderby - an expression string defining the order criteria
Arguments
• ascending - boolean, True for ascending, False for descending

• 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)))’
Examples
• geom_to_wkt(order_parts(geom_from_wkt('LineString(1 2, 3 2, 4 3)'), '1', True)) →
‘LineString(1 2, 3 2, 4 3)’

242. 13.2.13.88. oriented_bbox

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

Syntax oriented_bbox(geometry)
• geometry - a geometry
Arguments

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

Examples ‘Polygon ((3 2, 3 4, 1 4, 1 2, 3 2))’
Further reading: Oriented minimum bounding box algorithm

243. 13.2.13.89. 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)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

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

'LINESTRING(3 3, 4 4, 5 5)' ) ) → TRUE
Examples • overlaps( geom_from_wkt( 'LINESTRING(0 0, 1 1)' ), geom_from_wkt( 'LINESTRING(3 3,
4 4, 5 5)' ) ) → FALSE

244. 13.2.13.90. 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.

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

Syntax
[] marks optional 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.
Arguments
• 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)

• 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
Examples names, for the 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

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

• 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
Examples 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

246. 13.2.13.92. 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.

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

Syntax
[] marks optional 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.
Arguments • 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)

• 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
Examples
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

247. 13.2.13.93. 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.

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

• 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
Examples 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

248. 13.2.13.94. 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.

overlay_intersects(layer, [expression], [filter], [limit], [cache=false], [min_overlap],

[min_inscribed_circle_radius], [return_details], [sort_by_intersection_size])
Syntax
[] marks optional 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)
• min_overlap - defines an optional exclusion filter:
o for polygons, a minimum area in current feature squared units for the intersection. If the
intersection results in multiple polygons the intersection will be returned if at least one of the
polygons has an area greater or equal to the value
o for lines, a minimum length in current feature units. If the intersection results in multiple
lines the intersection will be returned if at least one of the lines has a length greater or equal
to the value.
Arguments • min_inscribed_circle_radius - defines an optional exclusion filter (for polygons only): minimum
radius in current feature units for the maximum inscribed circle of the intersection. If the intersection
results in multiple polygons the intersection will be returned if at least one of the polygons has a
radius for the maximum inscribed circle greater or equal to the value.

This argument requires GEOS >= 3.9.

• return_details - Set this to true to return a list of maps containing (key names in quotes) the feature
‘id’, the expression ‘result’ and the ‘overlap’ value. The ‘radius’ of the maximum inscribed circle is
also returned when the target layer is a polygon. Only valid when used with the expression parameter
• sort_by_intersection_size - only valid when used with an expression, set this to ‘des’ to return the
results ordered by the overlap value in descending order or set this to ‘asc’ for ascending order.

• 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
Examples • 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
• overlay_intersects(layer:='regions', min_overlap:=0.54) → TRUE if the current feature
spatially intersects a region and the intersection area (of at least one of the parts in case of
multipolygons) is greater or equal to 0.54
• overlay_intersects(layer:='regions', min_inscribed_circle_radius:=0.54) → TRUE if
the current feature spatially intersects a region and the intersection area maximum inscribed circle’s
radius (of at least one of the parts in case of multipart) is greater or equal to 0.54
• overlay_intersects(layer:='regions', expression:= geom_to_wkt($geometry),
return_details:=true) → an array of maps containing ‘id’, ‘result’, ‘overlap’ and ‘radius’
• overlay_intersects(layer:='regions', expression:= geom_to_wkt($geometry),
sort_by_intersection_size:='des') → an array of geometries (in WKT) ordered by the overlap
value in descending order

249. 13.2.13.95. 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.

overlay_nearest(layer, [expression], [filter], [limit=1], [max_distance], [cache=false])

Syntax
[] marks optional 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
Arguments
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)

• 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
Examples • 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

250. 13.2.13.96. 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.

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

• 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
Examples 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

251. 13.2.13.97. 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.

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

• 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
Examples 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

252. 13.2.13.98. $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
• $perimeter → 42
Examples

253. 13.2.13.99. 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)
• geometry - polygon geometry object
Arguments

• perimeter(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))')) → 12.0

Examples

254. 13.2.13.100. point_n

Returns a specific node from a geometry.

Syntax point_n(geometry, index)
• geometry - geometry object
• index - index of node to return, where 1 is the first node; if the value is negative, the selected vertex
Arguments
index will be its total count minus the absolute value

• geom_to_wkt(point_n(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))'),2)) →
Examples ‘Point (4 0)’

255. 13.2.13.101. point_on_surface

Returns a point guaranteed to lie on the surface of a geometry.

Syntax point_on_surface(geometry)
• geometry - a geometry
Arguments

• point_on_surface($geometry) → a point geometry

Examples

256. 13.2.13.102. 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)

• geometry - a geometry
Arguments • tolerance - maximum distance between the returned point and the true pole location

• geom_to_wkt(pole_of_inaccessibility( geom_from_wkt('POLYGON((0 1, 0 9, 3 10, 3 3,

Examples 10 3, 10 1, 0 1))'), 0.1)) → ‘Point(1.546875 2.546875)’

257. 13.2.13.103. project

Returns a point projected from a start point using a distance, a bearing (azimuth) and an elevation in radians.

project(point, distance, azimuth, [elevation])

Syntax
[] marks optional arguments
• point - start point
Arguments • distance - distance to project
• azimuth - azimuth in radians clockwise, where 0 corresponds to north
• elevation - angle of inclination in radians

• geom_to_wkt(project(make_point(1, 2), 3, radians(270))) → ‘Point(-2, 2)’

Examples

258. 13.2.13.104. 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)

• geometry - a geometry
Arguments • geometry - a geometry

• relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt(

Examples '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)

• geometry - a geometry
• geometry - a geometry
Arguments
• pattern - DE-9IM pattern to match

• relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt(

Examples 'LINESTRING(40 40,60 120)' ), '**1F001**' ) → TRUE

259. 13.2.13.105. reverse

Reverses the direction of a line string by reversing the order of its vertices.

Syntax reverse(geometry)
• geometry - a geometry
Arguments

• geom_to_wkt(reverse(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) → ‘LINESTRING(2

Examples 2, 1 1, 0 0)’

rotate(geometry, rotation, [center=NULL], [per_part=false])

Syntax
[] marks optional 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.
Arguments • per_part - apply rotation per part. If true, then rotation will apply around the center of each part’s
bounding box when the input geometry is multipart and an explicit rotation center point is not
specified.

• rotate($geometry, 45, make_point(4, 5)) → geometry rotated 45 degrees clockwise around

the (4, 5) point
Examples • rotate($geometry, 45) → geometry rotated 45 degrees clockwise around the center of its
bounding box

Fig. 13.7 Rotating features

261. 13.2.13.107. roundness

Calculates how close a polygon shape is to a circle. The function Returns TRUE when the polygon shape is a perfect
circle and 0 when it is completely flat.

Syntax roundness(geometry)
• geometry - a polygon
Arguments

• round(roundness(geom_from_wkt('POLYGON(( 0 0, 0 1, 1 1, 1 0, 0 0))')), 3) → 0.785

• round(roundness(geom_from_wkt('POLYGON(( 0 0, 0 0.1, 1 0.1, 1 0, 0 0))')), 3) →
Examples
0.260
Further reading: Roundness algorithm

262. 13.2.13.108. scale

Returns a scaled version of a geometry. Calculations are in the Spatial Reference System of this geometry.

scale(geometry, x_scale, y_scale, [center])

Syntax
[] marks optional arguments
• geometry - a geometry
• x_scale - x-axis scaling factor
Arguments • y_scale - y-axis scaling factor
• center - scaling center point. If not specified, the center of the geometry’s bounding box is used.

• scale($geometry, 2, 0.5, make_point(4, 5)) → geometry scaled twice horizontally and

halved vertically, around the (4, 5) point
Examples • scale($geometry, 2, 0.5) → geometry twice horizontally and halved vertically, around the center
of its bounding box

263. 13.2.13.109. segments_to_lines

Returns a multi line geometry consisting of a line for every segment in the input geometry.

Syntax segments_to_lines(geometry)
• geometry - geometry object
Arguments

• geom_to_wkt(segments_to_lines(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))) →
Examples ‘MultiLineString ((0 0, 1 1),(1 1, 2 2))’

264. 13.2.13.110. shared_paths

Returns a collection containing paths shared by the two input geometries. Those going in the same direction are in the first
element of the collection, those going in the opposite direction are in the second element. The paths themselves are given
in the direction of the first geometry.

Syntax shared_paths(geometry1, geometry2)

• geometry1 - a LineString/MultiLineString geometry
Arguments • geometry2 - a LineString/MultiLineString geometry

• geom_to_wkt(shared_paths(geom_from_wkt('MULTILINESTRING((26 125,26 200,126 200,126

125,26 125),(51 150,101 150,76 175,51 150)))'),geom_from_wkt('LINESTRING(151
100,126 156.25,126 125,90 161, 76 175)'))) → ‘GeometryCollection (MultiLineString ((126
156.25, 126 125),(101 150, 90 161),(90 161, 76 175)),MultiLineString EMPTY)’
Examples • geom_to_wkt(shared_paths(geom_from_wkt('LINESTRING(76 175,90 161,126 125,126
156.25,151 100)'),geom_from_wkt('MULTILINESTRING((26 125,26 200,126 200,126 125,26
125),(51 150,101 150,76 175,51 150))'))) → ‘GeometryCollection (MultiLineString
EMPTY,MultiLineString ((76 175, 90 161),(90 161, 101 150),(126 125, 126 156.25)))’
265. 13.2.13.111. 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)

• geometry1 - geometry to find shortest line from
Arguments • geometry2 - geometry to find shortest line to

• geom_to_wkt(shortest_line(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75

Examples )'),geom_from_wkt('POINT(100 100)'))) → ‘LineString(73.0769 115.384, 100 100)’

266. 13.2.13.112. 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)

• geometry - a geometry
Arguments • tolerance - maximum deviation from straight segments for points to be removed

• geom_to_wkt(simplify(geometry:=geom_from_wkt('LineString(0 0, 5 0.1, 10
Examples 0)'),tolerance:=5)) → ‘LineString(0 0, 10 0)’

267. 13.2.13.113. 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)

• geometry - a geometry
Arguments • tolerance - a measure of the maximum area created by a node for the node to be removed

• geom_to_wkt(simplify_vw(geometry:=geom_from_wkt('LineString(0 0, 5 0, 5.01 10,

Examples 5.02 0, 10 0)'),tolerance:=5)) → ‘LineString(0 0, 10 0)’

268. 13.2.13.114. 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.

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

Syntax
[] marks optional 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
Arguments
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)

• 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
Examples 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

269. 13.2.13.115. sinuosity

Returns the sinuosity of a curve, which is the ratio of the curve length to the straight (2D) distance between its endpoints.

Syntax sinuosity(geometry)
• geometry - Input curve (circularstring, linestring)
Arguments

• round(sinuosity(geom_from_wkt('LINESTRING(2 0, 2 2, 3 2, 3 3)')), 3) → 1.265

Examples • sinuosity(geom_from_wkt('LINESTRING( 3 1, 5 1)')) → 1.0

270. 13.2.13.116. 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.

smooth(geometry, [iterations=1], [offset=0.25], [min_length=-1], [max_angle=180])

Syntax
[] marks optional 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.
Arguments
• 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.
• 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,
Examples
5 1, 5 5)’

271. 13.2.13.117. square_wave

Constructs square/rectangular waves along the boundary of a geometry.

square_wave(geometry, wavelength, amplitude, [strict=False])

Syntax
[] marks optional arguments
• geometry - a geometry
• wavelength - wavelength of square waveform
• amplitude - amplitude of square waveform
• strict - By default the wavelength argument is treated as a “maximum wavelength”, where the actual
Arguments
wavelength will be dynamically adjusted so that an exact number of square waves are created along
the boundaries of the geometry. If the strict argument is set to true then the wavelength will be used
exactly and an incomplete pattern may be used for the final waveform.

• square_wave(geom_from_wkt('LineString(0 0, 10 0)'), 3, 1) → Square waves with

Examples wavelength 3 and amplitude 1 along the linestring

272. 13.2.13.118. square_wave_randomized

Constructs randomized square/rectangular waves along the boundary of a geometry.

square_wave_randomized(geometry, min_wavelength, max_wavelength, min_amplitude, max_amplitude,

[seed=0])
Syntax
[] marks optional arguments
• geometry - a geometry
• min_wavelength - minimum wavelength of waves
• max_wavelength - maximum wavelength of waves
• min_amplitude - minimum amplitude of waves
Arguments
• max_amplitude - maximum amplitude of waves
• seed - specifies a random seed for generating waves. If the seed is 0, then a completely random set of
waves will be generated.

• square_wave_randomized(geom_from_wkt('LineString(0 0, 10 0)'), 2, 3, 0.1, 0.2) →

Randomly sized square waves with wavelengths between 2 and 3 and amplitudes between 0.1 and
Examples
0.2 along the linestring

273. 13.2.13.119. start_point

Returns the first node from a geometry.

Syntax start_point(geometry)
• geometry - geometry object
Arguments

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

Examples

274. 13.2.13.120. straight_distance_2d

Returns the direct/euclidean distance between the first and last vertex of a geometry. The geometry must be a curve
(circularstring, linestring).

Syntax straight_distance_2d(geometry)
• geometry - The geometry.
Arguments

• straight_distance_2d(geom_from_wkt('LINESTRING(1 0, 1 1)')) → 1
Examples • round(straight_distance_2d(geom_from_wkt('LINESTRING(1 4, 3 5, 5 0)')), 3) → 5.657

275. 13.2.13.121. sym_difference

Returns a geometry that represents the portions of two geometries that do not intersect.

Syntax sym_difference(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• geom_to_wkt( sym_difference( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ),

Examples geom_from_wkt( 'LINESTRING(3 3, 8 8)' ) ) ) → ‘LINESTRING(5 5, 8 8)’

276. 13.2.13.122. tapered_buffer

Creates a buffer along a line geometry where the buffer diameter varies evenly over the length of the line.

tapered_buffer(geometry, start_width, end_width, [segments=8])

Syntax
[] marks optional arguments
• geometry - input geometry. Must be a (multi)line geometry.
• start_width - width of buffer at start of line,
Arguments • end_width - width of buffer at end of line.
• segments - number of segments to approximate quarter-circle curves in the buffer.
• 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
Examples
of 1 and ending with a diameter of 2 along the linestring geometry.

Fig. 13.8 Tapered buffer on line features

277. 13.2.13.123. 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)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• touches( geom_from_wkt( 'LINESTRING(5 3, 4 4)' ), geom_from_wkt( 'LINESTRING(3 3,

4 4, 5 5)' ) ) → TRUE
Examples
• touches( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(5 5)' ) ) → FALSE

278. 13.2.13.124. transform

Returns the geometry transformed from a source CRS to a destination CRS.

Syntax transform(geometry, source_auth_id, dest_auth_id)

• geometry - a geometry
• source_auth_id - the source auth CRS ID
Arguments
• dest_auth_id - the destination auth CRS ID

• geom_to_wkt( transform( make_point(488995.53240249, 7104473.38600835),

Examples 'EPSG:2154', 'EPSG:4326' ) ) → ‘POINT(0 51)’

279. 13.2.13.125. translate

Returns a translated version of a geometry. Calculations are in the Spatial Reference System of this geometry.

Syntax translate(geometry, dx, dy)

• geometry - a geometry
• dx - delta x
Arguments
• dy - delta y

• translate($geometry, 5, 10) → a geometry of the same type like the original one
Examples

Fig. 13.9 Translating features

280. 13.2.13.126. triangular_wave

Constructs triangular waves along the boundary of a geometry.

triangular_wave(geometry, wavelength, amplitude, [strict=False])

Syntax
[] marks optional arguments
Arguments • geometry - a geometry
• wavelength - wavelength of triangular waveform
• amplitude - amplitude of triangular waveform
• strict - By default the wavelength argument is treated as a “maximum wavelength”, where the actual
wavelength will be dynamically adjusted so that an exact number of triangular waves are created
along the boundaries of the geometry. If the strict argument is set to true then the wavelength will be
used exactly and an incomplete pattern may be used for the final waveform.

• triangular_wave(geom_from_wkt('LineString(0 0, 10 0)'), 3, 1) → Triangular waves with

Examples wavelength 3 and amplitude 1 along the linestring

281. 13.2.13.127. triangular_wave_randomized

Constructs randomized triangular waves along the boundary of a geometry.

triangular_wave_randomized(geometry, min_wavelength, max_wavelength, min_amplitude, max_amplitude,

• triangular_wave_randomized(geom_from_wkt('LineString(0 0, 10 0)'), 2, 3, 0.1, 0.2)

→ Randomly sized triangular waves with wavelengths between 2 and 3 and amplitudes between 0.1
Examples
and 0.2 along the linestring

282. 13.2.13.128. union

Returns a geometry that represents the point set union of the geometries.

Syntax union(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• geom_to_wkt( union( make_point(4, 4), make_point(5, 5) ) ) → ‘MULTIPOINT(4 4, 5 5)’

Examples

283. 13.2.13.129. wave

Constructs rounded (sine-like) waves along the boundary of a geometry.

wave(geometry, wavelength, amplitude, [strict=False])

Syntax
[] marks optional arguments
Arguments • geometry - a geometry
• wavelength - wavelength of sine-like waveform
• amplitude - amplitude of sine-like waveform
• strict - By default the wavelength argument is treated as a “maximum wavelength”, where the actual
wavelength will be dynamically adjusted so that an exact number of waves are created along the
boundaries of the geometry. If the strict argument is set to true then the wavelength will be used
exactly and an incomplete pattern may be used for the final waveform.

• wave(geom_from_wkt('LineString(0 0, 10 0)'), 3, 1) → Sine-like waves with wavelength 3

Examples and amplitude 1 along the linestring

284. 13.2.13.130. wave_randomized

Constructs randomized curved (sine-like) waves along the boundary of a geometry.

wave_randomized(geometry, min_wavelength, max_wavelength, min_amplitude, max_amplitude, [seed=0])

Syntax
[] marks optional arguments
• geometry - a geometry
• min_wavelength - minimum wavelength of waves
• max_wavelength - maximum wavelength of waves
• min_amplitude - minimum amplitude of waves
Arguments
• max_amplitude - maximum amplitude of waves
• seed - specifies a random seed for generating waves. If the seed is 0, then a completely random set of
waves will be generated.

• wave_randomized(geom_from_wkt('LineString(0 0, 10 0)'), 2, 3, 0.1, 0.2) → Randomly

sized curved waves with wavelengths between 2 and 3 and amplitudes between 0.1 and 0.2 along the
Examples
linestring

285. 13.2.13.131. wedge_buffer

Returns a wedge shaped buffer originating from a point geometry.

wedge_buffer(center, azimuth, width, outer_radius, [inner_radius=0.0])

Syntax
[] marks optional 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
Arguments side of the azimuth direction.
• outer_radius - outer radius for buffers
• inner_radius - optional inner radius for buffers

• wedge_buffer(center:=geom_from_wkt('POINT(1
2)'),azimuth:=90,width:=180,outer_radius:=1) → A wedge shaped buffer centered on the
Examples
point (1,2), facing to the East, with a width of 180 degrees and outer radius of 1.

Syntax within(geometry1, geometry2)

• geometry1 - a geometry
Arguments • geometry2 - a geometry

• within( geom_from_wkt( 'POINT( 0.5 0.5)' ), geom_from_wkt( 'POLYGON((0 0, 0 1, 1

1, 1 0, 0 0))' ) ) → TRUE
Examples • within( geom_from_wkt( 'POINT( 5 5 )' ), geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1
0, 0 0 ))' ) ) → FALSE

287. 13.2.13.133. $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
• $x → 42
Examples

288. 13.2.13.134. x

Returns the x coordinate of a point geometry, or the x coordinate of the centroid for a non-point geometry.

Syntax x(geometry)
• geometry - a geometry
Arguments

• x( geom_from_wkt( 'POINT(2 5)' ) ) → 2

Examples • x( $geometry ) → x coordinate of the current feature’s centroid

289. 13.2.13.135. $x_at

Retrieves a x coordinate of the current feature’s geometry.

Syntax $x_at(i)
• i - index of point of a line (indices start at 0; negative values apply from the last index, starting at -1)
Arguments

• $x_at(1) →5
Examples

290. 13.2.13.136. x_max

Returns the maximum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax x_max(geometry)
• geometry - a geometry
Arguments

• x_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) →4

Examples

291. 13.2.13.137. x_min

Returns the minimum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax x_min(geometry)
• geometry - a geometry
Arguments

• x_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) →2

Examples

292. 13.2.13.138. $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
• $y → 42
Examples

293. 13.2.13.139. y

Returns the y coordinate of a point geometry, or the y coordinate of the centroid for a non-point geometry.

Syntax y(geometry)
• geometry - a geometry
Arguments

• y( geom_from_wkt( 'POINT(2 5)' ) ) → 5

Examples • y( $geometry ) → y coordinate of the current feature’s centroid

294. 13.2.13.140. $y_at

Retrieves a y coordinate of the current feature’s geometry.

Syntax $y_at(i)
• i - index of point of a line (indices start at 0; negative values apply from the last index, starting at -1)
Arguments

• $y_at(1) →2
Examples

295. 13.2.13.141. y_max

Returns the maximum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax y_max(geometry)
• geometry - a geometry
Arguments

• y_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) →8

Examples

296. 13.2.13.142. y_min

Returns the minimum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.

Syntax y_min(geometry)
• geometry - a geometry
Arguments

• y_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') ) →5

Examples

297. 13.2.13.143. $z

Returns the z value of the current point feature if it is 3D. If the feature is a multipoint feature, then the z value of the first
point will be returned.

Syntax $z
• $z → 123
Examples

298. 13.2.13.144. z

Returns the z coordinate of a point geometry, or NULL if the geometry has no z value.

Syntax z(geometry)
• geometry - a point geometry
Arguments

• z( geom_from_wkt( 'POINTZ(2 5 7)' ) ) →7

Examples

299. 13.2.13.145. z_max

Returns the maximum z coordinate of a geometry, or NULL if the geometry has no z value.

Syntax z_max(geometry)
• geometry - a geometry with z coordinate
Arguments

• 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
Examples
• 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
300. 13.2.13.146. z_min

Returns the minimum z coordinate of a geometry, or NULL if the geometry has no z value.

Syntax z_min(geometry)
• geometry - a geometry with z coordinate
Arguments

• 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
Examples
• 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

301. 13.2.14. Layout Functions

This group contains functions to manipulate print layout items properties.

• item_variables
• map_credits

302. 13.2.14.1. item_variables

Returns a map of variables from a layout item inside this print layout.

Syntax item_variables(id)
• id - layout item ID
Arguments

• map_get( item_variables('Map 0'), 'map_scale') → scale of the item ‘Map 0’ in the current
Examples print layout

303. 13.2.14.2. map_credits

Returns a list of credit (usage rights) strings for the layers shown in a layout map item.

map_credits(id, [include_layer_names=false], [layer_name_separator=’: ‘])

Syntax
[] marks optional arguments
• id - map item ID
• include_layer_names - Set to true to include layer names before their credit strings
Arguments • layer_name_separator - String to insert between layer names and their credit strings, if
include_layer_names is true

• array_to_string( map_credits( 'Main Map' ) ) → comma separated list of layer credits for
Examples
layers shown in the ‘Main Map’ layout item, e.g ‘CC-BY-NC, CC-BY-SA’
• array_to_string( map_credits( 'Main Map', include_layer_names := true,
layer_name_separator := ': ' ) ) → comma separated list of layer names and their credits for
layers shown in the ‘Main Map’ layout item, e.g. ‘Railway lines: CC-BY-NC, Basemap: CC-BY-SA’

This function requires the Access metadata properties of the layers to have been filled.

304. 13.2.15. Map Layers

This group contains a list of the available layers in the current project and, for each layer, their fields (stored in the dataset,
virtual or auxiliary ones as well as from joins). The fields can be interacted the same way as mentioned in Fields and
Values, except that a double-click will add the name as a string (single quoted) to the expression instead of as a field
reference given that they do not belong to the active layer. This offers a convenient way to write expressions referring to
different layers, such as when performing aggregates, attribute or spatial queries.

It also provides some convenient functions to manipulate layers.

• decode_uri
• layer_property

305. 13.2.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.

decode_uri(layer, [part])
Syntax
[] marks optional arguments
• layer - The layer for which the uri should be decoded.
Arguments • part - The part of the uri to return. If unspecified, a map with all uri parts will be returned.

• decode_uri(@layer) → {‘layerId’: ‘0’, ‘layerName’: ‘’, ‘path’: ‘/home/qgis/shapefile.shp’}

• decode_uri(@layer) → {‘layerId’: NULL, ‘layerName’: ‘layer’, ‘path’:
Examples ‘/home/qgis/geopackage.gpkg’}
• decode_uri(@layer, 'path') → ‘C:\my_data\qgis\shape.shp’

306. 13.2.15.2. layer_property

Returns a matching layer property or metadata value.

Syntax layer_property(layer, property)

• layer - a string, representing either a layer name or layer ID
• property - a string corresponding to the property to return. Valid options are:
o name: layer name
o id: layer ID
o title: metadata title string
Arguments o abstract: metadata abstract string
o keywords: metadata keywords
o data_url: metadata URL
o attribution: metadata attribution string
o attribution_url: metadata attribution URL
o source: layer source
o min_scale: minimum display scale for layer
o max_scale: maximum display scale for layer
o is_editable: if layer is in edit mode
o crs: layer CRS
o crs_definition: layer CRS full definition
o crs_description: layer CRS description
o extent: layer extent (as a geometry object)
o distance_units: layer distance units
o type: layer type, e.g., Vector or Raster
o storage_type: storage format (vector layers only)
o geometry_type: geometry type, e.g., Point (vector layers only)
o feature_count: approximate feature count for layer (vector layers only)
o path: File path to the layer data source. Only available for file based layers.

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

• layer_property('airports','feature_count') → 120
Examples
• layer_property('landsat','crs') → ‘EPSG:4326’

307. 13.2.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.

• from_json
• hstore_to_map
• map
• map_akeys
• map_avals
• map_concat
• map_delete
• map_exist
• map_get
• map_insert
• map_prefix_keys
• map_to_hstore
• to_json
• url_encode

308. 13.2.16.1. from_json

Loads a JSON formatted string.

Syntax from_json(string)
• string - JSON string
Arguments

• from_json('{"qgis":"rocks"}') → { ‘qgis’: ‘rocks’ }

Examples • from_json('[1,2,3]') → [1,2,3]
309. 13.2.16.2. hstore_to_map

Creates a map from a hstore-formatted string.

Syntax hstore_to_map(string)
• string - the input string
Arguments

• hstore_to_map('qgis=>rocks') → { ‘qgis’: ‘rocks’ }

Examples

310. 13.2.16.3. map

Returns a map containing all the keys and values passed as pair of parameters.

Syntax map(key1, value1, key2, value2, …)

• key - a key (string)
Arguments • value - a value

• map('1','one','2', 'two') → { ‘1’: ‘one’, ‘2’: ‘two’ }

Examples • map('1','one','2', 'two')['1'] → ‘one’

311. 13.2.16.4. map_akeys

Returns all the keys of a map as an array.

Syntax map_akeys(map)
• map - a map
Arguments

• map_akeys(map('1','one','2','two')) → [ ‘1’, ‘2’ ]

Examples

312. 13.2.16.5. map_avals

Returns all the values of a map as an array.

Syntax map_avals(map)
• map - a map
Arguments

• map_avals(map('1','one','2','two')) → [ ‘one’, ‘two’ ]

Examples

313. 13.2.16.6. 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, …)

• map - a map
Arguments

• map_concat(map('1','one', '2','overridden'),map('2','two', '3','three')) → { ‘1’:

Examples ‘one’, ‘2’: ‘two’, ‘3’: ‘three’ }

314. 13.2.16.7. map_delete

Returns a map with the given key and its corresponding value deleted.

Syntax map_delete(map, key)

• map - a map
Arguments • key - the key to delete

• map_delete(map('1','one','2','two'),'2') → { ‘1’: ‘one’ }

Examples

315. 13.2.16.8. map_exist

Returns TRUE if the given key exists in the map.

Syntax map_exist(map, key)

• map - a map
Arguments • key - the key to lookup

• map_exist(map('1','one','2','two'),'3') → FALSE
Examples

316. 13.2.16.9. map_get

Returns the value of a map, given its key. Returns NULL if the key does not exist.

Syntax map_get(map, key)

• map - a map
Arguments • key - the key to lookup

• 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
Examples
the current print layout

Hint

You can also use the index operator ([]) to get a value from a map.

317. 13.2.16.10. 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)

• map - a map
• key - the key to add
Arguments
• value - the value to add

• map_insert(map('1','one'),'3','three') → { ‘1’: ‘one’, ‘3’: ‘three’ }

Examples • map_insert(map('1','one','2','overridden'),'2','two') → { ‘1’: ‘one’, ‘2’: ‘two’ }

318. 13.2.16.11. map_prefix_keys

Returns a map with all keys prefixed by a given string.

Syntax map_prefix_keys(map, prefix)

• map - a map
Arguments • prefix - a string

• map_prefix_keys(map('1','one','2','two'), 'prefix-') → { ‘prefix-1’: ‘one’, ‘prefix-2’:

Examples ‘two’ }

319. 13.2.16.12. map_to_hstore

Merge map elements into a hstore-formatted string.

Syntax map_to_hstore(map)
• map - the input map
Arguments

• map_to_hstore(map('qgis','rocks')) → ‘“qgis”=>”rocks”’
Examples

320. 13.2.16.13. to_json

Create a JSON formatted string from a map, array or other value.

Syntax to_json(value)
• value - The input value
Arguments

• to_json(map('qgis','rocks')) → {“qgis”:”rocks”}
Examples • to_json(array(1,2,3)) → [1,2,3]

321. 13.2.16.14. url_encode

Returns an URL encoded string from a map. Transforms all characters in their properly-encoded form producing a fully-
compliant query string.

Note that the plus sign ‘+’ is not converted.

Syntax url_encode(map)
• map - a map.
Arguments

• url_encode(map('a&+b', 'a and plus b', 'a=b', 'a equals b')) →

Examples ‘a%26+b=a%20and%20plus%20b&a%3Db=a%20equals%20b’

322. 13.2.17. Mathematical Functions

This group contains math functions (e.g., square root, sin and cos).

• abs
• acos
• asin
• atan
• atan2
• ceil
• clamp
• cos
• degrees
• exp
• floor
• ln
• log
• log10
• max
• min
• pi
• radians
• rand
• randf
• round
• scale_exp
• scale_linear
• sin
• sqrt
• tan

323. 13.2.17.1. abs

Returns the absolute value of a number.

Syntax abs(value)
• value - a number
Arguments

• abs(-2) →2
Examples

324. 13.2.17.2. acos

Returns the inverse cosine of a value in radians.

Syntax acos(value)
• value - cosine of an angle in radians
Arguments

• acos(0.5) → 1.0471975511966
Examples

325. 13.2.17.3. asin

Returns the inverse sine of a value in radians.

Syntax asin(value)
• value - sine of an angle in radians
Arguments

• asin(1.0) → 1.5707963267949
Examples

326. 13.2.17.4. atan

Returns the inverse tangent of a value in radians.

Syntax atan(value)
• value - tan of an angle in radians
Arguments

• atan(0.5) → 0.463647609000806
Examples

327. 13.2.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)

• dy - y coordinate difference
Arguments • dx - x coordinate difference

• atan2(1.0, 1.732) → 0.523611477769969

Examples

328. 13.2.17.6. ceil

Rounds a number upwards.

Syntax ceil(value)
• value - a number
Arguments

• ceil(4.9) → 5
Examples • ceil(-4.9) → -4

329. 13.2.17.7. clamp

Restricts an input value to a specified range.

Syntax clamp(minimum, input, maximum)

• minimum - the smallest value input is allowed to take.
• input - a value which will be restricted to the range specified by minimum and maximum
Arguments
• maximum - the largest value input is allowed to take

• clamp(1,5,10) →5

input is between 1 and 10 so is returned unchanged

• clamp(1,0,10) →1
Examples
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

330. 13.2.17.8. cos

Returns cosine of an angle.

Syntax cos(angle)
• angle - angle in radians
Arguments

• cos(1.571) → 0.000796326710733263
Examples

331. 13.2.17.9. degrees

Converts from radians to degrees.

Syntax degrees(radians)
• radians - numeric value
Arguments

• degrees(3.14159) → 180
Examples • degrees(1) → 57.2958

332. 13.2.17.10. exp

Returns exponential of an value.

Syntax exp(value)
• value - number to return exponent of
Arguments

• exp(1.0) → 2.71828182845905
Examples
333. 13.2.17.11. floor

Rounds a number downwards.

Syntax floor(value)
• value - a number
Arguments

• floor(4.9) → 4
Examples • floor(-4.9) → -5

334. 13.2.17.12. ln

Returns the natural logarithm of a value.

Syntax ln(value)
• value - numeric value
Arguments

• ln(1) → 0
Examples • ln(2.7182818284590452354) →1

335. 13.2.17.13. log

Returns the value of the logarithm of the passed value and base.

Syntax log(base, value)

• base - any positive number
Arguments • value - any positive number

• log(2, 32) → 5
Examples • log(0.5, 32) → -5

336. 13.2.17.14. log10

Returns the value of the base 10 logarithm of the passed expression.

Syntax log10(value)
• value - any positive number
Arguments

• log10(1) → 0
Examples • log10(100) → 2

337. 13.2.17.15. max

Returns the largest value in a set of values.

Syntax max(value1, value2, …)
• value - a number
Arguments

• max(2,10.2,5.5) → 10.2
Examples • max(20.5,NULL,6.2) → 20.5

338. 13.2.17.16. min

Returns the smallest value in a set of values.

Syntax min(value1, value2, …)

• value - a number
Arguments

• min(20.5,10,6.2) → 6.2
Examples • min(2,-10.3,NULL) → -10.3

339. 13.2.17.17. pi

Returns value of pi for calculations.

Syntax pi()
• pi() → 3.14159265358979
Examples

340. 13.2.17.18. radians

Converts from degrees to radians.

Syntax radians(degrees)
• degrees - numeric value
Arguments

• radians(180) → 3.14159
Examples • radians(57.2958) → 1

341. 13.2.17.19. 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.

rand(min, max, [seed=NULL])

Syntax
[] marks optional arguments
• min - an integer representing the smallest possible random number desired
• max - an integer representing the largest possible random number desired
Arguments
• seed - any value to use as seed
• rand(1, 10) →8
Examples

342. 13.2.17.20. 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.

randf([min=0.0], [max=1.0], [seed=NULL])

Syntax
[] marks optional arguments
• min - an float representing the smallest possible random number desired
• max - an float representing the largest possible random number desired
Arguments
• seed - any value to use as seed

• randf(1, 10) → 4.59258286403147

Examples

343. 13.2.17.21. round

Rounds a number to number of decimal places.

round(value, [places=0])
Syntax
[] marks optional arguments
• value - decimal number to be rounded
Arguments • places - Optional integer representing number of places to round decimals to. Can be negative.

• round(1234.567, 2) → 1234.57
• round(1234.567) → 1235
Examples
• round(1234.567, -1) → 1230

344. 13.2.17.22. 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)

• 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.
Arguments
• 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.

• scale_exp(5,0,10,0,100,2) → 25

easing in, using an exponent of 2

Examples
• scale_exp(3,0,10,0,100,0.5) → 54.772

easing out, using an exponent of 0.5

345. 13.2.17.23. 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)

• 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

Examples
• 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

346. 13.2.17.24. sin

Returns the sine of an angle.

Syntax sin(angle)
• angle - angle in radians
Arguments

• sin(1.571) → 0.999999682931835
Examples

347. 13.2.17.25. sqrt

Returns square root of a value.

Syntax sqrt(value)
• value - a number
Arguments

• sqrt(9) →3
Examples

348. 13.2.17.26. tan

Returns the tangent of an angle.

Syntax tan(angle)
• angle - angle in radians
Arguments

• tan(1.0) → 1.5574077246549
Examples

349. 13.2.18. Meshes Functions

This group contains functions which calculate or return mesh related values.

• $face_area
• $face_index
• $vertex_as_point
• $vertex_index
• $vertex_x
• $vertex_y
• $vertex_z

350. 13.2.18.1. $face_area

Returns the area of the current mesh face. 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 $face_area
• $face_area → 42
Examples

351. 13.2.18.2. $face_index

Returns the index of the current mesh face.

Syntax $face_index
• $face_index → 4581
Examples

352. 13.2.18.3. $vertex_as_point

Returns the current vertex as a point geometry.

Syntax $vertex_as_point
• geom_to_wkt( $vertex_as_point ) → ‘POINT(800 1500 41)’
Examples

353. 13.2.18.4. $vertex_index

Returns the index of the current mesh vertex.

Syntax $vertex_index
• $vertex_index → 9874
Examples

354. 13.2.18.5. $vertex_x

Returns the X coordinate of the current mesh vertex.

Syntax $vertex_x
• $vertex_x → 42.12
Examples

355. 13.2.18.6. $vertex_y

Returns the Y coordinate of the current mesh vertex.

Syntax $vertex_y
• $vertex_y → 12.24
Examples

356. 13.2.18.7. $vertex_z

Returns the Z value of the current mesh vertex.

Syntax $vertex_z
• $vertex_z → 42
Examples

357. 13.2.19. 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.

• %
• *
• +
• -
• /
• <
• <=
• <>
• =
• >
• >=
• AND
• BETWEEN
• ILIKE
• IN
• IS
• IS NOT
• LIKE
• NOT
• NOT BETWEEN
• OR
• []
• ^
• ||
• ~

358. 13.2.19.1. %

Remainder of division. Takes the sign of the dividend.

Syntax a%b
• a - value
Arguments • b - value

• 9 % 2→1
• 9 % -2 → 1
Examples • -9 % 2 → -1
• 5 % NULL → NULL

359. 13.2.19.2. *

Multiplication of two values

Syntax a*b
• a - value
Arguments • b - value

• 5 * 4 → 20
Examples • 5 * NULL → NULL

360. 13.2.19.3. +

Addition of two values. If one of the values is NULL the result will be NULL.

Syntax a+b
• a - value
Arguments • b - value

Examples • 5 + 4 →9
• 5 + NULL → NULL
• 'QGIS ' + 'ROCKS' → ‘QGIS ROCKS’
• to_datetime('2020-08-01 12:00:00') + '1 day 2 hours' → 2020-08-02T14:00:00

Division of two values

Syntax a/b
• a - value
Arguments • b - value

• 5 / 4 → 1.25
Examples • 5 / NULL → NULL

363. 13.2.19.6. <

Compares two values and evaluates to 1 if the left value is less than the right value.

Syntax a<b
• a - value
Arguments • b - value

• 5 < 4 → FALSE
• 5 < 5 → FALSE
Examples
• 4 < 5 → TRUE

364. 13.2.19.7. <=

Compares two values and evaluates to 1 if the left value is less or equal than the right value.
Syntax a <= b
• a - value
Arguments • b - value

• 5 <= 4 → FALSE
• 5 <= 5 → TRUE
Examples
• 4 <= 5 → TRUE

365. 13.2.19.8. <>

Compares two values and evaluates to 1 if they are not equal.

Syntax a <> b
• a - value
Arguments • b - value

• 5 <> 4 → TRUE
• 4 <> 4 → FALSE
Examples • 5 <> NULL → NULL
• NULL <> NULL → NULL

366. 13.2.19.9. =

Compares two values and evaluates to 1 if they are equal.

Syntax a=b
• a - value
Arguments • b - value

• 5 = 4 → FALSE
• 4 = 4 → TRUE
Examples • 5 = NULL → NULL
• NULL = NULL → NULL

367. 13.2.19.10. >

Compares two values and evaluates to 1 if the left value is greater than the right value.

Syntax a>b
• a - value
Arguments • b - value

• 5 > 4 → TRUE
• 5 > 5 → FALSE
Examples
• 4 > 5 → FALSE
368. 13.2.19.11. >=

Compares two values and evaluates to 1 if the left value is greater or equal than the right value.

Syntax a >= b
• a - value
Arguments • b - value

• 5 >= 4 → TRUE
• 5 >= 5 → TRUE
Examples
• 4 >= 5 → FALSE

369. 13.2.19.12. AND

Returns TRUE when conditions a and b are true.

Syntax a AND b
• a - condition
Arguments • b - condition

• TRUE AND TRUE → TRUE

• TRUE AND FALSE → FALSE
Examples • 4 = 2+2 AND 1 = 1 → TRUE
• 4 = 2+2 AND 1 = 2 → FALSE

370. 13.2.19.13. BETWEEN

Returns TRUE if value is within the specified range. The range is considered inclusive of the bounds. To test for
exclusion NOT BETWEEN can be used.

Syntax value BETWEEN lower_bound AND higher_bound

• value - the value to compare with a range. It can be a string, a number or a date.
Arguments • lower_bound AND higher_bound - range bounds

• 'B' BETWEEN 'A' AND 'C' → TRUE

• 2 BETWEEN 1 AND 3 → TRUE
• 2 BETWEEN 2 AND 3 → TRUE
Examples
• 'B' BETWEEN 'a' AND 'c' → FALSE
• lower('B') BETWEEN 'a' AND 'b' → TRUE

Note

value BETWEEN lower_bound AND higher_bound is the same as “value >= lower_bound AND value <=
higher_bound”.

371. 13.2.19.14. ILIKE

Returns TRUE if the first parameter matches case-insensitive the supplied pattern. LIKE can be used instead of ILIKE to
make the match case-sensitive. Works with numbers also.

Syntax string/number ILIKE pattern

• string/number - string to search
• pattern - pattern to find, you can use ‘%’ as a wildcard, ‘_’ as a single char and ‘\\’ to escape these
Arguments
special characters.

• 'A' ILIKE 'A' → TRUE

• 'A' ILIKE 'a' → TRUE
• 'A' ILIKE 'B' → FALSE
• 'ABC' ILIKE 'b' → FALSE
• 'ABC' ILIKE 'B' → FALSE
• 'ABC' ILIKE '_b_' → TRUE
• 'ABC' ILIKE '_B_' → TRUE
• 'ABCD' ILIKE '_b_' → FALSE
Examples
• 'ABCD' ILIKE '_B_' → FALSE
• 'ABCD' ILIKE '_b%' → TRUE
• 'ABCD' ILIKE '_B%' → TRUE
• 'ABCD' ILIKE '%b%' → TRUE
• 'ABCD' ILIKE '%B%' → TRUE
• 'ABCD%' ILIKE 'abcd\\%' → TRUE
• 'ABCD' ILIKE '%B\\%' → FALSE

372. 13.2.19.15. IN

Returns TRUE if value is found within a list of values.

Syntax a IN b
• a - value
Arguments • b - list of values

• 'A' IN ('A','B') → TRUE

Examples • 'A' IN ('C','B') → FALSE

373. 13.2.19.16. IS

Returns TRUE if a is the same as b.

Syntax a IS b
• a - any value
Arguments • b - any value

• 'A' IS 'A' → TRUE

• 'A' IS 'a' → FALSE
• 4 IS 4 → TRUE
Examples • 4 IS 2+2 → TRUE
• 4 IS 2 → FALSE
• $geometry IS NULL → 0, if your geometry is not NULL
374. 13.2.19.17. IS NOT

Returns TRUE if a is not the same as b.

Syntax a IS NOT b
• a - value
Arguments • b - value

• 'a' IS NOT 'b' → TRUE

• 'a' IS NOT 'a' → FALSE
Examples
• 4 IS NOT 2+2 → FALSE

375. 13.2.19.18. LIKE

Returns TRUE if the first parameter matches the supplied pattern. Works with numbers also.

Syntax string/number LIKE pattern

• string/number - value
• pattern - pattern to compare value with, you can use ‘%’ as a wildcard, ‘_’ as a single char and ‘\\’ to
Arguments
escape these special characters.

• 'A' LIKE 'A' → TRUE

• 'A' LIKE 'a' → FALSE
• 'A' LIKE 'B' → FALSE
• 'ABC' LIKE 'B' → FALSE
• 'ABC' LIKE '_B_' → TRUE
Examples • 'ABCD' LIKE '_B_' → FALSE
• 'ABCD' LIKE '_B%' → TRUE
• 'ABCD' LIKE '%B%' → TRUE
• '1%' LIKE '1\\%' → TRUE
• '1_' LIKE '1\\%' → FALSE

376. 13.2.19.19. NOT

Negates a condition.

Syntax NOT a
• a - condition
Arguments

• NOT 1 → FALSE
Examples • NOT 0 → TRUE

377. 13.2.19.20. NOT BETWEEN

Returns TRUE if value is not within the specified range. The range is considered inclusive of the bounds.

Syntax value NOT BETWEEN lower_bound AND higher_bound

• value - the value to compare with a range. It can be a string, a number or a date.
Arguments • lower_bound AND higher_bound - range bounds

• 'B' NOT BETWEEN 'A' AND 'C' → FALSE

• 1.0 NOT BETWEEN 1.1 AND 1.2 → TRUE
• 2 NOT BETWEEN 2 AND 3 → FALSE
Examples
• 'B' NOT BETWEEN 'a' AND 'c' → TRUE
• lower('B') NOT BETWEEN 'a' AND 'b' → FALSE

Note

value NOT BETWEEN lower_bound AND higher_bound is the same as “value < lower_bound OR value >
higher_bound”.

378. 13.2.19.21. OR

Returns TRUE when condition a or b is true.

Syntax a OR b
• a - condition
Arguments • b - condition

• 4 = 2+2 OR 1 = 1 → TRUE
• 4 = 2+2 OR 1 = 2 → TRUE
Examples
• 4 = 2 OR 1 = 2 → FALSE

379. 13.2.19.22. []

Index operator. Returns an element from an array or map value.

Syntax [index]
• index - array index or map key value
Arguments

• array(1,2,3)[0] → 1
• array(1,2,3)[2] → 3
• array(1,2,3)[-1] → 3
Examples
• map('a',1,'b',2)['a'] →1
• map('a',1,'b',2)['b'] →2

Power of two values.

Syntax a^b
• a - value
Arguments • b - value

• 5 ^ 4 → 625
Examples • 5 ^ NULL → NULL

381. 13.2.19.24. ||

Joins two values together into a string.

If one of the values is NULL the result will be NULL. See the CONCAT function for a different behavior.

Syntax a || b
• a - value
Arguments • b - value

• 'Here' || ' and ' || 'there' → ‘Here and there’

• 'Nothing' || NULL → NULL
Examples • 'Dia: ' || "Diameter" → ‘Dia: 25’
• 1 || 2 → ‘12’

Syntax string ~ regex

• string - A string value
Arguments • regex - A regular expression. Slashes must be escaped, eg \\d.

• 'hello' ~ 'll' → TRUE

• 'hello' ~ '^ll' → FALSE
Examples • 'hello' ~ 'llo$' → TRUE
• 'abc123' ~ '\\d+' → TRUE

383. 13.2.20. Processing Functions

This group contains functions that operate on processing algorithms.

• parameter

384. 13.2.20.1. parameter

Returns the value of a processing algorithm input parameter.

Syntax parameter(name)
• name - name of the corresponding input parameter
Arguments

• parameter('BUFFER_SIZE') → 5.6
Examples

385. 13.2.21. Rasters Functions

This group contains functions to operate on raster layer.

• raster_statistic
• raster_value

386. 13.2.21.1. raster_statistic

Returns statistics from a raster layer.

Syntax raster_statistic(layer, band, property)

• 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:
o min: minimum value
o max: maximum value
Arguments
o avg: average (mean) value
o stdev: standard deviation of values
o range: range of values (max - min)
o sum: sum of all values from raster

• raster_statistic('lc',1,'avg') → Average value from band 1 from ‘lc’ raster layer

Examples • raster_statistic('ac2010',3,'min') → Minimum value from band 3 from ‘ac2010’ raster layer

387. 13.2.21.2. raster_value

Returns the raster value found at the provided point.

Syntax raster_value(layer, band, point)

• layer - the name or id of a raster layer
• band - the band number to sample the value from.
Arguments • point - point geometry (for multipart geometries having more than one part, a NULL value will be
returned)

• raster_value('dem', 1, make_point(1,1)) → 25
Examples

388. 13.2.22. Record and Attributes Functions

This group contains functions that operate on record identifiers.

• attribute
• attributes
• $currentfeature
• display_expression
• get_feature
• get_feature_by_id
• $id
• is_selected
• maptip
• num_selected
• represent_attributes
• represent_value
• sqlite_fetch_and_increment
• uuid

389. 13.2.22.1. attribute

Returns an attribute from a feature.

Variant 1

Returns the value of an attribute from the current feature.

Syntax attribute(attribute_name)
• attribute_name - name of attribute to be returned
Arguments

• attribute( 'name' ) → value stored in ‘name’ attribute for the current feature
Examples

Variant 2

Allows the target feature and attribute name to be specified.

Syntax attribute(feature, attribute_name)

• feature - a feature
Arguments • attribute_name - name of attribute to be returned

• attribute( @atlas_feature, 'name' ) → value stored in ‘name’ attribute for the current atlas
Examples feature

390. 13.2.22.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()
• attributes()['name'] → value stored in ‘name’ attribute for the current feature
Examples
Variant 2

Allows the target feature to be specified.

Syntax attributes(feature)
• feature - a feature
Arguments

• attributes( @atlas_feature )['name'] → value stored in ‘name’ attribute for the current atlas
Examples feature

391. 13.2.22.3. $currentfeature

Returns the current feature being evaluated. This can be used with the ‘attribute’ function to evaluate attribute values from
the current feature. WARNING: This function is deprecated. It is recommended to use the replacement @feature
variable instead.

Syntax $currentfeature
• attribute( $currentfeature, 'name' ) → value stored in ‘name’ attribute for the current feature
Examples

392. 13.2.22.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()
• display_expression() → The display expression of the current feature in the current layer.
Examples

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)
• feature - The feature which should be evaluated.
Arguments

• display_expression(@atlas_feature) → The display expression of the current atlas feature.

Examples

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.
display_expression(layer, feature, [evaluate=true])
Syntax
[] marks optional arguments
• layer - The layer (or its ID or name)
• feature - The feature which should be evaluated.
Arguments • 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).

• display_expression( 'streets', get_feature_by_id('streets', 1)) → The display

expression of the feature with the ID 1 on the layer ‘streets’.
Examples • display_expression('a_layer_id', $currentfeature, 'False') → The display expression of
the given feature not evaluated.

393. 13.2.22.5. get_feature

Returns the first feature of a layer matching a given attribute value.

Single value variant

Along with the layer ID, a single column and value are specified.

Syntax get_feature(layer, attribute, value)

• layer - layer name or ID
• attribute - attribute name to use for the match
Arguments
• value - attribute value to match

• get_feature('streets','name','main st') → first feature found in “streets” layer with “main

Examples st” value in the “name” field

Map variant

Along with the layer ID, a map containing the columns (key) and their respective value to be used.

Syntax get_feature(layer, attribute)

• layer - layer name or ID
Arguments • attribute - Map containing the column and value pairs to use

• get_feature('streets',map('name','main st','lane_num','4')) → first feature found in

Examples “streets” layer with “main st” value in the “name” field and “4” value in the “lane_num” field

394. 13.2.22.6. get_feature_by_id

Returns the feature with an id on a layer.

Syntax get_feature_by_id(layer, feature_id)

• layer - layer, layer name or layer id
Arguments • feature_id - the id of the feature which should be returned
• get_feature_by_id('streets', 1) → the feature with the id 1 on the layer “streets”
Examples

395. 13.2.22.7. $id

Returns the feature id of the current row. WARNING: This function is deprecated. It is recommended to use the
replacement @id variable instead.

Syntax $id
• $id → 42
Examples

396. 13.2.22.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()
• is_selected() → TRUE if the current feature in the current layer is selected.
Examples

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)
• feature - The feature which should be checked for selection.
Arguments

• is_selected(@atlas_feature) → TRUE if the current atlas feature is selected.

• is_selected(get_feature('streets', 'name', 'Main St.')) → TRUE if the unique named
“Main St.” feature on the active “streets” layer is selected.
Examples
• is_selected(get_feature_by_id('streets', 1)) → TRUE if the feature with the id 1 on the
active “streets” 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)

• layer - The layer (its ID or name) on which the selection will be checked.
Arguments • feature - The feature which should be checked for selection.
• 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).
Examples
• is_selected( 'streets', get_feature_by_id('streets', 1)) → TRUE if the feature with the
id 1 on the “streets” layer is selected.

397. 13.2.22.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()
• maptip() → The maptip of the current feature in the current layer.
Examples

One ‘feature’ parameter

If called with a ‘feature’ parameter only, the function will evaluate the specified feature from the current layer.

Syntax maptip(feature)
• feature - The feature which should be evaluated.
Arguments

• maptip(@atlas_feature) → The maptip of the current atlas feature.

Examples

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.

maptip(layer, feature, [evaluate=true])

Syntax
[] marks optional arguments
• layer - The layer (or its ID or name)
• feature - The feature which should be evaluated.
Arguments • 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).

• maptip('streets', get_feature_by_id('streets', 1)) → The maptip of the feature with the

ID 1 on the layer ‘streets’.
Examples • maptip('a_layer_id', $currentfeature, 'False') → The maptip of the given feature not
evaluated.

398. 13.2.22.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.

num_selected([layer=current layer])
Syntax
[] marks optional arguments
• layer - The layer (or its id or name) on which the selection will be checked.
Arguments

• num_selected() → The number of selected features on the current layer.

Examples • num_selected('streets') → The number of selected features on the layer streets

399. 13.2.22.11. represent_attributes

Returns a map with the attribute names as keys and the configured representation values as values. The representation
value for the attributes depends on the configured widget type for each attribute. Can be used with zero, one or more
arguments, see below for details.

No parameters

If called with no parameters, the function will return the representation of the attributes of the current feature in the
current layer.

Syntax represent_attributes()
• represent_attributes() → The representation of the attributes for the current feature.
Examples

One ‘feature’ parameter

If called with a ‘feature’ parameter only, the function will return the representation of the attributes of the specified feature
from the current layer.

Syntax represent_attributes(feature)
• feature - The feature which should be evaluated.
Arguments

• represent_attributes(@atlas_feature) → The representation of the attributes for the specified

Examples feature from the current layer.

Layer and feature parameters

If called with a ‘layer’ and a ‘feature’ parameter, the function will return the representation of the attributes of the
specified feature from the specified layer.

Syntax represent_attributes(layer, feature)

• layer - The layer (or its ID or name).
Arguments • feature - The feature which should be evaluated.

• represent_attributes('atlas_layer', @atlas_feature) → The representation of the attributes

Examples for the specified feature from the specified layer.
Further reading: represent_value

400. 13.2.22.12. 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.

represent_value(value, [fieldName])
Syntax
[] marks optional arguments
• value - The value which should be resolved. Most likely a field.
Arguments • fieldName - The field name for which the widget configuration should be loaded.

• represent_value("field_with_value_map") → Description for value

Examples • represent_value('static value', 'field_name') → Description for static value

401. 13.2.22.13. 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.

sqlite_fetch_and_increment(database, table, id_field, filter_attribute, filter_value, [default_values])

Syntax
[] marks optional arguments
• database - Path to the sqlite file or geopackage layer
Arguments
• 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.

• sqlite_fetch_and_increment(@layer, 'sequence_table', 'last_unique_id',

'sequence_id', 'global', map('last_change', 'date(''now'')', 'user', '''' ||
@user_account_name || '''')) → 0
Examples • 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

402. 13.2.22.14. uuid

Generates a Universally Unique Identifier (UUID) for each row using the Qt QUuid::createUuid method.

uuid([format=’WithBraces’])
Syntax
[] marks optional arguments
• format - The format, as the UUID will be formatted. ‘WithBraces’, ‘WithoutBraces’ or ‘Id128’.
Arguments

• uuid() → ‘{0bd2f60f-f157-4a6d-96af-d4ba4cb366a1}’
• uuid('WithoutBraces') → ‘0bd2f60f-f157-4a6d-96af-d4ba4cb366a1’
Examples
• uuid('Id128') → ‘0bd2f60ff1574a6d96afd4ba4cb366a1’

403. 13.2.23. 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.

404. 13.2.24. String Functions

This group contains functions that operate on strings (e.g., that replace, convert to upper case).

• ascii
• char
• concat
• format
• format_date
• format_number
• left
• length
• lower
• lpad
• regexp_match
• regexp_replace
• regexp_substr
• replace
• right
• rpad
• strpos
• substr
• title
• to_string
• trim
• upper
• wordwrap

405. 13.2.24.1. ascii

Returns the unicode code associated with the first character of a string.

Syntax ascii(string)
• string - the string to convert to unicode code
Arguments

• ascii('Q') → 81
Examples

406. 13.2.24.2. char

Returns the character associated with a unicode code.

Syntax char(code)
• code - a unicode code number
Arguments

• char(81) → ‘Q’
Examples

407. 13.2.24.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, …)

• string - a string value
Arguments

• concat('sun', 'set') → ‘sunset’

• concat('a','b','c','d','e') → ‘abcde’
Examples • 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: '

408. 13.2.24.4. format

Format a string using supplied arguments.

Syntax format(string, arg1, arg2, …)

• string - A string with placeholders %1, %2, etc., for the arguments. Placeholders can be repeated.
The lowest numbered placeholder is replaced by arg1, the next by arg2, etc.
Arguments
• arg - any type. Any number of arguments.

• format('This %1 a %2','is', 'test') → ‘This is a test’

• format('This is %2','a bit unexpected but 2 is lowest number in string','normal')
Examples
→ ‘This is a bit unexpected but 2 is lowest number in string’

409. 13.2.24.5. format_date

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

format_date(datetime, format, [language])

Syntax
[] marks optional 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’)
Arguments 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. By default the current QGIS user locale is used.

410. 13.2.24.6. format_number

Returns a number formatted with the locale separator for thousands. By default the current QGIS user locale is used. Also
truncates the decimal places to the number of supplied places.

format_number(number, [places=0], [language], [omit_group_separators=false],

[trim_trailing_zeroes=false])
Syntax
[] marks optional 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. By default the current QGIS user locale is used.
Arguments
• omit_group_separators - if set to true then group separators will not be included in the string
• trim_trailing_zeroes - if set to true then trailing zeros following the decimal point will be trimmed
from the string

• format_number(10000000.332,2) → ‘10,000,000.33’ if e.g. the current locale is an English variant

Examples • format_number(10000000.332,2,'fr') → ‘10 000 000,33’

411. 13.2.24.7. left

Returns a substring that contains the n leftmost characters of the string.

Syntax left(string, length)

• string - a string
Arguments • length - integer. The number of characters from the left of the string to return.

• left('Hello World',5) → ‘Hello’

Examples

412. 13.2.24.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)
• string - string to count length of
Arguments

• length('hello') →5
Examples

Geometry variant

Syntax length(geometry)
• geometry - line geometry object
Arguments

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

Examples

413. 13.2.24.9. lower

Converts a string to lower case letters.

Syntax lower(string)
• string - the string to convert to lower case
Arguments

• lower('HELLO World') → ‘hello world’

Examples

414. 13.2.24.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)
• string - string to pad
• width - length of new string
Arguments
• fill - character to pad the remaining space with

• lpad('Hello', 10, 'x') → ‘xxxxxHello’

Examples • lpad('Hello', 3, 'x') → ‘Hel’

415. 13.2.24.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)

• regexp_match('QGIS ROCKS','\\sROCKS') →5
Examples • regexp_match('Budač','udač\\b') → 2

416. 13.2.24.12. regexp_replace

Returns a string with the supplied regular expression replaced.

Syntax regexp_replace(input_string, regex, replacement)

• 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).
Arguments
• 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.

• regexp_replace('QGIS SHOULD ROCK','\\sSHOULD\\s',' DOES ') → ‘QGIS DOES ROCK’

• regexp_replace('ABC123','\\d+','') → ‘ABC’
Examples
• regexp_replace('my name is John','(.*) is (.*)','\\2 is \\1') → ‘John is my name’

417. 13.2.24.13. regexp_substr

Returns the portion of a string which matches a supplied regular expression.

Syntax regexp_substr(input_string, regex)

• input_string - the string to find matches in
• regex - The regular expression to match against. Backslash characters must be double escaped (e.g.,
Arguments
“\\s” to match a white space character).

• regexp_substr('abc123','(\\d+)') → ‘123’
Examples
418. 13.2.24.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)

• string - the input string
• before - the string or array of strings to replace
Arguments
• after - the string or array of strings to use as a replacement

• replace('QGIS SHOULD ROCK','SHOULD','DOES') → ‘QGIS DOES ROCK’

• replace('QGIS ABC',array('A','B','C'),array('X','Y','Z')) → ‘QGIS XYZ’
Examples
• replace('QGIS',array('Q','S'),'') → ‘GI’

Map variant

Returns a string with the supplied map keys replaced by paired values. Longer map keys are evaluated first.

Syntax replace(string, map)

• string - the input string
Arguments • map - the map containing keys and values

• replace('APP SHOULD ROCK',map('APP','QGIS','SHOULD','DOES')) → ‘QGIS DOES ROCK’

Examples • replace('forty two',map('for','4','two','2','forty two','42')) → ‘42’

419. 13.2.24.15. right

Returns a substring that contains the n rightmost characters of the string.

Syntax right(string, length)

• string - a string
Arguments • length - integer. The number of characters from the right of the string to return.

• right('Hello World',5) → ‘World’

Examples

420. 13.2.24.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)

• string - string to pad
Arguments
• width - length of new string
• fill - character to pad the remaining space with

• rpad('Hello', 10, 'x') → ‘Helloxxxxx’

Examples • rpad('Hello', 3, 'x') → ‘Hel’

421. 13.2.24.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)

• haystack - string that is to be searched
Arguments • needle - string to search for

• strpos('HELLO WORLD','WORLD') → 7
Examples • strpos('HELLO WORLD','GOODBYE') → 0

422. 13.2.24.18. substr

Returns a part of a string.

substr(string, start, [length])

Syntax
[] marks optional 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
Arguments
• 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

• substr('HELLO WORLD',3,5) → ‘LLO W’

• substr('HELLO WORLD',6) → ‘ WORLD’
• substr('HELLO WORLD',-5) → ‘WORLD’
Examples • substr('HELLO',3,-1) → ‘LL’
• substr('HELLO WORLD',-5,2) → ‘WO’
• substr('HELLO WORLD',-5,-1) → ‘WORL’

423. 13.2.24.19. title

Converts all words of a string to title case (all words lower case with leading capital letter).

Syntax title(string)
• string - the string to convert to title case
Arguments

• title('hello WOrld') → ‘Hello World’

Examples

424. 13.2.24.20. to_string

Converts a number to string.

Syntax to_string(number)
• number - Integer or real value. The number to convert to string.
Arguments

• to_string(123) → ‘123’
Examples

425. 13.2.24.21. trim

Removes all leading and trailing whitespace (spaces, tabs, etc) from a string.

Syntax trim(string)
• string - string to trim
Arguments

• trim(' hello world ') → ‘hello world’

Examples

426. 13.2.24.22. upper

Converts a string to upper case letters.

Syntax upper(string)
• string - the string to convert to upper case
Arguments

• upper('hello WOrld') → ‘HELLO WORLD’

Examples

427. 13.2.24.23. wordwrap

Returns a string wrapped to a maximum/minimum number of characters.

wordwrap(string, wrap_length, [delimiter_string])

Syntax
[] marks optional 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
Arguments
to wrap.
• delimiter_string - Optional delimiter string to wrap to a new line.

• wordwrap('UNIVERSITY OF QGIS',13) → ‘UNIVERSITY OF<br>QGIS’

Examples • wordwrap('UNIVERSITY OF QGIS',-3) → ‘UNIVERSITY<br>OF QGIS’

428. 13.2.25. User Expressions

This group contains the expressions saved as user expressions.
429. 13.2.26. 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 Select by expression

dialog
• from the 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
represents the feature currently being edited in the parent form. Only usable in an embedded
current_parent_feature
form context.
represents the geometry of the feature currently being edited in the parent form. Only usable in
current_parent_geometry
an embedded form context.
What the form is used for, like AddFeatureMode, SingleEditMode, MultiEditMode,
form_mode
SearchMode, AggregateSearchMode or IdentifyMode as string.
The current feature being evaluated. This can be used with the ‘attribute’ function to evaluate
feature NEW in 3.28
attribute values from the current feature.
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 NEW in 3.28 The geometry of the current feature being evaluated
Variable Description
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
Current geometry ring number for feature being rendered (for polygon features only). The
geometry_ring_num
exterior ring has a value of 0.
grid_axis The current grid annotation axis (eg, ‘x’ for longitude, ‘y’ for latitude)
grid_number The current grid annotation value
id NEW in 3.28 The ID of the current feature being evaluated
item_id The layout item user ID (not necessarily unique)
item_uuid The layout item unique ID
layer The current layer
layer_crs The Coordinate Reference System Authority ID of 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
The active page height in the layout (in mm for standard paper sizes, or whatever unit was used
layout_pageheight
for custom paper size)
Array of Y coordinate of the top of each page. Allows to dynamically position items on pages
layout_pageoffsets
in a context where page sizes may change
The active page width in the layout (in mm for standard paper sizes, or whatever unit was used
layout_pagewidth
for custom paper size)
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
The descriptive name of the projection method used by the Coordinate reference system of the
map_crs_projection
map (e.g. ‘Albers Equal Area’)
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
Variable Description
map_extent_height The current height of the map
map_extent_width The current width of the map
The ID of current map destination. This will be ‘canvas’ for canvas renders, and the item ID for
map_id
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
Full path (including file name) of current model (or project path if model is embedded in a
model_path
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
Content of the notification message sent by the provider (available only for actions triggered by
notification_message
provider notifications).
Refers to the current feature in the parent layer, providing access to its attributes and geometry
parent
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
The distance unit for the current project, used when calculating lengths of geometries and
project_distance_units
distances
The name of the ellipsoid of the current project, used when calculating geodetic areas or
project_ellipsoid
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
Variable Description
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
Selected file path from file widget selector when uploading a file with an external storage
selected_file_path
system
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)
The label for the symbol (either a user defined label or the default autogenerated label - in the
symbol_label
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
Exact vector tile zoom level of the map that is being rendered (derived from the current map
vector_tile_zoom scale). Normally in interval [0, 20]. Unlike @zoom_level, this variable is a floating point value
which can be used to interpolate values between two integer zoom levels.
Allows setting a variable for usage within an expression and avoid recalculating the same value
with_variable
repeatedly
Vector tile zoom level of the map that is being rendered (derived from the current map scale).
zoom_level
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'
)
)

Effective Pandas
50% (2)
Effective Pandas
20 pages
QGIS 3.22 PyQGISDeveloperCookbook en
No ratings yet
QGIS 3.22 PyQGISDeveloperCookbook en
162 pages
MongoDB Aggregation Guide
No ratings yet
MongoDB Aggregation Guide
46 pages
Data Science Tools Study Guides For MIT's 15.003
No ratings yet
Data Science Tools Study Guides For MIT's 15.003
23 pages
LEE To ROSCO Equivalents
No ratings yet
LEE To ROSCO Equivalents
4 pages
Comprehensive Guide To Grouping and Aggregating With Pandas - Practical Business Python
No ratings yet
Comprehensive Guide To Grouping and Aggregating With Pandas - Practical Business Python
23 pages
MongoDB Aggregation Guide PDF
No ratings yet
MongoDB Aggregation Guide PDF
46 pages
Understanding Pandas Groupby For Data Aggregation
No ratings yet
Understanding Pandas Groupby For Data Aggregation
49 pages
SQL To Pandas - Group Aggregations
No ratings yet
SQL To Pandas - Group Aggregations
6 pages
QlikView Technical Brief - AGGR
No ratings yet
QlikView Technical Brief - AGGR
13 pages
Super Study Guide: Data Science Tools: Afshine Amidi and Shervine Amidi August 21, 2020
No ratings yet
Super Study Guide: Data Science Tools: Afshine Amidi and Shervine Amidi August 21, 2020
23 pages
Introduction to PHP, Part 2, Second Edition
From Everand
Introduction to PHP, Part 2, Second Edition
Adam Majczak
No ratings yet
Apache Spark Builtin Functions
No ratings yet
Apache Spark Builtin Functions
9 pages
Chapter-2 Python Pandas
100% (2)
Chapter-2 Python Pandas
33 pages
Data Manipulation and Analysis
No ratings yet
Data Manipulation and Analysis
32 pages
CO3_2_Aggregation and Concatenation, Grouping Data
No ratings yet
CO3_2_Aggregation and Concatenation, Grouping Data
33 pages
Data Manipulation With Pandas - Yulei's Sandbox
No ratings yet
Data Manipulation With Pandas - Yulei's Sandbox
18 pages
Learn C++
From Everand
Learn C++
Durgesh
4.5/5 (9)
Descriptive Statistics With Pandas: Data Handling Using Pandas - II
100% (1)
Descriptive Statistics With Pandas: Data Handling Using Pandas - II
37 pages
CSS Grid Layout
From Everand
CSS Grid Layout
Abdelfattah Ragab
No ratings yet
Basic GIS Data Analysis Operation: by Dechasa Ejara ID Ramit/488/09
No ratings yet
Basic GIS Data Analysis Operation: by Dechasa Ejara ID Ramit/488/09
38 pages
Answer
No ratings yet
Answer
21 pages
Unit - 1 Eda Continuation 2
No ratings yet
Unit - 1 Eda Continuation 2
34 pages
GIS Lec3 Spatial-Data-Analysis Final
No ratings yet
GIS Lec3 Spatial-Data-Analysis Final
19 pages
QGIS 3.16 PyQGISDeveloperCookbook en
No ratings yet
QGIS 3.16 PyQGISDeveloperCookbook en
164 pages
SNOW - Glide Aggregate
No ratings yet
SNOW - Glide Aggregate
25 pages
QGIS 3.16 PyQGISDeveloperCookbook en
No ratings yet
QGIS 3.16 PyQGISDeveloperCookbook en
164 pages
Aggregation_nates
No ratings yet
Aggregation_nates
12 pages
dbms
No ratings yet
dbms
13 pages
mongo2
No ratings yet
mongo2
2 pages
Working With Attributes - QGIS
No ratings yet
Working With Attributes - QGIS
17 pages
Bpath Lesson 10 Aggregations
No ratings yet
Bpath Lesson 10 Aggregations
7 pages
T3_L2_GROUPBY
No ratings yet
T3_L2_GROUPBY
25 pages
ELK 1 4 - ES Aggregations
No ratings yet
ELK 1 4 - ES Aggregations
14 pages
Week 3 Laboratory Activity
No ratings yet
Week 3 Laboratory Activity
7 pages
Chapter 6 PDF
No ratings yet
Chapter 6 PDF
77 pages
Lecture 7 Vector Analysis-converted
No ratings yet
Lecture 7 Vector Analysis-converted
44 pages
Aggregate Functions - in OBIEE
No ratings yet
Aggregate Functions - in OBIEE
10 pages
In Geographic Information Systems
No ratings yet
In Geographic Information Systems
5 pages
Dataframe Extended-Ii
No ratings yet
Dataframe Extended-Ii
19 pages
Mongodb Indexing and Aggregation in Mongodb
No ratings yet
Mongodb Indexing and Aggregation in Mongodb
33 pages
Applied GIS - 3022
No ratings yet
Applied GIS - 3022
140 pages
Relational Algebra and Data Aggregation
No ratings yet
Relational Algebra and Data Aggregation
43 pages
02 GROUP by Statements
No ratings yet
02 GROUP by Statements
67 pages
QGIS-3.34-PyQGISDeveloperCookbook-en
No ratings yet
QGIS-3.34-PyQGISDeveloperCookbook-en
170 pages
W3 R4 Aggregate
No ratings yet
W3 R4 Aggregate
16 pages
Data Integration
No ratings yet
Data Integration
30 pages
Working With Attributes (QGIS3) - QGIS Tutorials and Tips
No ratings yet
Working With Attributes (QGIS3) - QGIS Tutorials and Tips
13 pages
UNIT II -DA USING R
No ratings yet
UNIT II -DA USING R
18 pages
PostgreSQL Aggregate Functions
No ratings yet
PostgreSQL Aggregate Functions
4 pages
GlideAggregate API and it's Methods for Scripting.
No ratings yet
GlideAggregate API and it's Methods for Scripting.
16 pages
Relational Algebra Ii: CS121: Relational Databases Fall 2018 - Lecture 3
No ratings yet
Relational Algebra Ii: CS121: Relational Databases Fall 2018 - Lecture 3
43 pages
DATA AGGREGATION USING PYTHON (1)
No ratings yet
DATA AGGREGATION USING PYTHON (1)
33 pages
QGIS Testing PyQGISDeveloperCookbook en
No ratings yet
QGIS Testing PyQGISDeveloperCookbook en
170 pages
4- MongoDB aggregation framework (1)
No ratings yet
4- MongoDB aggregation framework (1)
38 pages
ADO Lecture VIII 2023-25
No ratings yet
ADO Lecture VIII 2023-25
27 pages
ADB - Lab Sheet 4
No ratings yet
ADB - Lab Sheet 4
11 pages
Python CheatSheet
No ratings yet
Python CheatSheet
2 pages
geog204_fall22_lecture5
No ratings yet
geog204_fall22_lecture5
14 pages
01-Numpy & Pandas
No ratings yet
01-Numpy & Pandas
69 pages
Find Neighbor Polygons A4
No ratings yet
Find Neighbor Polygons A4
11 pages
Study of Size-Segregated Particle (PM1, PM2.5, PM10) Concentrations Over Greece
No ratings yet
Study of Size-Segregated Particle (PM1, PM2.5, PM10) Concentrations Over Greece
12 pages
Advanced Topics in Optimization: Applications in Civil Engineering
No ratings yet
Advanced Topics in Optimization: Applications in Civil Engineering
10 pages
A Brief Guide To R For Beginners in Econometrics: Department of Economics, Stockholm University
No ratings yet
A Brief Guide To R For Beginners in Econometrics: Department of Economics, Stockholm University
31 pages
Tobler's First Law and Spatial Analysis
No ratings yet
Tobler's First Law and Spatial Analysis
7 pages
Sample Size For Nonparametric Tests
No ratings yet
Sample Size For Nonparametric Tests
2 pages
2007 Piarc Evaluating Automated Cracking Equipment
No ratings yet
2007 Piarc Evaluating Automated Cracking Equipment
25 pages
Nlogit An R Package Presentation
No ratings yet
Nlogit An R Package Presentation
40 pages
Before and After Survey
No ratings yet
Before and After Survey
4 pages
Level of Service Descriptions
No ratings yet
Level of Service Descriptions
1 page
Factor Analysis
No ratings yet
Factor Analysis
22 pages
Instructions For Authors Submitting For TRB 2020 Presentation and TRR Publication Review
No ratings yet
Instructions For Authors Submitting For TRB 2020 Presentation and TRR Publication Review
10 pages
Lit Rev On Emissions Exposure and Health
No ratings yet
Lit Rev On Emissions Exposure and Health
31 pages
Geoprocessing in QGIS
No ratings yet
Geoprocessing in QGIS
52 pages
DMX Protocol Robin Pointe - DMX Protocol, Version 1.4
No ratings yet
DMX Protocol Robin Pointe - DMX Protocol, Version 1.4
7 pages
Lilac Color - Google Search
No ratings yet
Lilac Color - Google Search
1 page
Dupont Artistri Product Offering: Textile Inks and Auxiliaries
No ratings yet
Dupont Artistri Product Offering: Textile Inks and Auxiliaries
2 pages
Real Time Myanmar Traffic Sign Recognition System Using HOG and SVM
No ratings yet
Real Time Myanmar Traffic Sign Recognition System Using HOG and SVM
5 pages
Taga 2007 Neutral Scales Press Calibration
No ratings yet
Taga 2007 Neutral Scales Press Calibration
9 pages
Burnyeat de Anima II 5 PDF
No ratings yet
Burnyeat de Anima II 5 PDF
63 pages
English (302) Tutor Marked Assignment: Max. Marks: 20
No ratings yet
English (302) Tutor Marked Assignment: Max. Marks: 20
3 pages
Lesson Plan G8 Week 12-13
No ratings yet
Lesson Plan G8 Week 12-13
5 pages
Inserto 038016 Alcohol Test en Orina Alc712
No ratings yet
Inserto 038016 Alcohol Test en Orina Alc712
1 page
Architectural Design 5 - Psychology of Space
No ratings yet
Architectural Design 5 - Psychology of Space
17 pages
Machine Vision For Line Detection With Labview
No ratings yet
Machine Vision For Line Detection With Labview
10 pages
Principles, Developments and Applications of Computer Vision For External Quality Inspection of Fruits and Vegetables A Review
No ratings yet
Principles, Developments and Applications of Computer Vision For External Quality Inspection of Fruits and Vegetables A Review
19 pages
This Is Your Presentati On Title
No ratings yet
This Is Your Presentati On Title
28 pages
Ricoh SG3110DN Instruction of CorelDraw Settings
No ratings yet
Ricoh SG3110DN Instruction of CorelDraw Settings
8 pages
NAVIGATION Lumion
No ratings yet
NAVIGATION Lumion
24 pages
Skin Segmentation Based On Improved Thresholding Method: By: G.Sreeramya 1118409
No ratings yet
Skin Segmentation Based On Improved Thresholding Method: By: G.Sreeramya 1118409
18 pages
Gat Assignment
No ratings yet
Gat Assignment
4 pages
Gallese & Lakoff - The Brain's Concepts
No ratings yet
Gallese & Lakoff - The Brain's Concepts
60 pages
Color 1 Color 2 Color 3 Color 4 Color 5
No ratings yet
Color 1 Color 2 Color 3 Color 4 Color 5
4 pages
Manual Optica PASCO
No ratings yet
Manual Optica PASCO
75 pages
Explanation Text About Rainbow
25% (4)
Explanation Text About Rainbow
4 pages
Blue BC Blue CLF Red FBB S4R Brown S3R: Blusbb
No ratings yet
Blue BC Blue CLF Red FBB S4R Brown S3R: Blusbb
186 pages
750-1-0001 Spectrum Survey Rev 5 (Low Res)
No ratings yet
750-1-0001 Spectrum Survey Rev 5 (Low Res)
294 pages
Beer'S Law Simulation Lab: 2. Grade Level
No ratings yet
Beer'S Law Simulation Lab: 2. Grade Level
14 pages
Manual lb230n Ingles
No ratings yet
Manual lb230n Ingles
8 pages
Dot Matrix SF
No ratings yet
Dot Matrix SF
2 pages
Color Wheel
No ratings yet
Color Wheel
8 pages
01 - Bill Nye Light and Colour 1 Page
No ratings yet
01 - Bill Nye Light and Colour 1 Page
1 page