配列関数のリファレンス
配列関数
| 名前 | 説明 |
ARRAY
|
入力引数ごとに 1 つの要素を含む ARRAY を返します。
|
ARRAY_CONCAT
|
複数の配列を 1 つの ARRAY に連結します。 |
ARRAY_CONTAINS
|
指定された ARRAY に特定の値が含まれている場合、TRUE を返します。 |
ARRAY_CONTAINS_ALL
|
すべての値が ARRAY に存在する場合、TRUE を返します。 |
ARRAY_CONTAINS_ANY
|
値のいずれかが ARRAY に存在する場合、TRUE を返します。 |
ARRAY_FILTER
|
述語を満たさない ARRAY の要素を除外します。 |
ARRAY_FIRST
|
ARRAY 内の最初の要素を返します。 |
ARRAY_FIRST_N
|
ARRAY 内の最初の n 個の要素を返します |
ARRAY_GET
|
ARRAY 内の指定されたインデックスにある要素を返します。
|
ARRAY_INDEX_OF
|
ARRAY 内で最初に出現する値のインデックスを返します。 |
ARRAY_INDEX_OF_ALL
|
ARRAY 内の値のすべてのインデックスを返します。 |
ARRAY_LENGTH
|
ARRAY 内の要素数を返します。 |
ARRAY_LAST
|
ARRAY 内の最後の要素を返します |
ARRAY_LAST_N
|
ARRAY 内の最後の n 個の要素を返します |
ARRAY_REVERSE
|
ARRAY 内の要素の順序を逆にします。 |
ARRAY_SLICE
|
ARRAY のスライスを返します。 |
ARRAY_TRANSFORM
|
ARRAY の各要素に式を適用して、要素を変換します。 |
MAXIMUM
|
ARRAY 内の最大値を返します。 |
MAXIMUM_N
|
ARRAY 内で n 番目に大きい値を返します。 |
MINIMUM
|
ARRAY 内の最小値を返します。 |
MINIMUM_N
|
ARRAY 内で n 番目に小さい値を返します。 |
SUM
|
ARRAY 内のすべての NUMERIC 値の合計を返します。 |
JOIN
|
ARRAY 内の要素の連結を STRING 値として生成します。
|
ARRAY
構文:
array(values: ANY...) -> ARRAY
説明:
指定された要素から配列を作成します。
- 引数が存在しない場合、結果の配列では
NULLに置き換えられます。
例:
| values | array(values) |
|---|---|
| () | [] |
| (1, 2, 3) | [1, 2, 3] |
| ("a", 1, true) | ["a", 1, true] |
| (1, null) | [1, null] |
| (1, [2, 3]) | [1, [2, 3]] |
ARRAY_CONCAT
構文:
array_concat(arrays: ARRAY...) -> ARRAY
説明:
2 つ以上の配列を 1 つの ARRAY に連結します。
例:
| arrays | array_concat(arrays) |
|---|---|
| ([1, 2], [3, 4]) | [1, 2, 3, 4] |
| (["a", "b"], ["c"]) | ["a", "b", "c"] |
| ([1], [2], [3]) | [1, 2, 3] |
| ([], [1, 2]) | [1, 2] |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres")) .execute();
Swift
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres")) .execute()
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_concat(Field.of("subGenre")).as_("allGenres")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres")) .execute() .get();
ARRAY_CONTAINS
構文:
array_contains(array: ARRAY, value: ANY) -> BOOLEAN
説明:
value が array に含まれている場合は TRUE、それ以外の場合は FALSE を返します。
例:
| 配列 | 値 | array_contains(array, value) |
|---|---|---|
| [1, 2, 3] | 2 | true |
| [[1, 2], [3]] | [1, 2] | true |
| [1, null] | null | true |
| "abc" | 任意 | エラー |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayContains(constant("mystery")).as("isMystery")) .execute();
ウェブ
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayContains(constant("mystery")).as("isMystery")) );
Swift
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayContains("mystery").alias("isMystery")) .execute()
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayContains("mystery").alias("isMystery")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_contains("mystery").as_("isMystery")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayContains(field("genre"), "mystery").as("isMystery")) .execute() .get();
ARRAY_CONTAINS_ALL
構文:
array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN
説明:
すべての search_values が array に含まれている場合は TRUE、それ以外の場合は FALSE を返します。
例:
| 配列 | search_values | array_contains_all(array, search_values) |
|---|---|---|
| [1, 2, 3] | [1, 2] | true |
| [1, 2, 3] | [1, 4] | false |
| [1, null] | [null] | true |
| [NaN] | [NaN] | true |
| [] | [] | true |
| [1, 2, 3] | [] | true |
Node.js
const result = await db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll([constant("fantasy"), constant("adventure")]) .as("isFantasyAdventure") ) .execute();
ウェブ
const result = await execute(db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll([constant("fantasy"), constant("adventure")]) .as("isFantasyAdventure") ) );
Swift
let result = try await db.pipeline() .collection("books") .select([ Field("genre") .arrayContainsAll([Constant("fantasy"), Constant("adventure")]) .as("isFantasyAdventure") ]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll(listOf("fantasy", "adventure")) .alias("isFantasyAdventure") ) .execute()
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll(Arrays.asList("fantasy", "adventure")) .alias("isFantasyAdventure") ) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select( Field.of("genre") .array_contains_all(["fantasy", "adventure"]) .as_("isFantasyAdventure") ) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select( arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure")) .as("isFantasyAdventure")) .execute() .get();
ARRAY_CONTAINS_ANY
構文:
array_contains_any(array: ARRAY, search_values: ARRAY) -> BOOLEAN
説明:
array に search_values のいずれかが含まれている場合は TRUE を返し、それ以外の場合は FALSE を返します。
例:
| 配列 | search_values | array_contains_any(array, search_values) |
|---|---|---|
| [1, 2, 3] | [4, 1] | true |
| [1, 2, 3] | [4, 5] | false |
| [1, 2, null] | [null] | true |
Node.js
const result = await db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny([constant("fantasy"), constant("nonfiction")]) .as("isMysteryOrFantasy") ) .execute();
ウェブ
const result = await execute(db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny([constant("fantasy"), constant("nonfiction")]) .as("isMysteryOrFantasy") ) );
Swift
let result = try await db.pipeline() .collection("books") .select([ Field("genre") .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")]) .as("isMysteryOrFantasy") ]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny(listOf("fantasy", "nonfiction")) .alias("isMysteryOrFantasy") ) .execute()
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny(Arrays.asList("fantasy", "nonfiction")) .alias("isMysteryOrFantasy") ) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select( Field.of("genre") .array_contains_any(["fantasy", "nonfiction"]) .as_("isMysteryOrFantasy") ) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select( arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction")) .as("isMysteryOrFantasy")) .execute() .get();
ARRAY_FILTER
構文:
array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY
説明:
predicate 式を使用して array をフィルタリングし、述語を満たす要素のみを含む新しい配列を返します。
arrayの要素ごとにpredicateが評価されます。trueを返した場合、要素が結果に含まれます。それ以外の場合(falseまたはnullを返した場合)、要素は省略されます。predicateが非ブール値または null 以外の値に評価される場合、関数はエラーを返します。
例:
| 配列 | predicate | array_filter(array, predicate) |
|---|---|---|
| [1, 2, 3] | x -> x > 1 | [2, 3] |
| [1, null, 3] | x -> x > 1 | [3] |
| ["a", "b", "c"] | x -> x != "b" | ["a", "c"] |
| [] | x -> true | [] |
ARRAY_GET
構文:
array_get(array: ARRAY, index: INT64) -> ANY
説明:
array 内の 0 ベースの index にある要素を返します。
indexが負の場合、配列の末尾から要素にアクセスします。ここで、-1は最後の要素です。arrayがARRAY型でなくnullでもない場合は、エラーを返します。indexが範囲外の場合、関数は欠損値を返します。indexがINT64型でない場合、この関数はエラーを返します。
例:
| 配列 | index | array_get(array, index) |
|---|---|---|
| [1, 2, 3] | 0 | 1 |
| [1, 2, 3] | -1 | 3 |
| [1, 2, 3] | 3 | 欠損 |
| [1, 2, 3] | -4 | 欠損 |
| "abc" | 0 | エラー |
| null | 0 | null |
Array |
"a" | エラー |
Array |
2.0 | エラー |
ARRAY_LENGTH
構文:
array_length(array: ARRAY) -> INT64
説明:
array 内の要素数を返します。
例:
| 配列 | array_length(array) |
|---|---|
| [1, 2, 3] | 3 |
| [] | 0 |
| [1, 1, 1] | 3 |
| [1, null] | 2 |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayLength().as("genreCount")) .execute();
ウェブ
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayLength().as("genreCount")) );
Swift
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayLength().as("genreCount")]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayLength().alias("genreCount")) .execute()
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayLength().alias("genreCount")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_length().as_("genreCount")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayLength(field("genre")).as("genreCount")) .execute() .get();
ARRAY_REVERSE
構文:
array_reverse(array: ARRAY) -> ARRAY
説明:
指定された array を逆順にします。
例:
| 配列 | array_reverse(array) |
|---|---|
| [1, 2, 3] | [3, 2, 1] |
| ["a", "b"] | ["b", "a"] |
| [1, 2, 2, 3] | [3, 2, 2, 1] |
Node.js
const result = await db.pipeline() .collection("books") .select(arrayReverse(field("genre")).as("reversedGenres")) .execute();
ウェブ
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayReverse().as("reversedGenres")) );
Swift
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayReverse().as("reversedGenres")]) .execute()
Kotlin
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayReverse().alias("reversedGenres")) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayReverse().alias("reversedGenres")) .execute();
Android
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_reverse().as_("reversedGenres")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayReverse(field("genre")).as("reversedGenres")) .execute() .get();
ARRAY_FIRST
構文:
array_first(array: ARRAY) -> ANY
説明:
array 内の最初の要素を返します。array_get(array, 0) と同じです。
arrayが空の場合、欠損値を返します。
例:
| 配列 | array_first(array) |
|---|---|
| [1, 2, 3] | 1 |
| [] | 欠損 |
ARRAY_FIRST_N
構文:
array_first_n(array: ARRAY, n: INT64) -> ARRAY
説明:
array の最初の n 個の要素を返します。array_slice(array, 0, n) と同じです。
nが負の場合、エラーが返されます。
例:
| 配列 | n | array_first_n(array, n) |
|---|---|---|
| [1, 2, 3, 4, 5] | 3 | [1, 2, 3] |
| [1, 2] | 3 | [1, 2] |
| [1, 2, 3] | 0 | [] |
ARRAY_INDEX_OF
構文:
array_index_of(array: ARRAY, value: ANY) -> INT64
説明:
array 内で最初に value が出現する位置の 0 ベース インデックスを返します。value が見つからない場合は -1 を返します。
例:
| 配列 | 値 | array_index_of(array, value) |
|---|---|---|
| [1, 2, 3, 2] | 2 | 1 |
| [1, 2, 3] | 4 | -1 |
| [1, null, 3] | null | 1 |
ARRAY_INDEX_OF_ALL
構文:
array_index_of_all(array: ARRAY, value: ANY) -> ARRAY<INT64>
説明:
array 内で value が出現するすべての位置の 0 ベース インデックスを含む配列を返します。value が見つからない場合は [] を返します。
例:
| 配列 | 値 | array_index_of_all(array, value) |
|---|---|---|
| [1, 2, 3, 2] | 2 | [1, 3] |
| [1, 2, 3] | 4 | [] |
| [1, null, 3, null] | null | [1, 3] |
ARRAY_LAST
構文:
array_last(array: ARRAY) -> ANY
説明:
array 内の最後の要素を返します。array_get(array, -1) と同じです。
arrayが空の場合、欠損値を返します。
例:
| 配列 | array_last(array) |
|---|---|
| [1, 2, 3] | 3 |
| [] | 欠損 |
ARRAY_LAST_N
構文:
array_last_n(array: ARRAY, n: INT64) -> ARRAY
説明:
array の最後の n 個の要素を返します。
nが負の場合、エラーが返されます。
例:
| 配列 | n | array_last_n(array, n) |
|---|---|---|
| [1, 2, 3, 4, 5] | 3 | [3, 4, 5] |
| [1, 2] | 3 | [1, 2] |
| [1, 2, 3] | 0 | [] |
ARRAY_SLICE
構文:
array_slice(array: ARRAY, offset: INT64, length: INT64) -> ARRAY
説明:
0 ベース インデックス offset から始まり、length 個の要素を含む array のサブセットを返します。
offsetが負の場合、-1を最後の要素として、配列の末尾からの開始位置を示します。lengthがoffset後に配列に残っている要素の数より大きい場合、結果は配列の末尾まで拡張されます。lengthは負でない値にする必要があります。それ以外の場合はエラーを返します。
例:
| 配列 | offset | 長さ | array_slice(array, offset, length) |
|---|---|---|---|
| [1, 2, 3, 4, 5] | 1 | 3 | [2, 3, 4] |
| [1, 2, 3, 4, 5] | -2 | 2 | [4, 5] |
| [1, 2, 3] | 1 | 5 | [2, 3] |
| [1, 2, 3] | 3 | 2 | [] |
ARRAY_TRANSFORM
構文:
array_transform(array: ARRAY, expression: (ANY) -> ANY) -> ARRAY
array_transform(array: ARRAY, expression: (ANY, INT64) -> ANY) -> ARRAY
説明:
expression を各要素に適用して array を変換し、変換された要素を含む新しい配列を返します。出力配列のサイズは常に入力配列と同じになります。
expressionは、単項関数element -> resultまたは二項関数(element, index) -> resultになります。expressionが単項の場合、arrayの各要素を使用して呼び出されます。expressionがバイナリの場合、arrayの各要素とその対応する 0 ベース インデックスを使用して呼び出されます。
例:
| 配列 | 式 | array_transform(array, expression) |
|---|---|---|
| [1, 2, 3] | x -> x * 2 | [2, 4, 6] |
| [1, 2, 3] | x -> x + 1 | [2, 3, 4] |
| [10, 20] | (x, i) -> x + i | [10, 21] |
| [] | x -> 1 | [] |
MAXIMUM
構文:
maximum(array: ARRAY) -> ANY
説明:
array 内の最大値を返します。
- 比較時には
NULL値は無視されます。 arrayが空の場合、またはNULL値のみが含まれている場合は、NULLを返します。
例:
| 配列 | maximum(array) |
|---|---|
| [1, 5, 2] | 5 |
| [1, null, 5] | 5 |
| ["a", "c", "b"] | "c" |
| [null, null] | null |
| [] | null |
MAXIMUM_N
構文:
maximum_n(array: ARRAY, n: INT64) -> ARRAY
説明:
array 内で n 番目に大きい値を降順で配列として返します。
NULL値は無視されます。nが負の場合、エラーが返されます。
例:
| 配列 | n | maximum_n(array, n) |
|---|---|---|
| [1, 5, 2, 4, 3] | 3 | [5, 4, 3] |
| [1, null, 5] | 3 | [5, 1] |
MINIMUM
構文:
minimum(array: ARRAY) -> ANY
説明:
array の最小値を返します。
- 比較時には
NULL値は無視されます。 arrayが空の場合、またはNULL値のみが含まれている場合は、NULLを返します。
例:
| 配列 | minimum(array) |
|---|---|
| [1, 5, 2] | 1 |
| [5, null, 1] | 1 |
| ["a", "c", "b"] | "a" |
| [null, null] | null |
| [] | null |
MINIMUM_N
構文:
minimum_n(array: ARRAY, n: INT64) -> ARRAY
説明:
array の中で n 番目に小さい値を昇順で配列として返します。
NULL値は無視されます。nが負の場合、エラーが返されます。
例:
| 配列 | n | minimum_n(array, n) |
|---|---|---|
| [1, 5, 2, 4, 3] | 3 | [1, 2, 3] |
| [5, null, 1] | 3 | [1, 5] |
SUM
構文:
sum(array: ARRAY) -> INT64 | FLOAT64
説明:
ARRAY 内のすべての NUMERIC 値の合計を返します。
- 配列内の数値以外の値は無視されます。
- 配列内のいずれかの数値が
NaNである場合、関数はNaNを返します。 - 戻り値の型は、配列内の最も広い数値型によって決まります(
INT64<FLOAT64)。 - 浮動小数点値を合計する前に 64 ビット整数オーバーフローが発生すると、エラーが返されます。浮動小数点値を合計してオーバーフローが発生した場合、正または負の無限大になります。
- 配列に数値がまったく含まれていない場合、
NULLを返します。
例:
| 配列 | sum(array) |
|---|---|
| [1, 2, 3] | 6L |
| [1L, 2L, 3L] | 6L |
| [2000000000, 2000000000] | 4000000000L |
| [10, 20.5] | 30.5 |
| [1, "a", 2] | 3L |
| [INT64.MAX_VALUE, 1] | エラー |
| [INT64.MAX_VALUE, 1, -1.0] | エラー |
| [INT64.MAX_VALUE, 1.0] | 9.223372036854776e+18 |
参加
構文:
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING
説明:
array 内の要素の連結を STRING として返します。array には STRING または BYTES のデータ型を指定できます。
arrayのすべての要素、delimiter、null_textは同じ型である必要があります。すべてSTRINGまたはすべてBYTESである必要があります。null_textが指定されている場合、array内のNULL値はすべてnull_textに置き換えられます。null_textが指定されていない場合、array内のNULL値は結果から除外されます。
例:
null_text が指定されていない場合:
| 配列 | 区切り文字 | join(array, delimiter) |
|---|---|---|
| ["a", "b", "c"] | "," | "a,b,c" |
| ["a", null, "c"] | "," | "a,c" |
| [b'a', b'b', b'c'] | b',' | b'a,b,c' |
| ["a", b'c'] | "," | エラー |
| ["a", "c"] | b',' | エラー |
| [b'a', b'c'] | "," | エラー |
null_text が指定されている場合:
| 配列 | 区切り文字 | null_text | join(array, delimiter, null_text) |
|---|---|---|---|
| ["a", null, "c"] | "," | "MISSING" | "a,MISSING,c" |
| [b'a', null, b'c'] | b',' | b'NULL' | b'a,NULL,c' |
| [null, "b", null] | "," | "MISSING" | "MISSING,b,MISSING" |
| [b'a', null, null] | b',' | b'NULL' | b'a,NULL,NULL' |
| ["a", null] | "," | b'N' | エラー |
| [b'a', null] | b',' | "N" | エラー |
次のステップ
- パイプライン クエリの概要をご覧ください。