所有函数参考文档

聚合

所有聚合函数都可以在 aggregate(...) 阶段用作顶级表达式。

名称 说明
COUNT 返回文档数量。
COUNT_IF 返回表达式求值结果为 TRUE 的文档数量
COUNT_DISTINCT 返回唯一非 NULL 值的数量
SUM 返回所有 NUMERIC 值的总和
AVERAGE 返回所有 NUMERIC 值的平均值
MINIMUM 返回最小的非 NULL 值
MAXIMUM 返回最大的非 NULL 值
FIRST 返回第一个文档的 expression 值。
LAST 返回最后一个文档的 expression 值。
ARRAY_AGG 返回一个包含所有输入值的数组。
ARRAY_AGG_DISTINCT 返回由所有不重复输入值构成的数组。

COUNT

语法：

count() -> INT64
count(expression: ANY) -> INT64

说明：

返回在上一阶段中，expression 的求值结果为任意非 NULL 值的文档数量。如果未提供 expression，则返回上一个阶段的文档总数。

Node.js
// Total number of books in the collection
const countOfAll = await db.pipeline()
  .collection("books")
  .aggregate(countAll().as("count"))
  .execute();

// Number of books with nonnull `ratings` field
const countField = await db.pipeline()
  .collection("books")
  .aggregate(field("ratings").count().as("count"))
  .execute();
test.firestore.js

Web

// Total number of books in the collection
const countOfAll = await execute(db.pipeline()
  .collection("books")
  .aggregate(countAll().as("count"))
);

// Number of books with nonnull `ratings` field
const countField = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("ratings").count().as("count"))
);
test.firestore.js
Swift
// Total number of books in the collection
let countAll = try await db.pipeline()
  .collection("books")
  .aggregate([CountAll().as("count")])
  .execute()

// Number of books with nonnull `ratings` field
let countField = try await db.pipeline()
  .collection("books")
  .aggregate([Field("ratings").count().as("count")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
// Total number of books in the collection
val countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute()

// Number of books with nonnull `ratings` field
val countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute()
DocSnippets.kt
Java
Android
// Total number of books in the collection
Task<Pipeline.Snapshot> countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute();

// Number of books with nonnull `ratings` field
Task<Pipeline.Snapshot> countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Count

# Total number of books in the collection
count_all = (
    client.pipeline().collection("books").aggregate(Count().as_("count")).execute()
)

# Number of books with nonnull `ratings` field
count_field = (
    client.pipeline()
    .collection("books")
    .aggregate(Count("ratings").as_("count"))
    .execute()
)
firestore_pipelines.py
Java
// Total number of books in the collection
Pipeline.Snapshot countAll =
    firestore.pipeline().collection("books").aggregate(countAll().as("count")).execute().get();

// Number of books with nonnull `ratings` field
Pipeline.Snapshot countField =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(count("ratings").as("count"))
        .execute()
        .get();
PipelineSnippets.java

COUNT_IF

语法：

count_if(expression: BOOLEAN) -> INT64

说明：

返回上一个阶段中 expression 的计算结果为 TRUE 的文档数量。

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(
    field("rating").greaterThan(4).countIf().as("filteredCount")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(
    field("rating").greaterThan(4).countIf().as("filteredCount")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([
    AggregateFunction("count_if", [Field("rating").greaterThan(4)]).as("filteredCount")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("rating").greater_than(4).count_if().as_("filteredCount"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(countIf(field("rating").greaterThan(4)).as("filteredCount"))
        .execute()
        .get();
PipelineSnippets.java

COUNT_DISTINCT

语法：

count_distinct(expression: ANY) -> INT64

说明：

返回 expression 中唯一且非 NULL、非 ABSENT 的值的数量。

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("author").countDistinct().as("unique_authors"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("author").countDistinct().as("unique_authors"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([AggregateFunction("count_distinct", [Field("author")]).as("unique_authors")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("author").count_distinct().as_("unique_authors"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(countDistinct("author").as("unique_authors"))
        .execute()
        .get();
PipelineSnippets.java

SUM

语法：

sum(expression: ANY) -> NUMBER

说明：

返回所有数值的总和，忽略非数值。如果任何值是 NaN，则返回 NaN。

输出类型通常与最宽的输入类型一致，但以下情况除外：

  • 如果 INTEGER 无法表示为 INTEGER，则会将其转换为 DOUBLE。
Node.js
const result = await db.pipeline()
  .collection("cities")
  .aggregate(field("population").sum().as("totalPopulation"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").sum().as("totalPopulation"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").sum().as("totalPopulation")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").sum().as_("totalPopulation"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .aggregate(sum("population").as("totalPopulation"))
        .execute()
        .get();
PipelineSnippets.java

平均

语法：

average(expression: ANY) -> FLOAT64

说明：

返回所有数值的平均值，忽略非数值。 如果任何值都是 NaN，则计算结果为 NaN；如果没有汇总任何数值，则计算结果为 NULL。

输出将具有与输入类型相同的类型，但以下情况除外：

  • 如果 INTEGER 无法表示为 INTEGER，则会将其转换为 DOUBLE。
Node.js
const result = await db.pipeline()
  .collection("cities")
  .aggregate(field("population").average().as("averagePopulation"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").average().as("averagePopulation"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").average().as("averagePopulation")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").average().as_("averagePopulation"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .aggregate(average("population").as("averagePopulation"))
        .execute()
        .get();
PipelineSnippets.java

MINIMUM

语法：

minimum(expression: ANY) -> ANY

说明：

返回在每个文档上求值时，expression 的最小非 NULL 且非缺失值。

如果不存在非 NULL 且非缺失的值，则返回 NULL。这也适用于未包含任何文档的情况。

如果存在多个相等的最小值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").minimum().as("minimumPrice")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").minimum().as_("minimumPrice"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(minimum("price").as("minimumPrice"))
        .execute()
        .get();
PipelineSnippets.java

MAXIMUM

语法：

maximum(expression: ANY) -> ANY

说明：

返回在每个文档上求值时，expression 的最大非 NULL 且非缺失值。

如果不存在非 NULL 且非缺失的值，则返回 NULL。这也适用于未包含任何文档的情况。

如果存在多个相等的最大值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").maximum().as("maximumPrice")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").maximum().as_("maximumPrice"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(maximum("price").as("maximumPrice"))
        .execute()
        .get();
PipelineSnippets.java

名字

语法：

first(expression: ANY) -> ANY

说明：

返回第一个返回的文档的 expression 值。

姓氏

语法：

last(expression: ANY) -> ANY

说明：

返回最后一个返回的文档的 expression 值。

ARRAY_AGG

语法：

array_agg(expression: ANY) -> ARRAY<ANY>

说明：

返回一个数组，其中包含对每个文档求值时 expression 的所有值。

如果表达式解析为缺失值，则会将其转换为 NULL。

输出数组中元素的顺序不稳定，请勿依赖此顺序。

ARRAY_AGG_DISTINCT

语法：

array_agg_distinct(expression: ANY) -> ARRAY<ANY>

说明：

返回一个数组，其中包含针对每个文档求值时 expression 的所有不同值。

如果表达式解析为缺失值，则会将其转换为 NULL。

输出数组中元素的顺序不稳定，请勿依赖此顺序。

算术函数

Firestore 中的所有算术函数都具有以下行为：

  • 如果任一输入参数为 NULL，则计算结果为 NULL。
  • 如果有任何实参为 NaN，则计算结果为 NaN。
  • 如果发生溢出或下溢，则生成错误。

此外，当算术函数接收多个不同类型的数值实参（例如：add(5.0, 6)）时，Firestore 会将这些实参隐式转换为范围最广的输入类型。如果仅提供 INT32 类型的输入值，则返回类型为 INT64。

名称 说明
ABS 返回 number 的绝对值
ADD 返回 x + y 的值
SUBTRACT 返回 x - y 的值
MULTIPLY 返回 x * y 的值
DIVIDE 返回 x / y 的值
MOD 返回 x / y 相除所得的余数
CEIL 返回 number 的向上取整值
FLOOR 返回 number 的向下取整值
ROUND 将 number 四舍五入到 places 位小数
POW 返回 base^exponent 的值
SQRT 返回 number 的平方根
EXP 返回欧拉数的 exponent 次幂
LN 返回 number 的自然对数
LOG 返回 number 的对数
LOG10 返回以 10 为底的 number 的对数
RAND 返回一个伪随机浮点数

ABS

语法：

abs[N <: INT32 | INT64 | FLOAT64](number: N) -> N

说明：

返回 number 的绝对值。

  • 当函数可能导致 INT32 或 INT64 类型的值溢出时，将抛出错误。

示例：

数值 abs(number)
10 10
-10 10
10L 10L
-0.0 0.0
10.5 10.5
-10.5 10.5
-231 [error]
-263 [error]

添加

语法：

add[N <: INT32 | INT64 | FLOAT64](x: N, y: N) -> N

说明：

返回 x + y 的值。

示例：

x y add(x, y)
20 3 23
10.0 1 11.0
22.5 2.0 24.5
INT64.MAX 1 [error]
INT64.MIN -1 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("soldBooks").add(field("unsoldBooks")).as("totalBooks"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("soldBooks").add(field("unsoldBooks")).as("totalBooks"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("soldBooks").add(Field("unsoldBooks")).as("totalBooks")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(Expression.add(field("soldBooks"), field("unsoldBooks")).alias("totalBooks"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.add(field("soldBooks"), field("unsoldBooks")).alias("totalBooks"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("soldBooks").add(Field.of("unsoldBooks")).as_("totalBooks"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(add(field("soldBooks"), field("unsoldBooks")).as("totalBooks"))
        .execute()
        .get();
PipelineSnippets.java

SUBTRACT

语法：

subtract[N <: INT32 | INT64 | FLOAT64](x: N, y: N) -> N

说明：

返回 x - y 的值。

示例：

x y subtract(x, y)
20 3 17
10.0 1 9.0
22.5 2.0 20.5
INT64.MAX -1 [error]
INT64.MIN 1 [error]
Node.js
const storeCredit = 7;
const result = await db.pipeline()
  .collection("books")
  .select(field("price").subtract(constant(storeCredit)).as("totalCost"))
  .execute();
test.firestore.js

Web

const storeCredit = 7;
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("price").subtract(constant(storeCredit)).as("totalCost"))
);
test.firestore.js
Swift
let storeCredit = 7
let result = try await db.pipeline()
  .collection("books")
  .select([Field("price").subtract(Constant(storeCredit)).as("totalCost")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val storeCredit = 7
val result = db.pipeline()
    .collection("books")
    .select(Expression.subtract(field("price"), storeCredit).alias("totalCost"))
    .execute()
DocSnippets.kt
Java
Android
int storeCredit = 7;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.subtract(field("price"), storeCredit).alias("totalCost"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

store_credit = 7
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("price").subtract(store_credit).as_("totalCost"))
    .execute()
)
firestore_pipelines.py
Java
int storeCredit = 7;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(subtract(field("price"), storeCredit).as("totalCost"))
        .execute()
        .get();
PipelineSnippets.java

MULTIPLY

语法：

multiply[N <: INT32 | INT64 | FLOAT64](x: N, y: N) -> N

说明：

返回 x * y 的值。

示例：

x y multiply(x, y)
20 3 60
10.0 1 10.0
22.5 2.0 45.0
INT64.MAX 2 [error]
INT64.MIN 2 [error]
FLOAT64.MAX FLOAT64.MAX +inf
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("price").multiply(field("soldBooks")).as("revenue"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("price").multiply(field("soldBooks")).as("revenue"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("price").multiply(Field("soldBooks")).as("revenue")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("price"), field("soldBooks")).alias("revenue"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("price"), field("soldBooks")).alias("revenue"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("price").multiply(Field.of("soldBooks")).as_("revenue"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(multiply(field("price"), field("soldBooks")).as("revenue"))
        .execute()
        .get();
PipelineSnippets.java

DIVIDE

语法：

divide[N <: INT32 | INT64 | FLOAT64](x: N, y: N) -> N

说明：

返回 x / y 的值。整数除法的结果会被截断。

示例：

x y divide(x, y)
20 3 6
10.0 3 3.333...
22.5 2 11.25
10 0 [error]
1.0 0.0 +inf
-1.0 0.0 -inf
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("ratings").divide(field("soldBooks")).as("reviewRate"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("ratings").divide(field("soldBooks")).as("reviewRate"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("ratings").divide(Field("soldBooks")).as("reviewRate")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(Expression.divide(field("ratings"), field("soldBooks")).alias("reviewRate"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.divide(field("ratings"), field("soldBooks")).alias("reviewRate"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("ratings").divide(Field.of("soldBooks")).as_("reviewRate"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(divide(field("ratings"), field("soldBooks")).as("reviewRate"))
        .execute()
        .get();
PipelineSnippets.java

MOD

语法：

mod[N <: INT32 | INT64 | FLOAT64](x: N, y: N) -> N

说明：

返回 x / y 的余数。

  • 对于整数类型 (INT64)，当除数 y 为零时，系统会抛出 error。
  • 对于浮点类型 (FLOAT64)，当除数 y 为零时，函数返回 NaN。

示例：

x y mod(x, y)
20 3 2
-10 3 -1
10 -3 1
-10 -3 -1
10 1 0
22.5 2 0.5
22.5 0.0 NaN
25 0 [error]
Node.js
const displayCapacity = 1000;
const result = await db.pipeline()
  .collection("books")
  .select(field("unsoldBooks").mod(constant(displayCapacity)).as("warehousedBooks"))
  .execute();
test.firestore.js

Web

const displayCapacity = 1000;
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("unsoldBooks").mod(constant(displayCapacity)).as("warehousedBooks"))
);
test.firestore.js
Swift
let displayCapacity = 1000
let result = try await db.pipeline()
  .collection("books")
  .select([Field("unsoldBooks").mod(Constant(displayCapacity)).as("warehousedBooks")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val displayCapacity = 1000
val result = db.pipeline()
    .collection("books")
    .select(Expression.mod(field("unsoldBooks"), displayCapacity).alias("warehousedBooks"))
    .execute()
DocSnippets.kt
Java
Android
int displayCapacity = 1000;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.mod(field("unsoldBooks"), displayCapacity).alias("warehousedBooks"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

display_capacity = 1000
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("unsoldBooks").mod(display_capacity).as_("warehousedBooks"))
    .execute()
)
firestore_pipelines.py
Java
int displayCapacity = 1000;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(mod(field("unsoldBooks"), displayCapacity).as("warehousedBooks"))
        .execute()
        .get();
PipelineSnippets.java

CEIL

语法：

ceil[N <: INT32 | INT64 | FLOAT64](number: N) -> N

说明：

返回不小于 number 的最小整数值。

示例：

数值 ceil(number)
20 20
10 10
0 0
24L 24L
-0.4 -0.0
0.4 1.0
22.5 23.0
+inf +inf
-inf -inf
Node.js
const booksPerShelf = 100;
const result = await db.pipeline()
  .collection("books")
  .select(
    field("unsoldBooks").divide(constant(booksPerShelf)).ceil().as("requiredShelves")
  )
  .execute();
test.firestore.js

Web

const booksPerShelf = 100;
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("unsoldBooks").divide(constant(booksPerShelf)).ceil().as("requiredShelves")
  )
);
test.firestore.js
Swift
let booksPerShelf = 100
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("unsoldBooks").divide(Constant(booksPerShelf)).ceil().as("requiredShelves")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val booksPerShelf = 100
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.divide(field("unsoldBooks"), booksPerShelf).ceil().alias("requiredShelves")
    )
    .execute()
DocSnippets.kt
Java
Android
int booksPerShelf = 100;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.divide(field("unsoldBooks"), booksPerShelf).ceil().alias("requiredShelves")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

books_per_shelf = 100
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("unsoldBooks")
        .divide(books_per_shelf)
        .ceil()
        .as_("requiredShelves")
    )
    .execute()
)
firestore_pipelines.py
Java
int booksPerShelf = 100;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(ceil(divide(field("unsoldBooks"), booksPerShelf)).as("requiredShelves"))
        .execute()
        .get();
PipelineSnippets.java

FLOOR

语法：

floor[N <: INT32 | INT64 | FLOAT64](number: N) -> N

说明：

返回小于或等于 number 的最大整数值。

示例：

数值 floor(number)
20 20
10 10
0 0
2147483648 2147483648
-0.4 -1.0
0.4 0.0
22.5 22.0
+inf +inf
-inf -inf
Node.js
const result = await db.pipeline()
  .collection("books")
  .addFields(
    field("wordCount").divide(field("pages")).floor().as("wordsPerPage")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .addFields(
    field("wordCount").divide(field("pages")).floor().as("wordsPerPage")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .addFields([
    Field("wordCount").divide(Field("pages")).floor().as("wordsPerPage")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .addFields(
        Expression.divide(field("wordCount"), field("pages")).floor().alias("wordsPerPage")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .addFields(
        Expression.divide(field("wordCount"), field("pages")).floor().alias("wordsPerPage")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .add_fields(
        Field.of("wordCount").divide(Field.of("pages")).floor().as_("wordsPerPage")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .addFields(floor(divide(field("wordCount"), field("pages"))).as("wordsPerPage"))
        .execute()
        .get();
PipelineSnippets.java

ROUND

语法：

round[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N) -> N
round[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N, places: INT64) -> N

说明：

将数值 number 按 places 指定的位数进行舍入。如果 places 为正数，则对小数点右侧的数字进行舍入；如果为负数，则对小数点左侧的数字进行舍入。

  • 如果仅提供 number，则会四舍五入到最接近的整数。
  • 中间数向远离 0 的方向舍入。
  • 如果使用负 places 值进行舍入导致溢出，则会抛出 error。

示例：

数值 个地点 round(number, places)
15.5 0 16.0
-15.5 0 -16.0
15 1 15
15 0 15
15 -1 20
15 -2 0
15.48924 1 15.5
231-1 -1 [error]
263-1L -1 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("soldBooks").multiply(field("price")).round().as("partialRevenue"))
  .aggregate(field("partialRevenue").sum().as("totalRevenue"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("soldBooks").multiply(field("price")).round().as("partialRevenue"))
  .aggregate(field("partialRevenue").sum().as("totalRevenue"))
  );
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("soldBooks").multiply(Field("price")).round().as("partialRevenue")])
  .aggregate([Field("partialRevenue").sum().as("totalRevenue")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("soldBooks"), field("price")).round().alias("partialRevenue"))
    .aggregate(AggregateFunction.sum("partialRevenue").alias("totalRevenue"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("soldBooks"), field("price")).round().alias("partialRevenue"))
    .aggregate(AggregateFunction.sum("partialRevenue").alias("totalRevenue"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("soldBooks")
        .multiply(Field.of("price"))
        .round()
        .as_("partialRevenue")
    )
    .aggregate(Field.of("partialRevenue").sum().as_("totalRevenue"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(round(multiply(field("soldBooks"), field("price"))).as("partialRevenue"))
        .aggregate(sum("partialRevenue").as("totalRevenue"))
        .execute()
        .get();
PipelineSnippets.java

POW

语法：

pow(base: FLOAT64, exponent: FLOAT64) -> FLOAT64

说明：

返回 base 的 exponent 次幂。

  • 如果 base <= 0 和 exponent 为负数，则会抛出错误。

  • 对于任何 exponent，pow(1, exponent) 均为 1。

  • 对于任何 base，pow(base, 0) 均为 1。

示例：

底座 exponent pow(base, exponent)
2 3 8.0
2 -3 0.125
+inf 0 1.0
1 +inf 1.0
-1 0.5 [error]
0 -1 [error]
Node.js
const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
  .execute();
test.firestore.js

Web

const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await execute(db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
);
test.firestore.js
Swift
let googleplex = CLLocation(latitude: 37.4221, longitude: 122.0853)
let result = try await db.pipeline()
  .collection("cities")
  .addFields([
    Field("lat").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    Field("lng").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  ])
  .select([
    Field("latitudeDifference").add(Field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val googleplex = GeoPoint(37.4221, -122.0853)
val result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.latitude)
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.longitude)
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute()
DocSnippets.kt
Java
Android
GeoPoint googleplex = new GeoPoint(37.4221, -122.0853);
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.getLatitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.getLongitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

googleplexLat = 37.4221
googleplexLng = -122.0853
result = (
    client.pipeline()
    .collection("cities")
    .add_fields(
        Field.of("lat")
        .subtract(googleplexLat)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("latitudeDifference"),
        Field.of("lng")
        .subtract(googleplexLng)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("longitudeDifference"),
    )
    .select(
        Field.of("latitudeDifference")
        .add(Field.of("longitudeDifference"))
        .sqrt()
        # Inaccurate for large distances or close to poles
        .as_("approximateDistanceToGoogle")
    )
    .execute()
)
firestore_pipelines.py
Java
double googleplexLat = 37.4221;
double googleplexLng = -122.0853;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .addFields(
            pow(multiply(subtract(field("lat"), googleplexLat), 111), 2)
                .as("latitudeDifference"),
            pow(multiply(subtract(field("lng"), googleplexLng), 111), 2)
                .as("longitudeDifference"))
        .select(
            sqrt(add(field("latitudeDifference"), field("longitudeDifference")))
                // Inaccurate for large distances or close to poles
                .as("approximateDistanceToGoogle"))
        .execute()
        .get();
PipelineSnippets.java

SQRT

语法：

sqrt[N <: FLOAT64 | DECIMAL128](number: N) -> N

说明：

返回 number 的平方根。

  • 如果 number 为负数，函数将抛出 error。

示例：

数值 sqrt(number)
25 5.0
12.002 3.464...
0.0 0.0
NaN NaN
+inf +inf
-inf [error]
x < 0 [error]
Node.js
const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
  .execute();
test.firestore.js

Web

const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await execute(db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
);
test.firestore.js
Swift
let googleplex = CLLocation(latitude: 37.4221, longitude: 122.0853)
let result = try await db.pipeline()
  .collection("cities")
  .addFields([
    Field("lat").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    Field("lng").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  ])
  .select([
    Field("latitudeDifference").add(Field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val googleplex = GeoPoint(37.4221, -122.0853)
val result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.latitude)
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.longitude)
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute()
DocSnippets.kt
Java
Android
GeoPoint googleplex = new GeoPoint(37.4221, -122.0853);
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.getLatitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.getLongitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

googleplexLat = 37.4221
googleplexLng = -122.0853
result = (
    client.pipeline()
    .collection("cities")
    .add_fields(
        Field.of("lat")
        .subtract(googleplexLat)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("latitudeDifference"),
        Field.of("lng")
        .subtract(googleplexLng)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("longitudeDifference"),
    )
    .select(
        Field.of("latitudeDifference")
        .add(Field.of("longitudeDifference"))
        .sqrt()
        # Inaccurate for large distances or close to poles
        .as_("approximateDistanceToGoogle")
    )
    .execute()
)
firestore_pipelines.py
Java
double googleplexLat = 37.4221;
double googleplexLng = -122.0853;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .addFields(
            pow(multiply(subtract(field("lat"), googleplexLat), 111), 2)
                .as("latitudeDifference"),
            pow(multiply(subtract(field("lng"), googleplexLng), 111), 2)
                .as("longitudeDifference"))
        .select(
            sqrt(add(field("latitudeDifference"), field("longitudeDifference")))
                // Inaccurate for large distances or close to poles
                .as("approximateDistanceToGoogle"))
        .execute()
        .get();
PipelineSnippets.java

EXP

语法：

exp(exponent: FLOAT64) -> FLOAT64

说明：

返回欧拉数 (e) 的 exponent 次幂的值，该函数也称为自然指数函数。

示例：

exponent exp(exponent)
0.0 1.0
10 e^10 (FLOAT64)
+inf +inf
-inf 0
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").exp().as("expRating"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").exp().as("expRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").exp().as("expRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("rating").exp().alias("expRating"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").exp().alias("expRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").exp().as_("expRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(exp(field("rating")).as("expRating"))
        .execute()
        .get();
PipelineSnippets.java

LN

语法：

ln(number: FLOAT64) -> FLOAT64

说明：

返回 number 的自然对数。此函数等效于 log(number)。

示例：

数值 ln(number)
1 0.0
2L 0.693...
1.0 0.0
e (FLOAT64) 1.0
-inf NaN
+inf +inf
x <= 0 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").ln().as("lnRating"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").ln().as("lnRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").ln().as("lnRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("rating").ln().alias("lnRating"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").ln().alias("lnRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").ln().as_("lnRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(ln(field("rating")).as("lnRating"))
        .execute()
        .get();
PipelineSnippets.java

LOG

语法：

log(number: FLOAT64, base: FLOAT64) -> FLOAT64
log(number: FLOAT64) -> FLOAT64

说明：

返回以 base 为底的 number 的对数。

  • 如果仅提供 number，则返回以 base 为底的 number 的对数（相当于 ln(number)）。

示例：

数值 底座 log(number, base)
100 10 2.0
-inf Numeric NaN
Numeric。 +inf NaN
number <= 0 Numeric [error]
Numeric base <= 0 [error]
Numeric 1.0 [error]

LOG10

语法：

log10(x: FLOAT64) -> FLOAT64

说明：

返回以 10 为底的 number 的对数。

示例：

数值 log10(number)
100 2.0
-inf NaN
+inf +inf
x <= 0 [error]

RAND

语法：

rand() -> FLOAT64

说明：

返回一个伪随机浮点数，该数均匀地取自 0.0（含）和 1.0（不含）之间。

数组函数

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

示例：

数组 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

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

说明：

如果所有 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();
test.firestore.js

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

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
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_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
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
  .execute();
test.firestore.js

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

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

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

语法：

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 时：

数组 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" 错误

比较函数

名称 说明
EQUAL 等值比较
GREATER_THAN 大于比较
GREATER_THAN_OR_EQUAL 大于或等于比较
LESS_THAN 小于比较
LESS_THAN_OR_EQUAL 小于或等于比较
NOT_EQUAL 不等于比较

EQUAL

语法：

equal(x: ANY, y: ANY) -> BOOLEAN

示例：

x y equal(x, y)
1L 1L TRUE
1.0 1L TRUE
-1.0 1L FALSE
NaN NaN TRUE
NULL NULL TRUE
NULL ABSENT FALSE

说明：

如果 x 和 y 相等，则返回 TRUE；否则返回 FALSE。

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").equal(5).as("hasPerfectRating"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").equal(5).as("hasPerfectRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").equal(5).as("hasPerfectRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("rating").equal(5).alias("hasPerfectRating"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").equal(5).alias("hasPerfectRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").equal(5).as_("hasPerfectRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(equal(field("rating"), 5).as("hasPerfectRating"))
        .execute()
        .get();
PipelineSnippets.java

GREATER_THAN

语法：

greater_than(x: ANY, y: ANY) -> BOOLEAN

说明：

如果 x 大于 y，则返回 TRUE；否则返回 FALSE。

如果 x 和 y 不可比较，则返回 FALSE。

示例：

x y greater_than(x, y)
1L 0.0 TRUE
1L 1L FALSE
1L 2L FALSE
"foo" 0L FALSE
0L "foo" FALSE
NaN 0L FALSE
0L NaN FALSE
NULL NULL FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").greaterThan(4).as("hasHighRating"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").greaterThan(4).as("hasHighRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").greaterThan(4).as("hasHighRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("rating").greaterThan(4).alias("hasHighRating"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").greaterThan(4).alias("hasHighRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").greater_than(4).as_("hasHighRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(greaterThan(field("rating"), 4).as("hasHighRating"))
        .execute()
        .get();
PipelineSnippets.java

GREATER_THAN_OR_EQUAL

语法：

greater_than_or_equal(x: ANY, y: ANY) -> BOOLEAN

说明：

如果 x 大于或等于 y，则返回 TRUE；否则返回 FALSE。

如果 x 和 y 不可比较，则返回 FALSE。

示例：

x y greater_than_or_equal(x, y)
1L 0.0 TRUE
1L 1L TRUE
1L 2L FALSE
"foo" 0L FALSE
0L "foo" FALSE
NaN 0L FALSE
0L NaN FALSE
NULL NULL TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("published").greaterThanOrEqual(1900).alias("publishedIn20thCentury"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("published").greaterThanOrEqual(1900).alias("publishedIn20thCentury"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("published")
        .greater_than_or_equal(1900)
        .as_("publishedIn20thCentury")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(greaterThanOrEqual(field("published"), 1900).as("publishedIn20thCentury"))
        .execute()
        .get();
PipelineSnippets.java

LESS_THAN

语法：

less_than(x: ANY, y: ANY) -> BOOLEAN

说明：

如果 x 小于 y，则返回 TRUE；否则返回 FALSE。

如果 x 和 y 不可比较，则返回 FALSE。

示例：

x y less_than(x, y)
1L 0.0 FALSE
1L 1L FALSE
1L 2L TRUE
"foo" 0L FALSE
0L "foo" FALSE
NaN 0L FALSE
0L NaN FALSE
NULL NULL FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("published").lessThan(1923).as("isPublicDomainProbably"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("published").lessThan(1923).as("isPublicDomainProbably"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("published").lessThan(1923).as("isPublicDomainProbably")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("published").lessThan(1923).alias("isPublicDomainProbably"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("published").lessThan(1923).alias("isPublicDomainProbably"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("published").less_than(1923).as_("isPublicDomainProbably"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(lessThan(field("published"), 1923).as("isPublicDomainProbably"))
        .execute()
        .get();
PipelineSnippets.java

LESS_THAN_OR_EQUAL

语法：

less_than_or_equal(x: ANY, y: ANY) -> BOOLEAN

说明：

如果 x 小于或等于 y，则返回 TRUE；否则返回 FALSE。

如果 x 和 y 不可比较，则返回 FALSE。

示例：

x y less_than(x, y)
1L 0.0 FALSE
1L 1L TRUE
1L 2L TRUE
"foo" 0L FALSE
0L "foo" FALSE
NaN 0L FALSE
0L NaN FALSE
NULL NULL TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").lessThanOrEqual(2).as("hasBadRating"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").lessThanOrEqual(2).as("hasBadRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").lessThanOrEqual(2).as("hasBadRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("rating").lessThanOrEqual(2).alias("hasBadRating"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").lessThanOrEqual(2).alias("hasBadRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").less_than_or_equal(2).as_("hasBadRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(lessThanOrEqual(field("rating"), 2).as("hasBadRating"))
        .execute()
        .get();
PipelineSnippets.java

NOT_EQUAL

语法：

not_equal(x: ANY, y: ANY) -> BOOLEAN

说明：

如果 x 不等于 y，则返回 TRUE；否则返回 FALSE。

示例：

x y not_equal(x, y)
1L 1L FALSE
1.0 1L FALSE
-1.0 1L TRUE
NaN 0L TRUE
NaN NaN FALSE
NULL NULL FALSE
NULL ABSENT TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("title").notEqual("1984").as("not1984")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").not_equal("1984").as_("not1984"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(notEqual(field("title"), "1984").as("not1984"))
        .execute()
        .get();
PipelineSnippets.java

调试函数

名称 说明
EXISTS 如果该值不是缺失值，则返回 TRUE
IS_ABSENT 如果该值为缺失值，则返回 TRUE
IF_ABSENT 如果该值为缺失值，则将其替换为表达式
IS_ERROR 捕获并检查底层表达式是否抛出错误
IF_ERROR 如果该值在求值过程中抛出错误，则将其替换为表达式

EXISTS

语法：

exists(value: ANY) -> BOOLEAN

说明：

如果 value 不是缺失值，则返回 TRUE。

示例：

value exists(value)
0L TRUE
"foo" TRUE
NULL TRUE
ABSENT FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").exists().as("hasRating"))
  .execute();
test.firestore.js

Web

示例：

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").exists().as("hasRating"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").exists().as("hasRating")])
  .execute()
PipelineSnippets.swift
Kotlin
Android

示例：

val result = db.pipeline()
    .collection("books")
    .select(field("rating").exists().alias("hasRating"))
    .execute()
DocSnippets.kt
Java
Android

示例：

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").exists().alias("hasRating"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").exists().as_("hasRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(exists(field("rating")).as("hasRating"))
        .execute()
        .get();
PipelineSnippets.java

IS_ABSENT

语法：

is_absent(value: ANY) -> BOOLEAN

说明：

如果 value 是缺失值，则返回 TRUE；否则返回 FALSE。缺失值是指输入中不存在的值，例如文档字段缺失。

示例：

value is_absent(value)
0L FALSE
"foo" FALSE
NULL FALSE
ABSENT TRUE

IF_ABSENT

语法：

if_absent(value: ANY, replacement: ANY) -> ANY

说明：

如果 value 是缺失值，则对 replacement 求值并返回结果。否则返回 value。

示例：

value replacement if_absent(value, replacement)
5L 0L 5L
NULL 0L NULL
ABSENT 0L 0L

IS_ERROR

语法：

is_error(try: ANY) -> BOOLEAN

说明：

如果在对 try 求值期间抛出错误，则返回 TRUE。否则返回 FALSE。

IF_ERROR

语法：

if_error(try: ANY, catch: ANY) -> ANY

说明：

如果在对 try 求值期间抛出错误，则对 replacement 求值并返回结果。否则，返回 try 的已解析值。

逻辑函数

名称 说明
AND 执行逻辑 AND
OR 执行逻辑 OR
XOR 执行逻辑 XOR
NOT 执行逻辑 NOT
CONDITIONAL 根据条件表达式分支评估。
EQUAL_ANY 检查某个值是否等于数组中的任何元素
NOT_EQUAL_ANY 检查某个值是否不等于数组中的任何元素
MAXIMUM 返回一组值中的最大值
MINIMUM 返回一组值中的最小值

且

语法：

and(x: BOOLEAN...) -> BOOLEAN

说明：

返回两个或多个布尔值的逻辑 AND。

如果由于任何给定值为 ABSENT 或 NULL 而无法得出结果，则返回 NULL。

示例：

x y and(x, y)
TRUE TRUE TRUE
FALSE TRUE FALSE
NULL TRUE NULL
ABSENT TRUE NULL
NULL FALSE FALSE
FALSE ABSENT FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    and(field("rating").greaterThan(4), field("price").lessThan(10))
      .as("under10Recommendation")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    and(field("rating").greaterThan(4), field("price").lessThan(10))
      .as("under10Recommendation")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("rating").greaterThan(4) && Field("price").lessThan(10))
      .as("under10Recommendation")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.and(field("rating").greaterThan(4),
          field("price").lessThan(10))
            .alias("under10Recommendation")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.and(
            field("rating").greaterThan(4),
            field("price").lessThan(10)
        ).alias("under10Recommendation")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, And

result = (
    client.pipeline()
    .collection("books")
    .select(
        And(
            Field.of("rating").greater_than(4), Field.of("price").less_than(10)
        ).as_("under10Recommendation")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            and(greaterThan(field("rating"), 4), lessThan(field("price"), 10))
                .as("under10Recommendation"))
        .execute()
        .get();
PipelineSnippets.java

或

语法：

or(x: BOOLEAN...) -> BOOLEAN

说明：

返回两个或多个布尔值的逻辑 OR 运算结果。

如果由于任何给定值为 ABSENT 或 NULL 而无法得出结果，则返回 NULL。

示例：

x y or(x, y)
TRUE TRUE TRUE
FALSE TRUE TRUE
NULL TRUE TRUE
ABSENT TRUE TRUE
NULL FALSE NULL
FALSE ABSENT NULL
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    or(field("genre").equal("Fantasy"), field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    or(field("genre").equal("Fantasy"), field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("genre").equal("Fantasy") || Field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.or(field("genre").equal("Fantasy"),
          field("tags").arrayContains("adventure"))
            .alias("matchesSearchFilters")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.or(
            field("genre").equal("Fantasy"),
            field("tags").arrayContains("adventure")
        ).alias("matchesSearchFilters")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, And, Or

result = (
    client.pipeline()
    .collection("books")
    .select(
        Or(
            Field.of("genre").equal("Fantasy"),
            Field.of("tags").array_contains("adventure"),
        ).as_("matchesSearchFilters")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            or(equal(field("genre"), "Fantasy"), arrayContains(field("tags"), "adventure"))
                .as("matchesSearchFilters"))
        .execute()
        .get();
PipelineSnippets.java

XOR

语法：

xor(x: BOOLEAN...) -> BOOLEAN

说明：

返回两个或更多布尔值的逻辑异或结果。

如果任何给定值为 ABSENT 或 NULL，则返回 NULL。

示例：

x y xor(x, y)
TRUE TRUE FALSE
FALSE FALSE FALSE
FALSE TRUE TRUE
NULL TRUE NULL
ABSENT TRUE NULL
NULL FALSE NULL
FALSE ABSENT NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    xor(field("tags").arrayContains("magic"), field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  )
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    xor(field("tags").arrayContains("magic"), field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("tags").arrayContains("magic") ^ Field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.xor(field("tags").arrayContains("magic"),
          field("tags").arrayContains("nonfiction"))
            .alias("matchesSearchFilters")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.xor(
            field("tags").arrayContains("magic"),
            field("tags").arrayContains("nonfiction")
        ).alias("matchesSearchFilters")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, Xor

result = (
    client.pipeline()
    .collection("books")
    .select(
        Xor(
            [
                Field.of("tags").array_contains("magic"),
                Field.of("tags").array_contains("nonfiction"),
            ]
        ).as_("matchesSearchFilters")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            xor(
                    arrayContains(field("tags"), "magic"),
                    arrayContains(field("tags"), "nonfiction"))
                .as("matchesSearchFilters"))
        .execute()
        .get();
PipelineSnippets.java

而非

语法：

not(x: BOOLEAN) -> BOOLEAN

说明：

返回布尔值的逻辑 NOT。

Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayContains("nonfiction").not()
      .as("isFiction")
  )
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayContains("nonfiction").not()
      .as("isFiction")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (!Field("tags").arrayContains("nonfiction"))
      .as("isFiction")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.not(
            field("tags").arrayContains("nonfiction")
        ).alias("isFiction")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.not(
            field("tags").arrayContains("nonfiction")
        ).alias("isFiction")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, Not

result = (
    client.pipeline()
    .collection("books")
    .select(Not(Field.of("tags").array_contains("nonfiction")).as_("isFiction"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(not(arrayContains(field("tags"), "nonfiction")).as("isFiction"))
        .execute()
        .get();
PipelineSnippets.java

CONDITIONAL

语法：

conditional(condition: BOOLEAN, true_case: ANY, false_case: ANY) -> ANY

说明：

如果 condition 的计算结果为 TRUE，则计算并返回 true_case。

如果条件解析为 FALSE、NULL 或 ABSENT 值，则评估并返回 false_case。

示例：

condition true_case false_case conditional(condition, true_case, false_case)
TRUE 1L 0L 1L
FALSE 1L 0L 0L
NULL 1L 0L 0L
ABSENT 1L 0L 0L
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayConcat([
      field("pages").greaterThan(100)
        .conditional(constant("longRead"), constant("shortRead"))
    ]).as("extendedTags")
  )
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayConcat([
      field("pages").greaterThan(100)
        .conditional(constant("longRead"), constant("shortRead"))
    ]).as("extendedTags")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("tags").arrayConcat([
      ConditionalExpression(
        Field("pages").greaterThan(100),
        then: Constant("longRead"),
        else: Constant("shortRead")
      )
    ]).as("extendedTags")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("tags").arrayConcat(
            Expression.conditional(
                field("pages").greaterThan(100),
                constant("longRead"),
                constant("shortRead")
            )
        ).alias("extendedTags")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("tags").arrayConcat(
            Expression.conditional(
                field("pages").greaterThan(100),
                constant("longRead"),
                constant("shortRead")
            )
        ).alias("extendedTags")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import (
    Field,
    Constant,
    Conditional,
)

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("tags")
        .array_concat(
            Conditional(
                Field.of("pages").greater_than(100),
                Constant.of("longRead"),
                Constant.of("shortRead"),
            )
        )
        .as_("extendedTags")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayConcat(
                    field("tags"),
                    conditional(
                        greaterThan(field("pages"), 100),
                        constant("longRead"),
                        constant("shortRead")))
                .as("extendedTags"))
        .execute()
        .get();
PipelineSnippets.java

EQUAL_ANY

语法：

equal_any(value: ANY, search_space: ARRAY) -> BOOLEAN

说明：

如果 value 位于 search_space 数组中，则返回 TRUE。

示例：

value search_space equal_any(value, search_space)
0L [1L, 2L, 3L] FALSE
2L [1L, 2L, 3L] TRUE
NULL [1L, 2L, 3L] FALSE
NULL [1L, NULL] TRUE
ABSENT [1L, NULL] FALSE
NaN [1L, NaN, 3L] TRUE
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  )
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre").equalAny(listOf("Science Fiction", "Psychological Thriller"))
            .alias("matchesGenreFilters")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre").equalAny(Arrays.asList("Science Fiction", "Psychological Thriller"))
            .alias("matchesGenreFilters")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .equal_any(["Science Fiction", "Psychological Thriller"])
        .as_("matchesGenreFilters")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            equalAny(field("genre"), Arrays.asList("Science Fiction", "Psychological Thriller"))
                .as("matchesGenreFilters"))
        .execute()
        .get();
PipelineSnippets.java

NOT_EQUAL_ANY

语法：

not_equal_any(value: ANY, search_space: ARRAY) -> BOOLEAN

说明：

如果 value 不在 search_space 数组中，则返回 TRUE。

示例：

value search_space not_equal_any(value, search_space)
0L [1L, 2L, 3L] TRUE
2L [1L, 2L, 3L] FALSE
NULL [1L, 2L, 3L] TRUE
NULL [1L, NULL] FALSE
ABSENT [1L, NULL] TRUE
NaN [1L, NaN, 3L] FALSE
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  )
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("author").notEqualAny(listOf("George Orwell", "F. Scott Fitzgerald"))
            .alias("byExcludedAuthors")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("author").notEqualAny(Arrays.asList("George Orwell", "F. Scott Fitzgerald"))
            .alias("byExcludedAuthors")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("author")
        .not_equal_any(["George Orwell", "F. Scott Fitzgerald"])
        .as_("byExcludedAuthors")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            notEqualAny(field("author"), Arrays.asList("George Orwell", "F. Scott Fitzgerald"))
                .as("byExcludedAuthors"))
        .execute()
        .get();
PipelineSnippets.java

MAXIMUM

语法：

maximum(x: ANY...) -> ANY
maximum(x: ARRAY) -> ANY

说明：

返回一系列值 x 中的最大非 NULL、非 ABSENT 值。

如果不存在非 NULL 且非 ABSENT 的值，则返回 NULL。

如果存在多个相等的最大值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

示例：

x y maximum(x, y)
FALSE TRUE TRUE
FALSE -10L -10L
0.0 -5L 0.0
"foo" "bar" "foo"
"foo" ["foo"] ["foo"]
ABSENT ABSENT NULL
NULL NULL NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("rating").logicalMaximum([1]).as("flooredRating")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMaximum(1).alias("flooredRating")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMaximum(1).alias("flooredRating")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").logical_maximum(1).as_("flooredRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(logicalMaximum(field("rating"), 1).as("flooredRating"))
        .execute()
        .get();
PipelineSnippets.java

MINIMUM

语法：

minimum(x: ANY...) -> ANY
minimum(x: ARRAY) -> ANY

说明：

返回一系列值 x 中的最小非 NULL、非 ABSENT 值。

如果不存在非 NULL 且非 ABSENT 的值，则返回 NULL。

如果存在多个相等的最小值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

示例：

x y minimum(x, y)
FALSE TRUE FALSE
FALSE -10L FALSE
0.0 -5L -5L
"foo" "bar" "bar"
"foo" ["foo"] "foo"
ABSENT ABSENT NULL
NULL NULL NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("rating").logicalMinimum([5]).as("cappedRating")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMinimum(5).alias("cappedRating")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMinimum(5).alias("cappedRating")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").logical_minimum(5).as_("cappedRating"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(logicalMinimum(field("rating"), 5).as("cappedRating"))
        .execute()
        .get();
PipelineSnippets.java

映射函数

名称 说明
MAP 根据一系列键值对构造一个映射值
MAP_GET 返回指定键在映射中的值
MAP_SET 返回一个更新了一系列键的映射副本
MAP_REMOVE 返回一个移除了指定一系列键的映射副本
MAP_MERGE 将一系列映射合并为一个映射。
CURRENT_CONTEXT 以映射的形式返回当前上下文。
MAP_KEYS 返回映射中所有键的数组。
MAP_VALUES 返回映射中所有值的数组。
MAP_ENTRIES 返回映射的键值对数组。

地图

语法：

map(key: STRING, value: ANY, ...) -> MAP

说明：

根据一系列键值对构造一个映射。

MAP_GET

语法：

map_get(map: ANY, key: STRING) -> ANY

说明：

返回映射中指定键对应的值。如果 key 在映射中不存在，或者 map 实参不是 MAP，则返回 ABSENT 值。

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("awards").mapGet("pulitzer").alias("hasPulitzerAward")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("awards").mapGet("pulitzer").alias("hasPulitzerAward")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("awards").map_get("pulitzer").as_("hasPulitzerAward"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(mapGet(field("awards"), "pulitzer").as("hasPulitzerAward"))
        .execute()
        .get();
PipelineSnippets.java

MAP_SET

语法：

map_set(map: MAP, key: STRING, value: ANY, ...) -> MAP

说明：

返回 map 值的副本，其内容会由一系列键值对更新。

如果给定的值解析为缺失值，系统会从映射中移除其关联的键。

如果 map 实参不是 MAP，则返回缺失值。

MAP_REMOVE

语法：

map_remove(map: MAP, key: STRING...) -> MAP

说明：

返回移除了指定一系列键的 map 值的副本。

MAP_MERGE

语法：

map_merge(maps: MAP...) -> MAP

合并 2 个或更多映射的内容。如果多个映射具有冲突的值，则以最后一个映射中的值为准。

CURRENT_CONTEXT

语法：

current_context() -> MAP

返回一个映射，其中包含当前执行点上的所有可用字段。

MAP_KEYS

语法：

map_keys(map: MAP) -> ARRAY<STRING>

说明：

返回包含 map 值的所有键的数组。

MAP_VALUES

语法：

map_values(map: MAP) -> ARRAY<ANY>

说明：

返回一个数组，其中包含 map 值的所有值。

MAP_ENTRIES

语法：

map_entries(map: MAP) -> ARRAY<MAP>

说明：

返回一个数组，其中包含 map 值中的所有键值对。

每个键值对都将采用包含两个条目（k 和 v）的映射形式。

示例：

map map_entries(map)
{} []
{"foo" : 2L} [{"k": "foo", "v" : 2L}]
{"foo" : "bar", "bar" : "foo"} [{"k": "foo", "v" : "bar" }, {"k" : "bar", "v": "foo"}]

字符串函数

名称 说明
BYTE_LENGTH 返回 STRING 或 BYTES 值中 BYTES 的数量
CHAR_LENGTH 返回 STRING 值中的 Unicode 字符数
STARTS_WITH 如果 STRING 以指定前缀开头，则返回 TRUE
ENDS_WITH 如果 STRING 以给定的后缀结尾，则返回 TRUE
LIKE 如果 STRING 与某种模式匹配，则返回 TRUE
REGEX_CONTAINS 如果某个值与正则表达式部分或完全匹配，则返回 TRUE
REGEX_MATCH 如果该值的任何部分与正则表达式匹配，则返回 TRUE
STRING_CONCAT 将多个 STRING 连接成一个 STRING
STRING_CONTAINS 如果值包含 STRING，则返回 TRUE
TO_UPPER 将 STRING 或 BYTES 值转换为大写。
TO_LOWER 将 STRING 或 BYTES 值转换为小写。
SUBSTRING 获取 STRING 或 BYTES 值的子字符串。
STRING_REVERSE 反转 STRING 或 BYTES 值。
TRIM 从 STRING 或 BYTES 值中去除前导和尾随字符。
SPLIT 将 STRING 或 BYTES 值拆分为数组。

BYTE_LENGTH

语法：

byte_length[T <: STRING | BYTES](value: T) -> INT64

说明：

返回 STRING 或 BYTES 值中 BYTES 的出现次数。

示例：

值 byte_length(value)
"abc" 3
"xyzabc" 6
b"abc" 3
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").byteLength().as("titleByteLength")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").byteLength().as("titleByteLength")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").byteLength().as("titleByteLength")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("title").byteLength().alias("titleByteLength")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").byteLength().alias("titleByteLength")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").byte_length().as_("titleByteLength"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(byteLength(field("title")).as("titleByteLength"))
        .execute()
        .get();
PipelineSnippets.java

CHAR_LENGTH

语法：

char_length(value: STRING) -> INT64

说明：

返回 STRING 值中的 Unicode 码位数量。

示例：

值 char_length(value)
"abc" 3
“你好” 5
"world" 5
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").charLength().as("titleCharLength")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("title").charLength().alias("titleCharLength")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").charLength().alias("titleCharLength")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").char_length().as_("titleCharLength"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(charLength(field("title")).as("titleCharLength"))
        .execute()
        .get();
PipelineSnippets.java

STARTS_WITH

语法：

starts_with(value: STRING, prefix: STRING) -> BOOLEAN

说明：

如果 value 以 prefix 开头，则返回 TRUE。

示例：

值 前缀 starts_with(value, prefix)
"abc" “a” true
"abc" "b" false
"abc" "" true
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("title").startsWith("The")
            .alias("needsSpecialAlphabeticalSort")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").startsWith("The")
            .alias("needsSpecialAlphabeticalSort")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("title").starts_with("The").as_("needsSpecialAlphabeticalSort")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(startsWith(field("title"), "The").as("needsSpecialAlphabeticalSort"))
        .execute()
        .get();
PipelineSnippets.java

ENDS_WITH

语法：

ends_with(value: STRING, postfix: STRING) -> BOOLEAN

说明：

如果 value 以 postfix 结尾，则返回 TRUE。

示例：

值 postfix ends_with(value, postfix)
"abc" "c" true
"abc" "b" false
"abc" "" true
Node.js
const result = await db.pipeline()
  .collection("inventory/devices/laptops")
  .select(
    field("name").endsWith("16 inch")
      .as("16InLaptops")
  )
  .execute();
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("inventory/devices/laptops")
  .select([
    Field("name").endsWith("16 inch")
      .as("16InLaptops")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("inventory/devices/laptops")
    .select(
        field("name").endsWith("16 inch")
            .alias("16InLaptops")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("inventory/devices/laptops")
    .select(
        field("name").endsWith("16 inch")
            .alias("16InLaptops")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("inventory/devices/laptops")
    .select(Field.of("name").ends_with("16 inch").as_("16InLaptops"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("inventory/devices/laptops")
        .select(endsWith(field("name"), "16 inch").as("16InLaptops"))
        .execute()
        .get();
PipelineSnippets.java

顶

语法：

like(value: STRING, pattern: STRING) -> BOOLEAN

说明：

如果 value 与 pattern 匹配，则返回 TRUE。

示例：

值 图案 like(value, pattern)
"Firestore" "Fire%" true
"Firestore" "%store" true
"Datastore" "Data_tore" true
“100%” "100\%" true
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre").like("%Fiction")
      .as("anyFiction")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").like("%Fiction")
      .as("anyFiction")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre").like("%Fiction")
      .as("anyFiction")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre").like("%Fiction")
            .alias("anyFiction")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre").like("%Fiction")
            .alias("anyFiction")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").like("%Fiction").as_("anyFiction"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(like(field("genre"), "%Fiction").as("anyFiction"))
        .execute()
        .get();
PipelineSnippets.java

REGEX_CONTAINS

语法：

regex_contains(value: STRING, pattern: STRING) -> BOOLEAN

说明：

如果 value 的某一部分与 pattern 匹配，则返回 TRUE。如果 pattern 不是有效的正则表达式，此函数会返回 error。

正则表达式遵循 re2 库的语法。

示例：

值 图案 regex_contains(value, pattern)
"Firestore" "Fire" true
"Firestore" "store$" true
"Firestore" "data" false
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexContains("Firestore (Enterprise|Standard)")
            .alias("isFirestoreRelated")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexContains("Firestore (Enterprise|Standard)")
            .alias("isFirestoreRelated")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("title")
        .regex_contains("Firestore (Enterprise|Standard)")
        .as_("isFirestoreRelated")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexContains(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreRelated"))
        .execute()
        .get();
PipelineSnippets.java

REGEX_MATCH

语法：

regex_match(value: STRING, pattern: STRING) -> BOOLEAN

说明：

如果 value 完全匹配 pattern，则返回 TRUE。如果 pattern 不是有效的正则表达式，此函数会返回 error。

正则表达式遵循 re2 库的语法。

示例：

值 图案 regex_match(value, pattern)
"Firestore" "F.*store" true
"Firestore" "Fire" false
"Firestore" "^F.*e$" true
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexMatch("Firestore (Enterprise|Standard)")
            .alias("isFirestoreExactly")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexMatch("Firestore (Enterprise|Standard)")
            .alias("isFirestoreExactly")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("title")
        .regex_match("Firestore (Enterprise|Standard)")
        .as_("isFirestoreExactly")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexMatch(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreExactly"))
        .execute()
        .get();
PipelineSnippets.java

STRING_CONCAT

语法：

string_concat(values: STRING...) -> STRING

说明：

将两个或多个 STRING 值串联成一个结果。

示例：

参数 string_concat(values...)
() 错误
("a") “a”
("abc", "def") "abcdef"
("a", "", "c") "ac"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").stringConcat(" by ", field("author"))
      .as("fullyQualifiedTitle")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").stringConcat(" by ", field("author"))
      .as("fullyQualifiedTitle")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").concat([" by ", Field("author")])
      .as("fullyQualifiedTitle")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("title").concat(" by ", field("author"))
            .alias("fullyQualifiedTitle")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").concat(" by ", field("author"))
            .alias("fullyQualifiedTitle")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("title")
        .concat(" by ", Field.of("author"))
        .as_("fullyQualifiedTitle")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(stringConcat(field("title"), " by ", field("author")).as("fullyQualifiedTitle"))
        .execute()
        .get();
PipelineSnippets.java

STRING_CONTAINS

语法：

string_contains(value: STRING, substring: STRING) -> BOOLEAN

说明：

检查 value 是否包含字面值字符串 substring。

示例：

值 substring string_contains(value, substring)
"abc" "b" true
"abc" “d” false
"abc" "" true
"a.c" "." true
"☃☃☃" "☃" true
Node.js
const result = await db.pipeline()
  .collection("articles")
  .select(
    field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("articles")
  .select(
    field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("articles")
  .select([
    Field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("articles")
    .select(
        field("body").stringContains("Firestore")
            .alias("isFirestoreRelated")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("articles")
    .select(
        field("body").stringContains("Firestore")
            .alias("isFirestoreRelated")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("articles")
    .select(Field.of("body").string_contains("Firestore").as_("isFirestoreRelated"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("articles")
        .select(stringContains(field("body"), "Firestore").as("isFirestoreRelated"))
        .execute()
        .get();
PipelineSnippets.java

TO_UPPER

语法：

to_upper[T <: STRING | BYTES](value: T) -> T

说明：

将 STRING 或 BYTES 值转换为大写。

如果某个字节或字符不属于 UTF-8 小写字母字符，则该字节或字符将保持原样，不作改动。

示例：

值 to_upper(value)
"abc" "ABC"
"AbC" "ABC"
b"abc" b"ABC"
b"a1c" b"A1C"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("name").toUpper()
      .as("uppercaseName")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("authors")
  .select(
    field("name").toUpper()
      .as("uppercaseName")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("name").toUpper()
      .as("uppercaseName")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("authors")
    .select(
        field("name").toUpper()
            .alias("uppercaseName")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("name").toUpper()
            .alias("uppercaseName")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("authors")
    .select(Field.of("name").to_upper().as_("uppercaseName"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(toUpper(field("name")).as("uppercaseName"))
        .execute()
        .get();
PipelineSnippets.java

TO_LOWER

语法：

to_lower[T <: STRING | BYTES](value: T) -> T

说明：

将 STRING 或 BYTES 值转换为小写。

如果某个字节或字符不属于 UTF-8 大写字母字符，则该字节或字符将保持原样，不作改动。

示例：

值 to_lower(value)
"ABC" "abc"
"AbC" "abc"
“A1C” "a1c"
b"ABC" b"abc"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("authors")
  .select(
    field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("authors")
    .select(
        field("genre").toLower().equal("fantasy")
            .alias("isFantasy")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("genre").toLower().equal("fantasy")
            .alias("isFantasy")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("authors")
    .select(Field.of("genre").to_lower().equal("fantasy").as_("isFantasy"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(equal(toLower(field("genre")), "fantasy").as("isFantasy"))
        .execute()
        .get();
PipelineSnippets.java

SUBSTRING

语法：

substring[T <: STRING | BYTES](input: T, position: INT64) -> T
substring[T <: STRING | BYTES](input: T, position: INT64, length: INT64) -> T

说明：

返回 input 的子字符串，从 position（从零开始的索引）开始，最多包含 length 个条目。如果未提供 length，则返回从 position 到 input 结尾的子字符串。

  • 如果 input 是 STRING 类型的值，则 position 和 length 的计量单位是 Unicode 码位。如果它是 BYTES 类型的值，则计量单位是字节。

  • 如果 position 大于 input 的长度，则返回空子字符串。如果 position 与 length 之和大于 input 的长度，则子字符串将从起始位置截取到 input 的末尾。

  • 如果 position 为负数，则位置从输入的末尾开始计算。如果负的 position 大于输入大小，则位置将被设置为零。length 必须为非负数。

示例：

未提供 length 时：

输入 position substring(input, position)
"abc" 0 "abc"
"abc" 1 "bc"
"abc" 3 ""
"abc" -1 "c"
b"abc" 1 b"bc"

当提供 length 时：

输入 position 长度 substring(input, position, length)
"abc" 0 1 “a”
"abc" 1 2 "bc"
"abc" -1 1 "c"
b"abc" 0 1 b"a"
Node.js
const result = await db.pipeline()
  .collection("books")
  .where(field("title").startsWith("The "))
  .select(
    field("title").substring(4)
      .as("titleWithoutLeadingThe")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .where(field("title").startsWith("The "))
  .select(
    field("title").substring(4)
      .as("titleWithoutLeadingThe")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .where(Field("title").startsWith("The "))
  .select([
    Field("title").substring(position: 4)
      .as("titleWithoutLeadingThe")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .where(field("title").startsWith("The "))
    .select(
        field("title")
          .substring(constant(4),
            field("title").charLength().subtract(4))
            .alias("titleWithoutLeadingThe")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .where(field("title").startsWith("The "))
    .select(
        field("title").substring(
          constant(4),
            field("title").charLength().subtract(4))
            .alias("titleWithoutLeadingThe")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .where(Field.of("title").starts_with("The "))
    .select(Field.of("title").substring(4).as_("titleWithoutLeadingThe"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .where(startsWith(field("title"), "The "))
        .select(
            substring(field("title"), constant(4), field("title").charLength())
                .as("titleWithoutLeadingThe"))
        .execute()
        .get();
PipelineSnippets.java

STRING_REVERSE

语法：

string_reverse[T <: STRING | BYTES](input: T) -> T

说明：

按相反顺序返回所提供的输入内容。

当输入为 STRING 类型时，字符以 Unicode 码位为单位进行划分；当输入为 BYTES 类型的值时，则以字节为单位进行划分。

示例：

输入 string_reverse(input)
"abc" "cba"
"a🌹b" "b🌹a"
“你好” "olleh"
b"abc" b"cba"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").reverse().as("reversedName")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("name").reverse().alias("reversedName")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").reverse().alias("reversedName")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("name").string_reverse().as_("reversedName"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(reverse(field("name")).as("reversedName"))
        .execute()
        .get();
PipelineSnippets.java

TRIM

语法：

trim[T <: STRING | BYTES](input: T, values_to_trim: T) -> T
trim[T <: STRING | BYTES](input: T) -> T

说明：

从所提供的 input 的开头和结尾处，移除指定的一组 BYTES 或 CHARS。

  • 如果未提供 values_to_trim，则会去除空白字符。

示例：

未提供 values_to_trim 时：

输入 trim(input)
" foo " "foo"
b" foo " b"foo"
"foo" "foo"
"" ""
" " ""
"\t foo \n" "foo"
b"\t foo \n" b"foo"
"\r\f\v foo \r\f\v" "foo"
b"\r\f\v foo \r\f\v" b"foo"

当提供 values_to_trim 时：

输入 values_to_trim trim(input, values_to_trim)
"abcbfooaacb" "abc" "foo"
"abcdaabadbac" "abc" "daabad"
b"C1C2C3" b"C1" b"C2C3"
b"C1C2" "foo" 错误
"foo" b"C1" 错误

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("name").trim().as("whitespaceTrimmedName")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").trim(" \n\t").as("whitespaceTrimmedName")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("name").trim().alias("whitespaceTrimmedName")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").trim().alias("whitespaceTrimmedName")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("name").trim().as_("whitespaceTrimmedName"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(trim(field("name")).as("whitespaceTrimmedName"))
        .execute()
        .get();
PipelineSnippets.java

SPLIT

语法：

split(input: STRING) -> ARRAY<STRING>
split[T <: STRING | BYTES](input: T, delimiter: T) -> ARRAY<T>

说明：

使用分隔符拆分 STRING 或 BYTES 值。

  • 对于 STRING，默认分隔符是英文逗号 ,。分隔符会被视为单个字符串。

  • 对于 BYTES，您必须指定一个分隔符。

  • 使用空分隔符进行拆分时，对于 STRING 类型的值会生成 Unicode 码位数组，而对于 BYTES 类型的值则会生成 BYTES 数组。

  • 拆分空 STRING 会返回一个 ARRAY，其中只包含一个空 STRING 元素。

示例：

未提供 delimiter 时：

输入 split(input)
"foo,bar,foo" ["foo", "bar", "foo"]
"foo" ["foo"]
",foo," ["", "foo", ""]
"" [""]
b"C120C2C4" 错误

当提供 delimiter 时：

输入 delimiter split(input, delimiter)
“foo bar foo” " " ["foo", "bar", "foo"]
“foo bar foo” "z" ["foo bar foo"]
"abc" "" ["a", "b", "c"]
b"C1,C2,C4" b"," [b"C1", b"C2", b"C4"]
b"ABC" b"" [b"A", b"B", b"C"]
"foo" b"C1" 错误

时间戳函数

名称 说明
CURRENT_TIMESTAMP 生成与请求时间对应的 TIMESTAMP。
TIMESTAMP_TRUNC 将 TIMESTAMP 按指定粒度进行截断。
UNIX_MICROS_TO_TIMESTAMP 将自 1970-01-01 00:00:00 UTC 以来的微秒数转换为 TIMESTAMP
UNIX_MILLIS_TO_TIMESTAMP 将自 1970-01-01 00:00:00 UTC 以来的毫秒数转换为 TIMESTAMP
UNIX_SECONDS_TO_TIMESTAMP 将自 1970-01-01 00:00:00 UTC 以来的秒数转换为 TIMESTAMP
TIMESTAMP_ADD 将时间间隔加到 TIMESTAMP
TIMESTAMP_SUB 从 TIMESTAMP 中减去一个时间间隔
TIMESTAMP_TO_UNIX_MICROS 将 TIMESTAMP 转换为自 1970-01-01 00:00:00 UTC 以来的微秒数
TIMESTAMP_TO_UNIX_MILLIS 将 TIMESTAMP 转换为自 1970-01-01 00:00:00 UTC 以来的毫秒数
TIMESTAMP_TO_UNIX_SECONDS 将 TIMESTAMP 转换为自 1970-01-01 00:00:00 UTC 以来的秒数

CURRENT_TIMESTAMP

语法：

current_timestamp() -> TIMESTAMP

说明：

获取请求时间 input 起始点的时间戳（该时间戳被解释为自 1970-01-01 00:00:00 UTC 以来经过的微秒数）。

此函数在单次查询中是稳定的，即多次调用将始终解析为同一个值。

TIMESTAMP_TRUNC

语法：

timestamp_trunc(timestamp: TIMESTAMP, granularity: STRING[, timezone: STRING]) -> TIMESTAMP

说明：

将时间戳按指定粒度向下取整。

granularity 实参必须为字符串，且必须是以下值之一：

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • week([weekday])
  • month
  • quarter
  • year
  • isoyear

如果提供了 timezone 实参，则截断将以指定时区的日历边界为准（例如，以指定时区的午夜作为一天的截断时间）。截断将遵循夏令时。

如果未提供 timezone，截断将以 UTC 日历边界为准。

timezone 实参应为 tz 数据库中某个时区的字符串表示法，例如 America/New_York。您还可以通过指定与 GMT 的偏移值来使用自定义时间偏移值。

示例：

timestamp granularity timezone timestamp_trunc(timestamp, granularity, timezone)
2000-01-01 10:20:30:123456 UTC “second” 未提供 2001-01-01 10:20:30 UTC
1997-05-31 04:30:30 UTC “day” 未提供 1997-05-31 00:00:00 UTC
1997-05-31 04:30:30 UTC “day” “America/Los_Angeles” 1997-05-30 07:00:00 UTC
2001-03-16 04:00:00 UTC "week(friday) 未提供 2001-03-16 00:00:00 UTC
2001-03-23 04:00:00 UTC "week(friday) “America/Los_Angeles” 2001-03-23 17:00:00 UTC
2026-01-24 20:00:00 UTC "month" "GMT+06:32:43" 2026-01-01T06:32:43 UTC

UNIX_MICROS_TO_TIMESTAMP

语法：

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

说明：

将 input（解释为自 1970-01-01 00:00:00 UTC 以来的微秒数）转换为 TIMESTAMP。如果 input 无法转换为有效的 TIMESTAMP，则会抛出 error。

示例：

input unix_micros_to_timestamp(input)
0L 1970-01-01 00:00:00 UTC
400123456L 1970-01-01 00:06:40.123456 UTC
-1000000L 1969-12-31 23:59:59 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMicros")
        .unix_micros_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

UNIX_MILLIS_TO_TIMESTAMP

语法：

unix_millis_to_timestamp(input: INT64) -> TIMESTAMP

说明：

将 input（解释为自 1970-01-01 00:00:00 UTC 以来的毫秒数）转换为 TIMESTAMP。如果 input 无法转换为有效的 TIMESTAMP，则会抛出 error。

示例：

input unix_millis_to_timestamp(input)
0L 1970-01-01 00:00:00 UTC
4000123L 1970-01-01 01:06:40.123 UTC
-1000000L 1969-12-31 23:43:20 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMillis")
        .unix_millis_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

UNIX_SECONDS_TO_TIMESTAMP

语法：

unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP

说明：

将 input（解释为自 1970-01-01 00:00:00 UTC 以来的秒数）转换为 TIMESTAMP。如果 input 无法转换为有效的 TIMESTAMP，则会抛出 error。

示例：

input unix_seconds_to_timestamp(input)
0L 1970-01-01 00:00:00 UTC
60L 1970-01-01 00:01:00 UTC
-300L 1969-12-31 23:55:00 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtSeconds")
        .unix_seconds_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

TIMESTAMP_ADD

语法：

timestamp_add(timestamp: TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

说明：

将 amount unit 加到 timestamp。amount 实参可以为负值，在这种情况下，其效果等同于 TIMESTAMP_SUB。

unit 实参必须为字符串，且必须是以下值之一：

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

如果生成的时间戳超出 TIMESTAMP 范围，将抛出错误。

示例：

timestamp unit amount timestamp_add(timestamp, unit, amount)
2025-02-20 00:00:00 UTC “minute” 2L 2025-02-20 00:02:00 UTC
2025-02-20 00:00:00 UTC "hour" -4L 2025-02-19 20:00:00 UTC
2025-02-20 00:00:00 UTC “day” 5L 2025-02-25 00:00:00 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAt").timestampAdd(3653, .day).as("expiresAt")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt")
          .timestampAdd("day", 3653)
          .alias("expiresAt")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt").timestampAdd("day", 3653).alias("expiresAt")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("createdAt").timestamp_add("day", 3653).as_("expiresAt"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt"))
        .execute()
        .get();
PipelineSnippets.java

TIMESTAMP_SUB

语法：

timestamp_sub(timestamp: TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

说明：

从 timestamp 减去 amount unit。amount 实参可以为负值，在这种情况下，其效果等同于 TIMESTAMP_ADD。

unit 实参必须为字符串，且必须是以下值之一：

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

如果生成的时间戳超出 TIMESTAMP 范围，将抛出错误。

示例：

timestamp unit amount timestamp_sub(timestamp, unit, amount)
2026-07-04 00:00:00 UTC “minute” 40L 2026-07-03 23:20:00 UTC
2026-07-04 00:00:00 UTC "hour" -24L 2026-07-05 00:00:00 UTC
2026-07-04 00:00:00 UTC “day” 3L 2026-07-01 00:00:00 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("expiresAt").timestampSubtract(14, .day).as("sendWarningTimestamp")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt")
          .timestampSubtract("day", 14)
          .alias("sendWarningTimestamp")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt").timestampSubtract("day", 14).alias("sendWarningTimestamp")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("expiresAt")
        .timestamp_subtract("day", 14)
        .as_("sendWarningTimestamp")
    )
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp"))
        .execute()
        .get();
PipelineSnippets.java

TIMESTAMP_TO_UNIX_MICROS

语法：

timestamp_to_unix_micros(input: TIMESTAMP) -> INT64

说明：

将 input 转换为自 1970-01-01 00:00:00 UTC 以来的微秒数。通过向下舍入到微秒来截断更高的精度。

示例：

input timestamp_to_unix_micros(input)
1970-01-01 00:00:00 UTC 0L
1970-01-01 00:06:40.123456 UTC 400123456L
1969-12-31 23:59:59 UTC -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMicros().as("unixMicros")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_micros().as_("unixMicros"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMicros(field("dateString")).as("unixMicros"))
        .execute()
        .get();
PipelineSnippets.java

TIMESTAMP_TO_UNIX_MILLIS

语法：

timestamp_to_unix_millis(input: TIMESTAMP) -> INT64

说明：

将 input 转换为自 1970-01-01 00:00:00 UTC 以来的毫秒数。通过向下舍入到毫秒来截断更高的精度。

示例：

input timestamp_to_unix_millis(input)
1970-01-01 00:00:00 UTC 0L
1970-01-01 01:06:40.123 UTC 4000123L
1969-12-31 23:43:20 -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMillis().as("unixMillis")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_millis().as_("unixMillis"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMillis(field("dateString")).as("unixMillis"))
        .execute()
        .get();
PipelineSnippets.java

TIMESTAMP_TO_UNIX_SECONDS

语法：

timestamp_to_unix_seconds(input: TIMESTAMP) -> INT64

说明：

将 input 转换为自 1970-01-01 00:00:00 UTC 以来的秒数。通过向下舍入到秒来截断更高的精度。

示例：

input timestamp_to_unix_seconds(input)
1970-01-01 00:00:00 UTC 0L
1970-01-01 00:01:00 UTC 60L
1969-12-31 23:55:00 UTC -300L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixSeconds().as("unixSeconds")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_seconds().as_("unixSeconds"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds"))
        .execute()
        .get();
PipelineSnippets.java
## **类型函数**
名称 说明
TYPE 以 STRING 的形式返回该值的类型。
### TYPE **语法：** ```none type(input: ANY) -> STRING ``` **说明：** 返回“input”类型的字符串表示法。 如果给定的是缺失值，则返回 `NULL`。 **示例：** | `input` | `type(input)` | |---|---| | NULL | "null" | | true | "boolean" | | 1 | "int32" | | -3L | "int64" | | 3.14 | "float64" | | 2024-01-01T00:00:00Z UTC | "timestamp" | | "foo" | "string" | | b"foo" | "bytes" | | [1, 2] | "array" | | {"a": 1} | "map" | | `path("c/d")` | "reference" | | `vector([1.0, 2.0])` | "vector" | | ABSENT | NULL | **客户端示例**
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("title").notEqual("1984").as("not1984")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").not_equal("1984").as_("not1984"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(notEqual(field("title"), "1984").as("not1984"))
        .execute()
        .get();
PipelineSnippets.java

向量函数

名称 说明
COSINE_DISTANCE 返回两个向量之间的余弦距离
DOT_PRODUCT 返回两个向量之间的点积
EUCLIDEAN_DISTANCE 返回两个向量之间的欧几里得距离
MANHATTAN_DISTANCE 返回两个向量之间的曼哈顿距离
VECTOR_LENGTH 返回向量中的元素数量

COSINE_DISTANCE

语法：

cosine_distance(x: VECTOR, y: VECTOR) -> FLOAT64

说明：

返回 x 和 y 之间的余弦距离。

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").cosineDistance(sampleVector).as("cosineDistance")
  )
  .execute();
test.firestore.js

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").cosineDistance(sampleVector).as("cosineDistance")));
test.firestore.js
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").cosineDistance(sampleVector).as("cosineDistance")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").cosineDistance(sampleVector).alias("cosineDistance")
    )
    .execute()
DocSnippets.kt
Java
Android
double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").cosineDistance(sampleVector).alias("cosineDistance")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("embedding").cosine_distance(sample_vector).as_("cosineDistance")
    )
    .execute()
)
firestore_pipelines.py
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(cosineDistance(field("embedding"), sampleVector).as("cosineDistance"))
        .execute()
        .get();
PipelineSnippets.java

DOT_PRODUCT

语法：

dot_product(x: VECTOR, y: VECTOR) -> FLOAT64

说明：

返回 x 和 y 的点积。

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").dotProduct(sampleVector).as("dotProduct")
  )
  .execute();
test.firestore.js

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").dotProduct(sampleVector).as("dotProduct")
  )
);
test.firestore.js
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").dotProduct(sampleVector).as("dotProduct")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").dotProduct(sampleVector).alias("dotProduct")
    )
    .execute()
DocSnippets.kt
Java
Android
double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").dotProduct(sampleVector).alias("dotProduct")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("embedding").dot_product(sample_vector).as_("dotProduct"))
    .execute()
)
firestore_pipelines.py
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(dotProduct(field("embedding"), sampleVector).as("dotProduct"))
        .execute()
        .get();
PipelineSnippets.java

EUCLIDEAN_DISTANCE

语法：

euclidean_distance(x: VECTOR, y: VECTOR) -> FLOAT64

说明：

计算 x 和 y 之间的欧几里得距离。

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  )
  .execute();
test.firestore.js

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  )
);
test.firestore.js
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").euclideanDistance(sampleVector).alias("euclideanDistance")
    )
    .execute()
DocSnippets.kt
Java
Android
double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").euclideanDistance(sampleVector).alias("euclideanDistance")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("embedding")
        .euclidean_distance(sample_vector)
        .as_("euclideanDistance")
    )
    .execute()
)
firestore_pipelines.py
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(euclideanDistance(field("embedding"), sampleVector).as("euclideanDistance"))
        .execute()
        .get();
PipelineSnippets.java

MANHATTAN_DISTANCE

语法：

manhattan_distance(x: VECTOR, y: VECTOR) -> FLOAT64

说明：

计算 x 和 y 之间的曼哈顿距离。

VECTOR_LENGTH

语法：

vector_length(vector: VECTOR) -> INT64

说明：

返回 VECTOR 中的元素数量。

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").vectorLength().as("vectorLength")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").vectorLength().as("vectorLength")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").vectorLength().as("vectorLength")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").vectorLength().alias("vectorLength")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").vectorLength().alias("vectorLength")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("embedding").vector_length().as_("vectorLength"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(vectorLength(field("embedding")).as("vectorLength"))
        .execute()
        .get();
PipelineSnippets.java

后续步骤