Referência de todas as funções

Aggregate

Todas as funções de agregação podem ser usadas como expressões de nível superior na etapa aggregate(...).

Nome Descrição
COUNT Retorna o número de documentos.
COUNT_IF Retorna a contagem de documentos em que uma expressão é avaliada como TRUE.
COUNT_DISTINCT Retorna a contagem de valores exclusivos e diferentes de NULL.
SUM Retorna a soma de todos os valores de NUMERIC
AVERAGE Retorna a média de todos os valores de NUMERIC.
MINIMUM Retorna o valor mínimo diferente de NULL.
MAXIMUM Retorna o valor máximo não NULL
FIRST Retorna o valor expression do primeiro documento.
LAST Retorna o valor expression do último documento.
ARRAY_AGG Retorna uma matriz de todos os valores de entrada.
ARRAY_AGG_DISTINCT Retorna uma matriz de todos os valores de entrada distintos.

COUNT

Sintaxe:

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

Descrição:

Retorna a contagem de documentos da etapa anterior em que expression é avaliado como qualquer valor diferente de NULL. Se nenhum expression for fornecido, vai retornar a contagem total de documentos da etapa anterior.

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

Sintaxe:

count_if(expression: BOOLEAN) -> INT64

Descrição:

Retorna o número de documentos da etapa anterior em que expression é avaliado como 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

Sintaxe:

count_distinct(expression: ANY) -> INT64

Descrição:

Retorna o número de valores não NULL e não ABSENT exclusivos de expression.

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

Sintaxe:

sum(expression: ANY) -> NUMBER

Descrição:

Retorna a soma de todos os valores numéricos, ignorando os não numéricos. Retorna NaN se algum valor for NaN.

A saída terá o mesmo tipo de entrada maior, exceto nestes casos:

  • Um INTEGER será convertido em um DOUBLE se não puder ser representado como um INTEGER.
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

MÉDIA

Sintaxe:

average(expression: ANY) -> FLOAT64

Descrição:

Retorna a média de todos os valores numéricos, ignorando os não numéricos. Será avaliado como NaN se algum valor for NaN ou NULL se nenhum valor numérico for agregado.

A saída terá o mesmo tipo da entrada, exceto nestes casos:

  • Um INTEGER será convertido em um DOUBLE se não puder ser representado como um INTEGER.
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

Sintaxe:

minimum(expression: ANY) -> ANY

Descrição:

Retorna o valor mínimo não NULL e não ausente de expression quando avaliado em cada documento.

Se não houver valores presentes e diferentes de NULL, NULL será retornado. Isso inclui quando nenhum documento é considerado.

Se houver vários valores equivalentes mínimos, qualquer um deles poderá ser retornado. A ordem de tipo de valor segue a ordem documentada.

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

Sintaxe:

maximum(expression: ANY) -> ANY

Descrição:

Retorna o valor máximo não NULL e não ausente de expression quando avaliado em cada documento.

Se não houver valores presentes e diferentes de NULL, NULL será retornado. Isso inclui quando nenhum documento é considerado.

Se houver vários valores equivalentes máximos, qualquer um deles poderá ser retornado. A ordem de tipo de valor segue a ordem documentada.

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

Sintaxe:

first(expression: ANY) -> ANY

Descrição:

Retorna o valor de expression do primeiro documento retornado.

LAST

Sintaxe:

last(expression: ANY) -> ANY

Descrição:

Retorna o valor de expression do último documento retornado.

ARRAY_AGG

Sintaxe:

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

Descrição:

Retorna uma matriz que contém todos os valores de expression quando avaliados em cada documento.

Se a expressão resultar em um valor ausente, ela será convertida em NULL.

A ordem dos elementos na matriz de saída não é estável e não deve ser usada como referência.

ARRAY_AGG_DISTINCT

Sintaxe:

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

Descrição:

Retorna uma matriz que contém todos os valores distintos de expression quando avaliados em cada documento.

Se a expressão resultar em um valor ausente, ela será convertida em NULL.

A ordem dos elementos na matriz de saída não é estável e não deve ser usada como referência.

Funções aritméticas

Todas as funções aritméticas no Firestore têm os seguintes comportamentos:

  • Será avaliado como NULL se algum dos parâmetros de entrada for NULL.
  • Será avaliado como NaN se algum dos argumentos for NaN.
  • Gera um erro se ocorrer um estouro ou um estouro negativo.

Além disso, quando uma função aritmética usa vários argumentos numéricos de tipos diferentes (por exemplo, add(5.0, 6)), o Firestore converte implicitamente os argumentos para o tipo de entrada mais amplo. Se apenas entradas INT32 forem fornecidas, o tipo de retorno será INT64.

Nome Descrição
ABS Retorna o valor absoluto de um number
ADD Retorna o valor de x + y
SUBTRACT Retorna o valor de x - y
MULTIPLY Retorna o valor de x * y
DIVIDE Retorna o valor de x / y
MOD Retorna o restante da divisão de x / y
CEIL Retorna o teto de um number
FLOOR Retorna o piso de um number
ROUND Arredonda um number para places casas decimais
TRUNC Trunca um number para places casas decimais
POW Retorna o valor de base^exponent
SQRT Retorna a raiz quadrada de um number
EXP Retorna o número de Euler elevado à potência de exponent
LN Retorna o logaritmo natural de um number
LOG Retorna o logaritmo de um number
LOG10 Retorna o logaritmo de number na base 10.
RAND Retorna um número de ponto flutuante pseudorrandômico.

ABS

Sintaxe:

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

Descrição:

Retorna o valor absoluto de um number.

  • Gera um erro quando a função excederia um valor INT32 ou INT64.

Exemplos:

número abs(number)
10 10
-10 10
10L 10L
-0,0 0,0
10,5 10,5
-10,5 10,5
-231 [error]
-263 [error]

ADICIONAR

Sintaxe:

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

Descrição:

Retorna o valor de x + y.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o valor de x - y.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o valor de x * y.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o valor de x / y. A divisão inteira está truncada.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o restante de x / y.

  • Gera um error quando y é zero para tipos de números inteiros (INT64).
  • Retorna NaN quando y é zero para tipos de ponto flutuante (FLOAT64).

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o menor valor inteiro que não é menor que number.

Exemplos:

número 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

Sintaxe:

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

Descrição:

Retorna o maior valor inteiro que não é maior que number.

Exemplos:

número 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

Sintaxe:

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

Descrição:

Arredonda places dígitos de um number. Arredonda os dígitos à direita da vírgula decimal se places for positivo e à esquerda se for negativo.

  • Se apenas number for fornecido, o arredondamento será para o valor inteiro mais próximo.
  • Arredonda para longe de zero em casos de metade.
  • Um error será gerado se o arredondamento com um valor places negativo resultar em estouro.

Exemplos:

número casas 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

TRUNC

Sintaxe:

trunc[N <: Number](number: N) -> N
trunc[N <: Number](number:  N, places: INT64) -> N

Descrição:

Trunca um number para um número especificado de places casas decimais. Trunca os dígitos à direita da vírgula decimal se places for positivo e à esquerda se for negativo.

  • Se apenas number for fornecido, o truncamento será para o valor inteiro mais próximo de zero.
  • Um error será gerado se o truncamento resultar em estouro.

Exemplos:

número casas trunc(number, places)
15.5 0 15.0
-15,5 0 -15.0
15 1 15
15 0 15
15 -1 10
15 -2 0
15.48924 1 15.4
-15.48924 2 -15.48

POW

Sintaxe:

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

Descrição:

Retorna o valor base elevado à potência de exponent.

  • Gera um erro se base <= 0 e exponent forem negativos.

  • Para qualquer exponent, pow(1, exponent) é 1.

  • Para qualquer base, pow(base, 0) é 1.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna a raiz quadrada de um number.

  • Gera um error se number for negativo.

Exemplos:

número 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

Sintaxe:

exp(exponent: FLOAT64) -> FLOAT64

Descrição:

Retorna o valor do número de Euler elevado à potência de exponent, também chamada de função exponencial natural.

Exemplos:

expoente 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

Sintaxe:

ln(number: FLOAT64) -> FLOAT64

Descrição:

Retorna o logaritmo natural de number. Esta função é equivalente a log(number).

Exemplos:

número 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

Sintaxe:

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

Descrição:

Retorna o logaritmo de number para base.

  • Se apenas number for fornecido, vai retornar o logaritmo de number para base (sinônimo de ln(number)).

Exemplos:

número base 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

Sintaxe:

log10(x: FLOAT64) -> FLOAT64

Descrição:

Retorna o logaritmo de number na base 10.

Exemplos:

número log10(number)
100 2,0
-inf NaN
+inf +inf
x <= 0 [error]

RAND

Sintaxe:

rand() -> FLOAT64

Descrição:

Retorna um número de ponto flutuante pseudorrandômico, escolhido uniformemente entre 0.0 (inclusivo) e 1.0 (exclusivo).

Funções de matriz

Nome Descrição
ARRAY Retorna um ARRAY que contém um elemento para cada argumento de entrada.
ARRAY_CONCAT Concatena várias matrizes em um único ARRAY
ARRAY_CONTAINS Retorna TRUE se um determinado ARRAY contém um valor específico.
ARRAY_CONTAINS_ALL Retorna TRUE se todos os valores estiverem presentes no ARRAY.
ARRAY_CONTAINS_ANY Retorna TRUE se algum dos valores estiver presente no ARRAY
ARRAY_FILTER Filtra elementos de um ARRAY que não satisfazem um predicado.
ARRAY_FIRST Retorna o primeiro elemento em um ARRAY
ARRAY_FIRST_N Retorna os primeiros elementos n em um ARRAY
ARRAY_GET Retorna o elemento em um determinado índice em um ARRAY
ARRAY_INDEX_OF Retorna o índice da primeira ocorrência de um valor em um ARRAY.
ARRAY_INDEX_OF_ALL Retorna todos os índices de um valor em um ARRAY
ARRAY_LENGTH Retorna o número de elementos em um ARRAY
ARRAY_LAST Retorna o último elemento em um ARRAY
ARRAY_LAST_N Retorna os últimos elementos n em um ARRAY
ARRAY_REVERSE Inverte a ordem dos elementos em um ARRAY.
ARRAY_SLICE Retorna uma fração de um ARRAY
ARRAY_TRANSFORM Transforma elementos em um ARRAY aplicando uma expressão a cada elemento
MAXIMUM Retorna o valor máximo em um ARRAY
MAXIMUM_N Retorna os n maiores valores em um ARRAY
MINIMUM Retorna o valor mínimo em um ARRAY
MINIMUM_N Retorna os n menores valores em um ARRAY.
SUM Retorna a soma de todos os valores NUMERIC em um ARRAY.
JOIN Produz uma concatenação dos elementos em um ARRAY como um valor STRING.

ARRAY

Sintaxe:

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

Descrição:

Cria uma matriz com base nos elementos fornecidos.

  • Se um argumento não existir, ele será substituído por NULL na matriz resultante.

Exemplos:

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

Sintaxe:

array_concat(arrays: ARRAY...) -> ARRAY

Descrição:

Concatena duas ou mais matrizes em um único ARRAY.

Exemplos:

matrizes 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

Sintaxe:

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

Descrição:

Retorna TRUE se value for encontrado no array. Caso contrário, retorna FALSE.

Exemplos:

matriz valor array_contains(array, value)
[1, 2, 3] 2 verdadeiro
[[1, 2], [3]] [1, 2] verdadeiro
[1, null] null verdadeiro
"abc" ANY erro
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

Sintaxe:

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

Descrição:

Retorna TRUE se todos os search_values forem encontrados no array. Caso contrário, retorna FALSE.

Exemplos:

matriz search_values array_contains_all(array, search_values)
[1, 2, 3] [1, 2] verdadeiro
[1, 2, 3] [1, 4] falso
[1, null] [null] verdadeiro
[NaN] [NaN] verdadeiro
[] [] verdadeiro
[1, 2, 3] [] verdadeiro
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

Sintaxe:

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

Descrição:

Retorna TRUE se um dos search_values for encontrado no array. Caso contrário, retorna FALSE.

Exemplos:

matriz search_values array_contains_any(array, search_values)
[1, 2, 3] [4, 1] verdadeiro
[1, 2, 3] [4, 5] falso
[1, 2, null] [null] verdadeiro
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_FILTER

Sintaxe:

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

Descrição:

Filtra array usando uma expressão predicate, retornando uma nova matriz com apenas elementos que satisfazem o predicado.

  • Para cada elemento em array, predicate é avaliado. Se ele retornar true, o elemento será incluído no resultado. Caso contrário (se retornar false ou null), ele será omitido.
  • Se predicate for avaliado como um valor não booleano ou não nulo, a função vai retornar um erro.

Exemplos:

matriz predicado array_filter(array, predicate)
[1, 2, 3] x -> x > 1 [2, 3]
[1, null, 3] x -> x > 1 [3]
["a", "b", "c"] x -> x != "b" ["a", "c"]
[] x -> true []

ARRAY_GET

Sintaxe:

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

Descrição:

Retorna o elemento no index baseado em zero em array.

  • Se index for negativo, os elementos serão acessados do final da matriz, em que -1 é o último elemento.
  • Se array não for do tipo ARRAY nem null, vai retornar um erro.
  • Se index estiver fora dos limites, a função vai retornar um valor ausente.
  • Se index não for do tipo INT64, a função vai retornar um erro.

Exemplos:

matriz índice array_get(array, index)
[1, 2, 3] 0 1
[1, 2, 3] -1 3
[1, 2, 3] 3 ausente
[1, 2, 3] -4 ausente
"abc" 0 erro
null 0 null
Array "a" erro
Array 2,0 erro

ARRAY_LENGTH

Sintaxe:

array_length(array: ARRAY) -> INT64

Descrição:

Retorna o número de elementos em um array.

Exemplos:

matriz 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

Sintaxe:

array_reverse(array: ARRAY) -> ARRAY

Descrição:

Inverte o array especificado.

Exemplos:

matriz 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

ARRAY_FIRST

Sintaxe:

array_first(array: ARRAY) -> ANY

Descrição:

Retorna o primeiro elemento em array. É equivalente a array_get(array, 0).

  • Se array estiver vazio, vai retornar um valor ausente.

Exemplos:

matriz array_first(array)
[1, 2, 3] 1
[] ausente

ARRAY_FIRST_N

Sintaxe:

array_first_n(array: ARRAY, n: INT64) -> ARRAY

Descrição:

Retorna os primeiros elementos n de array. É equivalente a array_slice(array, 0, n).

  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n array_first_n(array, n)
[1, 2, 3, 4, 5] 3 [1, 2, 3]
[1, 2] 3 [1, 2]
[1, 2, 3] 0 []

ARRAY_INDEX_OF

Sintaxe:

array_index_of(array: ARRAY, value: ANY) -> INT64

Descrição:

Retorna o índice baseado em zero da primeira ocorrência de value em array. Retorna -1 se value não for encontrado.

Exemplos:

matriz valor array_index_of(array, value)
[1, 2, 3, 2] 2 1
[1, 2, 3] 4 -1
[1, null, 3] null 1

ARRAY_INDEX_OF_ALL

Sintaxe:

array_index_of_all(array: ARRAY, value: ANY) -> ARRAY<INT64>

Descrição:

Retorna uma matriz que contém os índices baseados em zero de todas as ocorrências de value em array. Retorna [] se value não for encontrado.

Exemplos:

matriz valor array_index_of_all(array, value)
[1, 2, 3, 2] 2 [1, 3]
[1, 2, 3] 4 []
[1, null, 3, null] null [1, 3]

ARRAY_LAST

Sintaxe:

array_last(array: ARRAY) -> ANY

Descrição:

Retorna o último elemento em array. É equivalente a array_get(array, -1).

  • Se array estiver vazio, vai retornar um valor ausente.

Exemplos:

matriz array_last(array)
[1, 2, 3] 3
[] ausente

ARRAY_LAST_N

Sintaxe:

array_last_n(array: ARRAY, n: INT64) -> ARRAY

Descrição:

Retorna os últimos elementos n de array.

  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n array_last_n(array, n)
[1, 2, 3, 4, 5] 3 [3, 4, 5]
[1, 2] 3 [1, 2]
[1, 2, 3] 0 []

ARRAY_SLICE

Sintaxe:

array_slice(array: ARRAY, offset: INT64, length: INT64) -> ARRAY

Descrição:

Retorna um subconjunto de array começando pelo índice baseado em zero offset e incluindo length elementos.

  • Se offset for negativo, ele vai indicar a posição inicial do final da matriz, em que -1 é o último elemento.
  • Se length for maior que o número de elementos restantes na matriz após offset, o resultado será estendido até o final da matriz.
  • length não pode ser negativo. Caso contrário, um erro será retornado.

Exemplos:

matriz offset comprimento array_slice(array, offset, length)
[1, 2, 3, 4, 5] 1 3 [2, 3, 4]
[1, 2, 3, 4, 5] -2 2 [4, 5]
[1, 2, 3] 1 5 [2, 3]
[1, 2, 3] 3 2 []

ARRAY_TRANSFORM

Sintaxe:

array_transform(array: ARRAY, expression: (ANY) -> ANY) -> ARRAY
array_transform(array: ARRAY, expression: (ANY, INT64) -> ANY) -> ARRAY

Descrição:

Transforma array aplicando expression a cada elemento e retorna uma nova matriz com elementos transformados. A matriz de saída sempre terá o mesmo tamanho da matriz de entrada.

  • expression pode ser uma função unária element -> result ou uma função binária (element, index) -> result.
  • Se expression for unário, ele será chamado com cada elemento de array.
  • Se expression for binário, ele será chamado com cada elemento de array e o índice correspondente baseado em zero.

Exemplos:

matriz expressão array_transform(array, expression)
[1, 2, 3] x -> x * 2 [2, 4, 6]
[1, 2, 3] x -> x + 1 [2, 3, 4]
[10, 20] (x, i) -> x + i [10, 21]
[] x -> 1 []

MAXIMUM

Sintaxe:

maximum(array: ARRAY) -> ANY

Descrição:

Retorna o valor máximo em array.

  • Os valores NULL são ignorados durante a comparação.
  • Se array estiver vazio ou contiver apenas valores NULL, vai retornar NULL.

Exemplos:

matriz maximum(array)
[1, 5, 2] 5
[1, null, 5] 5
["a", "c", "b"] "c"
[null, null] null
[] null

MAXIMUM_N

Sintaxe:

maximum_n(array: ARRAY, n: INT64) -> ARRAY

Descrição:

Retorna uma matriz dos n maiores valores em array em ordem decrescente.

  • Os valores NULL são ignorados.
  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n maximum_n(array, n)
[1, 5, 2, 4, 3] 3 [5, 4, 3]
[1, null, 5] 3 [5, 1]

MINIMUM

Sintaxe:

minimum(array: ARRAY) -> ANY

Descrição:

Retorna o valor mínimo em array.

  • Os valores NULL são ignorados durante a comparação.
  • Se array estiver vazio ou contiver apenas valores NULL, vai retornar NULL.

Exemplos:

matriz minimum(array)
[1, 5, 2] 1
[5, null, 1] 1
["a", "c", "b"] "a"
[null, null] null
[] null

MINIMUM_N

Sintaxe:

minimum_n(array: ARRAY, n: INT64) -> ARRAY

Descrição:

Retorna uma matriz dos n menores valores em array em ordem crescente.

  • Os valores NULL são ignorados.
  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n minimum_n(array, n)
[1, 5, 2, 4, 3] 3 [1, 2, 3]
[5, null, 1] 3 [1, 5]

SUM

Sintaxe:

sum(array: ARRAY) -> INT64 | FLOAT64

Descrição:

Retorna a soma de todos os valores NUMERIC em um ARRAY.

  • Valores não numéricos na matriz são ignorados.
  • Se algum valor numérico na matriz for NaN, a função retornará NaN.
  • O tipo de retorno é determinado pelo tipo numérico mais amplo na matriz: INT64 < FLOAT64.
  • Se um número inteiro flutuante de 64 bits ocorrer antes que qualquer valor de ponto flutuante seja somado, um erro será retornado. Se valores de ponto flutuante forem somados, o valor flutuante vai resultar em +/- infinito.
  • Se a matriz não tiver valores numéricos, a função vai retornar NULL.

Exemplos:

matriz 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] erro
[INT64.MAX_VALUE, 1, -1.0] erro
[INT64.MAX_VALUE, 1.0] 9.223372036854776e+18

PARTICIPAR

Sintaxe:

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

Descrição:

Retorna uma concatenação dos elementos em array como um STRING. O array pode ser dos tipos de dados STRING ou BYTES.

  • Todos os elementos em array, delimiter e null_text precisam ser do mesmo tipo: todos precisam ser STRING ou BYTES.
  • Se null_text for fornecido, todos os valores NULL em array serão substituídos por null_text.
  • Se null_text não for fornecido, os valores NULL em array serão omitidos do resultado.

Exemplos:

Quando null_text não é fornecido:

matriz delimitador 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'] "," erro
["a", "c"] b',' erro
[b'a', b'c'] "," erro

Quando null_text é fornecido:

matriz delimitador 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' erro
[b'a', null] b',' "N" erro

Funções de comparação

Nome Descrição
EQUAL Comparação de igualdade
GREATER_THAN Comparação "maior que"
GREATER_THAN_OR_EQUAL Comparação "maior ou igual a"
LESS_THAN Comparação "menor que"
LESS_THAN_OR_EQUAL Comparação "menor ou igual a"
NOT_EQUAL Comparação "diferente de"
CMP Comparação geral

EQUAL

Sintaxe:

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

Exemplos:

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

Descrição:

Retorna TRUE se x e y forem iguais. Caso contrário, retorna 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

Sintaxe:

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

Descrição:

Retorna TRUE se x for maior que y e FALSE caso contrário.

Se x e y não forem comparáveis, retornará FALSE.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna TRUE se x for maior ou igual a y e FALSE caso contrário.

Se x e y não forem comparáveis, retornará FALSE.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna TRUE se x for menor que y. Caso contrário, retorna FALSE.

Se x e y não forem comparáveis, retornará FALSE.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna TRUE se x for menor ou igual a y e FALSE caso contrário.

Se x e y não forem comparáveis, retornará FALSE.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna TRUE se x não for igual a y. Caso contrário, retorna FALSE.

Exemplos:

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

CMP

Sintaxe:

cmp(x: ANY, y: ANY) -> Int64

Descrição:

Compara x e y, retornando:

  • 1L se x for maior que y.
  • -1L se x for menor que y.
  • Caso contrário, 0L.

Ao contrário de outras funções de comparação, a função cmp(...) funciona em todos os tipos, seguindo a mesma ordenação usada na etapa sort(...). Consulte ordem de tipo de valor para saber como os valores são ordenados entre os tipos.

Exemplos:

x y cmp(x, y)
1L 1L 0L
1.0 1L 0L
-1,0 1L -1L
42.5D "foo" -1L
NULL NULL 0L
NULL ABSENT 0L

Funções de depuração

Nome Descrição
EXISTS Retorna TRUE se o valor não estiver ausente
IS_ABSENT Retorna TRUE se o valor estiver ausente.
IF_ABSENT Substitui o valor por uma expressão se ele estiver ausente.
IS_ERROR Captura e verifica se uma expressão subjacente gerou um erro.
IF_ERROR Substitui o valor por uma expressão se ele tiver gerado um erro.
ERROR Encerra a avaliação e retorna um erro com a mensagem especificada.

EXISTS

Sintaxe:

exists(value: ANY) -> BOOLEAN

Descrição:

Retorna TRUE se value não for o valor ausente.

Exemplos:

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

Exemplo:

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

Exemplo:

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

Exemplo:

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

Sintaxe:

is_absent(value: ANY) -> BOOLEAN

Descrição:

Retorna TRUE se value for o valor ausente. Caso contrário, retorna FALSE. Valores ausentes são aqueles que não estão na entrada, como um campo de documento ausente.

Exemplos:

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

IF_ABSENT

Sintaxe:

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

Descrição:

Se value for um valor ausente, avalia e retorna replacement. Caso contrário, retornará value.

Exemplos:

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

IS_ERROR

Sintaxe:

is_error(try: ANY) -> BOOLEAN

Descrição:

Retorna TRUE se um erro for gerado durante a avaliação de try. Caso contrário, retorna FALSE.

IF_ERROR

Sintaxe:

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

Descrição:

Se um erro for gerado durante a avaliação de try, avalia e retorna replacement. Caso contrário, retorna o valor resolvido de try.

ERRO

Sintaxe:

error(message: STRING) -> ANY

Descrição:

A avaliação da função error resulta na avaliação do pipeline para ser encerrado com um erro. O message especificado está incluído no erro.

Exemplos:

cond res switch_on(cond, res, error("no condition matched"))
TRUE 1L 1L
FALSE 1L ERROR ("no condition matched")

Funções de referência

O tipo REFERENCE funciona como um "ponteiro" para outros documentos no banco de dados (ou até mesmo em outros bancos de dados). As funções a seguir permitem manipular esse tipo durante a execução da consulta.

Nome Descrição
COLLECTION_ID Retorna o ID da coleção de folhas na referência especificada.
DOCUMENT_ID Retorna o ID do documento na referência especificada.
PARENT Retorna a referência principal.
REFERENCE_SLICE Retorna um subconjunto de segmentos da referência especificada.

COLLECTION_ID

Sintaxe:

collection_id(ref: REFERENCE) -> STRING

Descrição:

Retorna o ID da coleção de folhas do REFERENCE especificado.

Exemplos:

ref collection_id(ref)
users/user1 "users"
users/user1/posts/post1 "posts"

DOCUMENT_ID

Sintaxe:

document_id(ref: REFERENCE) -> ANY

Descrição:

Retorna o ID do documento do REFERENCE especificado.

Exemplos:

ref document_id(ref)
users/user1 "user1"
users/user1/posts/post1 "post1"

PARENT

Sintaxe:

parent(ref: REFERENCE) -> REFERENCE

Descrição:

Retorna o REFERENCE principal da referência especificada ou NULL se a referência já for uma referência raiz.

Exemplos:

ref parent(ref)
/ NULL
users/user1 /
users/user1/posts/post1 users/user1

REFERENCE_SLICE

Sintaxe:

reference_slice(ref: REFERENCE, offset: INT, length: INT) -> REFERENCE

Descrição:

Um REFERENCE é uma lista de tuplas (collection_id, document_id), o que permite ter uma visualização dessa lista, assim como array_slice(...).

Retorna um novo REFERENCE que é um subconjunto dos segmentos do ref especificado.

  • offset: o índice inicial (base zero) da fração. Se for negativo, será um deslocamento do final da referência.
  • length: o número de segmentos a serem incluídos na fração.

Exemplos:

ref offset length reference_slice(ref, offset, length)
a/1/b/2/c/3 1L 2L b/2/c/3
a/1/b/2/c/3 0L 2L a/1/b/2
a/1/b/2/c/3 -2L 2L c/3

Funções lógicas

Nome Descrição
AND Executa um AND lógico
OR Executa um OR lógico
XOR Executa um XOR lógico
NOT Executa um NOT lógico
NOR Executa um NOR lógico
CONDITIONAL Ramifica a avaliação com base em uma expressão condicional.
IF_NULL Retorna o primeiro valor não nulo.
SWITCH_ON Ramifica a avaliação com base em uma série de condições
EQUAL_ANY Verifica se um valor é igual a algum elemento em uma matriz.
NOT_EQUAL_ANY Verifica se um valor não é igual a nenhum elemento em uma matriz.
MAXIMUM Retorna o valor máximo em um conjunto de valores.
MINIMUM Retorna o valor mínimo em um conjunto de valores.

E

Sintaxe:

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

Descrição:

Retorna o AND lógico de dois ou mais valores booleanos.

Retorna NULL se o resultado não puder ser derivado porque um dos valores fornecidos é ABSENT ou NULL.

Exemplos:

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

OU

Sintaxe:

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

Descrição:

Retorna o OR lógico de dois ou mais valores booleanos.

Retorna NULL se o resultado não puder ser derivado porque um dos valores fornecidos é ABSENT ou NULL.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o XOR lógico de dois ou mais valores booleanos.

Retorna NULL se algum dos valores especificados for ABSENT ou NULL.

Exemplos:

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

NOR

Sintaxe:

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

Descrição:

Retorna o NOR lógico de dois ou mais valores booleanos.

Retorna NULL se o resultado não puder ser derivado porque um dos valores fornecidos é ABSENT ou NULL.

Exemplos:

x y nor(x, y)
TRUE TRUE FALSE
FALSE TRUE FALSE
FALSE FALSE TRUE
NULL TRUE FALSE
ABSENT TRUE FALSE
NULL FALSE NULL
FALSE ABSENT NULL

NOT

Sintaxe:

not(x: BOOLEAN) -> BOOLEAN

Descrição:

Retorna o NOT lógico de um valor booleano.

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

Sintaxe:

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

Descrição:

Avalia e retorna o true_case se o condition for avaliado como TRUE.

Avalia e retorna o false_case se a condição for resolvida como FALSE, NULL ou um valor ABSENT.

Exemplos:

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

IF_NULL

Sintaxe:

if_null(expr: ANY, replacement: ANY) -> ANY

Descrição:

Retorna expr se não for NULL. Caso contrário, avalia e retorna replacement. A expressão replacement não é avaliada se expr for usada.

Exemplos:

expr replacement if_null(expr, replacement)
1L 2L 1L
NULL 2L 2L
ABSENT 2L ABSENT

SWITCH_ON

Sintaxe:

switch_on(cond1: BOOLEAN, res1: ANY, cond2: BOOLEAN, res2: ANY, ..., [default: ANY]) -> ANY

Descrição:

Avalia uma série de condições e retorna o resultado associado à primeira condição TRUE. Se nenhuma condição for avaliada como TRUE, o valor default será retornado, se fornecido. Se nenhum valor default for fornecido, um erro será gerado se nenhuma outra condição for avaliada como TRUE.

Para fornecer um valor default, transmita-o como o argumento final para que haja um número ímpar de argumentos.

Exemplos:

x switch_on(eq(x, 1L), "one", eq(x, 2L), "two", "other")
1L "uma"
2L "duas"
3L "outro"

EQUAL_ANY

Sintaxe:

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

Descrição:

Retorna TRUE se o value estiver na matriz search_space.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna TRUE se value não estiver na matriz search_space.

Exemplos:

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

Sintaxe:

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

Descrição:

Retorna o valor máximo não NULL e não ABSENT em uma série de valores x.

Se não houver valores diferentes de NULL e ABSENT, NULL será retornado.

Se houver vários valores equivalentes máximos, qualquer um deles poderá ser retornado. A ordem de tipo de valor segue a ordem documentada.

Exemplos:

x y maximum(x, y)
FALSE TRUE TRUE
FALSE -10L -10L
0,0 -5L 0,0
"foo" "barra" "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

Sintaxe:

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

Descrição:

Retorna o valor mínimo não NULL e não ABSENT em uma série de valores x.

Se não houver valores diferentes de NULL e ABSENT, NULL será retornado.

Se houver vários valores equivalentes mínimos, qualquer um deles poderá ser retornado. A ordem de tipo de valor segue a ordem documentada.

Exemplos:

x y minimum(x, y)
FALSE TRUE FALSE
FALSE -10L FALSE
0,0 -5L -5L
"foo" "barra" "barra"
"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

Funções de Mapa

Nome Descrição
MAP Cria um valor de mapa com base em uma série de pares de chave-valor.
MAP_GET Retorna o valor em um mapa com base em uma chave especificada.
MAP_SET Retorna uma cópia de um mapa com uma série de chaves atualizadas.
MAP_REMOVE Retorna uma cópia de um mapa com uma série de chaves removidas.
MAP_MERGE Mescla uma série de mapas.
CURRENT_CONTEXT Retorna o contexto atual como um mapa.
MAP_KEYS Retorna uma matriz de todas as chaves em um mapa.
MAP_VALUES Retorna uma matriz de todos os valores em um mapa.
MAP_ENTRIES Retorna uma matriz de pares de chave-valor de um mapa.

MAP

Sintaxe:

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

Descrição:

Cria um mapa com base em uma série de pares de chave-valor.

MAP_GET

Sintaxe:

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

Descrição:

Retorna o valor em um mapa com base em uma chave especificada. Retorna um valor ABSENT se key não existir no mapa ou se o argumento map não for um MAP.

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

Sintaxe:

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

Descrição:

Retorna uma cópia do valor map com o conteúdo atualizado por uma série de pares de chave-valor.

Se o valor fornecido for resolvido como um valor ausente, a chave associada será removida do mapa.

Se o argumento map não for um MAP, vai retornar um valor ausente.

MAP_REMOVE

Sintaxe:

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

Descrição:

Retorna uma cópia do valor map com uma série de chaves removidas.

MAP_MERGE

Sintaxe:

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

Mescla o conteúdo de dois ou mais mapas. Se vários mapas tiverem valores conflitantes, o último valor será usado.

CURRENT_CONTEXT

Sintaxe:

current_context() -> MAP

Retorna um mapa com todos os campos disponíveis no ponto de execução atual.

MAP_KEYS

Sintaxe:

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

Descrição:

Retorna uma matriz que contém todas as chaves do valor map.

MAP_VALUES

Sintaxe:

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

Descrição:

Retorna uma matriz que contém todos os valores de map.

MAP_ENTRIES

Sintaxe:

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

Descrição:

Retorna uma matriz que contém todos os pares de chave-valor no valor map.

Cada par de chave-valor estará na forma de um mapa com duas entradas, k e v.

Exemplos:

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

Funções de string

Nome Descrição
BYTE_LENGTH Retorna o número de BYTES em um valor STRING ou BYTES.
CHAR_LENGTH Retorna o número de caracteres Unicode em um valor STRING.
STARTS_WITH Retorna TRUE se um STRING começar com um prefixo especificado
ENDS_WITH Retorna TRUE se um STRING terminar com um sufixo específico
LIKE Retorna TRUE se um STRING corresponder a um padrão
REGEX_CONTAINS Retorna TRUE se um valor for uma correspondência parcial ou completa de uma expressão regular
REGEX_MATCH Retorna TRUE se alguma parte de um valor corresponder a uma expressão regular
STRING_CONCAT Concatena vários STRING em um STRING
STRING_CONTAINS Retorna TRUE se um valor contiver um STRING
STRING_INDEX_OF Retorna o índice baseado em zero da primeira ocorrência de um valor STRING ou BYTES.
TO_UPPER Converte um valor STRING ou BYTES em letras maiúsculas.
TO_LOWER Converte um valor STRING ou BYTES em minúsculas.
SUBSTRING Recebe uma substring de um valor STRING ou BYTES.
STRING_REVERSE Inverte um valor STRING ou BYTES.
STRING_REPEAT Repete um valor STRING ou BYTES um número especificado de vezes.
STRING_REPLACE_ALL Substitui todas as ocorrências de um valor STRING ou BYTES.
STRING_REPLACE_ONE Substitui a primeira ocorrência de um valor STRING ou BYTES.
TRIM Corta caracteres à direita e à esquerda de um valor STRING ou BYTES.
LTRIM Corta caracteres à esquerda de um valor STRING ou BYTES.
RTRIM Corta caracteres à direita de um valor STRING ou BYTES.
SPLIT Divide um valor STRING ou BYTES em uma matriz.

BYTE_LENGTH

Sintaxe:

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

Descrição:

Retorna o número de BYTES em um valor STRING ou BYTES.

Exemplos:

valor 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

Sintaxe:

char_length(value: STRING) -> INT64

Descrição:

Retorna o número de pontos de código Unicode no valor STRING.

Exemplos:

valor char_length(value)
"abc" 3
"hello" 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

Sintaxe:

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

Descrição:

Retorna TRUE se value começar com prefix.

Exemplos:

valor prefixo starts_with(value, prefix)
"abc" "a" verdadeiro
"abc" "b" falso
"abc" "" verdadeiro
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

Sintaxe:

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

Descrição:

Retorna TRUE se value terminar com postfix.

Exemplos:

valor postfix ends_with(value, postfix)
"abc" "c" verdadeiro
"abc" "b" falso
"abc" "" verdadeiro
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

Sintaxe:

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

Descrição:

Retorna TRUE se value corresponder a pattern.

Exemplos:

valor padrão like(value, pattern)
"Firestore" "Fire%" verdadeiro
"Firestore" "%store" verdadeiro
"Datastore" "Data_tore" verdadeiro
"100%" "100\%" verdadeiro
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

Sintaxe:

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

Descrição:

Retorna TRUE se alguma parte de value corresponder a pattern. Se pattern não for uma expressão regular válida, essa função vai retornar um error.

As expressões regulares seguem a sintaxe da biblioteca re2.

Exemplos:

valor padrão regex_contains(value, pattern)
"Firestore" "Fire" verdadeiro
"Firestore" "store$" verdadeiro
"Firestore" "data" falso
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

Sintaxe:

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

Descrição:

Retorna TRUE se value corresponder totalmente a pattern. Se pattern não for uma expressão regular válida, essa função vai retornar um error.

As expressões regulares seguem a sintaxe da biblioteca re2.

Exemplos:

valor padrão regex_match(value, pattern)
"Firestore" "F.*store" verdadeiro
"Firestore" "Fire" falso
"Firestore" "^F.*e$" verdadeiro
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

Sintaxe:

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

Descrição:

Concatena dois ou mais valores STRING em um único resultado.

Exemplos:

argumentos string_concat(values...)
() erro
("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

Sintaxe:

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

Descrição:

Verifica se value contém a string literal substring.

Exemplos:

valor substring string_contains(value, substring)
"abc" "b" verdadeiro
"abc" "d" falso
"abc" "" verdadeiro
"a.c" "." verdadeiro
"☃☃☃" "☃" verdadeiro
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

STRING_INDEX_OF

Sintaxe:

string_index_of[T <: STRING | BYTES](value: T, search: T) -> INT64

Descrição:

Retorna o índice baseado em zero da primeira ocorrência de search em value.

  • Retorna -1 se search não for encontrado.
  • Se value for um valor STRING, o resultado será medido em pontos de código Unicode. Se for um valor BYTES, ele será medido em bytes.
  • Se search for um valor STRING ou BYTES vazio, o resultado será 0.

Exemplos:

valor search string_index_of(value, search)
"hello world" "o" 4
"hello world" "l" 2
"hello world" "z" -1
"banana" "na" 2
"abc" "" 0
b"abc" b"b" 1
"é" "é" 0
b"é" b"é" 0

TO_UPPER

Sintaxe:

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

Descrição:

Converte um valor STRING ou BYTES em letras maiúsculas.

Se um byte ou gráfico não corresponder a um caractere alfabético minúsculo UTF-8, ele será transmitido sem alterações.

Exemplos:

valor 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

Sintaxe:

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

Descrição:

Converte um valor STRING ou BYTES em minúsculas.

Se um byte ou gráfico não corresponder a um caractere alfabético maiúsculo UTF-8, ele será transmitido sem alterações.

Exemplos:

valor 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

Sintaxe:

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

Descrição:

Retorna uma substring de input começando em position (índice baseado em zero) e incluindo até length entradas. Se nenhum length for fornecido, vai retornar a substring de position até o final do input.

  • Se input for um valor STRING, position e length serão medidos em caracteres pontos de código Unicode. Se for um valor BYTES, eles serão medidos em bytes.

  • Se position for maior que o comprimento de input, uma substring vazia será retornada. Se position mais length for maior que o comprimento de input, a substring será truncada até o final de input.

  • Se position for negativo, a posição será extraída do final da entrada. Se o position negativo for maior que o tamanho da entrada, a posição será definida como zero. length não pode ser negativo.

Exemplos:

Quando length não é fornecido:

entrada posição substring(input, position)
"abc" 0 "abc"
"abc" 1 "bc"
"abc" 3 ""
"abc" -1 "c"
b"abc" 1 b"bc"

Quando length é fornecido:

entrada posição comprimento 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

Sintaxe:

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

Descrição:

Retorna a entrada fornecida na ordem inversa.

Os caracteres são delimitados por pontos de código Unicode quando a entrada é um STRING e por bytes quando a entrada é um valor BYTES.

Exemplos:

entrada string_reverse(input)
"abc" "cba"
"a🌹b" "b🌹a"
"hello" "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

STRING_REPEAT

Sintaxe:

string_repeat[T <: STRING | BYTES](input: T, repetitions: INT64) -> T

Descrição:

Retorna a input repetida repetitions vezes.

  • repetitions precisa ser um número inteiro não negativo
  • Se repetitions for 0, vai retornar um valor vazio do mesmo tipo de input.
  • Se o resultado exceder o tamanho máximo permitido (1 MB), um erro será retornado.

Exemplos:

entrada repetições string_repeat(input, repetitions)
"foo" 3 "foofoofoo"
"foo" 0 ""
"a " 3 "a a a "
b"ab" 2 b"abab"
"é🦆" 2 "é🦆é🦆"

STRING_REPLACE_ALL

Sintaxe:

string_replace_all[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

Descrição:

Substitui todas as ocorrências não sobrepostas de find em input por replacement.

  • As correspondências diferenciam maiúsculas de minúsculas.
  • Se find estiver vazio, nenhuma substituição será feita.

Exemplos:

entrada encontrar substituição string_replace_all(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarbaz"
"ababab" "aba" "c" "cbab"
"foobar" "o" "" "fbar"
"é🦆🌎🦆" "🦆" "a" "éa🌎a"
b"abc" b"b" b"d" b"adc"

STRING_REPLACE_ONE

Sintaxe:

string_replace_one[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

Descrição:

Substitui as primeiras ocorrências de find em input com replacement.

  • As correspondências diferenciam maiúsculas de minúsculas.
  • Se find estiver vazio, nenhuma substituição será feita.

Exemplos:

entrada encontrar substituição string_replace_one(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarfoo"
"é" "é" "a" "a"
b"foobar" b"o" b"z" b"fzoobar"

TRIM

Sintaxe:

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

Descrição:

Remove um conjunto especificado de BYTES ou CHARS do início e do fim da input fornecida.

  • Se nenhum values_to_trim for fornecido, os caracteres de espaço em branco serão removidos.

Exemplos:

Quando values_to_trim não é fornecido:

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

Quando values_to_trim é fornecido:

entrada values_to_trim trim(input, values_to_trim)
"abcbfooaacb" "abc" "foo"
"abcdaabadbac" "abc" "daabad"
b"C1C2C3" b"C1" b"C2C3"
b"C1C2" "foo" erro
"foo" b"C1" erro

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

LTRIM

Sintaxe:

ltrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
ltrim[T <: STRING | BYTES](value: T) -> T

Descrição:

Remove um conjunto especificado de BYTES ou CHARS do início da value fornecida.

  • Se to_trim não for fornecido, os caracteres de espaço em branco iniciais serão removidos.

Exemplos:

Quando to_trim não é fornecido:

valor ltrim(value)
" foo " "foo "
"foo" "foo"

Quando to_trim é fornecido:

valor to_trim ltrim(value, to_trim)
"aaabc" "a" "bc"
"abacaba" "ba" "caba"
"é" "é" ""

RTRIM

Sintaxe:

rtrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
rtrim[T <: STRING | BYTES](value: T) -> T

Descrição:

Remove um conjunto especificado de BYTES ou CHARS do final da value fornecida.

  • Se to_trim não for fornecido, os caracteres de espaço em branco finais serão removidos.

Exemplos:

Quando to_trim não é fornecido:

valor rtrim(value)
" foo " " foo"
"foo" "foo"

Quando to_trim é fornecido:

valor to_trim rtrim(value, to_trim)
"abccc" "c" "ab"
"abacaba" "ba" "abac"
"é" "é" ""

SPLIT

Sintaxe:

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

Descrição:

Divide um valor STRING ou BYTES usando um delimitador.

  • Para STRING, o delimitador padrão é a vírgula ,. O delimitador é tratado como uma única string.

  • Para BYTES, especifique um delimitador.

  • A divisão em um delimitador vazio produz uma matriz de pontos de código Unicode para valores STRING e uma matriz de BYTES para valores BYTES.

  • A divisão de uma STRING vazia retorna uma ARRAY com uma única STRING vazia.

Exemplos:

Quando delimiter não é fornecido:

entrada split(input)
"foo,bar,foo" ["foo", "bar", "foo"]
"foo" ["foo"]
",foo," ["", "foo", ""]
"" [""]
b"C120C2C4" erro

Quando delimiter é fornecido:

entrada delimitador 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" erro

Funções de carimbo de data/hora

Nome Descrição
CURRENT_TIMESTAMP Gera um TIMESTAMP correspondente ao horário da solicitação.
TIMESTAMP_TRUNC Trunca um TIMESTAMP para uma determinada granularidade.
UNIX_MICROS_TO_TIMESTAMP Converte o número de microssegundos desde 1970-01-01 00:00:00 UTC em um TIMESTAMP
UNIX_MILLIS_TO_TIMESTAMP Converte o número de milissegundos desde 1970-01-01 00:00:00 UTC em um TIMESTAMP
UNIX_SECONDS_TO_TIMESTAMP Converte o número de segundos desde 1970-01-01 00:00:00 UTC em um TIMESTAMP
TIMESTAMP_ADD Adiciona um intervalo de tempo a um TIMESTAMP
TIMESTAMP_SUB Subtrai um intervalo de tempo de um TIMESTAMP
TIMESTAMP_TO_UNIX_MICROS Converte um TIMESTAMP no número de microssegundos desde 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_MILLIS Converte um TIMESTAMP no número de milissegundos desde 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_SECONDS Converte um TIMESTAMP no número de segundos desde 1970-01-01 00:00:00 UTC
TIMESTAMP_DIFF Retorna o número inteiro de intervalos unit especificados entre duas TIMESTAMPs.
TIMESTAMP_EXTRACT Extrai um part específico (por exemplo, ano, mês, dia) de um TIMESTAMP.

CURRENT_TIMESTAMP

Sintaxe:

current_timestamp() -> TIMESTAMP

Descrição:

Recebe o carimbo de data/hora no início do tempo de solicitação input (interpretado como o número de microssegundos desde 1970-01-01 00:00:00 UTC).

Ele é estável em uma consulta e sempre será resolvido com o mesmo valor se for chamado várias vezes.

TIMESTAMP_TRUNC

Sintaxe:

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

Descrição:

Trunca um carimbo de data/hora para uma determinada granularidade.

O argumento granularity precisa ser uma string e um dos seguintes:

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

Se o argumento timezone for fornecido, o truncamento será baseado nos limites do calendário do fuso horário especificado (por exemplo, o truncamento diário será feito até a meia-noite no fuso horário especificado). O truncamento vai respeitar o horário de verão.

Se timezone não for fornecido, o truncamento será baseado nos limites do calendário UTC.

O argumento timezone precisa ser uma representação de string de um fuso horário do banco de dados tz, por exemplo, America/New_York. Também é possível usar um ajuste de tempo personalizado especificando um ajuste de GMT.

Exemplos:

timestamp granularity timezone timestamp_trunc(timestamp, granularity, timezone)
2000-01-01 10:20:30:123456 UTC "segundo" Não fornecido 2001-01-01 10:20:30 UTC
1997-05-31 04:30:30 UTC "dia" Não fornecido 1997-05-31 00:00:00 UTC
1997-05-31 04:30:30 UTC "dia" "America/Los_Angeles" 1997-05-30 07:00:00 UTC
2001-03-16 04:00:00 UTC "semana(sexta-feira) Não fornecido 2001-03-16 00:00:00 UTC
2001-03-23 04:00:00 UTC "semana(sexta-feira) "America/Los_Angeles" 2001-03-23 17:00:00 UTC
2026-01-24 20:00:00 UTC "mês" "GMT+06:32:43" 2026-01-01T06:32:43 UTC

UNIX_MICROS_TO_TIMESTAMP

Sintaxe:

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

Descrição:

Converte input (interpretado como o número de microssegundos desde 1970-01-01 00:00:00 UTC) em um TIMESTAMP. Gera um error se input não puder ser convertido em um TIMESTAMP válido.

Exemplos:

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

Sintaxe:

unix_millis_to_timestamp(input: INT64) -> TIMESTAMP

Descrição:

Converte input (interpretado como o número de milissegundos desde 1970-01-01 00:00:00 UTC) em um TIMESTAMP. Gera um error se input não puder ser convertido em um TIMESTAMP válido.

Exemplos:

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

Sintaxe:

unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP

Descrição:

Converte input (interpretado como o número de segundos desde 1970-01-01 00:00:00 UTC) em um TIMESTAMP. Gera um error se input não puder ser convertido em um TIMESTAMP válido.

Exemplos:

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

Sintaxe:

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

Descrição:

Adiciona um amount de unit de timestamp. O argumento amount pode ser negativo. Nesse caso, é equivalente a TIMESTAMP_SUB.

O argumento unit precisa ser uma string e um dos seguintes:

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

Um erro será gerado se o carimbo de data/hora resultante não se encaixar no intervalo TIMESTAMP.

Exemplos:

timestamp unit amount timestamp_add(timestamp, unit, amount)
2025-02-20 00:00:00 UTC "minuto" 2L 2025-02-20 00:02:00 UTC
2025-02-20 00:00:00 UTC "hora" -4L 2025-02-19 20:00:00 UTC
2025-02-20 00:00:00 UTC "dia" 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

Sintaxe:

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

Descrição:

Subtrai um amount de unit de timestamp. O argumento amount pode ser negativo. Nesse caso, é equivalente a TIMESTAMP_ADD.

O argumento unit precisa ser uma string e um dos seguintes:

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

Um erro será gerado se o carimbo de data/hora resultante não se encaixar no intervalo TIMESTAMP.

Exemplos:

timestamp unit amount timestamp_sub(timestamp, unit, amount)
2026-07-04 00:00:00 UTC "minuto" 40L 2026-07-03 23:20:00 UTC
2026-07-04 00:00:00 UTC "hora" -24L 2026-07-05 00:00:00 UTC
2026-07-04 00:00:00 UTC "dia" 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

Sintaxe:

timestamp_to_unix_micros(input: TIMESTAMP) -> INT64

Descrição:

Converte input no número de microssegundos desde 1970-01-01 00:00:00 UTC. Trunca níveis mais elevados de precisão ao arredondar para baixo até o início do segundo.

Exemplos:

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

Sintaxe:

timestamp_to_unix_millis(input: TIMESTAMP) -> INT64

Descrição:

Converte input no número de milissegundos desde 1970-01-01 00:00:00 UTC. Trunca níveis mais altos de precisão ao arredondar para baixo até o início do milissegundo.

Exemplos:

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

Sintaxe:

timestamp_to_unix_seconds(input: TIMESTAMP) -> INT64

Descrição:

Converte input no número de segundos desde 1970-01-01 00:00:00 UTC. Trunca níveis mais elevados de precisão ao arredondar para baixo até o início do segundo.

Exemplos:

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

TIMESTAMP_DIFF

Sintaxe:

timestamp_diff(end: TIMESTAMP, start: TIMESTAMP, unit: STRING) -> INT64

Descrição:

Retorna o número inteiro de intervalos unit especificados entre duas TIMESTAMPs.

  • Retorna um valor negativo se end for anterior a start.
  • Trunca qualquer unidade fracionária. Por exemplo, timestamp_diff("2021-01-01 00:00:01", "2021-01-01 00:00:00", "minute") retorna 0.

O argumento unit precisa ser uma string e um dos seguintes:

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

Exemplos:

end start unit timestamp_diff(end, start, unit)
2026-07-04 00:01:00 UTC 2026-07-04 00:00:00 UTC "segundo" 60L
2026-07-04 00:00:00 UTC 2026-07-05 00:00:00 UTC "dia" -1L
2026-07-04 00:00:59 UTC 2026-07-04 00:00:00 UTC "minuto" 0L

TIMESTAMP_EXTRACT

Sintaxe:

timestamp_extract(timestamp: TIMESTAMP, part: STRING[, timezone: STRING]) -> INT64

Descrição:

Extrai um part específico (por exemplo, ano, mês, dia) de timestamp.

O argumento part precisa ser uma string e um dos seguintes:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • dayofweek: retorna um valor entre 1 (domingo) e 7 (sábado).
  • dayofyear
  • week: retorna o número da semana do ano, começando em 1 para o primeiro domingo do ano.
  • week([weekday]): retorna o número da semana do ano, começando no weekday especificado.
  • month
  • quarter
  • year
  • isoweek: retorna o número da semana ISO 8601.
  • isoyear: retorna o ano de numeração da semana ISO 8601.

Se o argumento timezone for fornecido, a extração será baseada no calendário do fuso horário especificado. A extração vai respeitar o horário de verão.

Se timezone não for fornecido, a extração será baseada em UTC.

O argumento timezone precisa ser uma representação de string de um fuso horário do banco de dados de fuso horário, por exemplo, America/New_York. Também é possível usar um ajuste de tempo personalizado especificando um ajuste de GMT.

Exemplos:

timestamp part timezone timestamp_extract(timestamp, part, timezone)
2025-02-20 10:20:30 UTC "ano" Não fornecido 2025
2025-02-20 10:20:30 UTC "dia" Não fornecido 20
2025-12-31 23:59:59 UTC "ano" "Ásia/Tóquio" 2026

Funções de tipo

Nome Descrição
TYPE Retorna o tipo do valor como um STRING.
IS_TYPE Retorna true se o valor corresponder ao tipo especificado.

TYPE

Sintaxe:

type(input: ANY) -> STRING

Descrição:

Retorna uma representação de string do tipo input.

Se um valor ausente for fornecido, vai retornar NULL.

Exemplos:

input type(input)
NULL "null"
verdadeiro "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"
AUSENTE NULL

Exemplos de clientes

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

IS_TYPE

Sintaxe:

is_type(input: ANY, type: STRING) -> BOOLEAN

Descrição:

Retorna true se o input corresponder ao type especificado. Caso contrário, retorna false. Se um input ausente for fornecido, vai retornar NULL.

As strings type compatíveis são:

  • "null"
  • "boolean"
  • "int32"
  • "int64"
  • "float64"
  • "decimal128"
  • "number"
  • "timestamp"
  • "string"
  • "bytes"
  • "array"
  • "map"
  • "reference"
  • "vector"
  • "geo_point"
  • "max_key"
  • "min_key"
  • "object_id"
  • "regex"
  • "bson_timestamp"

Exemplos:

input type is_type(input, type)
NULL "null" verdadeiro
verdadeiro "boolean" verdadeiro
3.14 "float64" verdadeiro
"foo" "string" verdadeiro
b"foo" "string" falso
[1, 2] "array" verdadeiro
{"a": 1} "map" verdadeiro
vector([1.0, 2.0]) "vector" verdadeiro
AUSENTE "string" NULL
"barra" "outro" ERRO

Funções de vetor

Nome Descrição
COSINE_DISTANCE Retorna a distância do cosseno entre dois vetores.
DOT_PRODUCT Retorna o produto escalar entre dois vetores.
EUCLIDEAN_DISTANCE Retorna a distância euclidiana entre dois vetores.
MANHATTAN_DISTANCE Retorna a distância de Manhattan entre dois vetores.
VECTOR_LENGTH Retorna o número de elementos em um vetor.

COSINE_DISTANCE

Sintaxe:

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

Descrição:

Retorna a distância do cosseno entre x e 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

Sintaxe:

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

Descrição:

Retorna o produto escalar de x e 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

Sintaxe:

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

Descrição:

Calcula a distância euclidiana entre x e 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

Sintaxe:

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

Descrição:

Calcula a distância de Manhattan entre x e y.

VECTOR_LENGTH

Sintaxe:

vector_length(vector: VECTOR) -> INT64

Descrição:

Retorna o número de elementos em um 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

A seguir