GQL 値と値型

この記事では、Microsoft Fabric のグラフの GQL 値と値型に関する包括的なリファレンスを提供します。

GQL 言語では、数値、文字列、グラフ要素など、さまざまな種類の値がサポートされています。 これらの値は、実行できる操作と、さまざまなコンテキストでの値の動作を定義する、値型と呼ばれるセットに編成されます。 型システムを理解することは、正しいクエリを記述し、実行時エラーを回避するために不可欠です。

主な概念:

• 値型 は 、null 値 を含めるか除外するかに応じて、null 許容型または マテリアル 型 (null 非許容) にすることができます。
• null 非許容値型 は、構文的に NOT NULLとして指定されます。
• 同じ値を 複数の値型 (ポリモーフィズム) に属させることができます。
• null 値 は、すべての null 許容値型のメンバーです。

値型の編成方法

すべての値型は、クエリで異なる目的を果たす 2 つの主要なカテゴリに分類されます。

• 定義済みの値型 - 数値、文字列、ブール値など、言語に組み込まれています。
• 構築された値型 - リストやパスなど、他の型から構成されます。

定義済みの値型は、さらに特殊なカテゴリに編成されます。

• ブール値の型 - 論理操作の True、false、および不明な値。
• 文字列値の型 - Unicode がサポートされているテキスト データ。
• 数値型 - 整数と浮動小数点数。
• テンポラル値の型 - タイムゾーンがサポートされている日付と時刻の値。
• 参照値の種類 - グラフ内のノードとエッジへの参照。
• 重要でない値の型 - null や nothing などの特殊な値。

等価性と比較のしくみ

GQL が値を比較する方法を理解することは、特にフィルター処理、並べ替え、結合を処理する場合に、効果的なクエリを記述するために重要です。

基本的な比較規則

• 通常、同じ種類の値を比較できます。
• 両方の値が数値の場合、GQLは数値で比較します。
• ノード参照とノード参照、エッジ参照とエッジ参照など、同じ種類のオブジェクトを参照する参照値のみを比較できます。

比較での Null 処理

任意の値を null と比較すると、結果は常に UNKNOWNされます。 Null 処理は、3 つの値を持つロジック原則に従います。 ORDER BY 比較とは別にヌル配置を扱います。 デフォルトでは、null値は昇順・降順の両方で最後にソートします。 NULLS FIRSTやNULLS LASTを使って、その配置を明確にコントロールしましょう。

区別と等価性

特定のステートメントは等価性をテストするのではなく、区別をテストします。 違いを理解することは、 DISTINCT や GROUP BYなどの操作にとって重要です。

区別テストは、1 つの重要な例外である等値と同じ規則に従います。 NULL は NULLとは区別されません。 区別は、 NULLを含む等値テストとは異なり、常に UNKNOWNになります。

次のステートメントでは、個別性テストを使用します。

• RETURN DISTINCT: 2 つの行が互いに重複しているかどうかを判断します。
• GROUP BY: 集計中に 2 つの行が同じグループ化キーに属しているかどうかを判断します。

両方の行の値が異なる列が少なくとも 1 つある場合、テーブルの 2 つの行は異なります。

ブール値型

ブール値は、 TRUE、 FALSE、 UNKNOWNの 3 つの値を持つロジックを使用します。

等価性のしくみ:

比較のしくみ:

FALSE が TRUE未満です。 UNKNOWNを含む比較では、UNKNOWNが発生します。

ブールリテラルを記述する方法:

• TRUE
• FALSE
• UNKNOWN または NULL

型構文:

BOOL [ NOT NULL ]

文字列値の型

文字列は Unicode コードポイントのシーケンスです (長さが 0 の場合もあります)。 空の文字列は null 値と同じではありません。

比較のしくみ:

文字列は、コードポイントの Unicode スカラー値を比較することによって比較されます。 この比較方法は、 UCS_BASIC 照合順序と呼ばれることもあります。

文字列リテラルを記述する方法:

文字を二重引用符 (") または単一引用符 (') で囲みます。

"Hello, World!"
'Guten Tag!'

文字列リテラルで特定の Unicode 制御文字を直接指定することはできません。 具体的には、Unicode 一般カテゴリ クラス "Cc" および "Cn" のすべての文字は許可されません。 代わりに、C スタイルの \エスケープを使用します。

GQL では、周囲の " と ' 文字を 2 倍にすることで、SQL スタイルのエスケープもサポートしています。

型構文:

STRING [ NOT NULL ]

数値型

正確な数値型

グラフは符号付き整数と符号なし整数の両方に対応しています。

比較のしくみ:

このシステムは、互換性のある正確な数値値を数値で比較します。

整数リテラルを記述する方法:

型構文:

INT [ NOT NULL ]
INT64 [ NOT NULL ]
UINT [ NOT NULL ]
UINT64 [ NOT NULL ]

INT 同じ数値型 INT64 指定します。 UINTとUINT64も行います。

近似数値型

Graph は、IEEE (電気電子学会) 754 互換浮動小数点数である概数をサポートしています。

比較のしくみ:

システムは、互換性のある近似数値値を数値で比較します。

浮動小数点リテラルを記述する方法:

数値に関するその他の考慮事項:

• オーバーフローおよびアンダーフロー:整数演算がサポート範囲を超えると、標準的なGQLSTATUS 22003でエラーが生じます。
• 精度: 浮動小数点演算では、IEEE 754 表現の制限により精度が失われる可能性があります。
• 特殊なfloat値:IEEE 754の特殊値のQuery API表現については 浮動小数点型 を参照してください。

型構文:

FLOAT [ NOT NULL ]
DOUBLE [ NOT NULL ]
FLOAT64 [ NOT NULL ]

DOUBLE、 FLOAT、および FLOAT64 はすべて同じ型を指定します。

テンポラル値型

Zoned datetime 値

ゾーン化された datetime 値は、ISO 8601 互換の datetime とタイムゾーン オフセットを表します。

比較のしくみ:

システムは、ゾーン化された datetime 値を、その絶対タイム ポイントで時系列的に比較します。

datetime リテラルを記述する方法:

タイムゾーン情報と共に ISO 8601 形式を使用します。

ZONED_DATETIME('2024-08-15T14:30:00+02:00')
ZONED_DATETIME('2024-08-15T12:30:00Z')
ZONED_DATETIME('2024-12-31T23:59:59.999-08:00')

型構文:

ZONED DATETIME [ NOT NULL ]

持続時間の値

持続時間の値はISO 8601の日中区間を表します。 ISO 8601の持続時間文字列を DURATIONに渡して作成します。

DURATION('P1DT2H30M')

持続時間の値は比較、加算、減算、スケーリングをサポートします。 ゾーン付きのデートタイムから期間を足したり引いたり、ゾーン付きのデートタイムを2つ引いたりして持続時間を導き出すことも可能です。

型構文:

DURATION [ NOT NULL ]

参照値の型

参照値には、一致するノードまたはエッジへの参照が含まれます。

ノード参照値

ノード参照値は、グラフ内の特定のノードへの参照を表します。 通常、これらの値は、ノードがグラフ パターンで一致する場合に取得されます。 これらの値を使用して、ノードのプロパティにアクセスし、比較を実行できます。

比較のしくみ:

ノード参照値を比較するのは等しい場合のみです。 2 つのノード参照値は、同じノードを参照している場合にのみ等しくなります。

Graph は、参照値に対する決定論的な順序を定義します。 ただし、この順序はクエリからクエリに変更される可能性があるため、運用環境のクエリではこれに依存しないでください。

プロパティにアクセスする方法:

ノードのプロパティにアクセスするには、ドット表記を使用します。

node_var.property_name

グラフ スキーマの抽象ノードの種類:

グラフ型を使用する場合は、継承の基本型として機能するが、直接インスタンス化できない抽象ノード型を定義します。 抽象型を使用すると、ポリモーフィックなクエリ パターンが有効になります。

-- Abstract base type (cannot be instantiated)
ABSTRACT
(:Person => {
  id :: INT64,
  name :: STRING,
  birth_date :: ZONED DATETIME
}),

-- Concrete types that inherit from abstract base
(:Employee => Person {
  employee_id :: STRING,
  department :: STRING,
  hire_date :: ZONED DATETIME
})

(:Customer => :Person {
  customer_id :: STRING,
  membership_level :: STRING,
  registration_date :: ZONED DATETIME
})

抽象型のポリモーフィック クエリ:

抽象型を使用すると、基本型と照合して派生型のすべてのインスタンスを検索する強力なクエリ パターンが可能になります。

-- Find all Person instances (both Employee and Customer)
MATCH (p:Person)
RETURN p.name, p.birthday, labels(p) AS label_names

-- Mixed type patterns
MATCH (e:Employee)-[:knows]-(c:Customer)
WHERE e.department = 'Sales' AND c.membership_level = 'Premium'
RETURN e.name AS sales_person, c.name AS customer

この方法では、グラフ スキーマで柔軟な継承ベースのデータ モデリングを有効にしながら、型の安全性が提供されます。

型構文:

NODE [ NOT NULL ]

グラフ エッジの参照値

グラフ のエッジ参照値は、グラフ内の特定のエッジへの参照を表します。 通常、これらの値は、グラフ パターンでエッジが一致する場合に取得されます。 これらの値を使用して、エッジ プロパティにアクセスし、比較を実行できます。

比較のしくみ:

比較できるのは、エッジ参照値と等価性のみです。 2 つのエッジ参照値は、同じエッジを参照している場合にのみ等しくなります。

プロパティにアクセスする方法:

エッジ プロパティにアクセスするには、ドット表記を使用します。

edge_var.property_name

型構文:

EDGE [ NOT NULL ]

重要ではない値の型

非マテリアル値型には、"通常の" マテリアル値は含まれません。

Null 値

null 値は、既知のマテリアル値がないことを表します。 これはすべての null 許容値型のメンバーであり、任意のマテリアル値とは異なります。 null 型の唯一の値です。

比較のしくみ:

値を null と比較すると、結果は UNKNOWN。

null リテラルを記述する方法:

NULL        -- type NULL
UNKNOWN     -- type BOOL

型構文:

NULL

Nothing 型

nothing 型は、値を含まない値型です。

技術的なように見えるかもしれませんが、nothing 型を使用すると、空のリスト値などの値に正確な型を割り当てることができます。 nothing 型を使用すると、リスト値型が必要な場所 (必要なリスト要素の型に関係なく) 空のリストを渡すことができます。

型構文:

NOTHING
NULL NOT NULL

(NOTHING と NULL NOT NULL は同じ型を指定します)

構築された値型

値を一覧表示する

リスト値は要素のシーケンスです。 リストには同じ型の要素を含め、null 値を含めることができます。

比較のしくみ:

リストは最初にサイズによって比較され、次に要素ごとに順番に比較されます。 サイズが同じで、対応するすべての要素が等しい場合、2 つのリストは等しくなります。

グループ リスト:

グループ リストは、一致する可変長エッジ パターンによってバインドされたリストです。 グラフは、その状態をグループ リストとして追跡します。

グループ リストは、水平集計で使用できます。 詳細については、「 GQL 式と関数」を参照してください。

リスト リテラルを記述する方法:

角かっこ表記を使用してリストを作成します。

[1, 2, 3, 4]
['hello', 'world']
[1.20m, 3.45m, NULL]
[]  -- empty list

要素にアクセスする方法:

リスト要素にアクセスするには、角かっこと 0 から始まるインデックスを使用します。

list_var[0]  -- first element
list_var[1]  -- second element

一般的なリスト操作:

-- Check if list contains a value
WHERE 'Engineering' IN employee.departments

-- List concatenation
RETURN [1, 2] || [3, 4]  -- [1, 2, 3, 4]

-- List size
size(list_var)

-- Test elements against a predicate
ANY(element IN list_var WHERE element IS NOT NULL)

ALL、ANY、NONE、SINGLEのリスト述語関数を使って、条件を満たすリスト要素の数を検証します。

型構文:

LIST<element_type> [ NOT NULL ]
LIST<element_type NOT NULL> [ NOT NULL ]

ここで、 element_type は、STRING、INT64、DOUBLE、BOOL など、サポートされている任意の型にすることができます。

パス値

パス値は、グラフ内で一致するパスを表します。 パス値には、ノード参照値で常に開始および終了する、交互のノードとエッジ参照値の空でないシーケンスが含まれます。 これらの参照値は、グラフ内の最初に一致したパスのノードとエッジを識別します。

パスの構造:

パスは次で構成されます。

• ノードとエッジのシーケンス: node₁ - edge₁ - node₂ - edge₂ - ... - nodeₙ
• 常にノードで開始および終了します。
• 少なくとも 1 つのノードが含まれています (パスの最小長は 0 エッジです)。

比較のしくみ:

等式のためにパス値を比較し、ソートキーとして使うことができます。 同じノードとエッジの参照列を含む2つのパス値は等しいとされます。 クエリ間の異なるパスの相対的なソート順に頼らないでください。

型構文:

PATH [ NOT NULL ]

型変換とキャスト

GQL では、型の安全性を維持しながら柔軟な操作を可能にするために、暗黙的な型変換と明示的な型変換の両方がサポートされています。

暗黙的な変換

ある数値型は、ある式が共通型を必要とする場合に暗黙的に変換できます:

• 整数と浮動小数点:整数は近似的な数値型に変換されます。

明示的なキャスト

互換性のある型間で値を明示的に変換するには、 CAST 関数を使用します。

CAST(value AS target_type)

例:

CAST(123 AS STRING)           -- "123"
CAST('456' AS INT64)          -- 456
CAST(3.14 AS STRING)          -- "3.14"
CAST('true' AS BOOL)          -- TRUE
CAST(-42.9m AS INT64)         -- -42
CAST(1.20m AS STRING)         -- "1.20"

キャストルール:

• 文字列へ: ほとんどの値型は、リテラル表現を使用して STRING にキャストできます。
• BOOL へ: 文字列 'true' または 'false' (大文字と小文字を区別しない) をブール値にキャストできます。
• 無効なキャスト: 互換性のない値をキャストしようとすると、ランタイム エラーが発生します。

関連コンテンツ

• GQL 言語ガイド
• GQL の式と関数
• GQL グラフの種類
• GQL クエリAPIの値符号化