陣列函式參考資料

陣列函式

名稱	說明
`ARRAY`	傳回 `ARRAY`，其中每個輸入引數都包含一個元素
`ARRAY_CONCAT`	將多個陣列連結成單一 `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` 的最小 `n` 值
`SUM`	傳回 `ARRAY` 中所有 `NUMERIC` 值的總和。
`JOIN`	產生 `ARRAY` 中元素的串連結果，做為 `STRING` 值。

ARRAY

語法：

array(values: ANY...) -> ARRAY

說明：

根據指定元素建構陣列。

如果引數不存在，結果陣列會以 NULL 取代。

範例：

值	`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

說明：

將兩個以上的陣列串連成單一 ARRAY。

範例：

陣列	`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();test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute()DocSnippets.kt

Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres"))
        .execute()
        .get();PipelineSnippets.java

ARRAY_CONTAINS

語法：

array_contains(array: ARRAY, value: ANY) -> BOOLEAN

說明：

如果在 array 中找到 value，則傳回 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();test.firestore.js

網頁

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute()DocSnippets.kt

Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayContains(field("genre"), "mystery").as("isMystery"))
        .execute()
        .get();PipelineSnippets.java

ARRAY_CONTAINS_ALL

語法：

array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN

說明：

如果 array 中包含所有 search_values，則傳回 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();test.firestore.js

網頁

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAll([Constant("fantasy"), Constant("adventure")])
      .as("isFantasyAdventure")
  ])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(listOf("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute()DocSnippets.kt

Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(Arrays.asList("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure"))
                .as("isFantasyAdventure"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

網頁

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")])
      .as("isMysteryOrFantasy")
  ])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(listOf("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute()DocSnippets.kt

Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(Arrays.asList("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction"))
                .as("isMysteryOrFantasy"))
        .execute()
        .get();PipelineSnippets.java

ARRAY_FILTER

語法：

array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY

說明：

使用 predicate 運算式篩選 array，只傳回符合述詞的元素，並組成新的陣列。

系統會評估 array 中的每個元素。predicate如果傳回 true，則結果會包含該元素；否則 (如果傳回 false 或 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 類型，函式會傳回錯誤。

範例：

陣列	索引	`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();test.firestore.js

網頁

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayLength().as("genreCount")])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute()DocSnippets.kt

Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_length().as_("genreCount"))
    .execute()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayLength(field("genre")).as("genreCount"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

網頁

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayReverse().as("reversedGenres"))
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayReverse().as("reversedGenres")])
  .execute()PipelineSnippets.swift

Kotlin
Android

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute()DocSnippets.kt

    Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_reverse().as_("reversedGenres"))
    .execute()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayReverse(field("genre")).as("reversedGenres"))
        .execute()
        .get();PipelineSnippets.java

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

說明：

傳回 array 的子集，從以 0 為基準的索引 offset 開始，並包含 length 個元素。

如果 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

說明：

將 array 中的每個元素套用 expression，然後傳回含有轉換後元素的新陣列。輸出陣列的大小一律與輸入陣列相同。

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(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

語法：

join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING

說明：

以 STRING 形式傳回 array 中元素的串連結果。array 可以是 STRING 或 BYTES 資料類型。

array、delimiter 和 null_text 中的所有元素必須是相同類型，也就是必須全為 STRING 或全為 BYTES。
如果提供 null_text，array 中的任何 NULL 值都會取代為 null_text。
如未提供 null_text，系統會從結果中省略 array 中的 NULL 值。

範例：

如果未提供 null_text：

陣列	delimiter	`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 時：

陣列	delimiter	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」	錯誤

後續步驟

請參閱管道查詢總覽

陣列函式參考資料

陣列函式

ARRAY

ARRAY_CONCAT

Node.js

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_CONTAINS

Node.js

網頁

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_CONTAINS_ALL

Node.js

網頁

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_CONTAINS_ANY

Node.js

網頁

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_FILTER

ARRAY_GET

ARRAY_LENGTH

Node.js

網頁

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_REVERSE

Node.js

網頁

Swift

KotlinAndroid

JavaAndroid

Python

Java

ARRAY_FIRST

ARRAY_FIRST_N

ARRAY_INDEX_OF

ARRAY_INDEX_OF_ALL

ARRAY_LAST

ARRAY_LAST_N

ARRAY_SLICE

ARRAY_TRANSFORM

MAXIMUM

MAXIMUM_N

最低

MINIMUM_N

SUM

JOIN

後續步驟

Kotlin
Android

Java
Android

Kotlin
Android

Java
Android

Kotlin
Android

Java
Android

Kotlin
Android

Java
Android

Kotlin
Android

Java
Android

Kotlin
Android

Java
Android