14.3. List of functions
The functions, operators and variables available in QGIS are listed below, grouped by categories.
14.3.1. Aggregates Functions
This group contains functions which aggregate values over layers and fields.
14.3.1.1. aggregate
Returns an aggregate value calculated using features from another layer.
Syntax |
aggregate(layer, aggregate, expression, [filter], [concatenator=‘‘], [order_by]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.2. array_agg
Returns an array of aggregated values from a field or expression.
Syntax |
array_agg(expression, [group_by], [filter], [order_by]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.3. collect
Returns the multipart geometry of aggregated geometries from an expression
Syntax |
collect(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.4. concatenate
Returns all aggregated strings from a field or expression joined by a delimiter.
Syntax |
concatenate(expression, [group_by], [filter], [concatenator], [order_by]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.5. concatenate_unique
Returns all unique strings from a field or expression joined by a delimiter.
Syntax |
concatenate_unique(expression, [group_by], [filter], [concatenator], [order_by]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.6. count
Returns the count of matching features.
Syntax |
count(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.7. count_distinct
Returns the count of distinct values.
Syntax |
count_distinct(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.8. count_missing
Returns the count of missing (NULL) values.
Syntax |
count_missing(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.9. iqr
Returns the calculated inter quartile range from a field or expression.
Syntax |
iqr(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.10. majority
Returns the aggregate majority of values (most commonly occurring value) from a field or expression.
Syntax |
majority(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.11. max_length
Returns the maximum length of strings from a field or expression.
Syntax |
max_length(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.12. maximum
Returns the aggregate maximum value from a field or expression.
Syntax |
maximum(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.13. mean
Returns the aggregate mean value from a field or expression.
Syntax |
mean(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.14. median
Returns the aggregate median value from a field or expression.
Syntax |
median(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.15. min_length
Returns the minimum length of strings from a field or expression.
Syntax |
min_length(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.16. minimum
Returns the aggregate minimum value from a field or expression.
Syntax |
minimum(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.17. minority
Returns the aggregate minority of values (least occurring value) from a field or expression.
Syntax |
minority(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.18. q1
Returns the calculated first quartile from a field or expression.
Syntax |
q1(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.19. q3
Returns the calculated third quartile from a field or expression.
Syntax |
q3(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.20. range
Returns the aggregate range of values (maximum - minimum) from a field or expression.
Syntax |
range(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.21. relation_aggregate
Returns an aggregate value calculated using all matching child features from a layer relation.
Syntax |
relation_aggregate(relation, aggregate, expression, [concatenator=‘‘], [order_by]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Creating one or many to many relations
14.3.1.22. stdev
Returns the aggregate standard deviation value from a field or expression.
Syntax |
stdev(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.1.23. sum
Returns the aggregate summed value from a field or expression.
Syntax |
sum(expression, [group_by], [filter]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.2. Array Functions
This group contains functions to create and manipulate arrays (also known as list data structures). The order of values within the array matters, unlike the ‚map‘ data structure, where the order of key-value pairs is irrelevant and values are identified by their keys.
14.3.2.1. array
Returns an array containing all the values passed as parameter.
Syntax |
array(value1, value2, …) |
Arguments |
|
Примери |
|
14.3.2.2. array_all
Returns true if an array contains all the values of a given array.
Syntax |
array_all(array_a, array_b) |
Arguments |
|
Примери |
|
14.3.2.3. array_append
Returns an array with the given value added at the end.
Syntax |
array_append(array, value) |
Arguments |
|
Примери |
|
14.3.2.4. array_cat
Returns an array containing all the given arrays concatenated.
Syntax |
array_cat(array1, array2, …) |
Arguments |
|
Примери |
|
14.3.2.5. array_contains
Returns true if an array contains the given value.
Syntax |
array_contains(array, value) |
Arguments |
|
Примери |
|
14.3.2.6. array_distinct
Returns an array containing distinct values of the given array.
Syntax |
array_distinct(array) |
Arguments |
|
Примери |
|
14.3.2.7. array_filter
Returns an array with only the items for which the expression evaluates to true.
Syntax |
array_filter(array, expression) |
Arguments |
|
Примери |
|
14.3.2.8. array_find
Returns the index (0 for the first one) of a value within an array. Returns -1 if the value is not found.
Syntax |
array_find(array, value) |
Arguments |
|
Примери |
|
14.3.2.9. array_first
Returns the first value of an array.
Syntax |
array_first(array) |
Arguments |
|
Примери |
|
14.3.2.10. array_foreach
Returns an array with the given expression evaluated on each item.
Syntax |
array_foreach(array, expression) |
Arguments |
|
Примери |
|
14.3.2.11. array_get
Returns the Nth value (0 for the first one) of an array.
Syntax |
array_get(array, index) |
Arguments |
|
Примери |
|
14.3.2.12. array_insert
Returns an array with the given value added at the given position.
Syntax |
array_insert(array, pos, value) |
Arguments |
|
Примери |
|
14.3.2.13. array_intersect
Returns true if at least one element of array1 exists in array2.
Syntax |
array_intersect(array1, array2) |
Arguments |
|
Примери |
|
14.3.2.14. array_last
Returns the last value of an array.
Syntax |
array_last(array) |
Arguments |
|
Примери |
|
14.3.2.15. array_length
Returns the number of elements of an array.
Syntax |
array_length(array) |
Arguments |
|
Примери |
|
14.3.2.16. array_prepend
Returns an array with the given value added at the beginning.
Syntax |
array_prepend(array, value) |
Arguments |
|
Примери |
|
14.3.2.17. array_remove_all
Returns an array with all the entries of the given value removed.
Syntax |
array_remove_all(array, value) |
Arguments |
|
Примери |
|
14.3.2.18. array_remove_at
Returns an array with the given index removed.
Syntax |
array_remove_at(array, pos) |
Arguments |
|
Примери |
|
14.3.2.19. array_reverse
Returns the given array with array values in reversed order.
Syntax |
array_reverse(array) |
Arguments |
|
Примери |
|
14.3.2.20. array_slice
Returns a portion of the array. The slice is defined by the start_pos and end_pos arguments.
Syntax |
array_slice(array, start_pos, end_pos) |
Arguments |
|
Примери |
|
14.3.2.21. array_sort
Returns the provided array with its elements sorted.
Syntax |
array_sort(array, [ascending=true]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.2.22. array_to_string
Concatenates array elements into a string separated by a delimiter and using optional string for empty values.
Syntax |
array_to_string(array, [delimiter=‘,‘], [empty_value=‘‘]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.2.23. generate_series
Creates an array containing a sequence of numbers.
Syntax |
generate_series(start, stop, [step=1]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.2.24. regexp_matches
Returns an array of all strings captured by capturing groups, in the order the groups themselves appear in the supplied regular expression against a string.
Syntax |
regexp_matches(string, regex, [empty_value=‘‘]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.2.25. string_to_array
Splits string into an array using supplied delimiter and optional string for empty values.
Syntax |
string_to_array(string, [delimiter=‘,‘], [empty_value=‘‘]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.3. Color Functions
This group contains functions for manipulating colors.
14.3.3.1. color_cmyk
Returns a string representation of a color based on its cyan, magenta, yellow and black components
Syntax |
color_cmyk(cyan, magenta, yellow, black) |
Arguments |
|
Примери |
|
14.3.3.2. color_cmyka
Returns a string representation of a color based on its cyan, magenta, yellow, black and alpha (transparency) components
Syntax |
color_cmyka(cyan, magenta, yellow, black, alpha) |
Arguments |
|
Примери |
|
14.3.3.3. color_grayscale_average
Applies a grayscale filter and returns a string representation from a provided color.
Syntax |
color_grayscale_average(color) |
Arguments |
|
Примери |
|
14.3.3.4. color_hsl
Returns a string representation of a color based on its hue, saturation, and lightness attributes.
Syntax |
color_hsl(hue, saturation, lightness) |
Arguments |
|
Примери |
|
14.3.3.5. color_hsla
Returns a string representation of a color based on its hue, saturation, lightness and alpha (transparency) attributes
Syntax |
color_hsla(hue, saturation, lightness, alpha) |
Arguments |
|
Примери |
|
14.3.3.6. color_hsv
Returns a string representation of a color based on its hue, saturation, and value attributes.
Syntax |
color_hsv(hue, saturation, value) |
Arguments |
|
Примери |
|
14.3.3.7. color_hsva
Returns a string representation of a color based on its hue, saturation, value and alpha (transparency) attributes.
Syntax |
color_hsva(hue, saturation, value, alpha) |
Arguments |
|
Примери |
|
14.3.3.8. color_mix_rgb
Returns a string representing a color mixing the red, green, blue, and alpha values of two provided colors based on a given ratio.
Syntax |
color_mix_rgb(color1, color2, ratio) |
Arguments |
|
Примери |
|
14.3.3.9. color_part
Returns a specific component from a color string, e.g., the red component or alpha component.
Syntax |
color_part(color, component) |
Arguments |
|
Примери |
|
14.3.3.10. color_rgb
Returns a string representation of a color based on its red, green, and blue components.
Syntax |
color_rgb(red, green, blue) |
Arguments |
|
Примери |
|
14.3.3.11. color_rgba
Returns a string representation of a color based on its red, green, blue, and alpha (transparency) components.
Syntax |
color_rgba(red, green, blue, alpha) |
Arguments |
|
Примери |
|
14.3.3.12. create_ramp
Returns a gradient ramp from a map of color strings and steps.
Syntax |
create_ramp(map, [discrete=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.3.13. darker
Returns a darker (or lighter) color string
Syntax |
darker(color, factor) |
Arguments |
|
Примери |
|
Further reading: lighter
14.3.3.14. lighter
Returns a lighter (or darker) color string
Syntax |
lighter(color, factor) |
Arguments |
|
Примери |
|
Further reading: darker
14.3.3.15. project_color
Returns a color from the project’s color scheme.
Syntax |
project_color(name) |
Arguments |
|
Примери |
|
Further reading: setting project colors
14.3.3.16. ramp_color
Returns a string representing a color from a color ramp.
Saved ramp variant
Returns a string representing a color from a saved ramp
Syntax |
ramp_color(ramp_name, value) |
Arguments |
|
Примери |
|
Note
The color ramps available vary between QGIS installations. This function may not give the expected results if you move your QGIS project between installations.
Expression-created ramp variant
Returns a string representing a color from an expression-created ramp
Syntax |
ramp_color(ramp, value) |
Arguments |
|
Примери |
|
Further reading: Setting a Color Ramp, The color ramp drop-down shortcut
14.3.3.17. set_color_part
Sets a specific color component for a color string, e.g., the red component or alpha component.
Syntax |
set_color_part(color, component, value) |
Arguments |
|
Примери |
|
14.3.4. Conditional Functions
This group contains functions to handle conditional checks in expressions.
14.3.4.1. CASE
CASE is used to evaluate a series of conditions and return a result for the first condition met. The conditions are evaluated sequentially, and if a condition is true, the evaluation stops, and the corresponding result is returned. If none of the conditions are true, the value in the ELSE clause is returned. Furthermore, if no ELSE clause is set and none of the conditions are met, NULL is returned.
CASE
WHEN condition THEN result
[ …n ]
[ ELSE result ]
END
[ ] marks optional components
Arguments |
|
Примери |
|
14.3.4.2. coalesce
Returns the first non-NULL value from the expression list.
This function can take any number of arguments.
Syntax |
coalesce(expression1, expression2, …) |
Arguments |
|
Примери |
|
14.3.4.3. if
Tests a condition and returns a different result depending on the conditional check.
Syntax |
if(condition, result_when_true, result_when_false) |
Arguments |
|
Примери |
|
14.3.4.4. nullif
Returns a NULL value if value1 equals value2; otherwise it returns value1. This can be used to conditionally substitute values with NULL.
Syntax |
nullif(value1, value2) |
Arguments |
|
Примери |
|
14.3.4.5. regexp_match
Return the first matching position matching a regular expression within an unicode string, or 0 if the substring is not found.
Syntax |
regexp_match(input_string, regex) |
Arguments |
|
Примери |
|
14.3.4.6. try
Tries an expression and returns its value if error-free. If the expression returns an error, an alternative value will be returned when provided otherwise the function will return NULL.
Syntax |
try(expression, [alternative]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.5. Conversions Functions
This group contains functions to convert one data type to another (e.g., string from/to integer, binary from/to string, string to date, …).
14.3.5.1. from_base64
Decodes a string in the Base64 encoding into a binary value.
Syntax |
from_base64(string) |
Arguments |
|
Примери |
|
14.3.5.2. hash
Creates a hash from a string with a given method. One byte (8 bits) is represented with two hex ‚‘digits‘‘, so ‚md4‘ (16 bytes) produces a 16 * 2 = 32 character long hex string and ‚keccak_512‘ (64 bytes) produces a 64 * 2 = 128 character long hex string.
Syntax |
hash(string, method) |
Arguments |
|
Примери |
|
14.3.5.3. md5
Creates a md5 hash from a string.
Syntax |
md5(string) |
Arguments |
|
Примери |
|
14.3.5.4. sha256
Creates a sha256 hash from a string.
Syntax |
sha256(string) |
Arguments |
|
Примери |
|
14.3.5.5. to_base64
Encodes a binary value into a string, using the Base64 encoding.
Syntax |
to_base64(value) |
Arguments |
|
Примери |
|
14.3.5.6. to_date
Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.
Syntax |
to_date(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.5.7. to_datetime
Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDate::fromString and QTime::fromString for additional documentation on the format.
Syntax |
to_datetime(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.5.8. to_decimal
Converts a degree, minute, second coordinate to its decimal equivalent.
Syntax |
to_decimal(value) |
Arguments |
|
Примери |
|
14.3.5.9. to_dm
Converts a coordinate to degree, minute.
Syntax |
to_dm(coordinate, axis, precision, [formatting=]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.5.10. to_dms
Converts a coordinate to degree, minute, second.
Syntax |
to_dms(coordinate, axis, precision, [formatting=]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.5.11. to_int
Converts a string to integer number. Nothing is returned if a value cannot be converted to integer (e.g ‚123asd‘ is invalid).
Syntax |
to_int(string) |
Arguments |
|
Примери |
|
14.3.5.12. to_interval
Converts a string to an interval type. Can be used to take days, hours, month, etc of a date.
Syntax |
to_interval(string) |
Arguments |
|
Примери |
|
14.3.5.13. to_real
Converts a string to a real number. Nothing is returned if a value cannot be converted to real (e.g ‚123.56asd‘ is invalid). Numbers are rounded after saving changes if the precision is smaller than the result of the conversion.
Syntax |
to_real(string) |
Arguments |
|
Примери |
|
14.3.5.14. to_string
Converts a number to string.
Syntax |
to_string(number) |
Arguments |
|
Примери |
|
14.3.5.15. to_time
Converts a string into a time object. An optional format string can be provided to parse the string; see QTime::fromString for additional documentation on the format.
Syntax |
to_time(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.6. Custom Functions
This group contains functions created by the user. See Function Editor for more details.
14.3.7. Date and Time Functions
This group contains functions for handling date and time data. This group shares several functions with the Conversions Functions (to_date, to_time, to_datetime, to_interval) and String Functions (format_date) groups.
Note
Storing date, datetime and intervals on fields
The ability to store date, time and datetime values directly on fields depends on the data source’s provider (e.g., Shapefile accepts date format, but not datetime or time format). The following are some suggestions to overcome this limitation:
date, datetime and time can be converted and stored in text type fields using the format_date() function.
Intervals can be stored in integer or decimal type fields after using one of the date extraction functions (e.g., day() to get the interval expressed in days)
14.3.7.1. age
Returns the difference between two dates or datetimes.
The difference is returned as an Interval
and needs to be used with one of the following functions in order to extract useful information:
year
month
week
day
hour
minute
second
Syntax |
age(datetime1, datetime2) |
Arguments |
|
Примери |
|
14.3.7.2. datetime_from_epoch
Returns a datetime whose date and time are the number of milliseconds, msecs, that have passed since 1970-01-01T00:00:00.000, Coordinated Universal Time (Qt.UTC), and converted to Qt.LocalTime.
Syntax |
datetime_from_epoch(int) |
Arguments |
|
Примери |
|
14.3.7.3. day
Extracts the day from a date, or the number of days from an interval.
Date variant
Extracts the day from a date or datetime.
Syntax |
day(date) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in days of an interval.
Syntax |
day(interval) |
Arguments |
|
Примери |
|
14.3.7.4. day_of_week
Returns the day of the week for a specified date or datetime. The returned value ranges from 0 to 6, where 0 corresponds to a Sunday and 6 to a Saturday.
Syntax |
day_of_week(date) |
Arguments |
|
Примери |
|
14.3.7.5. epoch
Returns the interval in milliseconds between the unix epoch and a given date value.
Syntax |
epoch(date) |
Arguments |
|
Примери |
|
14.3.7.6. format_date
Formats a date type or string into a custom string format. Uses Qt date/time format strings. See QDateTime::toString.
Syntax |
format_date(datetime, format, [language]) [] marks optional arguments |
||||||||||||||||||||||||||||||||||||||||||||||||
Arguments |
|
||||||||||||||||||||||||||||||||||||||||||||||||
Примери |
|
14.3.7.7. hour
Extracts the hour part from a datetime or time, or the number of hours from an interval.
Time variant
Extracts the hour part from a time or datetime.
Syntax |
hour(datetime) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in hours of an interval.
Syntax |
hour(interval) |
Arguments |
|
Примери |
|
14.3.7.8. make_date
Creates a date value from year, month and day numbers.
Syntax |
make_date(year, month, day) |
Arguments |
|
Примери |
|
14.3.7.9. make_datetime
Creates a datetime value from year, month, day, hour, minute and second numbers.
Syntax |
make_datetime(year, month, day, hour, minute, second) |
Arguments |
|
Примери |
|
14.3.7.10. make_interval
Creates an interval value from year, month, weeks, days, hours, minute and seconds values.
Syntax |
make_interval([years=0], [months=0], [weeks=0], [days=0], [hours=0], [minutes=0], [seconds=0]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.7.11. make_time
Creates a time value from hour, minute and second numbers.
Syntax |
make_time(hour, minute, second) |
Arguments |
|
Примери |
|
14.3.7.12. minute
Extracts the minutes part from a datetime or time, or the number of minutes from an interval.
Time variant
Extracts the minutes part from a time or datetime.
Syntax |
minute(datetime) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in minutes of an interval.
Syntax |
minute(interval) |
Arguments |
|
Примери |
|
14.3.7.13. month
Extracts the month part from a date, or the number of months from an interval.
Date variant
Extracts the month part from a date or datetime.
Syntax |
month(date) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in months of an interval.
Syntax |
month(interval) |
Arguments |
|
Примери |
|
14.3.7.14. now
Returns the current date and time. The function is static and will return consistent results while evaluating. The time returned is the time when the expression is prepared.
Syntax |
now() |
Примери |
|
14.3.7.15. second
Extracts the seconds part from a datetime or time, or the number of seconds from an interval.
Time variant
Extracts the seconds part from a time or datetime.
Syntax |
second(datetime) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in seconds of an interval.
Syntax |
second(interval) |
Arguments |
|
Примери |
|
14.3.7.16. to_date
Converts a string into a date object. An optional format string can be provided to parse the string; see QDate::fromString for additional documentation on the format.
Syntax |
to_date(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.7.17. to_datetime
Converts a string into a datetime object. An optional format string can be provided to parse the string; see QDate::fromString and QTime::fromString for additional documentation on the format.
Syntax |
to_datetime(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.7.18. to_interval
Converts a string to an interval type. Can be used to take days, hours, month, etc of a date.
Syntax |
to_interval(string) |
Arguments |
|
Примери |
|
14.3.7.19. to_time
Converts a string into a time object. An optional format string can be provided to parse the string; see QTime::fromString for additional documentation on the format.
Syntax |
to_time(string, [format], [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.7.20. week
Extracts the week number from a date, or the number of weeks from an interval.
Date variant
Extracts the week number from a date or datetime.
Syntax |
week(date) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in weeks of an interval.
Syntax |
week(interval) |
Arguments |
|
Примери |
|
14.3.7.21. year
Extracts the year part from a date, or the number of years from an interval.
Date variant
Extracts the year part from a date or datetime.
Syntax |
year(date) |
Arguments |
|
Примери |
|
Interval variant
Calculates the length in years of an interval.
Syntax |
year(interval) |
Arguments |
|
Примери |
|
Some examples:
Besides these functions, subtracting dates, datetimes or times using the
-
(minus) operator will return an interval.
Adding or subtracting an interval to dates, datetimes or times, using the
+
(plus) and -
(minus) operators, will return a datetime.
Get the number of days until QGIS 3.0 release:
to_date('2017-09-29') - to_date(now()) -- Returns <interval: 203 days>
The same with time:
to_datetime('2017-09-29 12:00:00') - now() -- Returns <interval: 202.49 days>
Get the datetime of 100 days from now:
now() + to_interval('100 days') -- Returns <datetime: 2017-06-18 01:00:00>
14.3.8. Fields and Values
Contains a list of fields from the layer.
Double-click a field name to have it added to your expression. You can also type the field name (preferably inside double quotes) or its alias.
To retrieve fields values to use in an expression, select the appropriate field and, in the shown widget, choose between 10 Samples and All Unique. Requested values are then displayed and you can use the Search box at the top of the list to filter the result. Sample values can also be accessed via right-clicking on a field.
To add a value to the expression you are writing, double-click on it in the list. If the value is of a string type, it should be simple quoted, otherwise no quote is needed.
14.3.9. Files and Paths Functions
This group contains functions which manipulate file and path names.
14.3.9.1. base_file_name
Returns the base name of the file without the directory or file suffix.
Syntax |
base_file_name(path) |
Arguments |
|
Примери |
|
14.3.9.2. file_exists
Returns true if a file path exists.
Syntax |
file_exists(path) |
Arguments |
|
Примери |
|
14.3.9.3. file_name
Returns the name of a file (including the file extension), excluding the directory.
Syntax |
file_name(path) |
Arguments |
|
Примери |
|
14.3.9.4. file_path
Returns the directory component of a file path. This does not include the file name.
Syntax |
file_path(path) |
Arguments |
|
Примери |
|
14.3.9.5. file_size
Returns the size (in bytes) of a file.
Syntax |
file_size(path) |
Arguments |
|
Примери |
|
14.3.9.6. file_suffix
Returns the file suffix (extension) from a file path.
Syntax |
file_suffix(path) |
Arguments |
|
Примери |
|
14.3.9.7. is_directory
Returns true if a path corresponds to a directory.
Syntax |
is_directory(path) |
Arguments |
|
Примери |
|
14.3.9.8. is_file
Returns true if a path corresponds to a file.
Syntax |
is_file(path) |
Arguments |
|
Примери |
|
14.3.10. Form Functions
This group contains functions that operate exclusively under the attribute form context. For example, in field’s widgets settings.
14.3.10.1. current_parent_value
Only usable in an embedded form context, this function returns the current, unsaved value of a field in the parent form currently being edited. This will differ from the parent feature’s actual attribute values for features which are currently being edited or have not yet been added to a parent layer. When used in a value-relation widget filter expression, this function should be wrapped into a ‚coalesce()‘ that can retrieve the actual parent feature from the layer when the form is not used in an embedded context.
Syntax |
current_parent_value(field_name) |
Arguments |
|
Примери |
|
14.3.10.2. current_value
Returns the current, unsaved value of a field in the form or table row currently being edited. This will differ from the feature’s actual attribute values for features which are currently being edited or have not yet been added to a layer.
Syntax |
current_value(field_name) |
Arguments |
|
Примери |
|
14.3.11. Fuzzy Matching Functions
This group contains functions for fuzzy comparisons between values.
14.3.11.1. hamming_distance
Returns the Hamming distance between two strings. This equates to the number of characters at corresponding positions within the input strings where the characters are different. The input strings must be the same length, and the comparison is case-sensitive.
Syntax |
hamming_distance(string1, string2) |
Arguments |
|
Примери |
|
14.3.11.2. levenshtein
Returns the Levenshtein edit distance between two strings. This equates to the minimum number of character edits (insertions, deletions or substitutions) required to change one string to another.
The Levenshtein distance is a measure of the similarity between two strings. Smaller distances mean the strings are more similar, and larger distances indicate more different strings. The distance is case sensitive.
Syntax |
levenshtein(string1, string2) |
Arguments |
|
Примери |
|
14.3.11.3. longest_common_substring
Returns the longest common substring between two strings. This substring is the longest string that is a substring of the two input strings. For example, the longest common substring of „ABABC“ and „BABCA“ is „BABC“. The substring is case sensitive.
Syntax |
longest_common_substring(string1, string2) |
Arguments |
|
Примери |
|
14.3.11.4. soundex
Returns the Soundex representation of a string. Soundex is a phonetic matching algorithm, so strings with similar sounds should be represented by the same Soundex code.
Syntax |
soundex(string) |
Arguments |
|
Примери |
|
14.3.12. General Functions
This group contains general assorted functions.
14.3.12.1. env
Gets an environment variable and returns its content as a string. If the variable is not found, NULL will be returned. This is handy to inject system specific configuration like drive letters or path prefixes. Definition of environment variables depends on the operating system, please check with your system administrator or the operating system documentation how this can be set.
Syntax |
env(name) |
Arguments |
|
Примери |
|
14.3.12.2. eval
Evaluates an expression which is passed in a string. Useful to expand dynamic parameters passed as context variables or fields.
Syntax |
eval(expression) |
Arguments |
|
Примери |
|
14.3.12.3. eval_template
Evaluates a template which is passed in a string. Useful to expand dynamic parameters passed as context variables or fields.
Syntax |
eval_template(template) |
Arguments |
|
Примери |
|
14.3.12.4. is_layer_visible
Returns true if a specified layer is visible.
Syntax |
is_layer_visible(layer) |
Arguments |
|
Примери |
|
14.3.12.5. layer_property
Returns a matching layer property or metadata value.
Syntax |
layer_property(layer, property) |
Arguments |
|
Примери |
|
14.3.12.6. var
Returns the value stored within a specified variable.
Syntax |
var(name) |
Arguments |
|
Примери |
|
Further reading: List of default variables
14.3.12.7. with_variable
This function sets a variable for any expression code that will be provided as 3rd argument. This is only useful for complicated expressions, where the same calculated value needs to be used in different places.
Syntax |
with_variable(name, value, expression) |
Arguments |
|
Примери |
|
14.3.13. Geometry Functions
This group contains functions that operate on geometry objects (e.g. buffer, transform, $area).
14.3.13.1. angle_at_vertex
Returns the bisector angle (average angle) to the geometry for a specified vertex on a linestring geometry. Angles are in degrees clockwise from north.
Syntax |
angle_at_vertex(geometry, vertex) |
Arguments |
|
Примери |
|
14.3.13.2. $area
Returns the area of the current feature. The area calculated by this function respects both the current project’s ellipsoid setting and area unit settings. For example, if an ellipsoid has been set for the project then the calculated area will be ellipsoidal, and if no ellipsoid is set then the calculated area will be planimetric.
Syntax |
$area |
Примери |
|
14.3.13.3. area
Returns the area of a geometry polygon object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned area will match the units for the SRS. This differs from the calculations performed by the $area function, which will perform ellipsoidal calculations based on the project’s ellipsoid and area unit settings.
Syntax |
area(geometry) |
Arguments |
|
Примери |
|
14.3.13.4. azimuth
Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.
Syntax |
azimuth(point_a, point_b) |
Arguments |
|
Примери |
|
14.3.13.5. boundary
Returns the closure of the combinatorial boundary of the geometry (ie the topological boundary of the geometry). For instance, a polygon geometry will have a boundary consisting of the linestrings for each ring in the polygon. Some geometry types do not have a defined boundary, e.g., points or geometry collections, and will return NULL.
Syntax |
boundary(geometry) |
Arguments |
|
Примери |
|
Further reading: Boundary algorithm
14.3.13.6. bounds
Returns a geometry which represents the bounding box of an input geometry. Calculations are in the Spatial Reference System of this geometry.
Syntax |
bounds(geometry) |
Arguments |
|
Примери |
|
Further reading: Bounding boxes algorithm
14.3.13.7. bounds_height
Returns the height of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.
Syntax |
bounds_height(geometry) |
Arguments |
|
Примери |
|
14.3.13.8. bounds_width
Returns the width of the bounding box of a geometry. Calculations are in the Spatial Reference System of this geometry.
Syntax |
bounds_width(geometry) |
Arguments |
|
Примери |
|
14.3.13.9. buffer
Returns a geometry that represents all points whose distance from this geometry is less than or equal to distance. Calculations are in the Spatial Reference System of this geometry.
Syntax |
buffer(geometry, distance, [segments=8]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Buffer algorithm
14.3.13.10. buffer_by_m
Creates a buffer along a line geometry where the buffer diameter varies according to the m-values at the line vertices.
Syntax |
buffer_by_m(geometry, [segments=8]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Variable width buffer (by M value) algorithm
14.3.13.11. centroid
Returns the geometric center of a geometry.
Syntax |
centroid(geometry) |
Arguments |
|
Примери |
|
Further reading: Centroids algorithm
14.3.13.12. close_line
Returns a closed line string of the input line string by appending the first point to the end of the line, if it is not already closed. If the geometry is not a line string or multi line string then the result will be NULL.
Syntax |
close_line(geometry) |
Arguments |
|
Примери |
|
14.3.13.13. closest_point
Returns the point on geometry1 that is closest to geometry2.
Syntax |
closest_point(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.14. collect_geometries
Collects a set of geometries into a multi-part geometry object.
List of arguments variant
Geometry parts are specified as separate arguments to the function.
Syntax |
collect_geometries(geometry1, geometry2, …) |
Arguments |
|
Примери |
|
Array variant
Geometry parts are specified as an array of geometry parts.
Syntax |
collect_geometries(array) |
Arguments |
|
Примери |
|
Further reading: Collect geometries algorithm
14.3.13.15. combine
Returns the combination of two geometries.
Syntax |
combine(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.16. contains
Tests whether a geometry contains another. Returns true if and only if no points of geometry2 lie in the exterior of geometry1, and at least one point of the interior of geometry2 lies in the interior of geometry1.
Syntax |
contains(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_contains
14.3.13.17. convex_hull
Returns the convex hull of a geometry. It represents the minimum convex geometry that encloses all geometries within the set.
Syntax |
convex_hull(geometry) |
Arguments |
|
Примери |
|
Further reading: Convex hull algorithm
14.3.13.18. crosses
Tests whether a geometry crosses another. Returns true if the supplied geometries have some, but not all, interior points in common.
Syntax |
crosses(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_crosses
14.3.13.19. difference
Returns a geometry that represents that part of geometry1 that does not intersect with geometry2.
Syntax |
difference(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: Difference algorithm
14.3.13.20. disjoint
Tests whether geometries do not spatially intersect. Returns true if the geometries do not share any space together.
Syntax |
disjoint(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_disjoint
14.3.13.21. distance
Returns the minimum distance (based on spatial ref) between two geometries in projected units.
Syntax |
distance(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.22. distance_to_vertex
Returns the distance along the geometry to a specified vertex.
Syntax |
distance_to_vertex(geometry, vertex) |
Arguments |
|
Примери |
|
14.3.13.23. end_point
Returns the last node from a geometry.
Syntax |
end_point(geometry) |
Arguments |
|
Примери |
|
Further reading: Extract specific vertices algorithm
14.3.13.24. extend
Extends the start and end of a linestring geometry by a specified amount. Lines are extended using the bearing of the first and last segment in the line. For a multilinestring, all the parts are extended. Distances are in the Spatial Reference System of this geometry.
Syntax |
extend(geometry, start_distance, end_distance) |
Arguments |
|
Примери |
|
Further reading: Extend lines algorithm
14.3.13.25. exterior_ring
Returns a line string representing the exterior ring of a polygon geometry. If the geometry is not a polygon then the result will be NULL.
Syntax |
exterior_ring(geometry) |
Arguments |
|
Примери |
|
14.3.13.26. extrude
Returns an extruded version of the input (Multi-)Curve or (Multi-)Linestring geometry with an extension specified by x and y.
Syntax |
extrude(geometry, x, y) |
Arguments |
|
Примери |
|
14.3.13.27. flip_coordinates
Returns a copy of the geometry with the x and y coordinates swapped. Useful for repairing geometries which have had their latitude and longitude values reversed.
Syntax |
flip_coordinates(geometry) |
Arguments |
|
Примери |
|
Further reading: Swap X and Y coordinates algorithm
14.3.13.28. force_rhr
Forces a geometry to respect the Right-Hand-Rule, in which the area that is bounded by a polygon is to the right of the boundary. In particular, the exterior ring is oriented in a clockwise direction and the interior rings in a counter-clockwise direction.
Syntax |
force_rhr(geometry) |
Arguments |
|
Примери |
|
Further reading: Force right-hand-rule algorithm
14.3.13.29. geom_from_gml
Returns a geometry from a GML representation of geometry.
Syntax |
geom_from_gml(gml) |
Arguments |
|
Примери |
|
14.3.13.30. geom_from_wkb
Returns a geometry created from a Well-Known Binary (WKB) representation.
Syntax |
geom_from_wkb(binary) |
Arguments |
|
Примери |
|
14.3.13.31. geom_from_wkt
Returns a geometry created from a Well-Known Text (WKT) representation.
Syntax |
geom_from_wkt(text) |
Arguments |
|
Примери |
|
14.3.13.32. geom_to_wkb
Returns the Well-Known Binary (WKB) representation of a geometry
Syntax |
geom_to_wkb(geometry) |
Arguments |
|
Примери |
|
14.3.13.33. geom_to_wkt
Returns the Well-Known Text (WKT) representation of the geometry without SRID metadata.
Syntax |
geom_to_wkt(geometry, [precision=8]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.34. $geometry
Returns the geometry of the current feature. Can be used for processing with other functions.
Syntax |
$geometry |
Примери |
|
14.3.13.35. geometry
Returns a feature’s geometry.
Syntax |
geometry(feature) |
Arguments |
|
Примери |
|
14.3.13.36. geometry_n
Returns a specific geometry from a geometry collection, or NULL if the input geometry is not a collection.
Syntax |
geometry_n(geometry, index) |
Arguments |
|
Примери |
|
14.3.13.37. hausdorff_distance
Returns the Hausdorff distance between two geometries. This is basically a measure of how similar or dissimilar 2 geometries are, with a lower distance indicating more similar geometries.
The function can be executed with an optional densify fraction argument. If not specified, an approximation to the standard Hausdorff distance is used. This approximation is exact or close enough for a large subset of useful cases. Examples of these are:
computing distance between Linestrings that are roughly parallel to each other, and roughly equal in length. This occurs in matching linear networks.
Testing similarity of geometries.
If the default approximate provided by this method is insufficient, specify the optional densify fraction argument. Specifying this argument performs a segment densification before computing the discrete Hausdorff distance. The parameter sets the fraction by which to densify each segment. Each segment will be split into a number of equal-length subsegments, whose fraction of the total length is closest to the given fraction. Decreasing the densify fraction parameter will make the distance returned approach the true Hausdorff distance for the geometries.
Syntax |
hausdorff_distance(geometry1, geometry2, [densify_fraction]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.38. inclination
Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.
Syntax |
inclination(point_a, point_b) |
Arguments |
|
Примери |
|
14.3.13.39. interior_ring_n
Returns a specific interior ring from a polygon geometry, or NULL if the geometry is not a polygon.
Syntax |
interior_ring_n(geometry, index) |
Arguments |
|
Примери |
|
14.3.13.40. intersection
Returns a geometry that represents the shared portion of two geometries.
Syntax |
intersection(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: Intersection algorithm
14.3.13.41. intersects
Tests whether a geometry intersects another. Returns true if the geometries spatially intersect (share any portion of space) and false if they do not.
Syntax |
intersects(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_intersects
14.3.13.42. intersects_bbox
Tests whether a geometry’s bounding box overlaps another geometry’s bounding box. Returns true if the geometries spatially intersect the bounding box defined and false if they do not.
Syntax |
intersects_bbox(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.43. is_closed
Returns true if a line string is closed (start and end points are coincident), or false if a line string is not closed. If the geometry is not a line string then the result will be NULL.
Syntax |
is_closed(geometry) |
Arguments |
|
Примери |
|
14.3.13.44. is_empty
Returns true if a geometry is empty (without coordinates), false if the geometry is not empty and NULL if there is no geometry. See also is_empty_or_null.
Syntax |
is_empty(geometry) |
Arguments |
|
Примери |
|
14.3.13.45. is_empty_or_null
Returns true if a geometry is NULL or empty (without coordinates) or false otherwise. This function is like the expression ‚$geometry IS NULL or is_empty($geometry)‘
Syntax |
is_empty_or_null(geometry) |
Arguments |
|
Примери |
|
14.3.13.46. is_multipart
Returns true if the geometry is of Multi type.
Syntax |
is_multipart(geometry) |
Arguments |
|
Примери |
|
14.3.13.47. is_valid
Returns true if a geometry is valid; if it is well-formed in 2D according to the OGC rules.
Syntax |
is_valid(geometry) |
Arguments |
|
Примери |
|
14.3.13.48. $length
Returns the length of a linestring. If you need the length of a border of a polygon, use $perimeter instead. The length calculated by this function respects both the current project’s ellipsoid setting and distance unit settings. For example, if an ellipsoid has been set for the project then the calculated length will be ellipsoidal, and if no ellipsoid is set then the calculated length will be planimetric.
Syntax |
$length |
Примери |
|
14.3.13.49. length
Returns the number of characters in a string or the length of a geometry linestring.
String variant
Returns the number of characters in a string.
Syntax |
length(string) |
Arguments |
|
Примери |
|
Geometry variant
Calculate the length of a geometry line object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned length will match the units for the SRS. This differs from the calculations performed by the $length function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.
Syntax |
length(geometry) |
Arguments |
|
Примери |
|
14.3.13.50. line_interpolate_angle
Returns the angle parallel to the geometry at a specified distance along a linestring geometry. Angles are in degrees clockwise from north.
Syntax |
line_interpolate_angle(geometry, distance) |
Arguments |
|
Примери |
|
14.3.13.51. line_interpolate_point
Returns the point interpolated by a specified distance along a linestring geometry.
Syntax |
line_interpolate_point(geometry, distance) |
Arguments |
|
Примери |
|
Further reading: Interpolate point on line algorithm
14.3.13.52. line_locate_point
Returns the distance along a linestring corresponding to the closest position the linestring comes to a specified point geometry.
Syntax |
line_locate_point(geometry, point) |
Arguments |
|
Примери |
|
14.3.13.53. line_merge
Returns a LineString or MultiLineString geometry, where any connected LineStrings from the input geometry have been merged into a single linestring. This function will return NULL if passed a geometry which is not a LineString/MultiLineString.
Syntax |
line_merge(geometry) |
Arguments |
|
Примери |
|
14.3.13.54. line_substring
Returns the portion of a line (or curve) geometry which falls between the specified start and end distances (measured from the beginning of the line). Z and M values are linearly interpolated from existing values.
Syntax |
line_substring(geometry, start_distance, end_distance) |
Arguments |
|
Примери |
|
Further reading: Line substring algorithm
14.3.13.55. m
Returns the m value of a point geometry.
Syntax |
m(geometry) |
Arguments |
|
Примери |
|
14.3.13.56. m_max
Returns the maximum m (measure) value of a geometry.
Syntax |
m_max(geometry) |
Arguments |
|
Примери |
|
14.3.13.57. m_min
Returns the minimum m (measure) value of a geometry.
Syntax |
m_min(geometry) |
Arguments |
|
Примери |
|
14.3.13.58. main_angle
Returns the main angle of a geometry (clockwise, in degrees from North), which represents the angle of the oriented minimal bounding rectangle which completely covers the geometry.
Syntax |
main_angle(geometry) |
Arguments |
|
Примери |
|
14.3.13.59. make_circle
Creates a circular polygon.
Syntax |
make_circle(center, radius, [segments=36]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.60. make_ellipse
Creates an elliptical polygon.
Syntax |
make_ellipse(center, semi_major_axis, semi_minor_axis, azimuth, [segments=36]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.61. make_line
Creates a line geometry from a series of point geometries.
List of arguments variant
Line vertices are specified as separate arguments to the function.
Syntax |
make_line(point1, point2, …) |
Arguments |
|
Примери |
|
Array variant
Line vertices are specified as an array of points.
Syntax |
make_line(array) |
Arguments |
|
Примери |
|
14.3.13.62. make_point
Creates a point geometry from an x and y (and optional z and m) value.
Syntax |
make_point(x, y, [z], [m]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.63. make_point_m
Creates a point geometry from an x, y coordinate and m value.
Syntax |
make_point_m(x, y, m) |
Arguments |
|
Примери |
|
14.3.13.64. make_polygon
Creates a polygon geometry from an outer ring and optional series of inner ring geometries.
Syntax |
make_polygon(outerRing, [innerRing1], [innerRing2], …) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.65. make_rectangle_3points
Creates a rectangle from 3 points.
Syntax |
make_rectangle_3points(point1, point2, point3, [option=0]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.66. make_regular_polygon
Creates a regular polygon.
Syntax |
make_regular_polygon(center, radius, number_sides, [circle=0]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.67. make_square
Creates a square from a diagonal.
Syntax |
make_square(point1, point2) |
Arguments |
|
Примери |
|
14.3.13.68. make_triangle
Creates a triangle polygon.
Syntax |
make_triangle(point1, point2, point3) |
Arguments |
|
Примери |
|
14.3.13.69. minimal_circle
Returns the minimal enclosing circle of a geometry. It represents the minimum circle that encloses all geometries within the set.
Syntax |
minimal_circle(geometry, [segments=36]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Minimum enclosing circles algorithm
14.3.13.70. nodes_to_points
Returns a multipoint geometry consisting of every node in the input geometry.
Syntax |
nodes_to_points(geometry, [ignore_closing_nodes=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Extract vertices algorithm
14.3.13.71. num_geometries
Returns the number of geometries in a geometry collection, or NULL if the input geometry is not a collection.
Syntax |
num_geometries(geometry) |
Arguments |
|
Примери |
|
14.3.13.72. num_interior_rings
Returns the number of interior rings in a polygon or geometry collection, or NULL if the input geometry is not a polygon or collection.
Syntax |
num_interior_rings(geometry) |
Arguments |
|
Примери |
|
14.3.13.73. num_points
Returns the number of vertices in a geometry.
Syntax |
num_points(geometry) |
Arguments |
|
Примери |
|
14.3.13.74. num_rings
Returns the number of rings (including exterior rings) in a polygon or geometry collection, or NULL if the input geometry is not a polygon or collection.
Syntax |
num_rings(geometry) |
Arguments |
|
Примери |
|
14.3.13.75. offset_curve
Returns a geometry formed by offsetting a linestring geometry to the side. Distances are in the Spatial Reference System of this geometry.
Syntax |
offset_curve(geometry, distance, [segments=8], [join=1], [miter_limit=2.0]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Offset lines algorithm
14.3.13.76. order_parts
Orders the parts of a MultiGeometry by a given criteria
Syntax |
order_parts(geometry, orderby, ascending) |
Arguments |
|
Примери |
|
14.3.13.77. oriented_bbox
Returns a geometry which represents the minimal oriented bounding box of an input geometry.
Syntax |
oriented_bbox(geometry) |
Arguments |
|
Примери |
|
Further reading: Oriented minimum bounding box algorithm
14.3.13.78. overlaps
Tests whether a geometry overlaps another. Returns true if the geometries share space, are of the same dimension, but are not completely contained by each other.
Syntax |
overlaps(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.79. overlay_contains
Returns whether the current feature spatially contains at least one feature from a target layer, or an array of expression-based results for the features in the target layer contained in the current feature.
Read more on the underlying GEOS „Contains“ predicate, as described in PostGIS ST_Contains function.
Syntax |
overlay_contains(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: contains, array manipulation, Избиране според местоположение algorithm
14.3.13.80. overlay_crosses
Returns whether the current feature spatially crosses at least one feature from a target layer, or an array of expression-based results for the features in the target layer crossed by the current feature.
Read more on the underlying GEOS „Crosses“ predicate, as described in PostGIS ST_Crosses function.
Syntax |
overlay_crosses(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: crosses, array manipulation, Избиране според местоположение algorithm
14.3.13.81. overlay_disjoint
Returns whether the current feature is spatially disjoint from all the features of a target layer, or an array of expression-based results for the features in the target layer that are disjoint from the current feature.
Read more on the underlying GEOS „Disjoint“ predicate, as described in PostGIS ST_Disjoint function.
Syntax |
overlay_disjoint(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: disjoint, array manipulation, Избиране според местоположение algorithm
14.3.13.82. overlay_equals
Returns whether the current feature spatially equals to at least one feature from a target layer, or an array of expression-based results for the features in the target layer that are spatially equal to the current feature.
Read more on the underlying GEOS „Equals“ predicate, as described in PostGIS ST_Equals function.
Syntax |
overlay_equals(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: array manipulation, Избиране според местоположение algorithm
14.3.13.83. overlay_intersects
Returns whether the current feature spatially intersects at least one feature from a target layer, or an array of expression-based results for the features in the target layer intersected by the current feature.
Read more on the underlying GEOS „Intersects“ predicate, as described in PostGIS ST_Intersects function.
Syntax |
overlay_intersects(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: intersects, array manipulation, Избиране според местоположение algorithm
14.3.13.84. overlay_nearest
Returns whether the current feature has feature(s) from a target layer within a given distance, or an array of expression-based results for the features in the target layer within a distance from the current feature.
Note: This function can be slow and consume a lot of memory for large layers.
Syntax |
overlay_nearest(layer, [expression], [filter], [limit=1], [max_distance], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: array manipulation, Join attributes by nearest algorithm
14.3.13.85. overlay_touches
Returns whether the current feature spatially touches at least one feature from a target layer, or an array of expression-based results for the features in the target layer touched by the current feature.
Read more on the underlying GEOS „Touches“ predicate, as described in PostGIS ST_Touches function.
Syntax |
overlay_touches(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: touches, array manipulation, Избиране според местоположение algorithm
14.3.13.86. overlay_within
Returns whether the current feature is spatially within at least one feature from a target layer, or an array of expression-based results for the features in the target layer that contain the current feature.
Read more on the underlying GEOS „Within“ predicate, as described in PostGIS ST_Within function.
Syntax |
overlay_within(layer, [expression], [filter], [limit], [cache=false]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: within, array manipulation, Избиране според местоположение algorithm
14.3.13.87. $perimeter
Returns the perimeter length of the current feature. The perimeter calculated by this function respects both the current project’s ellipsoid setting and distance unit settings. For example, if an ellipsoid has been set for the project then the calculated perimeter will be ellipsoidal, and if no ellipsoid is set then the calculated perimeter will be planimetric.
Syntax |
$perimeter |
Примери |
|
14.3.13.88. perimeter
Returns the perimeter of a geometry polygon object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned perimeter will match the units for the SRS. This differs from the calculations performed by the $perimeter function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.
Syntax |
perimeter(geometry) |
Arguments |
|
Примери |
|
14.3.13.89. point_n
Returns a specific node from a geometry.
Syntax |
point_n(geometry, index) |
Arguments |
|
Примери |
|
Further reading: Extract specific vertices algorithm
14.3.13.90. point_on_surface
Returns a point guaranteed to lie on the surface of a geometry.
Syntax |
point_on_surface(geometry) |
Arguments |
|
Примери |
|
Further reading: Point on Surface algorithm
14.3.13.91. pole_of_inaccessibility
Calculates the approximate pole of inaccessibility for a surface, which is the most distant internal point from the boundary of the surface. This function uses the ‚polylabel‘ algorithm (Vladimir Agafonkin, 2016), which is an iterative approach guaranteed to find the true pole of inaccessibility within a specified tolerance. More precise tolerances require more iterations and will take longer to calculate.
Syntax |
pole_of_inaccessibility(geometry, tolerance) |
Arguments |
|
Примери |
|
Further reading: Pole of inaccessibility algorithm
14.3.13.92. project
Returns a point projected from a start point using a distance, a bearing (azimuth) and an elevation in radians.
Syntax |
project(point, distance, azimuth, [elevation]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Project points (Cartesian) algorithm
14.3.13.93. relate
Tests the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between two geometries.
Relationship variant
Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between two geometries.
Syntax |
relate(geometry, geometry) |
Arguments |
|
Примери |
|
Pattern match variant
Tests whether the DE-9IM relationship between two geometries matches a specified pattern.
Syntax |
relate(geometry, geometry, pattern) |
Arguments |
|
Примери |
|
14.3.13.94. reverse
Reverses the direction of a line string by reversing the order of its vertices.
Syntax |
reverse(geometry) |
Arguments |
|
Примери |
|
Further reading: Reverse line direction algorithm
14.3.13.95. rotate
Returns a rotated version of a geometry. Calculations are in the Spatial Reference System of this geometry.
Syntax |
rotate(geometry, rotation, [center]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.13.96. segments_to_lines
Returns a multi line geometry consisting of a line for every segment in the input geometry.
Syntax |
segments_to_lines(geometry) |
Arguments |
|
Примери |
|
Further reading: Explode lines algorithm
14.3.13.97. shortest_line
Returns the shortest line joining geometry1 to geometry2. The resultant line will start at geometry1 and end at geometry2.
Syntax |
shortest_line(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.98. simplify
Simplifies a geometry by removing nodes using a distance based threshold (ie, the Douglas Peucker algorithm). The algorithm preserves large deviations in geometries and reduces the number of vertices in nearly straight segments.
Syntax |
simplify(geometry, tolerance) |
Arguments |
|
Примери |
|
Further reading: Simplify algorithm
14.3.13.99. simplify_vw
Simplifies a geometry by removing nodes using an area based threshold (ie, the Visvalingam-Whyatt algorithm). The algorithm removes vertices which create small areas in geometries, e.g., narrow spikes or nearly straight segments.
Syntax |
simplify_vw(geometry, tolerance) |
Arguments |
|
Примери |
|
Further reading: Simplify algorithm
14.3.13.100. single_sided_buffer
Returns a geometry formed by buffering out just one side of a linestring geometry. Distances are in the Spatial Reference System of this geometry.
Syntax |
single_sided_buffer(geometry, distance, [segments=8], [join=1], [miter_limit=2.0]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Single sided buffer algorithm
14.3.13.101. smooth
Smooths a geometry by adding extra nodes which round off corners in the geometry. If input geometries contain Z or M values, these will also be smoothed and the output geometry will retain the same dimensionality as the input geometry.
Syntax |
smooth(geometry, [iterations=1], [offset=0.25], [min_length=-1], [max_angle=180]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Smooth algorithm
14.3.13.102. start_point
Returns the first node from a geometry.
Syntax |
start_point(geometry) |
Arguments |
|
Примери |
|
Further reading: Extract specific vertices algorithm
14.3.13.103. sym_difference
Returns a geometry that represents the portions of two geometries that do not intersect.
Syntax |
sym_difference(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: Symmetrical difference algorithm
14.3.13.104. tapered_buffer
Creates a buffer along a line geometry where the buffer diameter varies evenly over the length of the line.
Syntax |
tapered_buffer(geometry, start_width, end_width, [segments=8]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Tapered buffers algorithm
14.3.13.105. touches
Tests whether a geometry touches another. Returns true if the geometries have at least one point in common, but their interiors do not intersect.
Syntax |
touches(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_touches
14.3.13.106. transform
Returns the geometry transformed from a source CRS to a destination CRS.
Syntax |
transform(geometry, source_auth_id, dest_auth_id) |
Arguments |
|
Примери |
|
Further reading: Reproject layer algorithm
14.3.13.107. translate
Returns a translated version of a geometry. Calculations are in the Spatial Reference System of this geometry.
Syntax |
translate(geometry, dx, dy) |
Arguments |
|
Примери |
|
Further reading: Translate algorithm
14.3.13.108. union
Returns a geometry that represents the point set union of the geometries.
Syntax |
union(geometry1, geometry2) |
Arguments |
|
Примери |
|
14.3.13.109. wedge_buffer
Returns a wedge shaped buffer originating from a point geometry.
Syntax |
wedge_buffer(center, azimuth, width, outer_radius, [inner_radius=0.0]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Create wedge buffers algorithm
14.3.13.110. within
Tests whether a geometry is within another. Returns true if the geometry1 is completely within geometry2.
Syntax |
within(geometry1, geometry2) |
Arguments |
|
Примери |
|
Further reading: overlay_within
14.3.13.111. $x
Returns the x coordinate of the current point feature. If the feature is a multipoint feature, then the x-coordinate of the first point will be returned.
Syntax |
$x |
Примери |
|
14.3.13.112. x
Returns the x coordinate of a point geometry, or the x coordinate of the centroid for a non-point geometry.
Syntax |
x(geometry) |
Arguments |
|
Примери |
|
14.3.13.113. $x_at
Retrieves a x coordinate of the current feature’s geometry.
Syntax |
$x_at(i) |
Arguments |
|
Примери |
|
14.3.13.114. x_max
Returns the maximum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax |
x_max(geometry) |
Arguments |
|
Примери |
|
14.3.13.115. x_min
Returns the minimum x coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax |
x_min(geometry) |
Arguments |
|
Примери |
|
14.3.13.116. $y
Returns the y coordinate of the current point feature. If the feature is a multipoint feature, then the y-coordinate of the first point will be returned.
Syntax |
$y |
Примери |
|
14.3.13.117. y
Returns the y coordinate of a point geometry, or the y coordinate of the centroid for a non-point geometry.
Syntax |
y(geometry) |
Arguments |
|
Примери |
|
14.3.13.118. $y_at
Retrieves a y coordinate of the current feature’s geometry.
Syntax |
$y_at(i) |
Arguments |
|
Примери |
|
14.3.13.119. y_max
Returns the maximum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax |
y_max(geometry) |
Arguments |
|
Примери |
|
14.3.13.120. y_min
Returns the minimum y coordinate of a geometry. Calculations are in the spatial reference system of this geometry.
Syntax |
y_min(geometry) |
Arguments |
|
Примери |
|
14.3.13.121. z
Returns the z coordinate of a point geometry, or NULL if the geometry has no z value.
Syntax |
z(geometry) |
Arguments |
|
Примери |
|
14.3.13.122. z_max
Returns the maximum z coordinate of a geometry, or NULL if the geometry has no z value.
Syntax |
z_max(geometry) |
Arguments |
|
Примери |
|
14.3.13.123. z_min
Returns the minimum z coordinate of a geometry, or NULL if the geometry has no z value.
Syntax |
z_min(geometry) |
Arguments |
|
Примери |
|
14.3.14. Layout Functions
This group contains functions to manipulate print layout items properties.
14.3.14.1. item_variables
Returns a map of variables from a layout item inside this print layout.
Syntax |
item_variables(id) |
Arguments |
|
Примери |
|
Further reading: List of default variables
14.3.15. Map Layers
This group contains a list of the available layers in the current project. This offers a convenient way to write expressions referring to multiple layers, such as when performing aggregates, attribute or spatial queries.
It also provides some convenient functions to manipulate layers.
14.3.15.1. decode_uri
Takes a layer and decodes the uri of the underlying data provider. It depends on the dataprovider, which data is available.
Syntax |
decode_uri(layer, [part]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.16. Maps Functions
This group contains functions to create or manipulate keys and values of map data structures (also known as dictionary objects, key-value pairs, or associative arrays). Unlike the list data structure where values order matters, the order of the key-value pairs in the map object is not relevant and values are identified by their keys.
14.3.16.1. from_json
Loads a JSON formatted string.
Syntax |
from_json(string) |
Arguments |
|
Примери |
|
14.3.16.2. hstore_to_map
Creates a map from a hstore-formatted string.
Syntax |
hstore_to_map(string) |
Arguments |
|
Примери |
|
14.3.16.3. json_to_map
Creates a map from a json-formatted string.
Syntax |
json_to_map(string) |
Arguments |
|
Примери |
|
14.3.16.4. map
Returns a map containing all the keys and values passed as pair of parameters.
Syntax |
map(key1, value1, key2, value2, …) |
Arguments |
|
Примери |
|
14.3.16.5. map_akeys
Returns all the keys of a map as an array.
Syntax |
map_akeys(map) |
Arguments |
|
Примери |
|
14.3.16.6. map_avals
Returns all the values of a map as an array.
Syntax |
map_avals(map) |
Arguments |
|
Примери |
|
14.3.16.7. map_concat
Returns a map containing all the entries of the given maps. If two maps contain the same key, the value of the second map is taken.
Syntax |
map_concat(map1, map2, …) |
Arguments |
|
Примери |
|
14.3.16.8. map_delete
Returns a map with the given key and its corresponding value deleted.
Syntax |
map_delete(map, key) |
Arguments |
|
Примери |
|
14.3.16.9. map_exist
Returns true if the given key exists in the map.
Syntax |
map_exist(map, key) |
Arguments |
|
Примери |
|
14.3.16.10. map_get
Returns the value of a map, given its key. Returns NULL if the key does not exist.
Syntax |
map_get(map, key) |
Arguments |
|
Примери |
|
14.3.16.11. map_insert
Returns a map with an added key/value. If the key already exists, its value is overridden.
Syntax |
map_insert(map, key, value) |
Arguments |
|
Примери |
|
14.3.16.12. map_to_hstore
Merge map elements into a hstore-formatted string.
Syntax |
map_to_hstore(map) |
Arguments |
|
Примери |
|
14.3.16.13. map_to_json
Merge map elements into a json-formatted string.
Syntax |
map_to_json(map) |
Arguments |
|
Примери |
|
14.3.16.14. to_json
Create a JSON formatted string from a map, array or other value.
Syntax |
to_json(value) |
Arguments |
|
Примери |
|
14.3.17. Mathematical Functions
This group contains math functions (e.g., square root, sin and cos).
14.3.17.1. abs
Returns the absolute value of a number.
Syntax |
abs(value) |
Arguments |
|
Примери |
|
14.3.17.2. acos
Returns the inverse cosine of a value in radians.
Syntax |
acos(value) |
Arguments |
|
Примери |
|
14.3.17.3. asin
Returns the inverse sine of a value in radians.
Syntax |
asin(value) |
Arguments |
|
Примери |
|
14.3.17.4. atan
Returns the inverse tangent of a value in radians.
Syntax |
atan(value) |
Arguments |
|
Примери |
|
14.3.17.5. atan2
Returns the inverse tangent of dy/dx by using the signs of the two arguments to determine the quadrant of the result.
Syntax |
atan2(dy, dx) |
Arguments |
|
Примери |
|
14.3.17.6. azimuth
Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on point_a to point_b.
Syntax |
azimuth(point_a, point_b) |
Arguments |
|
Примери |
|
14.3.17.7. ceil
Rounds a number upwards.
Syntax |
ceil(value) |
Arguments |
|
Примери |
|
14.3.17.8. clamp
Restricts an input value to a specified range.
Syntax |
clamp(minimum, input, maximum) |
Arguments |
|
Примери |
|
14.3.17.9. cos
Returns cosine of an angle.
Syntax |
cos(angle) |
Arguments |
|
Примери |
|
14.3.17.10. degrees
Converts from radians to degrees.
Syntax |
degrees(radians) |
Arguments |
|
Примери |
|
14.3.17.11. exp
Returns exponential of an value.
Syntax |
exp(value) |
Arguments |
|
Примери |
|
14.3.17.12. floor
Rounds a number downwards.
Syntax |
floor(value) |
Arguments |
|
Примери |
|
14.3.17.13. inclination
Returns the inclination measured from the zenith (0) to the nadir (180) on point_a to point_b.
Syntax |
inclination(point_a, point_b) |
Arguments |
|
Примери |
|
14.3.17.14. ln
Returns the natural logarithm of a value.
Syntax |
ln(value) |
Arguments |
|
Примери |
|
14.3.17.15. log
Returns the value of the logarithm of the passed value and base.
Syntax |
log(base, value) |
Arguments |
|
Примери |
|
14.3.17.16. log10
Returns the value of the base 10 logarithm of the passed expression.
Syntax |
log10(value) |
Arguments |
|
Примери |
|
14.3.17.17. max
Returns the largest value in a set of values.
Syntax |
max(value1, value2, …) |
Arguments |
|
Примери |
|
14.3.17.18. min
Returns the smallest value in a set of values.
Syntax |
min(value1, value2, …) |
Arguments |
|
Примери |
|
14.3.17.19. pi
Returns value of pi for calculations.
Syntax |
pi() |
Примери |
|
14.3.17.20. radians
Converts from degrees to radians.
Syntax |
radians(degrees) |
Arguments |
|
Примери |
|
14.3.17.21. rand
Returns a random integer within the range specified by the minimum and maximum argument (inclusive). If a seed is provided, the returned will always be the same, depending on the seed.
Syntax |
rand(min, max, [seed=NULL]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.17.22. randf
Returns a random float within the range specified by the minimum and maximum argument (inclusive). If a seed is provided, the returned will always be the same, depending on the seed.
Syntax |
randf([min=0.0], [max=1.0], [seed=NULL]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.17.23. round
Rounds a number to number of decimal places.
Syntax |
round(value, [places=0]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.17.24. scale_exp
Transforms a given value from an input domain to an output range using an exponential curve. This function can be used to ease values in or out of the specified output range.
Syntax |
scale_exp(value, domain_min, domain_max, range_min, range_max, exponent) |
Arguments |
|
Примери |
|
14.3.17.25. scale_linear
Transforms a given value from an input domain to an output range using linear interpolation.
Syntax |
scale_linear(value, domain_min, domain_max, range_min, range_max) |
Arguments |
|
Примери |
|
14.3.17.26. sin
Returns the sine of an angle.
Syntax |
sin(angle) |
Arguments |
|
Примери |
|
14.3.17.27. sqrt
Returns square root of a value.
Syntax |
sqrt(value) |
Arguments |
|
Примери |
|
14.3.17.28. tan
Returns the tangent of an angle.
Syntax |
tan(angle) |
Arguments |
|
Примери |
|
14.3.18. Operators
This group contains operators (e.g., +, -, *). Note that for most of the mathematical functions below, if one of the inputs is NULL then the result is NULL.
Function |
Описание |
---|---|
a + b |
Addition of two values (a plus b) |
a - b |
Subtraction of two values (a minus b). |
a * b |
Multiplication of two values (a multiplied by b) |
a / b |
Division of two values (a divided by b) |
a % b |
Remainder of division of a by b (eg, 7 % 2 = 1, or 2 fits into 7 three times with remainder 1) |
a ^ b |
Power of two values (for example, 2^2=4 or 2^3=8) |
a < b |
Compares two values and evaluates to 1 if the left value is less than the right value (a is smaller than b) |
a <= b |
Compares two values and evaluates to 1 if the left value is less than or equal to the right value |
a <> b |
Compares two values and evaluates to 1 if they are not equal |
a = b |
Compares two values and evaluates to 1 if they are equal |
a != b |
a and b are not equal |
a > b |
Compares two values and evaluates to 1 if the left value is greater than the right value (a is larger than b) |
a >= b |
Compares two values and evaluates to 1 if the left value is greater than or equal to the right value |
a ~ b |
a matches the regular expression b |
|| |
Joins two values together into a string. If one of the values is NULL the result will be NULL |
‚\n‘ |
Inserts a new line in a string |
LIKE |
Returns 1 if the first parameter matches the supplied pattern |
ILIKE |
Returns 1 if the first parameter matches case-insensitive the supplied pattern (ILIKE can be used instead of LIKE to make the match case-insensitive) |
a IS b |
Tests whether two values are identical. Returns 1 if a is the same as b |
a OR b |
Returns 1 when condition a or condition b is true |
a AND b |
Returns 1 when conditions a and b are true |
NOT |
Negates a condition |
„Column_name“ |
Value of the field Column_name, take care to not be confused with simple quote, see below |
‚string‘ |
a string value, take care to not be confused with double quote, see above |
NULL |
null value |
a IS NULL |
a has no value |
a IS NOT NULL |
a has a value |
a IN (value[,value]) |
a is below the values listed |
a NOT IN (value[,value]) |
a is not below the values listed |
Some examples:
Joins a string and a value from a column name:
'My feature''s id is: ' || "gid"
Test if the „description“ attribute field starts with the ‚Hello‘ string in the value (note the position of the
%
character):"description" LIKE 'Hello%'
14.3.19. Processing Functions
This group contains functions that operate on processing algorithms.
14.3.19.1. parameter
Returns the value of a processing algorithm input parameter.
Syntax |
parameter(name) |
Arguments |
|
Примери |
|
14.3.20. Rasters Functions
This group contains functions to operate on raster layer.
14.3.20.1. raster_statistic
Returns statistics from a raster layer.
Syntax |
raster_statistic(layer, band, property) |
Arguments |
|
Примери |
|
14.3.20.2. raster_value
Returns the raster value found at the provided point.
Syntax |
raster_value(layer, band, point) |
Arguments |
|
Примери |
|
14.3.21. Record and Attributes Functions
This group contains functions that operate on record identifiers.
14.3.21.1. attribute
Returns an attribute from a feature.
Variant 1
Returns the value of an attribute from the current feature.
Syntax |
attribute(attribute_name) |
Arguments |
|
Примери |
|
Variant 2
Allows the target feature and attribute name to be specified.
Syntax |
attribute(feature, attribute_name) |
Arguments |
|
Примери |
|
14.3.21.2. attributes
Returns a map containing all attributes from a feature, with field names as map keys.
Variant 1
Returns a map of all attributes from the current feature.
Syntax |
attributes() |
Примери |
|
Variant 2
Allows the target feature to be specified.
Syntax |
attributes(feature) |
Arguments |
|
Примери |
|
Further reading: Maps Functions
14.3.21.3. $currentfeature
Returns the current feature being evaluated. This can be used with the ‚attribute‘ function to evaluate attribute values from the current feature.
Syntax |
$currentfeature |
Примери |
|
14.3.21.4. display_expression
Returns the display expression for a given feature in a layer. The expression is evaluated by default. Can be used with zero, one or more arguments, see below for details.
No parameters
If called with no parameters, the function will evaluate the display expression of the current feature in the current layer.
Syntax |
display_expression() |
Примери |
|
One ‚feature‘ parameter
If called with a ‚feature‘ parameter only, the function will evaluate the specified feature from the current layer.
Syntax |
display_expression(feature) |
Arguments |
|
Примери |
|
Layer and feature parameters
If the function is called with both a layer and a feature, it will evaluate the specified feature from the specified layer.
Syntax |
display_expression(layer, feature, [evaluate=true]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.21.5. get_feature
Returns the first feature of a layer matching a given attribute value.
Syntax |
get_feature(layer, attribute, value) |
Arguments |
|
Примери |
|
14.3.21.6. get_feature_by_id
Returns the feature with an id on a layer.
Syntax |
get_feature_by_id(layer, feature_id) |
Arguments |
|
Примери |
|
Further reading: $id
14.3.21.7. $id
Returns the feature id of the current row.
Syntax |
$id |
Примери |
|
14.3.21.8. is_selected
Returns True if a feature is selected. Can be used with zero, one or two arguments, see below for details.
No parameters
If called with no parameters, the function will return true if the current feature in the current layer is selected.
Syntax |
is_selected() |
Примери |
|
One ‚feature‘ parameter
If called with a ‚feature‘ parameter only, the function returns true if the specified feature from the current layer is selected.
Syntax |
is_selected(feature) |
Arguments |
|
Примери |
|
Two parameters
If the function is called with both a layer and a feature, it will return true if the specified feature from the specified layer is selected.
Syntax |
is_selected(layer, feature) |
Arguments |
|
Примери |
|
14.3.21.9. maptip
Returns the maptip for a given feature in a layer. The expression is evaluated by default. Can be used with zero, one or more arguments, see below for details.
No parameters
If called with no parameters, the function will evaluate the maptip of the current feature in the current layer.
Syntax |
maptip() |
Примери |
|
One ‚feature‘ parameter
If called with a ‚feature‘ parameter only, the function will evaluate the specified feature from the current layer.
Syntax |
maptip(feature) |
Arguments |
|
Примери |
|
Layer and feature parameters
If the function is called with both a layer and a feature, it will evaluate the specified feature from the specified layer.
Syntax |
maptip(layer, feature, [evaluate=true]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.21.10. num_selected
Returns the number of selected features on a given layer. By default works on the layer on which the expression is evaluated.
Syntax |
num_selected([layer=current layer]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.21.11. represent_value
Returns the configured representation value for a field value. It depends on the configured widget type. Often, this is useful for ‚Value Map‘ widgets.
Syntax |
represent_value(value, fieldName) |
Arguments |
|
Примери |
|
Further reading: widget types
14.3.21.12. sqlite_fetch_and_increment
Manage autoincrementing values in sqlite databases.
SQlite default values can only be applied on insert and not prefetched.
This makes it impossible to acquire an incremented primary key via AUTO_INCREMENT before creating the row in the database. Sidenote: with postgres, this works via the option evaluate default values.
When adding new features with relations, it is really nice to be able to already add children for a parent, while the parents form is still open and hence the parent feature uncommitted.
To get around this limitation, this function can be used to manage sequence values in a separate table on sqlite based formats like gpkg.
The sequence table will be filtered for a sequence id (filter_attribute and filter_value) and the current value of the id_field will be incremented by 1 and the incremented value returned.
If additional columns require values to be specified, the default_values map can be used for this purpose.
Note
This function modifies the target sqlite table. It is intended for usage with default value configurations for attributes.
When the database parameter is a layer and the layer is in transaction mode, the value will only be retrieved once during the lifetime of a transaction and cached and incremented. This makes it unsafe to work on the same database from several processes in parallel.
Syntax |
sqlite_fetch_and_increment(database, table, id_field, filter_attribute, filter_value, [default_values]) [] marks optional arguments |
Arguments |
|
Примери |
|
Further reading: Data Sources Properties, Creating one or many to many relations
14.3.21.13. uuid
Generates a Universally Unique Identifier (UUID) for each row using the Qt QUuid::createUuid method. Each UUID is 38 characters long.
Syntax |
uuid() |
Примери |
|
14.3.22. Relations
This group contains the list of the relations available in the current project, with their description. It provides a quick access to the relation ID for writing an expression (with e.g. the relation_aggregate function) or customizing a form.
14.3.23. String Functions
This group contains functions that operate on strings (e.g., that replace, convert to upper case).
14.3.23.1. ascii
Returns the unicode code associated with the first character of a string.
Syntax |
ascii(string) |
Arguments |
|
Примери |
|
14.3.23.2. char
Returns the character associated with a unicode code.
Syntax |
char(code) |
Arguments |
|
Примери |
|
14.3.23.3. concat
Concatenates several strings to one. NULL values are converted to empty strings. Other values (like numbers) are converted to strings.
Syntax |
concat(string1, string2, …) |
Arguments |
|
Примери |
|
About fields concatenation
You can also concatenate strings or field values using either ||
or +
operators, with some special characteristics:
The
+
operator also means sum up expression, so if you have an integer (field or numeric value) operand, this can be error prone and you better use the others:'My feature id is: ' + "gid" => triggers an error as gid returns an integer
When any of the arguments is a NULL value, either
||
or+
will return a NULL value. To return the other arguments regardless the NULL value, you may want to use theconcat
function:'My feature id is: ' + NULL ==> NULL 'My feature id is: ' || NULL => NULL concat('My feature id is: ', NULL) => 'My feature id is: '
14.3.23.4. format
Format a string using supplied arguments.
Syntax |
format(string, arg1, arg2, …) |
Arguments |
|
Примери |
|
14.3.23.5. format_date
Formats a date type or string into a custom string format. Uses Qt date/time format strings. See QDateTime::toString.
Syntax |
format_date(datetime, format, [language]) [] marks optional arguments |
||||||||||||||||||||||||||||||||||||||||||||||||
Arguments |
|
||||||||||||||||||||||||||||||||||||||||||||||||
Примери |
|
14.3.23.6. format_number
Returns a number formatted with the locale separator for thousands. Also truncates the decimal places to the number of supplied places.
Syntax |
format_number(number, places, [language]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.23.7. left
Returns a substring that contains the n leftmost characters of the string.
Syntax |
left(string, length) |
Arguments |
|
Примери |
|
14.3.23.8. length
Returns the number of characters in a string or the length of a geometry linestring.
String variant
Returns the number of characters in a string.
Syntax |
length(string) |
Arguments |
|
Примери |
|
Geometry variant
Calculate the length of a geometry line object. Calculations are always planimetric in the Spatial Reference System (SRS) of this geometry, and the units of the returned length will match the units for the SRS. This differs from the calculations performed by the $length function, which will perform ellipsoidal calculations based on the project’s ellipsoid and distance unit settings.
Syntax |
length(geometry) |
Arguments |
|
Примери |
|
14.3.23.9. lower
Converts a string to lower case letters.
Syntax |
lower(string) |
Arguments |
|
Примери |
|
14.3.23.10. lpad
Returns a string padded on the left to the specified width, using a fill character. If the target width is smaller than the string’s length, the string is truncated.
Syntax |
lpad(string, width, fill) |
Arguments |
|
Примери |
|
14.3.23.11. regexp_match
Return the first matching position matching a regular expression within an unicode string, or 0 if the substring is not found.
Syntax |
regexp_match(input_string, regex) |
Arguments |
|
Примери |
|
14.3.23.12. regexp_replace
Returns a string with the supplied regular expression replaced.
Syntax |
regexp_replace(input_string, regex, replacement) |
Arguments |
|
Примери |
|
14.3.23.13. regexp_substr
Returns the portion of a string which matches a supplied regular expression.
Syntax |
regexp_substr(input_string, regex) |
Arguments |
|
Примери |
|
14.3.23.14. replace
Returns a string with the supplied string, array, or map of strings replaced.
String & array variant
Returns a string with the supplied string or array of strings replaced by a string or an array of strings.
Syntax |
replace(string, before, after) |
Arguments |
|
Примери |
|
Map variant
Returns a string with the supplied map keys replaced by paired values.
Syntax |
replace(string, map) |
Arguments |
|
Примери |
|
14.3.23.15. right
Returns a substring that contains the n rightmost characters of the string.
Syntax |
right(string, length) |
Arguments |
|
Примери |
|
14.3.23.16. rpad
Returns a string padded on the right to the specified width, using a fill character. If the target width is smaller than the string’s length, the string is truncated.
Syntax |
rpad(string, width, fill) |
Arguments |
|
Примери |
|
14.3.23.17. strpos
Return the first matching position of a substring within another string, or 0 if the substring is not found.
Syntax |
strpos(haystack, needle) |
Arguments |
|
Примери |
|
14.3.23.18. substr
Returns a part of a string.
Syntax |
substr(string, start, [length]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.23.19. title
Converts all words of a string to title case (all words lower case with leading capital letter).
Syntax |
title(string) |
Arguments |
|
Примери |
|
14.3.23.20. to_string
Converts a number to string.
Syntax |
to_string(number) |
Arguments |
|
Примери |
|
14.3.23.21. trim
Removes all leading and trailing whitespace (spaces, tabs, etc) from a string.
Syntax |
trim(string) |
Arguments |
|
Примери |
|
14.3.23.22. upper
Converts a string to upper case letters.
Syntax |
upper(string) |
Arguments |
|
Примери |
|
14.3.23.23. wordwrap
Returns a string wrapped to a maximum/minimum number of characters.
Syntax |
wordwrap(string, wrap_length, [delimiter_string]) [] marks optional arguments |
Arguments |
|
Примери |
|
14.3.24. User Expressions
This group contains the expressions saved as user expressions.
14.3.25. Variables
This group contains dynamic variables related to the application, the project file and other settings. The availability of variables depends on the context:
from the layer properties dialog
from the print layout
To use these variables in an expression, they should be preceded by the
@
character (e.g, @row_number
).
Variable |
Описание |
---|---|
algorithm_id |
The unique ID of an algorithm |
animation_end_time |
End of the animation’s overall temporal time range (as a datetime value) |
animation_interval |
Duration of the animation’s overall temporal time range (as an interval value) |
animation_start_time |
Start of the animation’s overall temporal time range (as a datetime value) |
atlas_feature |
The current atlas feature (as feature object) |
atlas_featureid |
The current atlas feature ID |
atlas_featurenumber |
The current atlas feature number in the layout |
atlas_filename |
The current atlas file name |
atlas_geometry |
The current atlas feature geometry |
atlas_layerid |
The current atlas coverage layer ID |
atlas_layername |
The current atlas coverage layer name |
atlas_pagename |
The current atlas page name |
atlas_totalfeatures |
The total number of features in atlas |
canvas_cursor_point |
The last cursor position on the canvas in the project’s geographical coordinates |
cluster_color |
The color of symbols within a cluster, or NULL if symbols have mixed colors |
cluster_size |
The number of symbols contained within a cluster |
current_feature |
The feature currently being edited in the attribute form or table row |
current_geometry |
The geometry of the feature currently being edited in the form or the table row |
current_parent_feature |
represents the feature currently being edited in the parent form. Only usable in an embedded form context. |
current_parent_geometry |
represents the geometry of the feature currently being edited in the parent form. Only usable in an embedded form context. |
form_mode |
What the form is used for, like AddFeatureMode, SingleEditMode, MultiEditMode, SearchMode, AggregateSearchMode or IdentifyMode as string. |
frame_duration |
Temporal duration of each animation frame (as an interval value) |
frame_number |
Current frame number during animation playback |
frame_rate |
Number of frames per second during animation playback |
fullextent_maxx |
Maximum x value from full canvas extent (including all layers) |
fullextent_maxy |
Maximum y value from full canvas extent (including all layers) |
fullextent_minx |
Minimum x value from full canvas extent (including all layers) |
fullextent_miny |
Minimum y value from full canvas extent (including all layers) |
geometry_part_count |
The number of parts in rendered feature’s geometry |
geometry_part_num |
The current geometry part number for feature being rendered |
geometry_point_count |
The number of points in the rendered geometry’s part |
geometry_point_num |
The current point number in the rendered geometry’s part |
grid_axis |
The current grid annotation axis (eg, ‚x‘ for longitude, ‚y‘ for latitude) |
grid_number |
The current grid annotation value |
item_id |
The layout item user ID (not necessarily unique) |
item_uuid |
The layout item unique ID |
layer |
The current layer |
layer_id |
The ID of current layer |
layer_ids |
The IDs of all the map layers in the current project as a list |
layer_name |
The name of current layer |
layers |
All the map layers in the current project as a list |
layout_dpi |
The composition resolution (DPI) |
layout_name |
The layout name |
layout_numpages |
The number of pages in the layout |
layout_page |
The page number of the current item in the layout |
layout_pageheight |
The active page height in the layout (in mm) |
layout_pagewidth |
The active page width in the layout (in mm) |
legend_column_count |
The number of columns in the legend |
legend_filter_by_map |
Indicates if the content of the legend is filtered by the map |
legend_filter_out_atlas |
Indicates if the atlas is filtered out of the legend |
legend_split_layers |
Indicates if layers can be split in the legend |
legend_title |
The title of the legend |
legend_wrap_string |
The character(s) used to wrap the legend text |
map_crs |
The Coordinate reference system of the current map |
map_crs_acronym |
The acronym of the Coordinate reference system of the current map |
map_crs_definition |
The full definition of the Coordinate reference system of the current map |
map_crs_description |
The name of the Coordinate reference system of the current map |
map_crs_ellipsoid |
The acronym of the ellipsoid of the Coordinate reference system of the current map |
map_crs_proj4 |
The Proj4 definition of the Coordinate reference system of the current map |
map_crs_wkt |
The WKT definition of the Coordinate reference system of the current map |
map_end_time |
The end of the map’s temporal time range (as a datetime value) |
map_extent |
The geometry representing the current extent of the map |
map_extent_center |
The point feature at the center of the map |
map_extent_height |
The current height of the map |
map_extent_width |
The current width of the map |
map_id |
The ID of current map destination. This will be ‚canvas‘ for canvas renders, and the item ID for layout map renders |
map_interval |
The duration of the map’s temporal time range (as an interval value) |
map_layer_ids |
The list of map layer IDs visible in the map |
map_layers |
The list of map layers visible in the map |
map_rotation |
The current rotation of the map |
map_scale |
The current scale of the map |
map_start_time |
The start of the map’s temporal time range (as a datetime value) |
map_units |
The units of map measurements |
model_path |
Full path (including file name) of current model (or project path if model is embedded in a project). |
model_folder |
Folder containing current model (or project folder if model is embedded in a project). |
model_name |
Name of current model |
model_group |
Group for current model |
notification_message |
Content of the notification message sent by the provider (available only for actions triggered by provider notifications). |
parent |
Refers to the current feature in the parent layer, providing access to its attributes and geometry when filtering an aggregate function |
project_abstract |
The project abstract, taken from project metadata |
project_area_units |
The area unit for the current project, used when calculating areas of geometries |
project_author |
The project author, taken from project metadata |
project_basename |
The basename of current project’s filename (without path and extension) |
project_creation_date |
The project creation date, taken from project metadata |
project_crs |
The Coordinate reference system of the project |
project_crs_arconym |
The acronym of the Coordinate reference system of the project |
project_crs_definition |
The full definition of the Coordinate reference system of the project |
project_crs_description |
The description of the Coordinate reference system of the project |
project_crs_ellipsoid |
The ellipsoid of the Coordinate reference system of the project |
project_crs_proj4 |
The Proj4 representation of the Coordinate reference system of the project |
project_crs_wkt |
The WKT (well known text) representation of the coordinate reference system of the project |
project_distance_units |
The distance unit for the current project, used when calculating lengths of geometries and distances |
project_ellipsoid |
The name of the ellipsoid of the current project, used when calculating geodetic areas or lengths of geometries |
project_filename |
The filename of the current project |
project_folder |
The folder of the current project |
project_home |
The home path of the current project |
project_identifier |
The project identifier, taken from the project’s metadata |
project_keywords |
The project keywords, taken from the project’s metadata |
project_last_saved |
Date/time when project was last saved. |
project_path |
The full path (including file name) of the current project |
project_title |
The title of current project |
project_units |
The units of the project’s CRS |
qgis_locale |
The current language of QGIS |
qgis_os_name |
The current Operating system name, eg ‚windows‘, ‚linux‘ or ‚osx‘ |
qgis_platform |
The QGIS platform, eg ‚desktop‘ or ‚server‘ |
qgis_release_name |
The current QGIS release name |
qgis_short_version |
The current QGIS version short string |
qgis_version |
The current QGIS version string |
qgis_version_no |
The current QGIS version number |
row_number |
Stores the number of the current row |
snapping_results |
Gives access to snapping results while digitizing a feature (only available in add feature) |
scale_value |
The current scale bar distance value |
symbol_angle |
The angle of the symbol used to render the feature (valid for marker symbols only) |
symbol_color |
The color of the symbol used to render the feature |
symbol_count |
The number of features represented by the symbol (in the layout legend) |
symbol_id |
The Internal ID of the symbol (in the layout legend) |
symbol_label |
The label for the symbol (either a user defined label or the default autogenerated label - in the layout legend) |
symbol_layer_count |
Total number of symbol layers in the symbol |
symbol_layer_index |
Current symbol layer index |
symbol_marker_column |
Column number for marker (valid for point pattern fills only). |
symbol_marker_row |
Row number for marker (valid for point pattern fills only). |
user_account_name |
The current user’s operating system account name |
user_full_name |
The current user’s operating system user name |
value |
The current value |
with_variable |
Allows setting a variable for usage within an expression and avoid recalculating the same value repeatedly |
zoom_level |
Zoom level of the tile that is being rendered (derived from the current map scale). Normally in interval [0, 20]. |
Some examples:
Return the X coordinate of a map item center in layout:
x( map_get( item_variables( 'map1'), 'map_extent_center' ) )
Return, for each feature in the current layer, the number of overlapping airport features:
aggregate( layer:='airport', aggregate:='count', expression:="code", filter:=intersects( $geometry, geometry( @parent ) ) )
Get the object_id of the first snapped point of a line:
with_variable( 'first_snapped_point', array_first( @snapping_results ), attribute( get_feature_by_id( map_get( @first_snapped_point, 'layer' ), map_get( @first_snapped_point, 'feature_id' ) ), 'object_id' ) )
14.3.26. Recent Functions
This group contains recently used functions. Depending on the context of its usage (feature selection, field calculator, generic), recently applied expressions are added to the corresponding list (up to ten expressions), sorted from more to less recent. This makes it easy to quickly retrieve and reapply previously used expressions.