配列関数のリファレンス

配列関数

名前 説明
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

説明:

valuearray に含まれている場合は 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_valuesarray に含まれている場合は 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

説明:

arraysearch_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 は最後の要素です。
  • arrayARRAY 型でなく null でもない場合は、エラーを返します。
  • index が範囲外の場合、関数は欠損値を返します。
  • indexINT64 型でない場合、この関数はエラーを返します。

例:

配列 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
Android
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayReverse().alias("reversedGenres")) .execute();
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 を最後の要素として、配列の末尾からの開始位置を示します。
  • lengthoffset 後に配列に残っている要素の数より大きい場合、結果は配列の末尾まで拡張されます。
  • 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 のすべての要素、delimiternull_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" エラー

次のステップ