ELEMENT_AT

説明

ELEMENT_AT 関数は、指定した位置またはキーに基づき、配列、マップ、構造体、VARIANT から要素の値を取り出します。

• ARRAY に適用すると、指定した位置の要素を返します。
• MAP に適用すると、指定したキーに対応する値を返します。
• STRUCT に適用すると、指定した位置 (1 始まり) またはフィールド名のサブフィールドを返します。STRUCT_ELEMENT と同等です。
• VARIANT に適用すると、指定したサブフィールドの値を返します。

構文

ELEMENT_AT(container, key_or_index)

パラメータ

• container: ARRAY、MAP、STRUCT、VARIANT のいずれかです。
• key_or_index:
  • ARRAY: 1 から始まる整数インデックスです。
  • MAP: キー型 (K) の値です。MAP でサポートされる任意のプリミティブ型を使用できます。
  • STRUCT: 1 から始まる定数の整数フィールド位置、または定数の文字列フィールド名です。名前の照合では大文字と小文字を区別しません。
  • VARIANT: 文字列型です。

戻り値

• ARRAY: 指定したインデックスの要素 (T 型) を返します。
• MAP: 指定したキーに対応する値 (V 型) を返します。
• STRUCT: 指定したサブフィールドの値を返します。
• VARIANT: VARIANT 型の値を返します。
• インデックスまたはキーが存在しない場合は NULL を返します。ただし、STRUCT の位置が範囲外、またはフィールド名が存在しない場合はエラーになります。
• パラメータが NULL の場合は NULL を返します。

注意事項

1. 配列のインデックスは 0 ではなく 1 から始まります。
2. 負のインデックスも使用できます。-1 は最後の要素、-2 は末尾から二番目の要素を表します。
3. ELEMENT_AT(container, key_or_index) は container[key_or_index] と同じように動作します (例を参照)。

例

1. ELEMENT_AT 関数は [] と同じように動作する。

   SELECT ELEMENT_AT([1, 2, 3], 2);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 2) |
   +--------------------------+
   |                        2 |
   +--------------------------+
   
   SELECT [1, 2, 3][2];
   +--------------+
   | [1, 2, 3][2] |
   +--------------+
   |            2 |
   +--------------+

2. 配列のインデックスは 1 から始まり、範囲外の参照では NULL を返す。

   SELECT ELEMENT_AT([1, 2, 3], 0);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 0) |
   +--------------------------+
   |                     NULL |
   +--------------------------+
   
   SELECT ELEMENT_AT([1, 2, 3], 4);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 4) |
   +--------------------------+
   |                     NULL |
   +--------------------------+

3. MAP に存在しないキーを指定すると NULL を返す。

   SELECT ELEMENT_AT({"a": 1, "b": 2}, "c");
   +-----------------------------------+
   | ELEMENT_AT({"a": 1, "b": 2}, "c") |
   +-----------------------------------+
   |                              NULL |
   +-----------------------------------+

4. STRUCT のサブフィールドを位置またはフィールド名で参照する (STRUCT_ELEMENT と同等)。

   SELECT ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1);
   +------------------------------------------------------------+
   | ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1) |
   +------------------------------------------------------------+
   | Jack                                                       |
   +------------------------------------------------------------+
   
   SELECT NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'];
   +--------------------------------------------------+
   | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
   +--------------------------------------------------+
   |                                          1728923 |
   +--------------------------------------------------+

5. VARIANT のサブフィールドを参照するとき、VARIANT 値が OBJECT でない場合は空の値を返す。

   SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");
   +------------------------------------------------------+
   | ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a") |
   +------------------------------------------------------+
   | 1                                                    |
   +------------------------------------------------------+
   
   SELECT ELEMENT_AT(CAST('123' AS VARIANT), "");
   +----------------------------------------+
   | ELEMENT_AT(CAST('123' AS VARIANT), "") |
   +----------------------------------------+
   |                                        |
   +----------------------------------------+