Cloud Firestore Enterprise edition in Native mode is now available! Learn more.

陣列函式

名稱	說明
`ARRAY`	傳回 `ARRAY`，其中每個輸入引數都有一個元素
`ARRAY_CONCAT`	將多個陣列連結成單一`ARRAY`
`ARRAY_CONTAINS`	如果指定 `ARRAY` 包含特定值，則傳回 `TRUE`
`ARRAY_CONTAINS_ALL`	如果所有值都存在於 `ARRAY` 中，則傳回 `TRUE`。
`ARRAY_CONTAINS_ANY`	如果 `ARRAY` 中存在任何值，則傳回 `TRUE`。
`ARRAY_GET`	傳回 `ARRAY` 中指定索引的元素。
`ARRAY_LENGTH`	傳回 `ARRAY` 中的元素數量
`ARRAY_REVERSE`	反轉 `ARRAY` 中的元素順序
`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]

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres"))
);test.firestore.js

Swift

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

Kotlin

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

Java

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

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"	下列任一項目	錯誤

Web

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

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

Java

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

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

Web

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

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

Java

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

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

Web

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

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

Java

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

ARRAY_GET

語法：

array_get(array: ARRAY, index: INT64) -> ANY

說明：

傳回 array 中以 0 為基準的 index 元素。

如果 index 為負數，系統會從陣列結尾存取元素，其中 -1 為最後一個元素。
如果 array 不是 ARRAY 類型，函式會傳回缺席值。
如果 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	缺席
`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

Web

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

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

Java

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

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]

Web

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

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

    Java
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

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

說明：

以 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

Web

Swift

Kotlin

Java

Python

ARRAY_CONTAINS

Web

Swift

Kotlin

Java

Python

ARRAY_CONTAINS_ALL

Web

Swift

Kotlin

Java

Python

ARRAY_CONTAINS_ANY

Web

Swift

Kotlin

Java

Python

ARRAY_GET

ARRAY_LENGTH

Web

Swift

Kotlin

Java

Python

ARRAY_REVERSE

Web

Swift

Kotlin

Java

Python

SUM

加入

陣列函式