표현식

Based on layer data and prebuilt or user defined functions, Expressions offer a powerful way to manipulate attribute value, geometry and variables in order to dynamically change the geometry style, the content or position of the label, the value for diagram, the height of a layout item, select some features, create virtual field …

표현식 문자열 작성기

Expression string builder 는 표현식을 생성하기 위한 주 대화창으로, QGIS의 여러 부분에서 이용할 수 있는데 특히 다음과 같은 경우에 접근할 수 있습니다:

표현식 작성기 대화창에서 다음 탭들을 선택할 수 있습니다:

  • 표현식 탭: 사전 정의 함수 목록을 이용해서 사용할 표현식을 작성하고 확인할 수 있습니다.

  • 함수 편집기 탭: 사용자 지정 함수를 생성해서 함수 목록을 확장할 수 있습니다.

몇몇 표현식 용례

  • 필드 계산기에서 기존 《total_pop》과 《area_km2》 필드를 이용, 《pop_density》 필드를 계산합니다:

    "total_pop" / "area_km2"
    
  • 《pop_density》 값에 따른 범주로 《density_level》 필드를 업데이트합니다:

    CASE WHEN "pop_density" < 50 THEN 'Low population density'
         WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
         WHEN "pop_density" >= 150 THEN 'High population density'
    END
    
  • 평균 집값이 제곱미터 당 1만 유로 이하인지 초과인지를 기준으로 모든 피처에 범주 스타일을 적용합니다:

    "price_m2" > 10000
    
  • Select By Expression… 도구를 통해 “High population density” 지역인 동시에 평균 집값이 제곱미터 당 1만 유로를 초과하는 지역을 나타내는 모든 피처를 선택합니다:

    "density_level" = 'High population density' and "price_m2" > 10000
    

    마찬가지로 이런 표현식을 이용해서 어떤 피처에 라벨을 적용하고 맵에 표시할지 정의할 수도 있습니다.

표현식을 이용하면 수많은 가능성이 열립니다.

표현식을 읽기 쉽도록 명명된 파라미터를 이용

어떤 함수들은 설정하는 데 여러 파라미터가 필요합니다. 표현식 엔진은 명명 파라미터를 지원하고 있습니다. 즉 암호 같은 표현식 clamp(1, 2, 9) 을 작성하는 대신, clamp(min:=1, value:=2, max:=9) 같은 표현식을 사용할 수 있다는 뜻입니다. 이렇게 하면 인자들도 clamp(value:=2, max:=9, min:=1) 처럼 위치를 바꿀 수 있습니다. 명명 파라미터를 이용하면 표현식 함수의 인자들이 어떤 의미인지 명확해집니다. 시간이 지난 뒤에 표현식을 해석하려 할 때 유용하겠죠!

함수 목록

The Expression tab provides the main interface to write expressions using functions, layer’s fields and values. It contains following widgets:

  • An expression editor area to type or paste expressions. Autocompletion is available to speed expression writing:

    • Corresponding variables, function names and field names to the input text are shown below: use the Up and Down arrows to browse the items and press Tab to insert in the expression or simply click on the wished item.

    • Function parameters are shown while filling them.

    QGIS also checks the expression rightness and highlights all the errors using:

    • Underline: for unknown functions, wrong or invalid arguments;

    • Marker: for every other error (eg, missing parenthesis, unexpected character) at a single location.

    Document your expression with comments

    When using complex expression, it is good practice to add text either as a multiline comment or inline comments to help you remember.

    /*
    Labels each region with its highest (in altitude) airport(s)
    and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
    */
    with_variable(
      'airport_alti', -- stores the highest altitude of the region
      aggregate(
        'airports',
        'max',
        "ELEV", -- the field containing the altitude
        -- and limit the airports to the region they are within
        filter := within( $geometry, geometry( @parent ) )
      ),
        aggregate( -- finds airports at the same altitude in the region
          'airports',
          'concatenate',
          "NAME",
          filter := within( $geometry, geometry( @parent ) )
            and "ELEV" = @airport_alti
        )
        || ' : ' || @airport_alti || 'm'
        -- using || allows regions without airports to be skipped
    )
    
  • Under the expression editor, an Output preview displays the result of the expression evaluated on the first feature of the layer. In case of error, it indicates it and you can access details with the provided hyperlink.

  • A function selector displays the list of functions, variables, fields… organized in groups. A search box is available to filter the list and quickly find a particular function or field. Double-clicking an item adds it to the expression editor.

  • A help panel displays help for each selected item in the function selector.

    Press Ctrl+Click when hovering a function name in an expression to automatically display its help in the dialog.

  • A field’s values widget shown when a field is selected in the function selector helps to fetch features attributes. Double-clicking a value adds it to the expression editor.

The right panel, showing functions help or field values, can be collapsed (invisible) in the dialog. Press the Show Values or Show Help button to get it back.

../../../_images/function_list.png

표현식 탭

집계 함수

이 그룹은 레이어 및 필드에 있는 값들을 집계하는 함수를 담고 있습니다.

함수

설명

aggregate

다른 레이어의 피처를 이용해서 계산한 합계값을 반환

array_agg

Returns an array of aggregated values from a field or expression

collect

Returns the multipart geometry of aggregated geometries from an expression

concatenate

필드 또는 표현식에서 나오는 문자열을 전부 구분자로 결합해서 반환

count

일치하는 피처의 개수를 반환

count_distinct

개별(distinct) 값의 개수를 반환

count_missing

없는 값(NULL)의 개수를 반환

iqr

필드 또는 표현식에서 계산된 내부 사분위수(quartile) 범위를 반환

majority

필드 또는 표현식에서 집계 다수 값(가장 흔하게 나타나는 값)을 반환

max_length

필드 또는 표현식에서 나오는 문자열의 최장 길이를 반환

maximum

필드 또는 표현식에서 나오는 집계 최대값을 반환

mean

필드 또는 표현식에서 나오는 집계 평균값을 반환

median

필드 또는 표현식에서 나오는 집계 중앙값을 반환

min_length

필드 또는 표현식에서 나오는 문자열의 최단 길이를 반환

minimum

필드 또는 표현식에서 나오는 집계 최소값을 반환

minority

필드 또는 표현식에서 집계 소수 값(가장 뜸하게 나타나는 값)을 반환

q1

필드 또는 표현식에서 계산된 첫 번째 사분위수를 반환

q3

필드 또는 표현식에서 계산된 세 번째 사분위수를 반환

range

필드 또는 표현식에서 나오는 값들의 (최대 ~ 최소) 집계 범위를 반환

relation_aggregate

레이어 관계에서 나오는 파생 피처들 가운데 일치하는 모든 피처를 이용해서 계산한 합계값을 반환

stdev

필드 또는 표현식에서 집계 표준 편차값을 반환

sum

필드 또는 표현식에서 집계 적산값을 반환


다음은 몇몇 예시입니다:

  • 《station_class》 필드로 그룹화된 레이어에 있는 피처에서 《passengers》 필드의 최대값을 반환합니다:

    maximum("passengers", group_by:="station_class")
    
  • 현재 지도 피처 안에 있는 역에 대해 총 승객 명수를 계산합니다:

    aggregate('rail_stations','sum',"passengers",
      intersects(@atlas_geometry, $geometry))
    
  • 레이어에서 〈my_relation〉 관계를 사용해서 일치하는 모든 파생 피처에 대해 《field_from_related_table》 필드의 평균값을 반환합니다:

    relation_aggregate('my_relation', 'mean', "field_from_related_table")
    

    또는 이렇게 작성할 수도 있습니다:

    relation_aggregate(relation:='my_relation', aggregate := 'mean',
      expression := "field_from_related_table")
    

Array Functions

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

함수

설명

array

Returns an array containing all the values passed as parameter

array_append

Returns an array with the given value added at the end

array_cat

Returns an array containing all the given arrays concatenated

array_contains

Returns true if an array contains the given value

array_distinct

Returns an array containing distinct values of the given array

array_filter

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

array_find

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

array_first

Returns the first value of an array

array_foreach

Returns an array with the given expression evaluated on each item

array_get

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

array_insert

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

array_intersect

Returns true if any element of array_1 exists in array_2

array_last

Returns the last element of an array

array_length

Returns the number of elements of an array

array_prepend

Returns an array with the given value added at the beginning

array_remove_all

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

array_remove_at

Returns an array with the given index removed

array_reverse

Returns the given array with array values in reversed order

array_slice

Returns the values of the array from the start_pos argument up to and including the end_pos argument

array_to_string

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

generate_series

Creates an array containing a sequence of numbers

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

string_to_array

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

색상 함수

이 그룹은 색상을 처리하기 위한 함수를 담고 있습니다.

함수

설명

color_cmyk

색상의 시안색, 마젠타색, 노랑색, 검정색 요소를 기반으로 색상의 문자열 표현을 반환

color_cmyka

색상의 시안색, 마젠타색, 노랑색, 검정색 그리고 알파(투명도) 요소를 기반으로 색상의 문자열 표현을 반환

color_grayscale_average

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

color_hsl

색상의 색상, 채도, 명도 속성을 기반으로 색상의 문자열 표현을 반환

color_hsla

색상의 색상, 채도, 명도 그리고 알파(투명도) 속성을 기반으로 색상의 문자열 표현을 반환

color_hsv

색상의 색상, 채도, 명도 속성을 기반으로 색상의 문자열 표현을 반환

color_hsva

색상의 색상, 채도, 명도 그리고 알파(투명도) 속성을 기반으로 색상의 문자열 표현을 반환

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

color_part

색상 문자열에서 빨강색 요소 또는 알파 요소 등 특정 요소를 반환

color_rgb

색상의 빨강색, 초록색, 파랑색 요소를 기반으로 색상의 문자열 표현을 반환

color_rgba

색상의 빨강색, 초록색, 파랑색 그리고 알파(투명도) 요소를 기반으로 색상의 문자열 표현을 반환

create_ramp

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

darker

더 어두운 (또는 더 밝은) 색상 문자열을 반환

lighter

더 밝은 (또는 더 어두운) 색상 문자열을 반환

project_color

프로젝트의 색상 스키마에서 색상을 반환

ramp_color

색상표에서 색상을 표현하는 문자열을 반환

set_color_part

색상 문자열에 빨강색 요소 또는 알파 요소 등 특정 색상 요소를 설정

Conditional Functions

이 그룹은 표현식에서 조건 검사를 처리하는 함수를 담고 있습니다.

함수

설명

CASE WHEN … THEN … END

표현식을 평가해서 참인 경우 결과를 반환합니다. 여러 조건을 동시에 검증할 수 있습니다.

CASE WHEN … THEN … ELSE … END

표현식을 평가해서 참인 경우 또는 거짓인 경우 서로 다른 결과를 반환합니다. 여러 조건을 동시에 검증할 수 있습니다.

coalesce

표현식 목록에서 NULL이 아닌 첫 번째 값을 반환

if

조건을 검증해서 조건 검사에 따라 서로 다른 결과를 반환


다음은 예시입니다:

  • 첫 번째 조건이 참인 경우 값을 회신하고, 아닌 경우 다른 값을 회신합니다:

    CASE WHEN "software" LIKE '%QGIS%' THEN 'QGIS' ELSE 'Other' END
    

변환 함수

이 그룹은 어느 데이터 유형을 다른 데이터 유형으로 변환하는 함수를 담고 있습니다. (예: 문자열을 정수형으로, 정수형을 문자열로)

함수

설명

to_date

문자열을 날짜 객체로 변환

to_datetime

문자열을 날짜&시간 객체로 변환

to_dm

Converts a coordinate to degree, minute

to_dms

Converts coordinate to degree, minute, second

to_int

문자열을 정수형 숫자로 변환

to_interval

문자열을 간격 유형으로 변환 (날짜 유형의 월, 일, 시 등을 추출하는 데 사용할 수 있습니다)

to_real

문자열을 실수형 숫자로 변환

to_string

숫자를 문자형으로 변환

to_time

문자열을 시간 객체로 변환

사용자 지정 함수

이 그룹은 사용자가 생성한 함수를 담고 있습니다. 자세한 내용은 함수 편집기 를 참조하세요.

날짜 및 시간 함수

이 그룹은 날짜 및 시간 데이터를 처리하기 위한 함수를 담고 있습니다.

함수

설명

age

두 날짜 또는 두 날짜&시간 사이의 차이를 간격 유형으로 반환

day

날짜 또는 날짜&시간에서 일(日)을 추출, 또는 간격 유형에서 일의 개수를 추출

day_of_week

지정한 날짜 또는 날짜&시간에 대해 요일에 대응하는 숫자를 반환

epoch

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

hour

날짜&시간 또는 시간에서 시(時)를 추출, 또는 간격 유형에서 시의 개수를 추출

minute

날짜&시간 또는 시간에서 분(分)을 추출, 또는 간격 유형에서 분의 개수를 추출

month

날짜 또는 날짜&시간에서 월(月)을 추출, 또는 간격 유형에서 월의 개수를 추출

now

현재 날짜 및 시간을 반환

second

날짜&시간 또는 시간에서 초(秒)를 추출, 또는 간격 유형에서 초의 개수를 추출

week

날짜 또는 날짜&시간에서 주(週) 번호를 추출, 또는 간격 유형에서 주의 개수를 추출

year

날짜 또는 날짜&시간에서 연도 부분을 추출, 또는 간격 유형에서 연도의 개수를 추출


이 그룹은 변환 함수 그룹과 몇몇 함수를( to_date, to_time, to_datetime, to_interval) 그리고 ref:string_functions 그룹과도 함수를(format_date) 공유하고 있습니다.

다음은 몇몇 예시입니다:

  • 《month_number/year》 서식으로 오늘의 월 및 연도를 얻으려면:

    format_date(now(),'MM/yyyy')
    -- Returns '03/2017'
    

이런 함수들 외에도, - (빼기) 연산자를 통해 날짜, 날짜&시간 또는 시간 유형을 뺄셈하면 간격 유형을 반환할 것입니다.

+ (더하기) 또는 - (빼기) 연산자를 이용해서 날짜, 날짜&시간 또는 시간 유형에 간격 유형을 더하거나 빼면 날짜&시간 유형을 반환합니다.

  • QGIS 3.0 배포일까지 며칠 남았는지 알아보려면:

    to_date('2017-09-29') - to_date(now())
    -- Returns <interval: 203 days>
    
  • 같은 내용을 시간 유형으로:

    to_datetime('2017-09-29 12:00:00') - to_datetime(now())
    -- Returns <interval: 202.49 days>
    
  • 현재부터 100일 후의 날짜&시간을 얻으려면:

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

참고

날짜, 날짜&시간, 간격 유형을 필드에 저장하기

The ability to store date, time and datetime values directly on fields may depend 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:

  • 날짜, 날짜&시간, 시간to_format() 함수로 처리한 다음 텍스트 유형 필드에 저장할 수 있습니다.

  • 간격 을 날짜 추출 함수 중 하나로 처리한 다음 (예: day() 함수는 날짜로 표현된 간격을 반환합니다) 정수 또는 실수 유형 필드에 저장할 수 있습니다.

필드 및 값

이 그룹은 레이어에 있는 필드의 목록을 담고 있습니다.

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.

퍼지 매칭 함수

이 그룹은 값들을 퍼지 비교하기 위한 함수를 담고 있습니다.

함수

설명

hamming_distance

문자들이 서로 다른 입력 문자열들 안에서 대응하는 위치에 있는 문자의 개수를 반환

levensheim

어떤 문자열을 다른 문자열로 변경하는 데 필요한 문자 편집(삽입, 삭제 또는 치환)의 최소 횟수를 반환합니다. 두 문자열 사이의 유사성을 측정하는 함수입니다.

longest_common_substring

두 문자열에서 가장 긴 공통 하위 문자열을 반환

soundex

문자열의 Soundex 표현을 반환

일반 함수

이 그룹은 일반으로 분류된 함수를 담고 있습니다.

함수

설명

env

Gets an environment variable and returns its content as a string. If the variable is not found, NULL will be returned.

eval

문자열로 전달된 표현식을 평가합니다. 맥락 상 변수 또는 필드로 전달되는 동적 파라미터를 확장하는 데 유용합니다.

is_layer_visible

Returns true if a specified layer is visible

layer_property

레이어의 속성 또는 레이어 메타데이터의 값(레이어명, 좌표계, 도형 유형, 피처 개수 등등 가운데 하나)을 반환

var

지정한 변수 내부에 저장된 값을 반환 (변수 함수 참조)

with_variable

Creates and sets a variable for any expression code that will be provided as a third argument. Useful to avoid repetition in expressions where the same value needs to be used more than once.

도형 함수

이 그룹은 도형 객체를 대상으로 하는 (예: 길이, 면적 등) 함수를 담고 있습니다.

함수

설명

$area

현재 피처의 면적 크기를 반환

$geometry

현재 피처의 도형을 반환 (다른 함수들과 함께 공간 처리 가능)

$length

현재 라인 피처의 길이를 반환

$perimeter

현재 폴리곤 피처의 둘레를 반환

$x

Returns the X coordinate of the current feature

$x_at(n)

Returns the X coordinate of the nth node of the current feature’s geometry

$y

Returns the Y coordinate of the current feature

$y_at(n)

Returns the Y coordinate of the nth node of the current feature’s geometry

angle_at_vertex

라인스트링 도형 상에 지정한 꼭짓점에서 도형에 대한 이등분선 각도(평균 각도)를 반환합니다. 여기서 각도는 진북에서 시계 방향으로 측정한 도 단위입니다.

area

도형 폴리곤 피처의 면적을 반환합니다. 해당 도형의 공간 참조 시스템 상에서 면적을 계산합니다.

azimuth

포인트 a의 수직선에서 포인트 b로 시계 방향으로 측정한 진북 기준 방위각을 라디안 단위 각도로 반환

boundary

Returns the closure of the combinatorial boundary of the geometry (ie the topological boundary of the geometry - see also Boundary).

bounds

Returns a geometry which represents the bounding box of an input geometry. Calculations are in the Spatial Reference System of this geometry (see also Bounding boxes)

bounds_height

도형의 경계 상자의 높이를 표현하는 도형을 반환합니다. 해당 도형의 공간 참조 시스템 상에서 경계 상자를 계산합니다.

bounds_width

도형의 경계 상자의 너비를 표현하는 도형을 반환합니다. 해당 도형의 공간 참조 시스템 상에서 경계 상자를 계산합니다.

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 (see also Buffer)

buffer_by_m

Creates a buffer along a line geometry where the buffer diameter varies according to the M values at the line vertices (see also Variable width buffer (by M value))

centroid

Returns the geometric center of a geometry (see also Centroids)

closest_point

첫 번째 도형의 포인트들 가운데 두 번째 도형에 가장 가까운 포인트를 반환

combine

두 도형의 조합을 반환

contains(a,b)

도형 b의 포인트 가운데 도형 a 외부에 있는 포인트가 하나도 없고, 도형 b 내부의 포인트 가운데 최소한 포인트 1개가 도형 a 내부에 있는 경우에만 1(참)을 반환

convex_hull

Returns the convex hull of a geometry (this represents the minimum convex geometry that encloses all geometries within the set) (see also Convex hull)

crosses

입력 도형들이 내부 포인트들 가운데 일부를 – 모두가 아니라 – 공유하는 경우 1(참)을 반환

difference(a,b)

Returns a geometry that represents that part of geometry a that does not intersect with geometry b (see also Difference)

disjoint

도형들이 어떤 공간도 함께 공유하지 않는 경우 1(참)을 반환

distance

두 도형 사이의 (공간 참조 시스템 기반) 최단 거리를 투영체 단위로 반환

distance_to_vertex

도형을 따라 지정한 꼭짓점까지의 거리를 반환

end_point

Returns the last node from a geometry (see also Extract specific vertices)

extend

Extends the start and end of a linestring geometry by a specified amount (see also Extend lines)

exterior_ring

폴리곤 도형의 외곽 고리를 표현하는 라인스트링을 반환 (도형이 폴리곤이 아닌 경우 NULL을 반환)

extrude(geom,x,y)

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

flip_coordinates

Returns a copy of the geometry with the X and Y coordinates swapped (see also Swap X and Y coordinates)

geom_from_gml

도형의 GML 표현으로부터 생성된 도형을 반환

geom_from_wkt

도형의 WKT(well-known text) 표현으로부터 생성된 도형을 반환

geom_to_wkt

SRID 메타데이터를 제외한 도형의 WKT(well-known text) 표현을 반환

geometry

피처의 도형을 반환

geometry_n

도형 집합에서 N번째 도형을 반환 (도형이 집합이 아닌 경우 NULL을 반환)

hausdorff_distance

Returns basically a measure of how similar or dissimilar 2 geometries are, with a lower distance indicating more similar geometries

inclination

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

interior_ring_n

폴리곤 도형에서 N번째 내곽 고리를 표현하는 도형을 반환 (도형이 폴리곤이 아닌 경우 NULL을 반환)

intersection

Returns a geometry that represents the shared portion of two geometries (see also Intersection)

intersects

도형들이 서로 교차하는지 검증합니다. 도형들이 공간적으로 교차하는 경우 (공간의 어떤 부분이라도 공유하는 경우) 1(참)을 반환하고 교차하지 않는 경우 0을 반환합니다.

intersects_bbox

도형의 경계 상자가 다른 도형의 경계 상자와 교차하는지 검증합니다. 도형들의 경계 상자가 공간적으로 교차하는 경우 (공간의 어떤 부분이라도 공유하는 경우) 1(참)을 반환하고 교차하지 않는 경우 0을 반환합니다.

is_closed

라인스트링이 닫힌 (시작점과 종단점이 일치하는) 경우 참을, 라인스트링이 닫히지 않은 경우 거짓을, 도형이 라인스트링이 아닌 경우 NULL을 반환

length

라인 도형 객체의 길이를 (또는 문자열의 길이를) 반환

line_interpolate_angle

라인스트링 도형을 따라 지정한 거리에서 도형과 평행한 각도를 반환합니다. 여기서 각도는 진북에서 시계 방향으로 측정한 도 단위입니다.

line_interpolate_point

Returns the point interpolated by a specified distance along a linestring geometry. (see also Interpolate point on line)

line_locate_point

라인스트링을 따라 라인스트링이 지정한 포인트 도형에 가장 가까워지는 위치에 상응하는 거리를 반환

line_substring

Returns the portion of a line or curve geometry falling betweeen specified start and end distances (measured from the beginning of the line) (see also Line substring)

line_merge

입력 도형에 있는 연결된 라인스트링들이 단일 라인스트링으로 합쳐진 [멀티]라인스트링 도형을 반환

m

Returns the M value of a point geometry

make_circle

Creates a circular geometry based on center point and radius

make_ellipse

Creates an elliptical geometry based on center point, axes and azimuth

make_line

일련의 포인트 도형들로부터 라인을 생성

make_point(x,y,z,m)

Returns a point geometry from X and Y (and optional Z or M) values

make_point_m(x,y,m)

Returns a point geometry from X and Y coordinates and M values

make_polygon

외곽 고리 그리고 부가적인 일련의 내곽 고리 도형으로부터 폴리곤 도형을 생성

make_regular_polygon

Creates a regular polygon

make_triangle

Creates a triangle polygon

minimal_circle

Returns the minimal enclosing circle of an input geometry (see also Minimum enclosing circles)

nodes_to_points

Returns a multipoint geometry consisting of every node in the input geometry (see also Extract vertices)

num_geometries

도형 집합에 있는 도형의 개수를 반환 (도형이 집합이 아닌 경우 NULL을 반환)

num_interior_rings

폴리곤 또는 도형 집합에 있는 내곽 고리의 개수를 반환 (도형이 폴리곤 또는 집합이 아닌 경우 NULL을 반환)

num_points

도형에 있는 꼭짓점의 개수를 반환

num_rings

폴리곤 또는 도형 집합에 있는 (외곽 고리를 포함한) 고리의 개수를 반환 (도형이 폴리곤 또는 집합이 아닌 경우 NULL을 반환)

offset_curve

Returns a geometry formed by offsetting a linestring geometry to the side. Distances are in the Spatial Reference System of this geometry. (see also Offset lines)

order_parts

지정한 기준으로 멀티 도형의 부분들을 정렬

oriented_bbox

Returns a geometry representing the minimal oriented bounding box of an input geometry (see also Oriented minimum bounding box)

overlaps

도형이 다른 도형과 중첩하는지 검증합니다. 도형들이 동일한 차원이며 공간을 공유하지만 서로를 완전히 담고 있지 않은 경우 1(참)을 반환합니다.

perimeter

폴리곤 도형 객체의 둘레를 반환합니다. 해당 도형의 공간 참조 시스템 상에서 둘레를 계산합니다.

point_n

Returns a specific node from a geometry (see also Extract specific vertices)

point_on_surface

Returns a point guaranteed to lie on the surface of a geometry (see also Point on Surface)

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 (see also Pole of inaccessibility)

project

Returns a point projected from a start point using a distance and bearing (azimuth) in radians (see also Project points (Cartesian))

relate

두 도형 간의 관계의 DE-9IM(Dimensional Extended 9 Intersection Model) 표현을 검증 또는 반환

reverse

Reverses the direction of a line string by reversing the order of its vertices (see also Reverse line direction)

segments_to_lines

Returns a multi line geometry consisting of a line for every segment in the input geometry (see also Explode lines)

shortest_line

두 도형을 연결하는 최단 라인을 반환합니다. 산출된 라인은 도형 a에서 시작돼 도형 b에서 끝납니다.

simplify

Simplifies a geometry by removing nodes using a distance based threshold (see also Simplify)

simplify_vw

Simplifies a geometry by removing nodes using an area based threshold (see also Simplify)

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 (see also Single sided buffer)

smooth

Smooths a geometry by adding extra nodes which round off corners in the geometry (see also Smooth)

start_point

Returns the first node from a geometry (see also Extract specific vertices)

sym_difference

Returns a geometry that represents the portions of two geometries that do not intersect (see also Symmetrical difference)

tapered_buffer

Creates a buffer along a line geometry where the buffer diameter varies evenly over the length of the line (see also Tapered buffers)

touches

도형이 다른 도형과 접하는지 검증합니다. 도형들이 최소한 포인트 1개를 공유하지만 각 도형의 내부가 교차하지 않는 경우 1(참)을 반환합니다.

transform

Returns the geometry transformed from the source CRS to the destination CRS (see also Reproject layer)

translate

Returns a translated version of a geometry. Calculations are in the Spatial Reference System of the geometry (see also Translate)

union

도형의 모든 포인트를 통합한 집합을 표현하는 도형을 반환

wedge_buffer

Returns a wedge shaped buffer originating from a point geometry given an angle and radii (see also Create wedge buffers)

within (a,b)

도형이 다른 도형 내부에 있는지 검증합니다. 도형 a가 도형 b 내부에 완전히 들어가 있는 경우 1(참)을 반환합니다.

x

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

x_min

Returns the minimum X coordinate of a geometry. Calculations are in the Spatial Reference System of this geometry

x_max

Returns the maximum X coordinate of a geometry. Calculations are in the Spatial Reference System of this geometry

y

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

y_min

Returns the minimum Y coordinate of a geometry. Calculations are in the Spatial Reference System of this geometry

y_max

Returns the maximum Y coordinate of a geometry. Calculations are in the Spatial Reference System of this geometry

z

Returns the Z coordinate of a point geometry


다음은 몇몇 예시입니다:

  • $geometry 변수로 현재 도형에 버퍼를 생성하거나 표면 상에 있는 포인트를 얻을 수 있습니다:

    buffer( $geometry, 10 )
    point_on_surface( $geometry )
    
  • Return the X coordinate of the current feature’s centroid:

    x( $geometry )
    
  • 피처의 면적에 따라 값을 회신합니다:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END
    

Layout Functions

This group contains functions to manipulate print layout items properties.

함수

설명

item_variables

Returns a map of variables from a layout item inside this print layout


다음은 예시입니다:

  • Get the scale of the 〈Map 0〉 in the current print layout:

    map_get( item_variables('Map 0'), 'map_scale')
    

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.

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.

함수

설명

hstore_to_map

Creates a map from a hstore-formatted string

json_to_map

Creates a map from a json-formatted string

map

Returns a map containing all the keys and values passed as pair of parameters

map_akeys

Returns all the keys of a map as an array

map_avals

Returns all the values of a map as an array

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.

map_delete

Returns a map with the given key and its corresponding value deleted

map_exist

Returns true if the given key exists in the map

map_get

Returns the value of a map, given it’s key

map_insert

Returns a map with an added key/value

map_to_hstore

Merges map elements into a hstore-formatted string

map_to_json

Merges map elements into a json-formatted string

수학 함수

이 그룹은 제곱근, 삼각함수 등의 수학 함수를 담고 있습니다.

함수

설명

abs

숫자의 절댓값을 반환

acos

값의 시컨트(역 코사인)를 라디안 단위로 반환

asin

값의 코시컨트(역 사인)를 라디안 단위로 반환

atan

Returns the inverse tangent of a value in radians

atan2(y,x)

Returns the inverse tangent of Y/X by using the signs of the two arguments to determine the quadrant of the result

azimuth(a,b)

포인트 a의 수직선에서 포인트 b로 시계 방향으로 측정한 진북 기준 방위각을 라디안 단위 각도로 반환

ceil

올림

clamp

입력값을 지정한 범위로 제한

cos

값의 코사인을 라디안 단위로 반환

degrees

라디안 단위를 도 단위로 변환

exp

값의 거듭제곱 지수를 반환

floor

내림

inclination

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

ln

표현식 인자의 자연로그 를 반환

log

값 및 밑(base) 인자의 로그 값을 반환

log10

표현식 인자의 상용로그 값을 반환

max

Returns the largest not null value in a set of values

min

Returns the smallest not null value in a set of values

pi

계산을 위한 파이(π) 값을 반환

radians

도 단위를 라디안 단위로 변환

rand

최소(이상) 및 최대(이하) 인자가 지정하는 범위 안에서 랜덤한 정수를 반환

randf

최소(이상) 및 최대(이하) 인자가 지정하는 범위 안에서 랜덤한 실수를 반환

round

반올림

scale_exp

지정한 값을 지수 곡선(exponential curve)을 이용해서 입력 범위에서 출력 범위로 변형

scale_linear

지정한 값을 선형 보간(linear interpolation)을 이용해서 입력 범위에서 출력 범위로 변형

sin

각도의 사인을 반환

sqrt

값의 제곱근을 반환

tan

각도의 탄젠트를 반환

연산자

이 그룹은 +, -, * 같은 연산자를 담고 있습니다. 다음에 설명하는 수학 함수들 대부분이, 입력 값 가운데 하나가 NULL인 경우 NULL을 반환한다는 점을 유념하십시오.

함수

설명

a + b

두 값의 덧셈 (a 더하기 b)

a - b

두 값의 뺄셈 (a 빼기 b)

a * b

두 값의 곱셈 (a 곱하기 b)

a / b

두 값의 나눗셈 (a를 b로 나누기)

a % b

a를 b로 나눈 나머지 (예: 7%2=1, 또는 7을 2로 나누면 3과 나머지 1)

a ^ b

두 값의 거듭제곱 (예: 2^2=4 또는 2^3=8)

a < b

두 값을 비교해서 왼쪽 값이 오른쪽 값보다 작은 경우 1로 평가 (a가 b 미만)

a <= b

두 값을 비교해서 왼쪽 값이 오른쪽 값보다 작거나 같은 경우 1로 평가 (a가 b 이하)

a <> b

두 값을 비교해서 두 값이 같지 않은 경우 1로 평가

a = b

두 값을 비교해서 두 값이 같은 경우 1로 평가

a != b

a와 b는 같지 않음

a > b

두 값을 비교해서 왼쪽 값이 오른쪽 값보다 큰 경우 1로 평가 (a가 b 초과)

a >= b

두 값을 비교해서 왼쪽 값이 오른쪽 값보다 크거나 같은 경우 1로 평가 (a가 b 이상)

a ~ b

a와 정규 표현식 b가 일치

||

두 값을 문자열로 결합합니다. 한 쪽 값이 NULL인 경우 NULL을 반환합니다.

〈\n〉

문자열에 줄바꿈 삽입

LIKE

첫 번째 파라미터가 지정한 패턴과 일치하는 경우 1을 반환

ILIKE

첫 번째 파라미터가 대소문자를 구분하는 지정 패턴과 일치하는 경우 1을 반환 (대소문자 상태까지 일치하는지 확인하려 할 때 LIKE 대신 ILIKE를 쓸 수 있습니다)

a IS b

두 값이 동일한지 검증해서 a와 b가 동일한 경우 1을 반환

a OR b

조건 a 또는 조건 b가 참인 경우 1을 반환

a AND b

조건 a와 조건 b가 참인 경우 1을 반환

NOT

조건 무효화

column name 《column name》

필드 열 명칭의 값으로, 다음 작은따옴표와 혼동하지 않도록 조심하십시오.

〈string〉

문자열 값으로, 이전 큰따옴표와 혼동하지 않도록 조심하십시오.

NULL

NULL 값

a IS NULL

a가 값을 가지고 있지 않음

a IS NOT NULL

a가 값을 가지고 있음

a IN (value[,value])

a가 값 목록에 있음

a NOT IN (value[,value])

a가 값 목록에 있지 않음


참고

필드 연결에 대해

|| 또는 + 가운데 하나를 사용해서 문자열을 연결할 수 있습니다. + 기호는 덧셈 표현식이기도 합니다. 따라서 정수형(필드 또는 숫자값)이 있을 경우 오류를 낼 가능성이 있으므로, || 을 사용해야 합니다. 문자열 값 2개를 연결하는 경우엔 둘 다 사용해도 됩니다.

다음은 몇몇 예시입니다:

  • 문자열과 열 명칭의 값을 연결합니다:

    'My feature''s id is: ' || "gid"
    'My feature''s id is: ' + "gid" => triggers an error as gid is an integer
    "country_name" + '(' + "country_code" + ')'
    "country_name" || '(' || "country_code" || ')'
    
  • 《description》 속성 필드의 값이 〈Hello〉 문자열로 시작하는지 검증합니다(% 문자의 위치를 주목하세요):

    "description" LIKE 'Hello%'
    

Rasters Functions

This group contains functions to operate on raster layer.

함수

설명

raster_statistic

Returns statistics from a raster layer

raster_value

Returns the raster band value at the provided point

Record and Attributes Functions

이 그룹은 레코드 식별자를 대상으로 하는 함수를 담고 있습니다.

함수

설명

$currentfeature

평가 중인 현재 피처를 반환합니다. 현재 피처에서 속성값을 평가하는 attribute 함수와 함께 사용할 수 있습니다.

$id

현재 행의 피처 ID를 반환

attribute

피처에서 지정한 속성의 값을 반환

get_feature

레이어에서 지정한 속성값과 일치하는 첫 번째 피처를 반환

get_feature_by_id

Returns the feature of a layer matching the given feature ID

is_selected

Returns if a feature is selected

num_selected

Returns the number of selected features on a given layer

represent_value

Returns the configured representation value for a field value (convenient with some widget types)

uuid

각 행에 대해 UUID(Universally Unique Identifier)를 생성합니다. 각 UUID는 문자 38개 길이입니다.


다음은 몇몇 예시입니다:

  • 《LayerA》 레이어에서 《id》 필드가 현재 피처의 《name》 필드와 동일한 값을 지닌 첫 번째 피처를 반환합니다(필드 결합의 일종입니다):

    get_feature( 'layerA', 'id', attribute( $currentfeature, 'name') )
    
  • 이전 예시에서 결합된 피처의 면적을 계산합니다:

    area( geometry( get_feature( 'layerA', 'id', attribute( $currentfeature, 'name') ) ) )
    

문자열 함수

이 그룹은 문자열을 대상으로 하는 (예: 치환, 대문자 변환 등) 함수를 담고 있습니다.

함수

설명

char

유니코드 코드와 관련된 문자를 반환

concat

여러 문자열을 하나로 연결

format

지정한 인자를 이용해서 문자열 서식을 변경

format_date

날짜 또는 문자열 유형을 사용자 지정 문자열 서식으로 변경

format_number

현지의 천 단위 자릿수 표시 기호로 서식을 변경한 숫자를 반환 (또 숫자를 지정한 자릿수로 잘라냅니다)

left(string, n)

문자열 가장 왼쪽에 있는 N개의 문자를 담은 하위 문자열을 반환

length

문자열의 길이를 (또는 라인 도형 객체의 길이를) 반환

lower

문자열을 소문자로 변환

lpad

Returns a string padded on the left to the specified width, using the fill character

regexp_match

Returns the first matching position matching a regular expression within a string, or 0 if the substring is not found

regexp_replace

지정한 정규 표현식을 치환한 문자열을 반환

regexp_substr

문자열에서 지정한 정규 표현식과 일치하는 부분을 반환

replace

Returns a string with the supplied string, array, or map of strings replaced by a string, an array of strings or paired values

right(string, n)

문자열 가장 오른쪽에 있는 N개의 문자를 담은 하위 문자열을 반환

rpad

Returns a string padded on the right to the specified width, using the fill character

strpos

Returns the first matching position of a substring within another string, or 0 if the substring is not found

substr

문자열의 부분을 반환

title

문자열의 모든 단어를 제목 서식 으로 변환 (모든 단어의 첫 문자가 대문자, 나머지 문자는 소문자)

trim

문자열에서 맨 앞과 맨 뒤의 모든 빈 자리(공백, 탭 등)를 제거

upper

문자열을 대문자로 변환

wordwrap

최대/최소 문자 개수로 행갈이한 문자열을 반환

변수 함수

이 그룹은 응용 프로그램, 프로젝트 파일 및 기타 설정과 관련된 동적 변수를 담고 있습니다. 즉 다음 맥락에 따라 일부 함수를 사용하지 못 할 수도 있다는 뜻입니다:

  • expressionSelect Select by expression 대화창에서

  • calculateField Field calculator 대화창에서

  • 레이어 속성 대화창에서

  • from the print layout

표현식에 다음 함수들을 사용하려면, 앞에 @ 문자를 (예: @row_number) 붙여야 합니다:

함수

설명

algorithm_id

Returns the unique ID of an algorithm

atlas_feature

현재 지도 피처를 (피처 객체로) 반환

atlas_featureid

현재 지도 피처 ID를 반환

atlas_featurenumber

Returns the current atlas feature number in the layout

atlas_filename

현재 지도 파일명을 반환

atlas_geometry

현재 지도 피처 도형을 반환

atlas_layerid

Returns the current atlas coverage layer ID

atlas_layername

Returns the current atlas coverage layer name

atlas_pagename

현재 지도 페이지 명칭을 반환

atlas_totalfeatures

지도에 있는 피처의 총 개수를 반환

canvas_cursor_point

Returns the last cursor position on the canvas in the project’s geographical coordinates

cluster_color

Returns the color of symbols within a cluster, or NULL if symbols have mixed colors

cluster_size

Returns the number of symbols contained within a cluster

current_feature

Returns the feature currently being edited in the attribute form or table row

current_geometry

Returns the geometry of the feature currently being edited in the form or the table row

geometry_part_count

Returns the number of parts in rendered feature’s geometry

geometry_part_num

Returns the current geometry part number for feature being rendered

geometry_point_count

Returns the number of points in the rendered geometry’s part

geometry_point_num

Returns the current point number in the rendered geometry’s part

grid_axis

현재 그리드 주석 축을 반환 (예: 경도는 〈x〉, 위도는 〈y〉)

grid_number

현재 그리드 주석 값을 반환

item_id

Returns the layout item user ID (not necessarily unique)

item_uuid

Returns the layout item unique ID

layer

Returns the current layer

layer_id

현재 레이어의 ID를 반환

layer_name

현재 레이어의 명칭을 반환

layout_dpi

조판 해상도(DPI)를 반환

layout_name

Returns the layout name

layout_numpages

Returns the number of pages in the layout

layout_page

Returns the page number of the current item in the layout

layout_pageheight

Returns the active page height in the layout (in mm)

layout_pagewidth

Returns the active page width in the layout (in mm)

map_crs

Returns the Coordinate reference system of the current map

map_crs_definition

Returns the full definition of the Coordinate reference system of the current map

map_extent

Returns the geometry representing the current extent of the map

map_extent_center

맵의 중앙에 있는 포인트 피처를 반환

map_extent_height

맵의 현재 높이를 반환

map_extent_width

맵의 현재 너비를 반환

map_id

Returns the ID of current map destination. This will be 〈canvas〉 for canvas renders, and the item ID for layout map renders

map_layer_ids

Returns the list of map layer IDs visible in the map

map_layers

Returns the list of map layers visible in the map

map_rotation

맵의 현재 기울기를 반환

map_scale

맵의 현재 축척을 반환

map_units

Returns the units of map measurements

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

Returns the project abstract, taken from project metadata

project_author

Returns the project author, taken from project metadata

project_basename

Returns the basename of current project’s filename (without path and extension)

project_creation_date

Returns the project creation date, taken from project metadata

project_crs

Returns the Coordinate reference system of the project

project_crs_definition

Returns the full definition of the Coordinate reference system of the project

project_filename

Returns the filename of the current project

project_folder

Returns the folder of the current project

project_home

Returns the home path of the current project

project_identifier

Returns the project identifier, taken from the project’s metadata

project_keywords

Returns the project keywords, taken from the project’s metadata

project_path

Returns the full path (including file name) of the current project

project_title

현재 프로젝트의 제목을 반환

qgis_locale

Returns the current language of QGIS

qgis_os_name

현재 운영체제의 명칭을 반환 (예: 〈windows〉, 〈linux〉 또는 〈osx〉)

qgis_platform

QGIS의 플랫폼을 반환 (예: 〈desktop〉 또는 〈server〉)

qgis_release_name

현재 QGIS의 배포명을 반환

qgis_short_version

Returns current QGIS version short string

qgis_version

현재 QGIS의 버전 문자열을 반환

qgis_version_no

현재 QGIS의 버전 숫자를 반환

snapping_results

Gives access to snapping results while digitizing a feature (only available in add feature)

symbol_angle

피처를 렌더링하는 데 쓰인 심볼의 각도를 반환 (마커 심볼 전용)

symbol_color

피처를 렌더링하는 데 쓰인 심볼의 색상을 반환

user_account_name

현재 사용자의 운영체제 계정명을 반환

user_full_name

현재 사용자의 운영체제 사용자명을 반환

row_number

현재 행의 번호를 저장

value

현재 값을 반환

with_variable

Allows setting a variable for usage within an expression and avoid recalculating the same value repeatedly


다음은 몇몇 예시입니다:

  • Return the X coordinate of a map item center to insert into a label in layout:

    x( map_get( item_variables( 'map1'), 'map_extent_center' ) )
    
  • Return for each feature in the current layer the number of overlapping airports 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'
      )
    )
    

최근 함수

This group contains recently used functions. Depending on the context of its usage (feature selection, field calculator, generic), any applied expression is added to the corresponding list (up to ten expressions), sorted from the more recent to the less one. This helps to quickly retrieve and reapply any previously used expression.

함수 편집기

With the Function Editor tab, you are able to write your own functions in Python language. This provides a handy and comfortable way to address particular needs that would not be covered by the predefined functions.

../../../_images/function_editor.png

함수 편집기 탭

To create a new function:

  1. Press the signPlus New File button.

  2. Enter a name to use in the form that pops up and press OK.

    A new item of the name you provide is added in the left panel of the Function Editor tab; this is a Python .py file based on QGIS template file and stored in the /python/expressions folder under the active user profile directory.

  3. The right panel displays the content of the file: a python script template. Update the code and its help according to your needs.

  4. Press the start Save and Load Functions button. The function you wrote is added to the functions tree in the Expression tab, by default under the Custom group.

  5. Enjoy your new function.

  6. If the function requires improvements, enable the Function Editor tab, do the changes and press again the start Save and Load Functions button to make them available in the file, hence in any expression tab.

Custom Python functions are stored under the user profile directory, meaning that at each QGIS startup, it will auto load all the functions defined with the current user profile. Be aware that new functions are only saved in the /python/expressions folder and not in the project file. If you share a project that uses one of your custom functions you will need to also share the .py file in the /python/expressions folder.

다음은 사용자 고유의 함수를 생성하는 방법에 대한 간단한 예시입니다:

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

The short example creates a function my_sum that will give you a function with two values. When using the args='auto' function argument the number of function arguments required will be calculated by the number of arguments the function has been defined with in Python (minus 2 - feature, and parent).

This function can then be used in expressions:

../../../_images/customFunction.png

Custom Function added to the Expression tab

PyQGIS 개발자 쿡북 에서 파이썬 코드 생성 관련 심화 정보를 찾아볼 수 있습니다.