Contains functions which aggregate values over layers and fields.
Returns an aggregate value calculated using features from another layer.
aggregate
(
layer
,
aggregate
,
expression
[,
filter
][,
concatenator
][,
order_by
])
| layer | a string, representing either a layer name or layer ID |
| aggregate |
a string corresponding to the aggregate to calculate. Valid options are:
|
| expression | sub expression or field name to aggregate |
| filter | optional filter expression to limit the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. The source feature can be accessed with the variable @parent. |
| concatenator | optional string to use to join values for 'concatenate' aggregate |
| order_by | optional filter expression to order the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. |
aggregate(layer:='rail_stations',aggregate:='sum',expression:="passengers")
→
sum of all values from the passengers field in the rail_stations layer
aggregate('rail_stations','sum', "passengers"/7)
→
calculates a daily average of "passengers" by dividing the "passengers" field by 7 before summing the values
aggregate(layer:='rail_stations',aggregate:='sum',expression:="passengers",filter:="class">3)
→
sums up all values from the "passengers" field from features where the "class" attribute is greater than 3 only
aggregate(layer:='rail_stations',aggregate:='concatenate', expression:="name", concatenator:=',')
→
comma separated list of the name field for all features in the rail_stations layer
aggregate(layer:='countries', aggregate:='max', expression:="code", filter:=intersects( $geometry, geometry(@parent) ) )
→
The country code of an intersecting country on the layer 'countries'
Returns an array of aggregated values from a field or expression.
array_agg
(
expression
[,
group_by
][,
filter
][,
order_by
])
| expression | sub expression of field to aggregate |
| group_by | optional expression to use to group aggregate calculations |
| filter | optional expression to use to filter features used to calculate aggregate |
| order_by | optional expression to use to order features used to calculate aggregate |
array_agg("name",group_by:="state")
→
list of name values, grouped by state field
Returns the multipart geometry of aggregated geometries from an expression
collect
(
expression
[,
group_by
][,
filter
])
| expression | geometry expression to aggregate |
| group_by | optional expression to use to group aggregate calculations |
| filter | optional expression to use to filter features used to calculate aggregate |
collect( $geometry )
→
multipart geometry of aggregated geometries
Returns all aggregated strings from a field or expression joined by a delimiter.
concatenate
(
expression
[,
group_by
][,
filter
][,
concatenator
][,
order_by
])
| expression | sub expression of field to aggregate |
| group_by | optional expression to use to group aggregate calculations |
| filter | optional expression to use to filter features used to calculate aggregate |
| concatenator | optional string to use to join values |
| order_by | optional expression to use to order features used to calculate aggregate |
concatenate("town_name",group_by:="state",concatenator:=',')
→
comma separated list of town_names, grouped by state field
Returns all unique strings from a field or expression joined by a delimiter.
concatenate_unique
(
expression
[,
group_by
][,
filter
][,
concatenator
][,
order_by
])
| expression | sub expression of field to aggregate |
| group_by | optional expression to use to group aggregate calculations |
| filter | optional expression to use to filter features used to calculate aggregate |
| concatenator | optional string to use to join values |
| order_by | optional expression to use to order features used to calculate aggregate |
concatenate("town_name",group_by:="state",concatenator:=',')
→
comma separated list of unique town_names, grouped by state field
Returns the count of matching features.
count
(
expression
[,
group_by
][,
filter
])
| 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 |
count("stations",group_by:="state")
→
count of stations, grouped by state field
Returns the count of distinct values.
count_distinct
(
expression
[,
group_by
][,
filter
])
| 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 |
count_distinct("stations",group_by:="state")
→
count of distinct stations values, grouped by state field
Returns the count of missing (null) values.
count_missing
(
expression
[,
group_by
][,
filter
])
| 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 |
count_missing("stations",group_by:="state")
→
count of missing (null) station values, grouped by state field
Returns the calculated inter quartile range from a field or expression.
iqr
(
expression
[,
group_by
][,
filter
])
| 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 |
iqr("population",group_by:="state")
→
inter quartile range of population value, grouped by state field
Returns the aggregate majority of values (most commonly occurring value) from a field or expression.
majority
(
expression
[,
group_by
][,
filter
])
| 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 |
majority("class",group_by:="state")
→
most commonly occurring class value, grouped by state field
Returns the maximum length of strings from a field or expression.
max_length
(
expression
[,
group_by
][,
filter
])
| 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 |
max_length("town_name",group_by:="state")
→
maximum length of town_name, grouped by state field
Returns the aggregate maximum value from a field or expression.
maximum
(
expression
[,
group_by
][,
filter
])
| 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 |
maximum("population",group_by:="state")
→
maximum population value, grouped by state field
Returns the aggregate mean value from a field or expression.
mean
(
expression
[,
group_by
][,
filter
])
| 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 |
mean("population",group_by:="state")
→
mean population value, grouped by state field
Returns the aggregate median value from a field or expression.
median
(
expression
[,
group_by
][,
filter
])
| 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 |
median("population",group_by:="state")
→
median population value, grouped by state field
Returns the minimum length of strings from a field or expression.
min_length
(
expression
[,
group_by
][,
filter
])
| 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 |
min_length("town_name",group_by:="state")
→
minimum length of town_name, grouped by state field
Returns the aggregate minimum value from a field or expression.
minimum
(
expression
[,
group_by
][,
filter
])
| 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 |
minimum("population",group_by:="state")
→
minimum population value, grouped by state field
Returns the aggregate minority of values (least occurring value) from a field or expression.
minority
(
expression
[,
group_by
][,
filter
])
| 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 |
minority("class",group_by:="state")
→
least occurring class value, grouped by state field
Returns the calculated first quartile from a field or expression.
q1
(
expression
[,
group_by
][,
filter
])
| 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 |
q1("population",group_by:="state")
→
first quartile of population value, grouped by state field
Returns the calculated third quartile from a field or expression.
q3
(
expression
[,
group_by
][,
filter
])
| 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 |
q3("population",group_by:="state")
→
third quartile of population value, grouped by state field
Returns the aggregate range of values (maximum - minimum) from a field or expression.
range
(
expression
[,
group_by
][,
filter
])
| 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 |
range("population",group_by:="state")
→
range of population values, grouped by state field
Returns an aggregate value calculated using all matching child features from a layer relation.
relation_aggregate
(
relation
,
aggregate
,
expression
[,
concatenator
][,
filter
])
| relation | a string, representing a relation ID |
| aggregate |
a string corresponding to the aggregate to calculate. Valid options are:
|
| expression | sub expression or field name to aggregate |
| concatenator | optional string to use to join values for 'concatenate' aggregate |
| filter | optional filter expression to order the features used for calculating the aggregate. Fields and geometry are from the features on the joined layer. |
relation_aggregate(relation:='my_relation',aggregate:='mean',expression:="passengers")
→
mean value of all matching child features using the 'my_relation' relation
relation_aggregate('my_relation','sum', "passengers"/7)
→
sum of the passengers field divided by 7 for all matching child features using the 'my_relation' relation
relation_aggregate('my_relation','concatenate', "towns", concatenator:=',')
→
comma separated list of the towns field for all matching child features using the 'my_relation' relation
relation_aggregate('my_relation','array_agg', "id")
→
array of the id field from all matching child features using the 'my_relation' relation
Returns the aggregate standard deviation value from a field or expression.
stdev
(
expression
[,
group_by
][,
filter
])
| 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 state field
Returns the aggregate summed value from a field or expression.
sum
(
expression
[,
group_by
][,
filter
])
| 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 |
sum("population",group_by:="state")
→
summed population value, grouped by state field
This group contains expression functions for the creation and manipulation of arrays (also known as list data structures). The order of values within the array matters, in contrary to the 'map' data structure, where the order of key-value pairs is irrelevant and values are identified by their keys.
Returns an array containing all the values passed as parameter.
array
(
value1
,
value2
…)
| value | a value |
array(2,10)
→
[ 2, 10 ]
Returns true if an array contains all the values of a given array.
array_all
(
array_a
,
array_b
)
| array_a | an array |
| array_b | the array of values to search |
array_all(array(1,2,3),array(2,3))
→
true
array_all(array(1,2,3),array(1,2,4))
→
false
Returns an array with the given value added at the end.
array_append
(
array
,
value
)
| array | an array |
| value | the value to add |
array_append(array(1,2,3),4)
→
[ 1, 2, 3, 4 ]
Returns an array containing all the given arrays concatenated.
array_cat
(
array1
,
array2
…)
| array | an array |
array_cat(array(1,2),array(2,3))
→
[ 1, 2, 2, 3 ]
Returns true if an array contains the given value.
array_contains
(
array
,
value
)
| array | an array |
| value | the value to search |
array_contains(array(1,2,3),2)
→
true
Returns an array containing distinct values of the given array.
array_distinct
(
array
)
| array | an array |
array_distinct(array(1,2,3,2,1))
→
[ 1, 2, 3 ]
Returns an array with only the items for which the expression evaluates to true.
array_filter
(
array
,
expression
)
| array | an array |
| expression | an expression to evaluate on each item. The variable `@element` will be replaced by the current value. |
array_filter(array(1,2,3),@element < 3)
→
[ 1, 2 ]
Returns the index (0 for the first one) of a value within an array. Returns -1 if the value is not found.
array_find
(
array
,
value
)
| array | an array |
| value | the value to search |
array_find(array(1,2,3),2)
→
1
Returns the first value of an array.
array_first
(
array
)
| array | an array |
array_first(array('a','b','c'))
→
'a'
Returns an array with the given expression evaluated on each item.
array_foreach
(
array
,
expression
)
| array | an array |
| expression | an expression to evaluate on each item. The variable `@element` will be replaced by the current value. |
array_foreach(array('a','b','c'),upper(@element))
→
[ 'A', 'B', 'C' ]
array_foreach(array(1,2,3),@element + 10)
→
[ 11, 12, 13 ]
Returns the Nth value (0 for the first one) of an array.
array_get
(
array
,
index
)
| array | an array |
| index | the index to get (0 based) |
array_get(array('a','b','c'),1)
→
'b'
Returns an array with the given value added at the given position.
array_insert
(
array
,
pos
,
value
)
| array | an array |
| pos | the position where to add (0 based) |
| value | the value to add |
array_insert(array(1,2,3),1,100)
→
[ 1, 100, 2, 3 ]
Returns true if at least one element of array1 exists in array2.
array_intersect
(
array1
,
array2
)
| array1 | an array |
| array2 | another array |
array_intersect(array(1,2,3,4),array(4,0,2,5))
→
true
Returns the last value of an array.
array_last
(
array
)
| array | an array |
array_last(array('a','b','c'))
→
'c'
Returns the number of elements of an array.
array_length
(
array
)
| array | an array |
array_length(array(1,2,3))
→
3
Returns an array with the given value added at the beginning.
array_prepend
(
array
,
value
)
| array | an array |
| value | the value to add |
array_prepend(array(1,2,3),0)
→
[ 0, 1, 2, 3 ]
Returns an array with all the entries of the given value removed.
array_remove_all
(
array
,
value
)
| array | an array |
| value | the values to remove |
array_remove_all(array('a','b','c','b'),'b')
→
[ 'a', 'c' ]
Returns an array with the given index removed.
array_remove_at
(
array
,
pos
)
| array | an array |
| pos | the position to remove (0 based) |
array_remove_at(array(1,2,3),1)
→
[ 1, 3 ]
Returns the given array with array values in reversed order.
array_reverse
(
array
)
| array | an array |
array_reverse(array(2,4,0,10))
→
[ 10, 0, 4, 2 ]
Returns a portion of the array. The slice is defined by the start_pos and end_pos arguments.
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). |
| 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 ]
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_slice(array('Dufour','Valmiera','Chugiak','Brighton'),-2,-1)
→
[ 'Chugiak', 'Brighton' ]
Returns the provided array with its elements sorted.
array_sort
(
array
[,
ascending=true
])
| array | an array |
| ascending | set this parameter to false to sort the array in descending order |
array_sort(array(3,2,1))
→
[ 1, 2, 3 ]
Concatenates array elements into a string separated by a delimiter and using optional string for empty values.
array_to_string
(
array
[,
delimiter=','
][,
empty_value=''
])
| array | the input array |
| delimiter | the string delimiter used to separate concatenated array elements |
| empty_value | the optional string to use as replacement for empty (zero length) matches |
array_to_string(array('1','2','3'))
→
'1,2,3'
array_to_string(array(1,2,3),'-')
→
'1-2-3'
array_to_string(array('1','','3'),',','0')
→
'1,0,3'
Creates an array containing a sequence of numbers.
generate_series
(
start
,
stop
[,
step=1
])
| start | first value of the sequence |
| stop | value that ends the sequence once reached |
| step | value used as the increment between values |
generate_series(1,5)
→
[ 1, 2, 3, 4, 5 ]
generate_series(5,1,-1)
→
[ 5, 4, 3, 2, 1 ]
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=''
])
| string | the string to capture groups from against the regular expression |
| regex | the regular expression used to capture groups |
| empty_value | the optional string to use as replacement for empty (zero length) matches |
regexp_matches('QGIS=>rocks','(.*)=>(.*)')
→
[ 'QGIS', 'rocks' ]
regexp_matches('key=>','(.*)=>(.*)','empty value')
→
[ 'key', 'empty value' ]
Splits string into an array using supplied delimiter and optional string for empty values.
string_to_array
(
string
[,
delimiter=','
][,
empty_value=''
])
| string | the input string |
| delimiter | the string delimiter used to split the input string |
| empty_value | the optional string to use as replacement for empty (zero length) matches |
string_to_array('1,2,3',',')
→
[ '1', '2', '3' ]
string_to_array('1,,3',',','0')
→
[ '1', '0', '3' ]
This group contains functions for manipulating colors
Returns a string representation of a color based on its cyan, magenta, yellow and black components
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 |
| 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
Returns a string representation of a color based on its cyan, magenta, yellow, black and alpha (transparency) components
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 |
| 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_cmyk(100,50,0,10,200)
→
0,115,230,200
Applies a grayscale filter and returns a string representation from a provided color.
color_grayscale_average
(
color
)
| color | a color string |
color_grayscale_average('255,100,50')
→
127,127,127,255
Returns a string representation of a color based on its hue, saturation, and lightness attributes.
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 |
| lightness | lightness percentage of the color as an integer value from 0 to 100 |
color_hsl(100,50,70)
→
166,217,140
Returns a string representation of a color based on its hue, saturation, lightness and alpha (transparency) attributes
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 |
| 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
Returns a string representation of a color based on its hue, saturation, and value attributes.
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 |
| value | value percentage of the color as an integer from 0 to 100 |
color_hsv(40,100,100)
→
255,170,0
Returns a string representation of a color based on its hue, saturation, value and alpha (transparency) attributes.
color_hsva
(
hue
,
saturation
,
value
,
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 |
| 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
Returns a string representing a color mixing the red, green, blue, and alpha values of two provided colors based on a given ratio.
color_mix_rgb
(
color1
,
color2
,
ratio
)
| color1 | a color string |
| color2 | a color string |
| ratio | a ratio |
color_mix_rgb('0,0,0','255,255,255',0.5)
→
127,127,127,255
Returns a specific component from a color string, e.g., the red component or alpha component.
color_part
(
color
,
component
)
| color | a color string |
| component |
a string corresponding to the color component to return. Valid options are:
|
color_part('200,10,30','green')
→
10
Returns a string representation of a color based on its red, green, and blue components.
color_rgb
(
red
,
green
,
blue
)
| 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
Returns a string representation of a color based on its red, green, blue, and alpha (transparency) components.
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 |
| 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
Returns a gradient ramp from a map of color strings and steps.
create_ramp
(
map
[,
discrete
])
| map | a map of color strings and steps |
| discrete | declare whether the color ramp is discrete |
ramp_color(create_array(map(0,'0,0,0',1,'255,0,0')),1)
→
'255,0,0,255'
Returns a darker (or lighter) color string
darker
(
color
,
factor
)
| color | a color string |
| factor |
a integer number corresponding to the darkening factor:
|
darker('200,10,30',300)
→
'66,3,10,255'
Returns a lighter (or darker) color string
lighter
(
color
,
factor
)
| color | a color string |
| factor |
a integer number corresponding to the lightening factor:
|
lighter('200,10,30',200)
→
'255,158,168,255'
Returns a color from the project's color scheme.
project_color
(
name
)
| name | a color name |
project_color('Logo color')
→
20,140,50
Returns a string representing a color from a color ramp.
ramp_color
(
ramp_name
,
value
)
| ramp_name | the name of the color ramp as a string, for example 'Spectral' |
| value | the position on the ramp to select the color from as a real number between 0 and 1 |
ramp_color('Spectral',0.3)
→
'253,190,115,255'
The color ramps available vary between QGIS installations. This function may not give the expected results if you move your QGIS project between installations.
ramp_color
(
ramp
,
value
)
| ramp | the color ramp |
| 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'
Sets a specific color component for a color string, e.g., the red component or alpha component.
set_color_part
(
color
,
component
,
value
)
| color | a color string |
| component |
a string corresponding to the color component to set. Valid options are:
|
| value | new value for color component, respecting the ranges listed above |
set_color_part('200,10,30','green',50)
→
200,50,30
This group contains functions to handle conditional checks in expressions.
Returns the first non-NULL value from the expression list.
This function can take any number of arguments.
coalesce
(
expression1
,
expression2
…)
| expression | any valid expression or value, regardless of type. |
coalesce(NULL, 2)
→
2
coalesce(NULL, 2, 3)
→
2
coalesce(7, NULL, 3*2)
→
7
coalesce("fieldA", "fallbackField", 'ERROR')
→
value of fieldA if it is non-NULL else the value of "fallbackField" or the string 'ERROR' if both are NULL
Tests a condition and returns a different result depending on the conditional check.
if
(
condition
,
result_when_true
,
result_when_false
)
| condition | the condition which should be checked |
| result_when_true | the result which will be returned when the condition is true or another value that does not convert to false. |
| result_when_false | the result which will be returned when the condition is false or another value that converts to false like 0 or ''. NULL will also be converted to false. |
if( 1+1=2, 'Yes', 'No' )
→
'Yes'
if( 1+1=3, 'Yes', 'No' )
→
'No'
if( 5 > 3, 1, 0)
→
1
if( '', 'It is true (not empty)', 'It is false (empty)' )
→
'It is false (empty)'
if( ' ', 'It is true (not empty)', 'It is false (empty)' )
→
'It is true (not empty)'
if( 0, 'One', 'Zero' )
→
'Zero'
if( 10, 'One', 'Zero' )
→
'One'
Returns a null value if value1 equals value2; otherwise it returns value1. This can be used to conditionally substitute values with NULL.
nullif
(
value1
,
value2
)
| value1 | The value that should either be used or substituted with NULL. |
| value2 | The control value that will trigger the NULL substitution. |
nullif('(none)', '(none)')
→
NULL
nullif('text', '(none)')
→
'text'
nullif("name", '')
→
NULL, if name is an empty string (or already NULL), the name in any other case.
Return the first matching position matching a regular expression within a string, or 0 if the substring is not found.
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., "\\s" to match a white space character). |
regexp_match('QGIS ROCKS','\\sROCKS')
→
4
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
])
| 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
try( to_date( 'invalid_date' ) )
→
NULL
This group contains functions to convert on data type to another e.g string to integer, integer to string.
Creates a hash from a string with a given method.
hash
(
string
,
method
)
| string | the string to hash |
| method | The hash method among 'md4', 'md5', 'sha1', 'sha224', 'sha384', 'sha512', 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512', 'keccak_224', 'keccak_256', 'keccak_384', 'keccak_512' |
hash('QGIS', md4)
→
'c0fc71c241cdebb6e888cbac0e2b68eb'
hash('QGIS', md5)
→
'57470aaa9e22adaefac7f5f342f1c6da'
hash('QGIS', sha1)
→
'f87cfb2b74cdd5867db913237024e7001e62b114'
hash('QGIS', sha224)
→
'4093a619ada631c770f44bc643ead18fb393b93d6a6af1861fcfece0'
hash('QGIS', sha256)
→
'eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309'
hash('QGIS', sha384)
→
'91c1de038cc3d09fdd512e99f9dd9922efadc39ed21d3922e69a4305cc25506033aee388e554b78714c8734f9cd7e610'
hash('QGIS', sha512)
→
'c2c092f2ab743bf8edbeb6d028a745f30fc720408465ed369421f0a4e20fa5e27f0c90ad72d3f1d836eaa5d25cd39897d4cf77e19984668ef58da6e3159f18ac'
hash('QGIS', sha3_224)
→
'467f49a5039e7280d5d42fd433e80d203439e338eaabd701f0d6c17d'
hash('QGIS', sha3_256)
→
'540f7354b6b8a6e735f2845250f15f4f3ba4f666c55574d9e9354575de0e980f'
hash('QGIS', sha3_384)
→
'96052da1e77679e9a65f60d7ead961b287977823144786386eb43647b0901fd8516fa6f1b9d243fb3f28775e6dde6107'
hash('QGIS', sha3_512)
→
'900d079dc69761da113980253aa8ac0414a8bd6d09879a916228f8743707c4758051c98445d6b8945ec854ff90655005e02aceb0a2ffc6a0ebf818745d665349'
hash('QGIS', keccak_224)
→
'5b0ce6acef8b0a121d4ac4f3eaa8503c799ad4e26a3392d1fb201478'
hash('QGIS', keccak_256)
→
'991c520aa6815392de24087f61b2ae0fd56abbfeee4a8ca019c1011d327c577e'
hash('QGIS', keccak_384)
→
'c57a3aed9d856fa04e5eeee9b62b6e027cca81ba574116d3cc1f0d48a1ef9e5886ff463ea8d0fac772ee473bf92f810d'
keccak_512('QGIS')
→
'6f0f751776b505e317de222508fa5d3ed7099d8f07c74fed54ccee6e7cdc6b89b4a085e309f2ee5210c9'
Creates a md5 hash from a string.
md5
(
string
)
| string | the string to hash |
md5('QGIS')
→
'57470aaa9e22adaefac7f5f342f1c6da'
Creates a sha256 hash from a string.
sha256
(
string
)
| string | the string to hash |
sha256('QGIS')
→
'eb045cba7a797aaa06ac58830846e40c8e8c780bc0676d3393605fae50c05309'
Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.
to_date
(
string
[,
format
][,
language
])
| string | string representing a date value |
| format | format used to convert the string into a date |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a date |
to_date('2012-05-04')
→
2012-05-04
to_date('June 29, 2019','MMMM d, yyyy')
→
2019-06-29
to_date('29 juin, 2019','d MMMM, yyyy','fr')
→
2019-06-29
Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDateTime::fromString for additional documentation on the format.
to_datetime
(
string
[,
format
][,
language
])
| string | string representing a datetime value |
| format | format used to convert the string into a datetime |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a datetime |
to_datetime('2012-05-04 12:50:00')
→
2012-05-04T12:50:00
to_datetime('June 29, 2019 @ 12:34','MMMM d, yyyy @ HH:mm')
→
2019-06-29T12:34
to_datetime('29 juin, 2019 @ 12:34','d MMMM, yyyy @ HH:mm','fr')
→
2019-06-29T12:34
Convert a coordinate to degree, minute.
to_dm
(
coordinate
,
axis
,
precision
[,
formatting
])
| coordinate | A latitude or longitude value. |
| axis | The axis of the coordinate. Either 'x' or 'y'. |
| precision | Number of decimals. |
| formatting | Designates the formatting type. Acceptable values are NULL, 'aligned' or 'suffix'. |
to_dm(6.3545681, 'x', 3)
→
6°21.274′
to_dm(6.3545681, 'y', 4, 'suffix')
→
6°21.2741′N
Convert a coordinate to degree, minute, second.
to_dms
(
coordinate
,
axis
,
precision
[,
formatting
])
| coordinate | A latitude or longitude value. |
| axis | The axis of the coordinate. Either 'x' or 'y'. |
| precision | Number of decimals. |
| formatting | Designates the formatting type. Acceptable values are NULL, 'aligned' or 'suffix'. |
to_dms(6.3545681, 'x', 3)
→
6°21′16.445″
to_dms(6.3545681, 'y', 4, 'suffix')
→
6°21′16.4452″N
Converts a string to integer number. Nothing is returned if a value cannot be converted to integer (e.g '123asd' is invalid).
to_int
(
string
)
| string | string to convert to integer number |
to_int('123')
→
123
Converts a string to a interval type. Can be used to take days, hours, month, etc of a date.
to_interval
(
string
)
| string | a string representing an interval. Allowable formats include {n} days {n} hours {n} months. |
to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours')
→
2012-05-04T10:00:00
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.
to_real
(
string
)
| string | string to convert to real number |
to_real('123.45')
→
123.45
Converts a number to string.
to_string
(
number
)
| number | Integer or real value. The number to convert to string. |
to_string(123)
→
'123'
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
])
| string | string representing a time value |
| format | format used to convert the string into a time |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a time |
to_time('12:30:01')
→
12:30:01
to_time('12:34','HH:mm')
→
12:34:00
to_time('12:34','HH:mm','fr')
→
12:34:00
This group contains custom user-created Python functions.
function help for countLegendElements missing
function help for my_custom_color_calculation missing
This group contains functions for handling date and time data.
Returns the difference between two dates or datetimes.
The difference is returned as a
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
age
(
datetime1
,
datetime2
)
| datetime1 | a string, date or datetime representing the later date |
| datetime2 | a string, date or datetime representing the earlier date |
day(age('2012-05-12','2012-05-02'))
→
10
hour(age('2012-05-12','2012-05-02'))
→
240
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.
datetime_from_epoch
(
int
)
| int | number (milliseconds) |
datetime_from_epoch(1483225200000)
→
2017-01-01T00:00:00
Extracts the day from a date, or the number of days from an interval.
day
(
date
)
| date | a date or datetime value |
day('2012-05-12')
→
12
day
(
interval
)
| interval | interval value to return number of days from |
day(to_interval('3 days'))
→
3
day(to_interval('3 weeks 2 days'))
→
23
day(age('2012-01-01','2010-01-01'))
→
730
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.
day_of_week
(
date
)
| date | date or datetime value |
day_of_week(to_date('2015-09-21'))
→
1
Returns the interval in milliseconds between the unix epoch and a given date value.
epoch
(
date
)
| date | a date or datetime value |
epoch(to_date('2017-01-01'))
→
1483203600000
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
])
| datetime | date, time or datetime value | ||||||||||||||||||||||||||||||||||||||||||||||||
| format |
String template used to format the string.
These expressions may be used for the time part of the format string:
|
||||||||||||||||||||||||||||||||||||||||||||||||
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to format the date into a custom string |
format_date('2012-05-15','dd.MM.yyyy')
→
'15.05.2012'
format_date('2012-05-15','d MMMM yyyy','fr')
→
'15 juin 2012'
Extracts the hour part from a datetime or time, or the number of hours from an interval.
hour
(
datetime
)
| datetime | a time or datetime value |
hour('2012-07-22T13:24:57')
→
13
hour
(
interval
)
| interval | interval value to return number of hours from |
hour(tointerval('3 hours'))
→
3
hour(age('2012-07-22T13:00:00','2012-07-22T10:00:00'))
→
3
hour(age('2012-01-01','2010-01-01'))
→
17520
Extracts the minutes part from a datetime or time, or the number of minutes from an interval.
minute
(
datetime
)
| datetime | a time or datetime value |
minute('2012-07-22T13:24:57')
→
24
minute
(
interval
)
| interval | interval value to return number of minutes from |
minute(tointerval('3 minutes'))
→
3
minute(age('2012-07-22T00:20:00','2012-07-22T00:00:00'))
→
20
minute(age('2012-01-01','2010-01-01'))
→
1051200
Extracts the month part from a date, or the number of months from an interval.
month
(
date
)
| date | a date or datetime value |
month('2012-05-12')
→
05
month
(
interval
)
| interval | interval value to return number of months from |
month(to_interval('3 months'))
→
3
month(age('2012-01-01','2010-01-01'))
→
4.03333
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.
now
()
now()
→
2012-07-22T13:24:57
Extracts the seconds part from a datetime or time, or the number of seconds from an interval.
second
(
datetime
)
| datetime | a time or datetime value |
second('2012-07-22T13:24:57')
→
57
second
(
interval
)
| interval | interval value to return number of seconds from |
second(age('2012-07-22T00:20:00','2012-07-22T00:00:00'))
→
1200
second(age('2012-01-01','2010-01-01'))
→
63072000
Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.
to_date
(
string
[,
format
][,
language
])
| string | string representing a date value |
| format | format used to convert the string into a date |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a date |
to_date('2012-05-04')
→
2012-05-04
to_date('June 29, 2019','MMMM d, yyyy')
→
2019-06-29
to_date('29 juin, 2019','d MMMM, yyyy','fr')
→
2019-06-29
Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDateTime::fromString for additional documentation on the format.
to_datetime
(
string
[,
format
][,
language
])
| string | string representing a datetime value |
| format | format used to convert the string into a datetime |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a datetime |
to_datetime('2012-05-04 12:50:00')
→
2012-05-04T12:50:00
to_datetime('June 29, 2019 @ 12:34','MMMM d, yyyy @ HH:mm')
→
2019-06-29T12:34
to_datetime('29 juin, 2019 @ 12:34','d MMMM, yyyy @ HH:mm','fr')
→
2019-06-29T12:34
Converts a string to a interval type. Can be used to take days, hours, month, etc of a date.
to_interval
(
string
)
| string | a string representing an interval. Allowable formats include {n} days {n} hours {n} months. |
to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours')
→
2012-05-04T10:00:00
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
])
| string | string representing a time value |
| format | format used to convert the string into a time |
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to convert the string into a time |
to_time('12:30:01')
→
12:30:01
to_time('12:34','HH:mm')
→
12:34:00
to_time('12:34','HH:mm','fr')
→
12:34:00
Extracts the week number from a date, or the number of weeks from an interval.
week
(
date
)
| date | a date or datetime value |
week('2012-05-12')
→
19
week
(
interval
)
| interval | interval value to return number of months from |
week(to_interval('3 weeks'))
→
3
week(age('2012-01-01','2010-01-01'))
→
104.285
Extracts the year part from a date, or the number of years from an interval.
year
(
date
)
| date | a date or datetime value |
year('2012-05-12')
→
2012
year
(
interval
)
| interval | interval value to return number of years from |
year(to_interval('3 years'))
→
3
year(age('2012-01-01','2010-01-01'))
→
1.9986
Contains functions which manipulate file and path names.
Returns the base name of the file without the directory or file suffix.
base_file_name
(
path
)
| path | a file path |
base_file_name('/home/qgis/data/country_boundaries.shp')
→
'country_boundaries'
Returns true if a file path exists.
file_exists
(
path
)
| path | a file path |
file_exists('/home/qgis/data/country_boundaries.shp')
→
true
Returns the name of a file (including the file extension), excluding the directory.
file_name
(
path
)
| path | a file path |
file_name('/home/qgis/data/country_boundaries.shp')
→
'country_boundaries.shp'
Returns the directory component of a file path. This does not include the file name.
file_path
(
path
)
| path | a file path |
file_path('/home/qgis/data/country_boundaries.shp')
→
'/home/qgis/data'
Returns the size (in bytes) of a file.
file_size
(
path
)
| path | a file path |
file_size('/home/qgis/data/country_boundaries.geojson')
→
5674
Returns the file suffix (extension) from a file path.
file_suffix
(
path
)
| path | a file path |
file_suffix('/home/qgis/data/country_boundaries.shp')
→
'shp'
Returns true if a path corresponds to a directory.
is_directory
(
path
)
| path | a file path |
is_directory('/home/qgis/data/country_boundaries.shp')
→
false
is_directory('/home/qgis/data/')
→
true
Returns true if a path corresponds to a file.
is_file
(
path
)
| path | a file path |
is_file('/home/qgis/data/country_boundaries.shp')
→
true
is_file('/home/qgis/data/')
→
false
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.
current_value
(
field_name
)
| field_name | a field name in the current form or table row |
current_value( 'FIELD_NAME' )
→
The current value of field 'FIELD_NAME'.
This group contains functions for fuzzy comparisons between values.
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.
hamming_distance
(
string1
,
string2
)
| string1 | a string |
| string2 | a string |
hamming_distance('abc','xec')
→
2
hamming_distance('abc','ABc')
→
2
hamming_distance(upper('abc'),upper('ABC'))
→
0
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.
levenshtein
(
string1
,
string2
)
| string1 | a string |
| string2 | a string |
levenshtein('kittens','mitten')
→
2
levenshtein('Kitten','kitten')
→
1
levenshtein(upper('Kitten'),upper('kitten'))
→
0
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 "ABC". The substring is case sensitive.
longest_common_substring
(
string1
,
string2
)
| string1 | a string |
| string2 | a string |
longest_common_substring('ABABC','BABCA')
→
'ABC'
longest_common_substring('abcDeF','abcdef')
→
'abc'
longest_common_substring(upper('abcDeF'),upper('abcdex'))
→
'ABCDE'
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.
soundex
(
string
)
| string | a string |
soundex('robert')
→
'R163'
soundex('rupert')
→
'R163'
soundex('rubin')
→
'R150'
This group contains general assorted functions.
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.
env
(
name
)
| name | The name of the environment variable which should be retrieved. |
env( 'LANG' )
→
'en_US.UTF-8'
env( 'MY_OWN_PREFIX_VAR' )
→
'Z:'
env( 'I_DO_NOT_EXIST' )
→
NULL
Evaluates an expression which is passed in a string. Useful to expand dynamic parameters passed as context variables or fields.
eval
(
expression
)
| expression | an expression string |
eval(''nice'')
→
'nice'
eval(@expression_var)
→
[whatever the result of evaluating @expression_var might be…]
Returns true if a specified layer is visible.
is_layer_visible
(
layer
)
| layer | a string, representing either a layer name or layer ID |
is_layer_visible('baseraster')
→
True
Returns a matching layer property or metadata value.
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:
|
layer_property('streets','title')
→
'Basemap Streets'
layer_property('airports','feature_count')
→
120
layer_property('landsat','crs')
→
'EPSG:4326'
Returns the value stored within a specified variable.
var
(
name
)
| name | a variable name |
var('qgis_version')
→
'2.12'
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.
with_variable
(
name
,
value
,
expression
)
| name | the name of the variable to set |
| value | the value to set |
| expression | the expression for which the variable will be available |
with_variable('my_sum', 1 + 2 + 3, @my_sum * 2 + @my_sum * 5)
→
42
This group contains functions that operate on geometry objects e.g length, 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.
$area
$area
→
42
Returns the geometry of the current feature. Can be used for processing with other functions.
$geometry
geomToWKT( $geometry )
→
POINT(6 50)
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.
$length
$length
→
42.4711
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.
$perimeter
$perimeter
→
42
Retrieves a x coordinate of the current feature's geometry.
$x_at
(
i
)
| i | index of point of a line (indices start at 0; negative values apply from the last index, starting at -1) |
$x_at(1)
→
5
Retrieves a y coordinate of the current feature's geometry.
$y_at
(
i
)
| i | index of point of a line (indices start at 0; negative values apply from the last index, starting at -1) |
$y_at(1)
→
2
Returns the bisector angle (average angle) to the geometry for a specified vertex on a linestring geometry. Angles are in degrees clockwise from north.
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 total count minus the absolute value |
angle_at_vertex(geometry:=geom_from_wkt('LineString(0 0, 10 0, 10 10)'),vertex:=1)
→
45.0
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.
area
(
geometry
)
| geometry | polygon geometry object |
area(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))'))
→
8.0
Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.
azimuth
(
point_a
,
point_b
)
| point_a | point geometry |
| point_b | point geometry |
degrees( azimuth( make_point(25, 45), make_point(75, 100) ) )
→
42.273689
degrees( azimuth( make_point(75, 100), make_point(25,45) ) )
→
222.273689
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.
boundary
(
geometry
)
| geometry | a geometry |
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)'
Returns a geometry which represents the bounding box of an input geometry. Calculations are in the Spatial Reference System of this geometry.
bounds
(
geom
)
| geom | a geometry |
bounds($geometry)
→
bounding box of $geometry
Returns the height of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.
bounds_height
(
geom
)
| geom | a geometry |
bounds_height($geometry)
→
height of bounding box of $geometry
Returns the width of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.
bounds_width
(
geom
)
| geom | a geometry |
bounds_width($geometry)
→
width of bounding box of $geometry
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
(
geom
,
distance
[,
segments=8
])
| geom | 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. |
buffer($geometry, 10.5)
→
polygon of $geometry buffered by 10.5 units
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
])
| geometry | input geometry. Must be a (multi)line geometry with m values. |
| 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 linestring geometry.
Returns the geometric center of a geometry.
centroid
(
geom
)
| geom | a geometry |
centroid($geometry)
→
a point geometry
Returns the point on geometry1 that is closest to geometry2.
closest_point
(
geometry1
,
geometry2
)
| geometry1 | geometry to find closest point on |
| geometry2 | geometry to find closest point to |
geom_to_wkt(closest_point(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75 )'),geom_from_wkt('POINT(100 100)')))
→
Point(73.0769 115.384)
Collects a set of geometries into a multi-part geometry object.
collect_geometries
(
geometry1
,
geometry2
…)
| geometry | a geometry |
geom_to_wkt(collect_geometries(make_point(1,2), make_point(3,4), make_point(5,6)))
→
'MultiPoint ((1 2),(3 4),(5 6))'
collect_geometries
(
array
)
| array | array of geometry objects |
geom_to_wkt(collect_geometries(array(make_point(1,2), make_point(3,4), make_point(5,6))))
→
'MultiPoint ((1 2),(3 4),(5 6))'
Returns the combination of two geometries.
combine
(
geometry1
,
geometry2
)
| geometry1 | a geometry |
| 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))
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)
Tests whether a geometry contains another. Returns true if and only if no points of geometry b lie in the exterior of geometry a, and at least one point of the interior of b lies in the interior of a.
contains
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | 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
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
Returns the convex hull of a geometry. It represents the minimum convex geometry that encloses all geometries within the set.
convex_hull
(
geometry
)
| geometry | a geometry |
geom_to_wkt( convex_hull( geom_from_wkt( 'LINESTRING(3 3, 4 4, 4 10)' ) ) )
→
POLYGON((3 3,4 10,4 4,3 3))
Tests whether a geometry crosses another. Returns true if the supplied geometries have some, but not all, interior points in common.
crosses
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | a geometry |
crosses( geom_from_wkt( 'LINESTRING(3 5, 4 4, 5 3)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
true
crosses( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
false
Returns a geometry that represents that part of geometry_a that does not intersect with geometry_b.
difference
(
geometry_a
,
geometry_b
)
| geometry_a | a geometry |
| geometry_b | a geometry |
geom_to_wkt( difference( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4)' ) ) )
→
LINESTRING(4 4, 5 5)
Tests whether geometries do not spatially intersect. Returns true if the geometries do not share any space together.
disjoint
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | 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
disjoint( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'POINT(4 4)' ))
→
false
Returns the minimum distance (based on spatial ref) between two geometries in projected units.
distance
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | a geometry |
distance( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(4 8)' ) )
→
4
Returns the distance along the geometry to a specified vertex.
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 total count minus the absolute value |
distance_to_vertex(geometry:=geom_from_wkt('LineString(0 0, 10 0, 10 10)'),vertex:=1)
→
10.0
Returns the last node from a geometry.
end_point
(
geometry
)
| geometry | geometry object |
geom_to_wkt(end_point(geom_from_wkt('LINESTRING(4 0, 4 2, 0 2)')))
→
'Point (0 2)'
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. Distances are in the Spatial Reference System of this geometry.
extend
(
geometry
,
start_distance
,
end_distance
)
| geometry | a (multi)linestring geometry |
| start_distance | distance to extend the start of the line |
| end_distance | distance to extend the end of the line. |
geom_to_wkt(extend(geom_from_wkt('LineString(0 0, 1 0, 1 1)'),1,2))
→
LineString (-1 0, 1 0, 1 3)
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.
exterior_ring
(
geom
)
| geom | a polygon geometry |
geom_to_wkt(exterior_ring(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),( 0.1 0.1, 0.1 0.2, 0.2 0.2, 0.2, 0.1, 0.1 0.1))')))
→
'LineString (-1 -1, 4 0, 4 2, 0 2, -1 -1)'
Returns an extruded version of the input (Multi-)Curve or (Multi-)Linestring geometry with an extension specified by x and y.
extrude
(
geom
,
x
,
y
)
| geom | a polygon geometry |
| x | x extension, numeric value |
| y | y extension, numeric value |
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))
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)))
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.
flip_coordinates
(
geom
)
| geom | a geometry |
geom_to_wkt(flip_coordinates(make_point(1, 2)))
→
Point (2 1)
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.
force_rhr
(
geom
)
| geom | a geometry. Any non-polygon geometries are returned unchanged. |
geom_to_wkt(force_rhr(geometry:=geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1))')))
→
Polygon ((-1 -1, 0 2, 4 2, 4 0, -1 -1))
Returns a geometry from a GML representation of geometry.
geom_from_gml
(
gml
)
| gml | GML representation of a geometry as a string |
geom_from_gml('<gml:LineString srsName="EPSG:4326"><gml:coordinates>4,4 5,5 6,6</gml:coordinates></gml:LineString>')
→
a line geometry object
Returns a geometry created from a Well-Known Binary (WKB) representation.
geom_from_wkb
(
binary
)
| binary | Well-Known Binary (WKB) representation of a geometry (as a binary blob) |
geom_from_wkb( geom_to_wkb( make_point(4,5) ) )
→
a point geometry object
Returns a geometry created from a Well-Known Text (WKT) representation.
geom_from_wkt
(
text
)
| text | Well-Known Text (WKT) representation of a geometry |
geom_from_wkt( 'POINT(4 5)' )
→
a geometry object
Returns the Well-Known Binary (WKB) representation of a geometry as a binary blob.
geom_to_wkb
(
geometry
)
| geometry | a geometry |
geom_to_wkb( $geometry )
→
binary blob containing a geometry object
Returns the Well-Known Text (WKT) representation of the geometry without SRID metadata.
geom_to_wkt
(
geometry
[,
precision
])
| geometry | a geometry |
| precision | numeric precision |
geom_to_wkt( $geometry )
→
POINT(6 50)
Returns a feature's geometry.
geometry
(
feature
)
| feature | a feature object |
geom_to_wkt( geometry( get_feature( layer, attributeField, value ) ) )
→
'POINT(6 50)'
intersects( $geometry, geometry( get_feature( layer, attributeField, value ) ) )
→
true
Returns a specific geometry from a geometry collection, or null if the input geometry is not a collection.
geometry_n
(
geometry
,
index
)
| geometry | geometry collection |
| 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), POINT(1 0), POINT(1 1))'),3))
→
'Point (1 0)'
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:
hausdorff_distance
(
geometry a
,
geometry b
[,
densify_fraction
])
| geometry a | a geometry |
| geometry b | a geometry |
| 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 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
Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.
inclination
(
point_a
,
point_b
)
| point_a | point geometry |
| 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
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
Returns a specific interior ring from a polygon geometry, or null if the geometry is not a polygon.
interior_ring_n
(
geometry
,
index
)
| geometry | polygon geometry |
| 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 -1))'),1))
→
'LineString (-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))'
Returns a geometry that represents the shared portion of two geometries.
intersection
(
geometry1
,
geometry2
)
| geometry1 | a geometry |
| 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)
Tests whether a geometry intersects another. Returns true if the geometries spatially intersect (share any portion of space) and false if they do not.
intersects
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | a geometry |
intersects( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
true
intersects( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'POINT(5 5)' ) )
→
false
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.
intersects_bbox
(
geometry
,
geometry
)
| geometry | a geometry |
| geometry | a geometry |
intersects_bbox( geom_from_wkt( 'POINT(4 5)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
true
intersects_bbox( geom_from_wkt( 'POINT(6 5)' ), geom_from_wkt( 'POLYGON((3 3, 4 4, 5 5, 3 3))' ) )
→
false
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.
is_closed
(
geom
)
| geom | a line string geometry |
is_closed(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))
→
false
is_closed(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2, 0 0)'))
→
true
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`.
is_empty
(
geom
)
| geom | a geometry |
is_empty(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))
→
false
is_empty(geom_from_wkt('LINESTRING EMPTY'))
→
true
is_empty(geom_from_wkt('POINT(7 4)'))
→
false
is_empty(geom_from_wkt('POINT EMPTY'))
→
true
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)'
is_empty_or_null
(
geom
)
| geom | a geometry |
is_empty_or_null(NULL)
→
true
is_empty_or_null(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)'))
→
false
is_empty_or_null(geom_from_wkt('LINESTRING EMPTY'))
→
true
is_empty_or_null(geom_from_wkt('POINT(7 4)'))
→
false
is_empty_or_null(geom_from_wkt('POINT EMPTY'))
→
true
Returns true if a geometry is valid; if it is well-formed in 2D according to the OGC rules.
is_valid
(
geom
)
| geom | a geometry |
is_valid(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2, 0 0)'))
→
true
is_valid(geom_from_wkt('LINESTRING(0 0)'))
→
false
Returns the number of characters in a string or the length of a geometry linestring.
length
(
string
)
| string | string to count length of |
length('hello')
→
5
length
(
geometry
)
| geometry | line geometry object |
length(geom_from_wkt('LINESTRING(0 0, 4 0)'))
→
4.0
Returns the angle parallel to the geometry at a specified distance along a linestring geometry. Angles are in degrees clockwise from north.
line_interpolate_angle
(
geometry
,
distance
)
| geometry | a linestring geometry |
| distance | distance along line to interpolate angle at |
line_interpolate_angle(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),distance:=5)
→
90.0
Returns the point interpolated by a specified distance along a linestring geometry.
line_interpolate_point
(
geometry
,
distance
)
| geometry | a linestring geometry |
| distance | distance along line to interpolate |
geom_to_wkt(line_interpolate_point(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),distance:=5))
→
'Point (5 0)'
Returns the distance along a linestring corresponding to the closest position the linestring comes to a specified point geometry.
line_locate_point
(
geometry
,
point
)
| geometry | a linestring geometry |
| point | point geometry to locate closest position on linestring to |
line_locate_point(geometry:=geom_from_wkt('LineString(0 0, 10 0)'),point:=geom_from_wkt('Point(5 0)'))
→
5.0
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.
line_merge
(
geometry
)
| geometry | a LineString/MultiLineString geometry |
geom_to_wkt(line_merge(geom_from_wkt('MULTILINESTRING((0 0, 1 1),(1 1, 2 2))')))
→
'LineString(0 0,1 1,2 2)'
geom_to_wkt(line_merge(geom_from_wkt('MULTILINESTRING((0 0, 1 1),(11 1, 21 2))')))
→
'MultiLineString((0 0, 1 1),(11 1, 21 2)'
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.
line_substring
(
geometry
,
start_distance
,
end_distance
)
| geometry | a linestring or curve geometry |
| 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 0)'),start_distance:=2,end_distance=6))
→
'LineString (2 0,6 0)'
Returns the m value of a point geometry.
m
(
geom
)
| geom | a point geometry |
m( geom_from_wkt( 'POINTM(2 5 4)' ) )
→
4
Creates a circular polygon.
make_circle
(
center
,
radius
[,
segment=36
]…)
| center | center point of the circle |
| radius | radius of the circle |
| segment | 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 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))'
Creates an elliptical polygon.
make_ellipse
(
center
,
semi_major_axis
,
semi_minor_axis
,
azimuth
[,
segment=36
]…)
| center | center point of the ellipse |
| semi_major_axis | semi-major axis of the ellipse |
| semi_minor_axis | semi-minor axis of the ellipse |
| azimuth | orientation of the ellipse |
| segment | 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 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))'
Creates a line geometry from a series of point geometries.
make_line
(
point1
,
point2
…)
| point | a point geometry (or array of points) |
geom_to_wkt(make_line(make_point(2,4),make_point(3,5)))
→
'LineString (2 4, 3 5)'
geom_to_wkt(make_line(make_point(2,4),make_point(3,5),make_point(9,7)))
→
'LineString (2 4, 3 5, 9 7)'
make_line
(
array
)
| array | array of points |
geom_to_wkt(make_line(array(make_point(2,4),make_point(3,5),make_point(9,7))))
→
'LineString (2 4, 3 5, 9 7)'
Creates a point geometry from an x and y (and optional z and m) value.
make_point
(
x
,
y
[,
z
][,
m
])
| x | x coordinate of point |
| y | y coordinate of point |
| 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)'
geom_to_wkt(make_point(2,4,6,8))
→
'PointZM (2 4 6 8)'
Creates a point geometry from an x, y coordinate and m value.
make_point_m
(
x
,
y
,
m
)
| x | x coordinate of point |
| y | y coordinate of point |
| m | m value of point |
geom_to_wkt(make_point_m(2,4,6))
→
'PointM (2 4 6)'
Creates a polygon geometry from an outer ring and optional series of inner ring geometries.
make_polygon
(
outerRing
[,
innerRing1
][,
innerRing2
]…)
| outerRing | closed line geometry for polygon's outer ring |
| 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 )'),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))'
Creates a rectangle from 3 points.
make_rectangle_3points
(
point1
,
point2
,
point3
[,
option=0
]…)
| point1 | First point. |
| point2 | Second point. |
| point3 | Third point. |
| option | An optional argument to construct the rectangle. By default this value is 0. Value can be 0 (distance) or 1 (projected). Option distance: Second distance is equal to the distance between 2nd and 3rd point. Option projected: Second distance is equal to the distance of the perpendicular projection of the 3rd point on the segment or its extension. |
geom_to_wkt(make_rectangle(make_point(0, 0), make_point(0,5), make_point(5, 5), 0)))
→
'Polygon ((0 0, 0 5, 5 5, 5 0, 0 0))'
geom_to_wkt(make_rectangle(make_point(0, 0), make_point(0,5), make_point(5, 3), 1)))
→
'Polygon ((0 0, 0 5, 5 5, 5 0, 0 0))'
Creates a regular polygon.
make_regular_polygon
(
center
,
radius
,
number_sides
[,
circle=0
]…)
| center | center of the regular polygon |
| radius | second point. The first if the regular polygon is inscribed. The midpoint of the first side if the regular polygon is circumscribed. |
| number_sides | Number of sides/edges of the regular polygon |
| circle | Optional argument to construct the regular polygon. By default this value is 0. Value can be 0 (inscribed) or 1 (circumscribed) |
geom_to_wkt(make_regular_polygon(make_point(0,0), make_point(0,5), 5))
→
'Polygon ((0 5, 4.76 1.55, 2.94 -4.05, -2.94 -4.05, -4.76 1.55, 0 5))'
geom_to_wkt(make_regular_polygon(make_point(0,0), project(make_point(0,0), 4.0451, radians(36)), 5))
→
'Polygon ((0 5, 4.76 1.55, 2.94 -4.05, -2.94 -4.05, -4.76 1.55, 0 5))'
Creates a square from a diagonal.
make_square
(
point1
,
point2
…)
| point1 | First point of the regular polygon |
| point2 | Second point |
geom_to_wkt(make_square( make_point(0,0), make_point(5,5)))
→
'Polygon ((0 0, -0 5, 5 5, 5 0, 0 0))'
geom_to_wkt(make_square( make_point(5,0), make_point(5,5)))
→
'Polygon ((5 0, 2.5 2.5, 5 5, 7.5 2.5, 5 0))'
Creates a triangle polygon.
make_triangle
(
point 1
,
point 2
,
point 3
)
| point 1 | first point of the triangle |
| point 2 | second point of the triangle |
| point 3 | 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))'
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)'
Returns the minimal enclosing circle of a geometry. It represents the minimum circle that encloses all geometries within the set.
minimal_circle
(
geometry
[,
segment=36
])
| geometry | a geometry |
| segment | 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))
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))
Returns a multipoint geometry consisting of every node in the input geometry.
nodes_to_points
(
geometry
[,
ignore_closing_nodes=false
])
| geometry | geometry object |
| ignore_closing_nodes | optional argument specifying whether to include duplicate nodes which close lines or polygons rings. Defaults to false, set to true to avoid including these duplicate nodes in the output collection. |
geom_to_wkt(nodes_to_points(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')))
→
'MultiPoint ((0 0),(1 1),(2 2))'
geom_to_wkt(nodes_to_points(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1))'),true))
→
'MultiPoint ((-1 -1),(4 0),(4 2),(0 2))'
Returns the number of geometries in a geometry collection, or null if the input geometry is not a collection.
num_geometries
(
geometry
)
| geometry | geometry collection |
num_geometries(geom_from_wkt('GEOMETRYCOLLECTION(POINT(0 1), POINT(0 0), POINT(1 0), POINT(1 1))'))
→
4
Returns the number of interior rings in a polygon or geometry collection, or null if the input geometry is not a polygon or collection.
num_interior_rings
(
geometry
)
| geometry | input geometry |
num_interior_rings(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),(-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))'))
→
1
Returns the number of vertices in a geometry.
num_points
(
geom
)
| geom | a geometry |
num_points($geometry)
→
number of vertices in $geometry
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.
num_rings
(
geometry
)
| geometry | input geometry |
num_rings(geom_from_wkt('POLYGON((-1 -1, 4 0, 4 2, 0 2, -1 -1),(-0.1 -0.1, 0.4 0, 0.4 0.2, 0 0.2, -0.1 -0.1))'))
→
2
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
])
| geometry | a (multi)linestring geometry |
| distance | offset distance. Positive values will be buffered to the left of lines, negative values to the right |
| segments | number of segments to use to represent a quarter circle when a round join style is used. A larger number results in a smoother line with more nodes. |
| join | join style for corners, where 1 = round, 2 = miter and 3 = bevel |
| miter_limit | limit on the miter ratio used for very sharp corners (when using miter joins only) |
offset_curve($geometry, 10.5)
→
line offset to the left by 10.5 units
offset_curve($geometry, -10.5)
→
line offset to the right by 10.5 units
offset_curve($geometry, 10.5, segments=16, join=1)
→
line offset to the left by 10.5 units, using more segments to result in a smoother curve
offset_curve($geometry, 10.5, join=3)
→
line offset to the left by 10.5 units, using a beveled join
Orders the parts of a MultiGeometry by a given criteria
order_parts
(
geom
,
orderby
,
ascending
)
| geom | a multi-type geometry |
| orderby | an expression string defining the order criteria |
| ascending | boolean, True for ascending, False for descending |
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)))
order_parts(geom_from_wkt('LineString(1 2, 3 2, 4 3)'), '1', True)
→
LineString(1 2, 3 2, 4 3)
Returns a geometry which represents the minimal oriented bounding box of an input geometry.
oriented_bbox
(
geom
)
| geom | a geometry |
geom_to_wkt( oriented_bbox( geom_from_wkt( 'MULTIPOINT(1 2, 3 4, 3 2)' ) ) )
→
Polygon ((1 4, 1 2, 3 2, 3 4, 1 4))
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.
overlaps
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | 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
overlaps( geom_from_wkt( 'LINESTRING(0 0, 1 1)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
false
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.
perimeter
(
geometry
)
| geometry | polygon geometry object |
perimeter(geom_from_wkt('POLYGON((0 0, 4 0, 4 2, 0 2, 0 0))'))
→
12.0
Returns a specific node from a geometry.
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 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))
→
'Point (4 0)'
Returns a point guaranteed to lie on the surface of a geometry.
point_on_surface
(
geom
)
| geom | a geometry |
point_on_surface($geometry)
→
a point geometry
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.
pole_of_inaccessibility
(
geometry
,
tolerance
)
| geometry | a geometry |
| 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, 10 3, 10 1, 0 1))'), 0.1))
→
Point(1.55, 1.55)
Returns a point projected from a start point using a distance, a bearing (azimuth) and an elevation in radians.
project
(
point
,
distance
,
azimuth
[,
elevation
])
| point | start point |
| 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)
Tests the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between two geometries.
relate
(
geometry
,
geometry
)
| geometry | a geometry |
| geometry | a geometry |
relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt( 'LINESTRING(40 40,60 120)' ) )
→
'FF1F00102'
relate
(
geometry
,
geometry
,
pattern
)
| geometry | a geometry |
| geometry | a geometry |
| pattern | DE-9IM pattern to match |
relate( geom_from_wkt( 'LINESTRING(40 40,120 120)' ), geom_from_wkt( 'LINESTRING(40 40,60 120)' ), '**1F001**' )
→
True
Reverses the direction of a line string by reversing the order of its vertices.
reverse
(
geom
)
| geom | a geometry |
geom_to_wkt(reverse(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')))
→
'LINESTRING(2 2, 1 1, 0 0)'
Returns a rotated version of a geometry. Calculations are in the Spatial Reference System of this geometry.
rotate
(
geom
,
rotation
[,
point
])
| geom | a geometry |
| rotation | clockwise rotation in degrees |
| point | rotation center point. If not specified, the center of the geometry's bounding box is used. |
rotate($geometry, 45, make_point(4, 5))
→
geometry rotated 45 degrees clockwise around the (4, 5) point
rotate($geometry, 45)
→
geometry rotated 45 degrees clockwise around the center of its bounding box
Returns a multi line geometry consisting of a line for every segment in the input geometry.
segments_to_lines
(
geometry
)
| geometry | geometry object |
geom_to_wkt(segments_to_lines(geom_from_wkt('LINESTRING(0 0, 1 1, 2 2)')))
→
'MultiLineString ((0 0, 1 1),(1 1, 2 2))'
Returns the shortest line joining geometry1 to geometry2. The resultant line will start at geometry1 and end at geometry2.
shortest_line
(
geometry1
,
geometry2
)
| geometry1 | geometry to find shortest line from |
| geometry2 | geometry to find shortest line to |
geom_to_wkt(shortest_line(geom_from_wkt('LINESTRING (20 80, 98 190, 110 180, 50 75 )'),geom_from_wkt('POINT(100 100)')))
→
LineString(73.0769 115.384, 100 100)
Simplifies a geometry by removing nodes using a distance based threshold (ie, the Douglas Peucker algorithm). The algorithm preserves large deviations in geometries and reduces the number of vertices in nearly straight segments.
simplify
(
geometry
,
tolerance
)
| geometry | a geometry |
| 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 0)'),tolerance:=5))
→
'LineString(0 0, 10 0)'
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.
simplify_vw
(
geometry
,
tolerance
)
| geometry | a geometry |
| 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, 5.02 0, 10 0)'),tolerance:=5))
→
'LineString(0 0, 10 0)'
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
])
| geometry | a (multi)linestring geometry |
| distance | buffer distance. Positive values will be buffered to the left of lines, negative values to the right |
| segments | number of segments to use to represent a quarter circle when a round join style is used. A larger number results in a smoother buffer with more nodes. |
| join | join style for corners, where 1 = round, 2 = miter and 3 = bevel |
| miter_limit | limit on the miter ratio used for very sharp corners (when using miter joins only) |
single_sided_buffer($geometry, 10.5)
→
line buffered to the left by 10.5 units
single_sided_buffer($geometry, -10.5)
→
line buffered to the right by 10.5 units
single_sided_buffer($geometry, 10.5, segments=16, join=1)
→
line buffered to the left by 10.5 units, using more segments to result in a smoother buffer
single_sided_buffer($geometry, 10.5, join=3)
→
line buffered to the left by 10.5 units, using a beveled join
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
][,
offset
][,
min_length
][,
max_angle
])
| geometry | a geometry |
| iterations | number of smoothing iterations to apply. Larger numbers result in smoother but more complex geometries. |
| offset | value between 0 and 0.5 which controls how tightly the smoothed geometry follow the original geometry. Smaller values result in a tighter smoothing, larger values result in looser smoothing. |
| min_length | minimum length of segments to apply smoothing to. This parameter can be used to avoid placing excessive additional nodes in shorter segments of the geometry. |
| max_angle | maximum angle at node for smoothing to be applied (0-180). By lowering the maximum angle intentionally sharp corners in the geometry can be preserved. For instance, a value of 80 degrees will retain right angles in the geometry. |
geom_to_wkt(smooth(geometry:=geom_from_wkt('LineString(0 0, 5 0, 5 5)'),iterations:=1,offset:=0.2,min_length:=-1,max_angle:=180))
→
'LineString (0 0, 4 0, 5 1, 5 5)'
Returns the first node from a geometry.
start_point
(
geometry
)
| geometry | geometry object |
geom_to_wkt(start_point(geom_from_wkt('LINESTRING(4 0, 4 2, 0 2)')))
→
'Point (4 0)'
Returns a geometry that represents the portions of two geometries that do not intersect.
sym_difference
(
geometry1
,
geometry2
)
| geometry1 | a geometry |
| geometry2 | a geometry |
geom_to_wkt( sym_difference( geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ), geom_from_wkt( 'LINESTRING(3 3, 8 8)' ) ) )
→
LINESTRING(5 5, 8 8)
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
])
| geometry | input geometry. Must be a (multi)line geometry. |
| start_width | width of buffer at start of line, |
| end_width | width of buffer at end of line. |
| segments | number of segments to approximate quarter-circle curves in the buffer. |
tapered_buffer(geometry:=geom_from_wkt('LINESTRING(1 2, 4 2)'),start_width:=1,end_width:=2,segments:=8)
→
A tapered buffer starting with a diameter of 1 and ending with a diameter of 2 along the linestring geometry.
Tests whether a geometry touches another. Returns true if the geometries have at least one point in common, but their interiors do not intersect.
touches
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | a geometry |
touches( geom_from_wkt( 'LINESTRING(5 3, 4 4)' ), geom_from_wkt( 'LINESTRING(3 3, 4 4, 5 5)' ) )
→
true
touches( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(5 5)' ) )
→
false
Returns the geometry transformed from a source CRS to a destination CRS.
transform
(
geom
,
source_auth_id
,
dest_auth_id
)
| geom | a geometry |
| source_auth_id | the source auth CRS ID |
| dest_auth_id | the destination auth CRS ID |
geom_to_wkt( transform( $geometry, 'EPSG:2154', 'EPSG:4326' ) )
→
POINT(0 51)
Returns a translated version of a geometry. Calculations are in the Spatial Reference System of this geometry.
translate
(
geom
,
dx
,
dy
)
| geom | a geometry |
| dx | delta x |
| dy | delta y |
translate($geometry, 5, 10)
→
a geometry of the same type like the original one
Returns a geometry that represents the point set union of the geometries.
union
(
geometry1
,
geometry2
)
| geometry1 | a geometry |
| geometry2 | a geometry |
geom_to_wkt( union( geom_from_wkt( 'POINT(4 4)' ), geom_from_wkt( 'POINT(5 5)' ) ) )
→
MULTIPOINT(4 4, 5 5)
Returns a wedge shaped buffer originating from a point geometry.
wedge_buffer
(
center
,
azimuth
,
width
,
outer_radius
[,
inner_radius=0.0
])
| center | center point (origin) of buffer. Must be a point geometry. |
| azimuth | angle (in degrees) for the middle of the wedge to point. |
| width | buffer width (in degrees). Note that the wedge will extend to half of the angular width either side of the azimuth direction. |
| outer_radius | outer radius for buffers |
| inner_radius | optional inner radius for buffers |
wedge_buffer(center:=geom_from_wkt('POINT(1 2)'),azimuth:=90,width:=180,outer_radius:=1)
→
A wedge shaped buffer centered on the point (1,2), facing to the East, with a width of 180 degrees and outer radius of 1.
Tests whether a geometry is within another. Returns true if the geometry a is completely within geometry b.
within
(
geometry a
,
geometry b
)
| geometry a | a geometry |
| geometry b | 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
within( geom_from_wkt( 'POINT( 5 5 )' ), geom_from_wkt( 'POLYGON((0 0, 0 1, 1 1, 1 0, 0 0 ))' ) )
→
false
Returns the x coordinate of a point geometry, or the x-coordinate of the centroid for a non-point geometry.
x
(
geom
)
| geom | a geometry |
x( geom_from_wkt( 'POINT(2 5)' ) )
→
2
x( $geometry )
→
x coordinate of the current feature's centroid
Returns the maximum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
x_max
(
geom
)
| geom | a geometry |
x_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') )
→
4
Returns the minimum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
x_min
(
geom
)
| geom | a geometry |
x_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') )
→
2
Returns the y coordinate of a point geometry, or the y-coordinate of the centroid for a non-point geometry.
y
(
geom
)
| geom | a geometry |
y( geom_from_wkt( 'POINT(2 5)' ) )
→
5
y( $geometry )
→
y coordinate of the current feature's centroid
Returns the maximum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
y_max
(
geom
)
| geom | a geometry |
y_max( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') )
→
8
Returns the minimum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
y_min
(
geom
)
| geom | a geometry |
y_min( geom_from_wkt( 'LINESTRING(2 5, 3 6, 4 8)') )
→
5
Returns the z coordinate of a point geometry.
z
(
geom
)
| geom | a point geometry |
z( geom_from_wkt( 'POINTZ(2 5 7)' ) )
→
7
Returns a map of variables from a composer item inside this composition.
item_variables
(
id
)
| id | composer item ID |
map_get(item_variables('main_map'), 'map_scale')
→
2000
Contains a list of map layers available in the current project.
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
])
| layer | The layer for which the uri should be decoded. |
| part | The part of the uri to return. If unspecified, a map with all uri parts will be returned. |
decode_uri(@layer)
→
{'layerId': '0', 'layerName': '', 'path': '/home/qgis/shapefile.shp'}
decode_uri(@layer)
→
{'layerId': NULL, 'layerName': 'layer', 'path': '/home/qgis/geopackage.gpkg'}
decode_uri(@layer, 'path')
→
'C:\my_data\qgis\shape.shp'
This group contains expression functions for the creation and manipulation of 'map' data structures (also known as dictionary objects, key-value pairs, or associative arrays). One can assign values to given keys. The order of the key-value pairs in the map object is not relevant.
Loads a JSON formatted string.
from_json
(
string
)
| string | JSON string |
from_json('{"qgis":"rocks"}')
→
{ "qgis" : "rocks" }
from_json('[1,2,3]')
→
[1,2,3]
Creates a map from a hstore-formatted string.
hstore_to_map
(
string
)
| string | the input string |
hstore_to_map('qgis=>rocks')
→
{ "qgis" : "rocks" }
Creates a map from a json-formatted string.
json_to_map
(
string
)
| string | the input string |
json_to_map('{"qgis":"rocks"}')
→
{ "qgis" : "rocks" }
Returns a map containing all the keys and values passed as pair of parameters.
map
(
key1
,
value1
,
key2
,
value2
…)
| key | a key (string) |
| value | a value |
map('1','one','2', 'two')
→
{ '1': 'one', '2': 'two' }
Returns all the keys of a map as an array.
map_akeys
(
map
)
| map | a map |
map_akeys(map('1','one','2','two'))
→
[ '1', '2' ]
Returns all the values of a map as an array.
map_avals
(
map
)
| map | a map |
map_avals(map('1','one','2','two'))
→
[ 'one', 'two' ]
Returns a map containing all the entries of the given maps. If two maps contain the same key, the value of the second map is taken.
map_concat
(
map1
,
map2
…)
| map | a map |
map_concat(map('1','one', '2','overridden'),map('2','two', '3','three'))
→
{ '1': 'one, '2': 'two', '3': 'three' }
Returns a map with the given key and its corresponding value deleted.
map_delete
(
map
,
key
)
| map | a map |
| key | the key to delete |
map_delete(map('1','one','2','two'),'2')
→
{ '1': 'one' }
Returns true if the given key exists in the map.
map_exist
(
map
,
key
)
| map | a map |
| key | the key to lookup |
map_exist(map('1','one','2','two'),'3')
→
false
Returns the value of a map, given it's key.
map_get
(
map
,
key
)
| map | a map |
| key | the key to lookup |
map_get(map('1','one','2','two'),'2')
→
'two'
Returns a map with an added key/value.
map_insert
(
map
,
key
,
value
)
| map | a map |
| key | the key to add |
| value | the value to add |
map_insert(map('1','one'),'3','three')
→
{ '1': 'one', '3': 'three' }
Merge map elements into a hstore-formatted string.
map_to_hstore
(
map
)
| map | the input map |
map_to_hstore(map('qgis','rocks'))
→
"qgis"=>"rocks"}
Merge map elements into a json-formatted string.
map_to_json
(
map
)
| map | the input map |
map_to_json(map('qgis','rocks'))
→
{"qgis":"rocks"}
Create a JSON formatted string from a map, array or other value.
to_json
(
value
)
| value | The input value |
to_json(map('qgis','rocks'))
→
{"qgis":"rocks"}
to_json(array(1,2,3))
→
[1,2,3]
This group contains math functions e.g square root, sin and cos
Returns the absolute value of a number.
abs
(
value
)
| value | a number |
abs(-2)
→
2
Returns the inverse cosine of a value in radians.
acos
(
value
)
| value | cosine of an angle in radians |
acos(0.5)
→
1.0471975511966
Returns the inverse sine of a value in radians.
asin
(
value
)
| value | sine of an angle in radians |
asin(1.0)
→
1.5707963267949
Returns the inverse tangent of a value in radians.
atan
(
value
)
| value | tan of an angle in radians |
atan(0.5)
→
0.463647609000806
Returns the inverse tangent of dy/dx by using the signs of the two arguments to determine the quadrant of the result.
atan2
(
dy
,
dx
)
| dy | y coordinate difference |
| dx | x coordinate difference |
atan2(1.0, 1.732)
→
0.523611477769969
Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.
azimuth
(
point_a
,
point_b
)
| point_a | point geometry |
| point_b | point geometry |
degrees( azimuth( make_point(25, 45), make_point(75, 100) ) )
→
42.273689
degrees( azimuth( make_point(75, 100), make_point(25,45) ) )
→
222.273689
Rounds a number upwards.
ceil
(
value
)
| value | a number |
ceil(4.9)
→
5
ceil(-4.9)
→
-4
Restricts an input value to a specified range.
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 |
| 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
(
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)
Returns cosine of an angle.
cos
(
angle
)
| angle | angle in radians |
cos(1.571)
→
0.000796326710733263
Converts from radians to degrees.
degrees
(
radians
)
| radians | numeric value |
degrees(3.14159)
→
180
degrees(1)
→
57.2958
Returns exponential of an value.
exp
(
value
)
| value | number to return exponent of |
exp(1.0)
→
2.71828182845905
Rounds a number downwards.
floor
(
value
)
| value | a number |
floor(4.9)
→
4
floor(-4.9)
→
-5
Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.
inclination
(
point_a
,
point_b
)
| point_a | point geometry |
| 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
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
Returns the natural logarithm of a value.
ln
(
value
)
| value | numeric value |
ln(1)
→
0
ln(2.7182818284590452354)
→
1
Returns the value of the logarithm of the passed value and base.
log
(
base
,
value
)
| base | any positive number |
| value | any positive number |
log(2, 32)
→
5
log(0.5, 32)
→
-5
Returns the value of the base 10 logarithm of the passed expression.
log10
(
value
)
| value | any positive number |
log10(1)
→
0
log10(100)
→
2
Returns the largest value in a set of values.
max
(
value1
,
value2
…)
| value | a number |
max(2,10.2,5.5)
→
10.2
max(20.5,NULL,6.2)
→
20.5
Returns the smallest value in a set of values.
min
(
value1
,
value2
…)
| value | a number |
min(20.5,10,6.2)
→
6.2
min(2,-10.3,NULL)
→
-10.3
Converts from degrees to radians.
radians
(
degrees
)
| degrees | numeric value |
radians(180)
→
3.14159
radians(57.2958)
→
1
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
])
| min | an integer representing the smallest possible random number desired |
| max | an integer representing the largest possible random number desired |
| seed | any value to use as seed |
rand(1, 10)
→
8
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
])
| min | an float representing the smallest possible random number desired |
| max | an float representing the largest possible random number desired |
| seed | any value to use as seed |
randf(1, 10)
→
4.59258286403147
Rounds a number to number of decimal places.
round
(
value
[,
places=0
])
| value | decimal number to be rounded |
| places | Optional integer representing number of places to round decimals to. Can be negative. |
round(1234.567, 2)
→
1234.57
round(1234.567)
→
1235
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.
scale_exp
(
val
,
domain_min
,
domain_max
,
range_min
,
range_max
,
exponent
)
| val | A value in the input domain. The function will return a corresponding scaled value in the output range. |
| domain_min | Specifies the minimum value in the input domain, the smallest value the input value should take. |
| domain_max | Specifies the maximum value in the input domain, the largest value the input value should take. |
| range_min | Specifies the minimum value in the output range, the smallest value which should be output by the function. |
| range_max | Specifies the maximum value in the output range, the largest value which should be output by the function. |
| exponent | A positive value (greater than 0), which dictates the way input values are mapped to the output range. Large exponents will cause the output values to 'ease in', starting slowly before accelerating as the input values approach the domain maximum. Smaller exponents (less than 1) will cause output values to 'ease out', where the mapping starts quickly but slows as it approaches the domain maximum. |
scale_exp(5,0,10,0,100,2)
→
25
(easing in, using an exponent of 2)
scale_exp(3,0,10,0,100,0.5)
→
54.772
(easing out, using an exponent of 0.5)
Transforms a given value from an input domain to an output range using linear interpolation.
scale_linear
(
val
,
domain_min
,
domain_max
,
range_min
,
range_max
)
| val | A value in the input domain. The function will return a corresponding scaled value in the output range. |
| domain_min | Specifies the minimum value in the input domain, the smallest value the input value should take. |
| domain_max | Specifies the maximum value in the input domain, the largest value the input value should take. |
| range_min | Specifies the minimum value in the output range, the smallest value which should be output by the function. |
| range_max | Specifies the maximum value in the output range, the largest value which should be output by the function. |
scale_linear(5,0,10,0,100)
→
50
scale_linear(0.2,0,1,0,360)
→
72
(scaling a value between 0 and 1 to an angle between 0 and 360)
scale_linear(1500,1000,10000,9,20)
→
9.6111111
(scaling a population which varies between 1000 and 10000 to a font size between 9 and 20)
Returns the sine of an angle.
sin
(
angle
)
| angle | angle in radians |
sin(1.571)
→
0.999999682931835
Returns square root of a value.
sqrt
(
value
)
| value | a number |
sqrt(9)
→
3
Returns the tangent of an angle.
tan
(
angle
)
| angle | angle in radians |
tan(1.0)
→
1.5574077246549
Returns the value of a processing algorithm input parameter.
parameter
(
name
)
| name | name of the corresponding input parameter |
parameter('BUFFER_SIZE')
→
5.6
function help for $mask_geometry missing
function help for in_mask missing
Contains functions which calculate raster statistics and values.
Returns statistics from a raster layer.
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:
|
raster_statistic('lc',1,'avg')
→
Average value from band 1 from 'lc' raster layer
raster_statistic('ac2010',3,'min')
→
Minimum value from band 3 from 'ac2010' raster layer
Returns the raster value found at the provided point.
raster_value
(
layer
,
band
,
point
)
| layer | the name or id of a raster layer |
| band | the band number to sample the value from. |
| point | point geometry (for multipart geometries having more than one part, a null value will be returned) |
raster_value('dem', 1, make_point(1,1))
→
25
This group contains functions that operate on record identifiers.
Returns the current feature being evaluated. This can be used with the 'attribute' function to evaluate attribute values from the current feature.
$currentfeature
attribute( $currentfeature, 'name' )
→
value stored in 'name' attribute for the current feature
Returns an attribute from a feature.
attribute
(
attribute_name
)
| attribute_name | name of attribute to be returned |
attribute( 'name' )
→
value stored in 'name' attribute for the current feature
attribute
(
feature
,
attribute_name
)
| feature | a feature |
| attribute_name | name of attribute to be returned |
attribute( @atlas_feature, 'name' )
→
value stored in 'name' attribute for the current atlas feature
Returns a map containing all attributes from a feature, with field names as map keys.
attributes
()
attributes()['name']
→
value stored in 'name' attribute for the current feature
attributes
(
feature
)
| feature | a feature |
attributes( @atlas_feature )['name']
→
value stored in 'name' attribute for the current atlas feature
Returns the first feature of a layer matching a given attribute value.
get_feature
(
layer
,
attribute
,
value
)
| layer | layer name or ID |
| attribute | attribute name |
| value | attribute value to match |
get_feature('streets','name','main st')
→
first feature found in "streets" layer with "main st" value in the "name" field
Returns the feature with an id on a layer.
get_feature_by_id
(
layer
,
feature_id
)
| layer | layer, layer name or layer id |
| feature_id | the id of the feature which should be returned |
get_feature('streets', 1)
→
the feature with the id 1 on the layer "streets"
Returns if a feature is selected. If called with no parameters checks the current feature.
is_selected
([
feature=current feature
][,
layer=current layer
])
| feature | The feature which should be checked for selection. |
| layer | The layer (or its id or name) on which the selection will be checked. |
is_selected()
→
True if the current feature is selected.
is_selected(get_feature('streets', 'name', "street_name"), 'streets')
→
True if the current building's street is 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
])
| layer | The layer (or its id or name) on which the selection will be checked. |
num_selected()
→
The number of selected features on the current layer.
num_selected('streets')
→
The number of selected features on the layer streets
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
)
| value | The value which should be resolved. Most likely a field. |
| fieldName | The field name for which the widget configuration should be loaded. (Optional) |
represent_value("field_with_value_map")
→
Description for value
represent_value('static value', 'field_name')
→
Description for static value
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_value 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
])
| database | Path to the sqlite file or geopackage layer |
| table | Name of the table that manages the sequences |
| id_field | Name of the field that contains the current value |
| filter_attribute | Name the field that contains a unique identifier for this sequence. Must have a UNIQUE index. |
| filter_value | Name of the sequence to use. |
| default_values | Map with default values for additional columns on the table. The values need to be fully quoted. Functions are allowed. |
sqlite_fetch_and_increment(@layer, 'sequence_table', 'last_unique_id', 'sequence_id', 'global', map('last_change','date(''now'')','user','''' || @user_account_name || ''''))
→
0
sqlite_fetch_and_increment(layer_property(@layer, 'path'), 'sequence_table', 'last_unique_id', 'sequence_id', 'global', map('last_change','date(''now'')','user','''' || @user_account_name || ''''))
→
0
Generates a Universally Unique Identifier (UUID) for each row using the Qt QUuid::createUuid method. Each UUID is 38 characters long.
uuid
()
uuid()
→
'{0bd2f60f-f157-4a6d-96af-d4ba4cb366a1}'
This group contains functions that operate on strings e.g replace, convert to upper case.
Returns the character associated with a unicode code.
char
(
code
)
| code | a unicode code number |
char(81)
→
'Q'
Concatenates several strings to one. NULL values are converted to empty strings. Other values (like numbers) are converted to strings.
concat
(
string1
,
string2
…)
| string | a string value |
concat('sun', 'set')
→
'sunset'
concat('a','b','c','d','e')
→
'abcde'
concat('Anno ', 1984)
→
'Anno 1984'
concat('The Wall', NULL)
→
'The Wall'
Format a string using supplied arguments.
format
(
string
,
arg1
,
arg2
…)
| string | A string with place holders for the arguments. Use %1, %2, etc for placeholders. Placeholders can be repeated. |
| arg | any type. Any number of arguments. |
format('This %1 a %2','is', 'test')
→
'This is a test''
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
])
| datetime | date, time or datetime value | ||||||||||||||||||||||||||||||||||||||||||||||||
| format |
String template used to format the string.
These expressions may be used for the time part of the format string:
|
||||||||||||||||||||||||||||||||||||||||||||||||
| language | language (lowercase, two- or three-letter, ISO 639 language code) used to format the date into a custom string |
format_date('2012-05-15','dd.MM.yyyy')
→
'15.05.2012'
format_date('2012-05-15','d MMMM yyyy','fr')
→
'15 juin 2012'
Returns a number formatted with the locale separator for thousands. Also truncates the number to the number of supplied places.
format_number
(
number
,
places
)
| number | number to be formatted |
| places | integer representing the number of decimal places to truncate the string to. |
format_number(10000000.332,2)
→
'10,000,000.33'
Returns a substring that contains the n leftmost characters of the string.
left
(
string
,
length
)
| string | a string |
| length | integer. The number of characters from the left of the string to return. |
left('Hello World',5)
→
'Hello'
Returns the number of characters in a string or the length of a geometry linestring.
length
(
string
)
| string | string to count length of |
length('hello')
→
5
length
(
geometry
)
| geometry | line geometry object |
length(geom_from_wkt('LINESTRING(0 0, 4 0)'))
→
4.0
Converts a string to lower case letters.
lower
(
string
)
| string | the string to convert to lower case |
lower('HELLO World')
→
'hello world'
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.
lpad
(
string
,
width
,
fill
)
| string | string to pad |
| width | length of new string |
| fill | character to pad the remaining space with |
lpad('Hello', 10, 'x')
→
'xxxxxHello'
lpad('Hello', 3, 'x')
→
'Hel'
Return the first matching position matching a regular expression within a string, or 0 if the substring is not found.
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., "\\s" to match a white space character). |
regexp_match('QGIS ROCKS','\\sROCKS')
→
4
Returns a string with the supplied regular expression replaced.
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). |
| 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'
Returns the portion of a string which matches a supplied regular expression.
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., "\\s" to match a white space character). |
regexp_substr('abc123','(\\d+)')
→
'123'
Returns a string with the supplied string, array, or map of strings replaced.
replace
(
string
,
before
,
after
)
| string | the input string |
| before | the string or array of strings to replace |
| after | the string or array of strings to use as a replacement |
replace('QGIS SHOULD ROCK','SHOULD','DOES')
→
'QGIS DOES ROCK'
replace('QGIS ABC',array('A','B','C'),array('X','Y','Z'))
→
'QGIS XYZ'
replace('QGIS',array('Q','S'),'')
→
'GI'
replace
(
string
,
map
)
| string | the input string |
| map | the map containing keys and values |
replace('APP SHOULD ROCK',map('APP','QGIS','SHOULD','DOES'))
→
'QGIS DOES ROCK'
Returns a substring that contains the n rightmost characters of the string.
right
(
string
,
length
)
| string | a string |
| length | integer. The number of characters from the right of the string to return. |
right('Hello World',5)
→
'World'
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.
rpad
(
string
,
width
,
fill
)
| string | string to pad |
| width | length of new string |
| fill | character to pad the remaining space with |
rpad('Hello', 10, 'x')
→
'Helloxxxxx'
rpad('Hello', 3, 'x')
→
'Hel'
Return the first matching position of a substring within another string, or 0 if the substring is not found.
strpos
(
haystack
,
needle
)
| haystack | string that is to be searched |
| needle | string to search for |
strpos('HELLO WORLD','WORLD')
→
7
strpos('HELLO WORLD','GOODBYE')
→
0
Returns a part of a string.
substr
(
string
,
start
[,
length
])
| string | the full input string |
| start | integer representing start position to extract beginning with 1; if start is negative, the return string will begin at the end of the string minus the start value |
| length | integer representing length of string to extract; if length is negative, the return string will omit the given length of characters from the end of the string |
substr('HELLO WORLD',3,5)
→
'LLO W'
substr('HELLO WORLD',6)
→
' WORLD'
substr('HELLO WORLD',-5)
→
'WORLD'
substr('HELLO',3,-1)
→
'LL'
substr('HELLO WORLD',-5,2)
→
'WO'
substr('HELLO WORLD',-5,-1)
→
'WORL'
Converts all words of a string to title case (all words lower case with leading capital letter).
title
(
string
)
| string | the string to convert to title case |
title('hello WOrld')
→
'Hello World'
Converts a number to string.
to_string
(
number
)
| number | Integer or real value. The number to convert to string. |
to_string(123)
→
'123'
Removes all leading and trailing whitespace (spaces, tabs, etc) from a string.
trim
(
string
)
| string | string to trim |
trim(' hello world ')
→
'hello world'
Converts a string to upper case letters.
upper
(
string
)
| string | the string to convert to upper case |
upper('hello WOrld')
→
'HELLO WORLD'
Returns a string wrapped to a maximum/minimum number of characters.
wordwrap
(
string
,
wrap_length
[,
delimiter_string
])
| string | the string to be wrapped |
| wrap_length | an integer. If wrap_length is positive the number represents the ideal maximum number of characters to wrap; if negative, the number represents the minimum number of characters to wrap. |
| delimiter_string | Optional delimiter string to wrap to a new line. |
wordwrap('UNIVERSITY OF QGIS',13)
→
'UNIVERSITY OF
QGIS'
wordwrap('UNIVERSITY OF QGIS',-3)
→
'UNIVERSITY
OF QGIS'