13.1. 式
レイヤのデータと組み込みの関数やユーザー定義の関数に基づいた 式 は、属性値やジオメトリ、変数を操作する強力な方法です。ジオメトリのスタイル、ラベルの内容や位置、ダイアグラムの値、レイアウトアイテムの高さ、地物の一部の選択、仮想フィールドの作成などを動的に変更することができます。
注釈
式の作成に使えるデフォルトの関数や変数のリストは、詳細な情報や例付きで 関数のリスト にあります。
13.1.1. 式文字列ビルダー
式を組み立てるための主要なダイアログである 式文字列ビルダー は、QGISの多くの部分から使用することができますが、特に以下のような時に使うことができます。
ボタンをクリックしたとき
式による地物選択... ツールで 地物を選択 するとき例えば
フィールド計算機 ツールで 属性を編集する とき
データによって定義された上書き ツールを使用して、シンボロジやラベル、レイアウトアイテムのパラメータを操作するとき（ データによって定義された上書きの設定 参照）ジオメトリジェネレータ のシンボルレイヤを作成するとき
何らかの ジオプロセシング を行うとき
式ビルダーダイアログからは、以下のタブにアクセス可能です。
13.1.1.1. インターフェース
式 タブには関数やレイヤのフィールド、値を使用して式を作成するためのメインのインターフェースがあります。これには、以下のウィジェットが含まれます：
図 13.1 式タブ
式を入力したり張り付けたりするための式エディタ領域。以下のような自動補完を利用でき、式の入力を短縮できます：
入力したテキストに応じた変数名、関数名、フィールド名が下に表示されます。 Up 矢印キーと Down 矢印キーを使って項目間を移動することができます。式に挿入するには Tab キーを押すか、挿入したい項目を単にクリックします。
関数を入力している間、関数のパラメータが表示されます。
また、QGISは式が正しいかをチェックし、エラーを以下の方法で強調表示します：
アンダーライン ：未定義の関数や、間違ったあるいは無効な引数
マーカー ：単一の場所でのその他エラー（対応していない括弧、不要な文字など）
Tip
コメントで式をドキュメンテーションする
複雑な式を使用する場合には、思い出しやすいように複数行コメントやインラインコメントとしてテキストを追加するのがよいでしょう。
/* 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 )式エディタの上部には、以下のようなツールセットがあります：
式エディタをクリアユーザー式 を作成、管理する
式エディタの下部には、以下のものがあります：
式を構築するのに役立つ基本的な演算子のセット
データで地物のプロパティを決める際に、出力の期待されるフォーマットの表示
デフォルトでレイヤの最初の地物で評価された、式のライブ プレビュー (最大60文字) 。60文字を超える出力プレビューテキストを表示するには、テキストにカーソルを合わせ、出力プレビュー全体を含むツールチップのポップアップを表示します。出力プレビューテキストをクリップボードにコピーするには、出力プレビューテキストを右クリックして、
式の値をコピー を選択します。レイヤの他の地物は、 地物 コンボボックスを使って閲覧・評価することができます（値はレイヤの 表示名 プロパティから取得されます）。
エラーとなった場合には、エラーが表示され、ハイパーリンクからエラーの詳細情報にアクセスできます。
関数セレクタには、関数や変数、フィールドなどのグループ化されたリストが表示されます。検索ボックスを利用して、リストをフィルタし特定の関数やフィールドを素早く見つけることができます。アイテムをダブルクリックすると、そのアイテムが式エディタに追加されます。
ヘルプパネルには、関数セレクタで選択したアイテムに対するヘルプが表示されます。
Tip
式内で関数名にカーソルを乗せて Ctrl+Click すると、ダイアログでその関数のヘルプが表示されます。
関数セレクタでフィールドを選択している場合には、フィールドの値ウィジェットが表示され、以下のように地物の属性値の取得に役立ちます。
特定のフィールド値を検索する
全ユニーク または 10個のサンプル 値のリストを表示する。これはフィールドの右クリックからも利用できます。
フィールドが他のレイヤや値のセットにマッピングされている場合、すなわち、 フィールド編集ウィジェット が リレーションの参照 、 値のリレーション または バリューマップ タイプの場合には、（参照されたレイヤ、テーブル、リストから）マッピングされたフィールドの値をすべてリストすることができます。さらに、このリストをフィルタリングして、現在のフィールドで
使用中の値のみ表示 することもできます。
ウィジェット内でフィールド値をダブルクリックすると、式エディタに値が追加されます。
Tip
関数のヘルプやフィールドの値が表示される右側パネルは、ダイアログ内でたたむ（非表示にする）ことができます。 値を表示 や ヘルプを表示 ボタンを押すと、非表示状態から表示状態に戻すことができます。
13.1.1.2. 式の作成
QGISの式は、地物の選択や値の設定に使われます。QGISで式を作成するには、以下のいくつかのルールに従います。
ダイアログでコンテキストを定義する: SQLに慣れているならば、 select features from layer where condition や、 update layer set field = new_value where condition といった形式のクエリを知っているでしょう。QGIS式もこれらの情報すべてを必要としますが、式ビルダーダイアログを開くためのツールが、必要な情報の一部を提供します。例えば、あるレイヤ（
buildings）が、あるフィールド（height）を持っているとします:- 式による地物選択 ツールを押すことは、 "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.
Tip
名前付きパラメータを使用して式を読みやすくする
いくつかの関数は多数のパラメータを設定する必要があります。式エンジンは名前付きパラメータの使用をサポートしています。つまり、暗号めいた式 clamp( 1, 2, 9) と書く代わりに、 clamp( min:=1, value:=2, max:=9) を使うことができます。引数を入れ替え、例えば clamp( value:=2, max:=9, min:=1) とすることもできます。名前付きパラメータを使うことで、式の関数の引数が何を指しているのかを明確にすることができ、後で式を理解しようとするときに役立ちます。
13.1.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
「式による地物選択...」ツールを使用して、“High population density” に相当し、加えて平方メートルあたりの住宅の平均価格が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 ), ' ,' ) )
13.1.1.4. 式の保存
式エディタフレームの上部にある 
現在の式をユーザー保存式に追加 ボタンを使用すると、簡単にアクセスしたい重要な式を保存することができます。この式は中央のパネルの ユーザー式 グループから利用することができます。ユーザー保存式は ユーザープロファイル （ <userprofile>/QGIS/QGIS3.ini ファイル）内に保存され、あらゆるプロジェクトで現在のユーザープロファイルを使用すれば、すべての式ダイアログで利用可能です。
式エディタフレームの上部にあるツール群を使用して、ユーザー式の管理ができます：
- 現在の式をユーザー保存式に追加 ：式をユーザープロファイル内に保存します。ラベルとヘルプ文を追加して、識別しやすくできます。
ユーザー保存式から選択した式を編集 は、式やヘルプ文、ラベルを編集できます。
選択した式をユーザー保存式から削除
ユーザー式をインポート は、 .jsonファイルからユーザー式をアクティブなユーザープロファイルのフォルダ内にインポートします。
ユーザー式をエクスポート は、ユーザー式を .jsonファイルとしてエクスポートします。ユーザープロファイルQGIS3.iniファイル内のユーザー式をすべて共有することができます。
13.1.2. 関数エディタ
関数エディタ タブでは、Python言語を使って独自の関数を書くことができます。これにより、定義済みの関数ではカバーできない特定のニーズに対処するための、手軽で簡単な手段を手に入れることができます。
図 13.2 関数エディタタブ
新しい関数を作成するには次のようにします。
新規ファイル ボタンをクリックします。フォームがポップアップするので、使用する名前を入力して 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
@qgsfunction デコレーターは次の引数を受け取ります:
args: 引数の数。args='auto'を使用すると、必要な関数の引数の数は、Pythonで関数が定義されている引数の数（マイナス2 -featureとparent）から計算されます。args = -1とすると、任意の数の引数を受け取ることができます。引数
groupは、式ダイアログで関数をリストするグループを示します。usesgeometry=True：式が地物のジオメトリにアクセスする必要があるかどうか。デフォルトはFalseです。handlesnull=True：式がNULL値のカスタム処理を持つかどうか。False（デフォルト）の場合、任意のパラメータがNULLであるときには常に即座に結果がNULLとなります。referenced_columns=[list]：この関数が必要とする属性名の配列。デフォルトは[QgsFeatureRequest.ALL_ATTRIBUTES]です。
この関数自体には次のような引数があります:
関数に渡したい任意の数と型のパラメータは、以下の引数よりも前に設定します。
feature: 現在の地物parent:QgsExpressionオブジェクトcontext: 最後の位置にcontextという引数がある場合、この変数にはQgsExpressionContextオブジェクトが含まれ、式変数のような様々な追加情報へのアクセスを可能にします。例context.variable( 'layer_id' )
上記の例の関数は、次のように式中で使うことができます。
図 13.3 式タブに追加されたカスタム関数
Pythonコードの作成に関する詳しい情報は PyQGIS 開発者用 Cookbook で見つけることができます。