现已推出与 MongoDB 兼容的 Cloud Firestore 企业版！了解详情。

数组函数

名称	说明
`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。

示例：

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

说明：

将两个或多个数组串联成一个 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]

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"	ANY	错误

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

说明：

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

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 中索引为 index（从 0 开始计数）的元素。

如果 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 位整数溢出，系统将返回一个错误。如果对浮点值求和，溢出将导致结果为 +/- infinity（正/负无穷大）。
如果数组中完全不含任何数值，该函数将返回 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"	错误

数组函数 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

数组函数

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

加入

数组函数