14.2. 式
レイヤのデータと組み込みの関数やユーザー定義の関数をベースにした 式 は、属性値やジオメトリ、変数を操作する強力な方法です。ジオメトリのスタイル、ラベルの内容や位置、ダイアグラムの値、レイアウトアイテムの高さ、地物の一部の選択、仮想フィールドの作成などを動的に変更することができます。
注釈
式の作成に使えるデフォルトの関数や変数のリストは、詳細な情報や例付きで 関数のリスト にあります。
14.2.1. 式文字列ビルダー
式を組み立てるための主要なダイアログである 式文字列ビルダー は、QGISの多くの部分から使用することができますが、特に以下のような時に使うことができます。
ボタンをクリックしたとき
式による地物選択... ツールで 地物を選択 するとき例えば
フィールド計算機 ツールで 属性を編集する とき
データによって定義された上書き ツールを使用して、シンボロジやラベル、レイアウトアイテムのパラメータを操作するとき（ データによって定義された上書きの設定 参照）ジオメトリジェネレータ のシンボルレイヤを構築するとき
何らかの ジオプロセシング を行うとき
式ビルダーダイアログから以下のタブにアクセス可能です。
14.2.1.1. インターフェース
式 タブには関数やレイヤのフィールド、値を使用して式を作成するためのメインのインターフェースがあります。これには、以下のウィジェットが含まれます：
図 14.65 式タブ
式を入力したり張り付けたりするための式編集エリア。以下のような自動補完を利用でき、式の入力を短縮できます：
入力したテキストに応じた変数名、関数名、フィールド名が下に表示されます。 Up 矢印キーと Down 矢印キーを使って項目間を移動することができます。式に挿入するには Tab キーを押すか、挿入したい項目を単にクリックします。
関数を入力している間、関数のパラメータが表示されます。
また、QGISは式が正しいかをチェックし、エラーを以下の方法で強調表示します：
アンダーライン ：未定義の関数や、間違ったあるいは無効な引数
マーカー ：単一の場所でのその他エラー（対応していない括弧、不要な文字など）
ちなみに
コメントで式をドキュメンテーションする
複雑な式を使用する場合には、思い出しやすいように複数行コメントやインラインコメントとしてテキストを追加するのがよいでしょう。
/* 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 )式エディタの上部には、以下のようなツールセットがあります：
式エディタのクリアユーザー式 の作成や編集
式エディタの下部には、以下のものがあります：
式の作成を助ける基本的な演算子のセット
データ定義の地物プロパティを設定する場合には、期待されるアウトプットのフォーマットに関する指示
式のライブ プレビュー 。デフォルトではレイヤの最初の地物に対して評価されます。 地物 コンボボックス（この値はレイヤの 表示名 プロパティを使用します）を使用して、レイヤの他の地物を参照し評価することができます。
エラーとなった場合には、エラーが表示され、ハイパーリンクからエラーの詳細情報にアクセスできます。
関数セレクタには、関数や変数、フィールドなどのグループ化されたリストが表示されます。検索ボックスを利用して、リストをフィルタし特定の関数やフィールドを素早く見つけることができます。アイテムをダブルクリックすると、そのアイテムが式エディタに追加されます。
ヘルプパネルには、関数セレクタで選択したアイテムに対するヘルプが表示されます。
ちなみに
式内で関数名にカーソルを乗せて Ctrl+Click すると、ダイアログでその関数のヘルプが表示されます。
関数セレクタでフィールドを選択している場合には、フィールドの値ウィジェットが表示され、以下のように地物の属性値の取得に役立ちます。
特定のフィールド値を検索する
全ユニーク または 10個のサンプル 値のリストを表示する。これはフィールドの右クリックからも利用できます。
フィールドが他のレイヤや値のセットにマッピングされている場合、すなわち、 フィールド編集ウィジェット が リレーションの参照 、 値のリレーション または バリューマップ タイプの場合には、（参照されたレイヤ、テーブル、リストから）マッピングされたフィールドの値をすべてリストすることができます。さらに、このリストをフィルタリングして、現在のフィールドで
使用中の値のみ表示 することもできます。
ウィジェット内でフィールド値をダブルクリックすると、式エディタに値が追加されます。
ちなみに
関数のヘルプやフィールドの値が表示される右側パネルは、ダイアログ内でたたむ（非表示にする）ことができます。 値を表示 や ヘルプを表示 ボタンを押すと、非表示状態から表示状態に戻すことができます。
14.2.1.2. 式の作成
QGISの式は、地物の選択や値の設定に使われます。QGISで式を作成するには、以下のいくつかのルールに従います。
ダイアログがコンテキストを定義する ：SQLに慣れているのならば、 select features from layer where condition や update layer set field = new_value where condition といった形式のクエリをご存知でしょう。QGISの式もこれらの情報を必要としますが、式ビルダーダイアログを開くためのツールが必要な情報の一部を提供します。例えば、（height）フィールドを持つ（building）レイヤがあるとします。
- 式による地物選択 ツールを押すことは、 "select features from buildings" を意味します。式テキストウィジェットに入力する必要がある情報は condition のみです。つまり、
"height" > 20と入力すれば、高さが20よりも大きい建物を選択します。 この選択をした状態で、
フィールド計算機 ボタンを押して 既存のフィールドを更新する で "height" を選択することは、 "update buildings set height = ??? where height > 20" コマンドを入力したも同然です。この場合に残っている入力する必要のあるものは、 新しい値 だけです。つまり、単に 50と入力すれば、選択した buildings の height の値がこれに設定されます。
引用符に注意 ：シングルクォートはリテラルを返します。このため、シングルクォートに挟まれたテキスト（
'145'）は文字列として解釈されます。ダブルクォートはそのテキストの値を返すので、フィールドにはダブルクォートを使用してください（"myfield"）。フィールドは引用符なしでも使用できます（myfield）。数値には引用符は不要です（3.16）。注釈
関数は通常、フィールド名を表す文字列を引数にとります。次のようにしてください:
attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature
以下のようにしてはいけません:
attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.
ちなみに
名前付きパラメータを使用して式を読みやすくする
いくつかの関数は多数のパラメータを設定する必要があります。式エンジンは名前付きパラメータの使用をサポートしています。つまり、暗号めいた式 clamp( 1, 2, 9) と書く代わりに、 clamp( min:=1, value:=2, max:=9) を使うことができます。引数を入れ替え、例えば clamp( value:=2, max:=9, min:=1) とすることもできます。名前付きパラメータを使うことで、式の関数の引数が何を指しているのかを明確にすることができ、後で式を理解しようとするときに役立ちます。
14.2.1.3. 式の使用例
フィールド計算機を使用して、既存の「total_pop」と「area_km2」フィールドを用いて「pop_density」フィールドを計算します:
"total_pop" / "area_km2"
面積に基づいてラベル付けやカテゴリ分けをします:
CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END
「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
住宅の平均価格が平方メートル当たり10000€より小さいか大きいかに応じて、すべての地物に分類したスタイルを適用します:
"price_m2" > 10000
「式で選択...」ツールを使用して、「高人口密度」エリアに相当し、加えて平方メートルあたりの住宅の平均価格が10000€よりも高くなるエリアのすべての地物を選択します:
"density_level" = 'High population density' and "price_m2" > 10000
この式は、どの地物をラベル付けするか、あるいはどの地物を地図に表示するかを定義するためにも使用できます。
ジオメトリジェネレータを使用して、レイヤに様々なシンボル（タイプ）を作成します:
point_on_surface( $geometry )
ポイント地物に対して、このジオメトリの周囲に閉じた輪を（
make_lineを使用して）生成します:make_line( -- using an array of points placed around the original array_foreach( -- list of angles for placing the projected points (every 90°) array:=generate_series( 0, 360, 90 ), -- translate the point 20 units in the given direction (angle) expression:=project( $geometry, distance:=20, azimuth:=radians( @element ) ) ) )印刷レイアウトのラベルにおいて、レイアウトの "Map 1" アイテム内にある "airports" 地物の名前を表示します:
with_variable( 'extent', map_get( item_variables( 'Map 1' ), 'map_extent' ), aggregate( 'airports', 'concatenate', "NAME", intersects( $geometry, @extent ), ' ,' ) )
14.2.1.4. 式の保存
式エディタフレームの上部にある 
現在の式をユーザー保存式に追加 ボタンを使用すると、簡単にアクセスしたい重要な式を保存することができます。この式は中央のパネルの ユーザー式 グループから利用することができます。ユーザー保存式はユーザープロファイル（ <userprofile>/QGIS/QGIS3.ini ファイル）内に保存され、現在のユーザープロファイルでのすべてのプロジェクト内のあらゆる式ダイアログで利用可能です。
式エディタフレームの上部にあるツール群を使用して、ユーザー式の管理ができます：
- 現在の式をユーザー保存式に追加 ：式をユーザープロファイル内に保存します。ラベルとヘルプ文を追加して、見つけやすいようにできます。
ユーザー保存式から選択した式を編集 では、式やヘルプ文、ラベルを編集できます。
選択した式をユーザー保存式から削除
ユーザー式をインポート は、 .jsonファイルからユーザー式をアクティブなユーザープロファイルのフォルダ内にインポートします。
ユーザー式をエクスポート は、ユーザー式を .jsonファイルとしてエクスポートします。ユーザープロファイルQGIS3.iniファイル内のユーザー式をすべて共有することができます。
14.2.2. 関数エディタ
関数エディタ タブでは、Python言語を使って独自の関数を書くことができます。これにより、定義済みの関数ではカバーできない特定のニーズに対処するための、便利で快適な手段を手に入れることができます。
図 14.66 関数エディタタブ
新しい関数を作成するには次のようにします。
新規ファイル ボタンをクリックします。フォームがポップアップしますので、使用する名前を入力して OK をクリックします。
入力した名前の新しいアイテムが 関数エディタ タブの左側のパネルに追加されます。これはQGISのテンプレートから生成されたPython
.pyファイルです。このファイルは現在有効になっている ユーザープロファイル のディレクトリ下の/python/expressionsフォルダに格納されます。右側のパネルはファイルの内容を表示します。最初はテンプレートのPythonスクリプトが表示されていますので、このコードやヘルプを必要に応じて書き換えてください。
関数の保存と読み込み ボタンをクリックします。あなたの書いた関数が 式 タブの関数ツリーの中に追加されます。デフォルトでは Customグループの中に追加されます。新しい関数を使いましょう。
関数に改善が必要なときは、 関数エディタ タブに戻って修正を加えた後、再度
関数の保存と読み込み ボタンをクリックして、ファイル内、つまりは任意の式タブで利用できるようにします。
カスタムPython関数はユーザープロファイルのディレクトリ下に格納されます。これはQGISが起動するたびに、現在のユーザープロファイルの下で定義されたすべての関数が自動的に読み込まれることを意味します。新しい関数は /python/expressions フォルダの中にのみ保存されて、プロジェクトファイルには保存されないことに注意してください。カスタム関数を使用したプロジェクトを共有するときは、 /python/expressions フォルダの .py ファイルも共有する必要があります。
カスタム関数を削除するには：
関数エディタ タブを有効にします。
リストから削除したい関数を選択します。
選択した関数ファイルを削除 ボタンを押します。関数がリストから削除され、対応する .pyファイルがユーザープロファイルフォルダから削除されます。
例
これは、2つの値を操作する独自の my_sum 関数を作成する簡単な例です。
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
関数デコレータの引数に args='auto' を使用した場合、その関数で必須となる引数の数は、Pythonで定義された関数の引数の個数から2を引いた数（ feature と parent を引いた数）になります。 group='Custom' 引数は、この関数が式ダイアログでどのグループにリストされるかを指定します。
次のようになキーワード引数を追加することも可能です：
usesgeometry=True：式が地物のジオメトリにアクセスする必要があるかどうか。デフォルトはFalseです。handlesnull=True：式がNULL値のカスタム処理を持つかどうか。False（デフォルト）の場合、任意のパラメータがNULLであるときには常に即座に結果がNULLとなります。referenced_columns=[list]：この関数が必要とする属性名の配列。デフォルトは[QgsFeatureRequest.ALL_ATTRIBUTES]です。
上記の例の関数は、次のように式中で使うことができます。
図 14.67 式タブに追加されたカスタム関数
Pythonコードの作成に関する詳しい情報は PyQGIS 開発者用 Cookbook で見つけることができます。