Package google.firestore.v1beta1

Índice

Firestore

O serviço Cloud Firestore.

O Cloud Firestore é um banco de dados de documentos NoSQL rápido, totalmente gerenciado, sem servidor e nativo da nuvem que simplifica o armazenamento, a sincronização e a consulta de dados para seus aplicativos em dispositivos móveis, na Web e de IoT em escala global. As bibliotecas de cliente dele oferecem sincronização em tempo real e suporte off-line. Além disso, os recursos de segurança e de integração com o Firebase e o Google Cloud Platform aceleram a criação de aplicativos verdadeiramente sem servidor.

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Recebe vários documentos.

Não há garantia de que os documentos retornados por esse método serão retornados na mesma ordem em que foram solicitados.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

BatchWrite

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

Aplica um lote de operações de gravação.

O método BatchWrite não aplica as operações de gravação atomicamente e pode aplicá-las fora de ordem. O método não permite mais de uma gravação por documento. Cada gravação é bem-sucedida ou falha de maneira independente. Consulte o BatchWriteResponse para saber o status de êxito de cada gravação.

Se você precisar de um conjunto de gravações aplicado atomicamente, use Commit.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

BeginTransaction

rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse)

Inicia uma nova transação.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

Confirmação

rpc Commit(CommitRequest) returns (CommitResponse)

Confirma uma transação e atualiza os documentos opcionalmente.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

CreateDocument

rpc CreateDocument(CreateDocumentRequest) returns (Document)

Cria um novo documento.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

DeleteDocument

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

Exclui um documento.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Recebe um único documento.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

ListCollectionIds

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

Lista todos os IDs de coleções em um documento.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

ListDocuments

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

Lista os documentos.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

Detectar

rpc Listen(ListenRequest) returns (ListenResponse)

Detecta mudanças. Esse método só está disponível via gRPC ou WebChannel (não REST).

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

PartitionQuery

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse)

Particiona uma consulta retornando cursores de partição que podem ser usados para executar a consulta em paralelo. Os cursores de partição retornados são pontos de divisão que podem ser usados pelo RunQuery como pontos de início/término para os resultados da consulta.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

Reversão

rpc Rollback(RollbackRequest) returns (Empty)

Reverte uma transação.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse)

Executa uma consulta de agregação.

Em vez de produzir resultados de Document como Firestore.RunQuery, essa API permite executar uma agregação para produzir uma série de AggregationResult do lado do servidor.

Exemplo de alto nível:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

Executar consulta

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

Executa uma consulta.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

UpdateDocument

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

Atualiza ou insere um documento.

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

Gravação

rpc Write(WriteRequest) returns (WriteResponse)

Transmite lotes de atualizações e exclusões de documentos em ordem. Esse método só está disponível via gRPC ou WebChannel (não REST).

Escopos de autorização

Requer um dos seguintes escopos de OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para saber mais, consulte a Visão geral da autenticação.

AggregateResult

Resultado de um único bucket de uma consulta de agregação do Firestore.

As chaves de aggregate_fields são as mesmas para todos os resultados em uma consulta de agregação, ao contrário das consultas de documentos, que podem ter campos diferentes para cada resultado.

Campos
aggregate_fields

map<string, Value>

O resultado das funções de agregação, por exemplo: COUNT(*) AS total_docs.

A chave é o alias atribuído à função de agregação na entrada, e o tamanho desse mapa é igual ao número de funções de agregação na consulta.

ArrayValue

Um valor de matriz.

Campos
values[]

Value

Valores na matriz.

BatchGetDocumentsRequest

A solicitação para Firestore.BatchGetDocuments.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

documents[]

string

Os nomes dos documentos a serem recuperados. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. A solicitação falhará se algum dos documentos não for um recurso filho da database especificada. Nomes duplicados serão ocultados.

mask

DocumentMask

Os campos a serem retornados. Se não for definido, todos os campos serão retornados.

Se um documento tiver um campo que não esteja presente nessa máscara, esse campo não será retornado na resposta.

Campo de união consistency_selector. O modo de consistência para esta transação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

bytes

Lê documentos em uma transação.

new_transaction

TransactionOptions

Inicia uma nova transação e lê os documentos. O padrão é uma transação somente leitura. O novo ID da transação será retornado como a primeira resposta no fluxo.

read_time

Timestamp

Lê os documentos como estavam no momento especificado.

Precisa ser um carimbo de data/hora com precisão de microssegundos na última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

BatchGetDocumentsResponse

A resposta transmitida para Firestore.BatchGetDocuments.

Campos
transaction

bytes

A transação que foi iniciada como parte da solicitação. Será definido apenas na primeira resposta e somente se BatchGetDocumentsRequest.new_transaction tiver sido definido na solicitação.

read_time

Timestamp

A hora em que o documento foi lido. Isso pode ser monoticamente crescente. Neste caso, os documentos anteriores no fluxo de resultados têm a garantia de não terem sido alterados entre o read_time e este.

Campo de união result. Um único resultado. Pode estar vazio se o servidor estiver apenas retornando uma transação. result pode ser apenas de um dos tipos a seguir:
found

Document

Um documento que foi solicitado.

missing

string

Um nome de documento que foi solicitado, mas não existe. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

BatchWriteRequest

A solicitação para Firestore.BatchWrite.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

writes[]

Write

As gravações a serem aplicadas.

O método não aplica gravações atomicamente e não garante ordem. Cada gravação é bem-sucedida ou falha de maneira independente. Não é possível gravar no mesmo documento mais de uma vez por solicitação.

labels

map<string, string>

Rótulos associados a essa gravação em lote.

BatchWriteResponse

A resposta de Firestore.BatchWrite.

Campos
write_results[]

WriteResult

O resultado da aplicação das gravações.

Esse i-ésimo resultado de gravação corresponde à i-ésima gravação na solicitação.

status[]

Status

O status da aplicação das gravações.

Esse status de i-ésima gravação corresponde à i-ésima gravação na solicitação.

BeginTransactionRequest

A solicitação para Firestore.BeginTransaction.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

options

TransactionOptions

As opções da transação. O padrão é uma transação de leitura e gravação.

BeginTransactionResponse

A resposta para Firestore.BeginTransaction.

Campos
transaction

bytes

A transação que foi iniciada.

BitSequência

Uma sequência de bits, codificada em uma matriz de bytes.

Cada byte na matriz de bytes bitmap armazena 8 bits da sequência. A única exceção é o último byte, que pode armazenar 8 ou menos bits. O padding define o número de bits do último byte a ser ignorado como "padding". Os valores desses "padding" Os bits não são especificados e precisam ser ignorados.

Para recuperar o primeiro bit, bit 0, calcule: (bitmap[0] & 0x01) != 0. Para recuperar o segundo bit, bit 1, calcule: (bitmap[0] & 0x02) != 0. Para recuperar o terceiro bit, bit 2, calcule: (bitmap[0] & 0x04) != 0. Para recuperar o quarto bit, bit 3, calcule: (bitmap[0] & 0x08) != 0. Para recuperar o bit n, calcule: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

O "tamanho" de um BitSequence (o número de bits que ele contém) é calculado por esta fórmula: (bitmap.length * 8) - padding.

Campos
bitmap

bytes

Os bytes que codificam a sequência de bits. Pode ter um comprimento de zero.

padding

int32

O número de bits do último byte em bitmap que será ignorado como "padding". Se o comprimento de bitmap for zero, esse valor precisará ser 0. Caso contrário, esse valor precisa estar entre 0 e 7.

FiltroBloom

Um filtro de flores (https://en.wikipedia.org/wiki/Bloom_filter).

O filtro Bloom gera hash das entradas com MD5 e trata o hash de 128 bits resultante como dois valores de hash de 64 bits distintos, interpretados como números inteiros não assinados usando a codificação de complemento de 2.

Esses dois valores de hash, chamados h1 e h2, são usados para calcular os valores de hash hash_count usando a fórmula, começando com i=0:

h(i) = h1 + (i * h2)

Em seguida, esses valores resultantes são usados com base no módulo do número de bits no filtro de florescência para que os bits do filtro sejam testados para a entrada especificada.

Campos
bits

BitSequence

Dados do filtro de flores.

hash_count

int32

O número de hashes usados pelo algoritmo.

CommitRequest

A solicitação para Firestore.Commit.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

writes[]

Write

As gravações a serem aplicadas.

Sempre executado atomicamente e em ordem.

transaction

bytes

Se definido, aplica todas as gravações nesta transação e confirma-as.

CommitResponse

A resposta para Firestore.Commit.

Campos
write_results[]

WriteResult

O resultado da aplicação das gravações.

Esse i-ésimo resultado de gravação corresponde à i-ésima gravação na solicitação.

commit_time

Timestamp

O horário em que a confirmação ocorreu. Qualquer leitura com um read_time igual ou maior garante a visualização dos efeitos da confirmação.

CreateDocumentRequest

A solicitação para Firestore.CreateDocument.

Campos
parent

string

Obrigatório. O recurso pai. Por exemplo: projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}

collection_id

string

Obrigatório. O ID da coleção, relativo a parent, para a lista. Por exemplo, chatrooms.

document_id

string

O ID do documento atribuído pelo cliente para usar neste documento.

Opcional. Se não for especificado, um ID será atribuído pelo serviço.

document

Document

Obrigatório. O documento a ser criado. name não pode ser definido.

mask

DocumentMask

Os campos a serem retornados. Se não for definido, todos os campos serão retornados.

Se o documento tiver um campo que não esteja presente na máscara, esse campo não será retornado na resposta.

Cursor

Uma posição em um conjunto de resultados de consulta.

Campos
values[]

Value

Os valores que representam uma posição, na ordem em que aparecem na ordem por cláusula de uma consulta.

Pode conter menos valores do que o especificado na ordem por cláusula.

before

bool

Se a posição estiver logo antes ou depois dos valores fornecidos, em relação à ordem de classificação definida pela consulta.

DeleteDocumentRequest

A solicitação para Firestore.DeleteDocument.

Campos
name

string

Obrigatório. O nome do recurso do documento a ser excluído. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

current_document

Precondition

Uma pré-condição opcional no documento. A solicitação falhará se esse valor for definido e não for atendido pelo documento de destino.

Documento

Um documento do Firestore.

Não pode exceder 1 MiB a 4 bytes.

Campos
name

string

O nome de recurso do documento, por exemplo, projects/{project_id}/databases/{database_id}/documents/{document_path}.

fields

map<string, Value>

create_time

Timestamp

Apenas saída. A hora em que o documento foi criado.

Esse valor aumenta monotonicamente quando um documento é excluído e recriado. Também pode ser comparado com valores de outros documentos e com o read_time de uma consulta.

update_time

Timestamp

Apenas saída. A hora em que o documento foi alterado pela última vez.

Inicialmente, esse valor é definido como create_time e aumenta monotonicamente a cada mudança no documento. Também pode ser comparado com valores de outros documentos e com o read_time de uma consulta.

DocumentChange

Um Document foi alterado.

Pode ser o resultado de várias writes, incluindo exclusões, que resultaram em um novo valor de Document.

Várias mensagens DocumentChange poderão ser retornadas para a mesma alteração lógica se vários destinos forem afetados.

Campos
document

Document

O novo estado da Document.

Se mask estiver definido, conterá apenas campos que foram atualizados ou adicionados.

target_ids[]

int32

Um conjunto de IDs de destinos que correspondem a este documento.

removed_target_ids[]

int32

Um conjunto de IDs de destino para segmentações que não correspondem mais a este documento.

Exclusão de documento

Um Document foi excluído.

Pode ser o resultado de várias writes, incluindo atualizações. A última delas excluiu o Document.

Várias mensagens DocumentDelete podem ser retornadas para a mesma exclusão lógica se vários destinos forem afetados.

Campos
document

string

O nome do recurso do Document que foi excluído.

removed_target_ids[]

int32

Um conjunto de IDs de destino para destinos que corresponderam anteriormente a essa entidade.

read_time

Timestamp

Carimbo de data/hora de leitura em que a exclusão foi observada.

Maior ou igual ao commit_time da exclusão.

DocumentMask

Um conjunto de caminhos de campo em um documento. Usado para restringir uma operação de obtenção ou atualização em um documento a um subconjunto dos campos dele. Isso é diferente das máscaras de campo padrão, já que esse objeto sempre tem o escopo definido como Document e considera a natureza dinâmica do Value.

Campos
field_paths[]

string

A lista de caminhos de campo na máscara. Consulte Document.fields para conferir uma referência de sintaxe de caminho do campo.

Documento removido

Um Document foi removido da visualização dos destinos.

Enviado se o documento não for mais relevante para um destino e estiver fora da visualização. Pode ser enviado no lugar de um DocumentDelete ou um DocumentChange se o servidor não puder enviar o novo valor do documento.

Várias mensagens DocumentRemove poderão ser retornadas para a mesma gravação ou exclusão lógica se vários destinos forem afetados.

Campos
document

string

O nome do recurso do Document que saiu da área de visualização.

removed_target_ids[]

int32

Um conjunto de IDs de destino para destinos que corresponderam anteriormente a este documento.

read_time

Timestamp

Carimbo de data/hora de leitura em que a remoção foi observada.

Maior ou igual ao commit_time de alteração/exclusão/remoção.

Transformação de documentos

Uma transformação de um documento.

Campos
document

string

O nome do documento a ser transformado.

field_transforms[]

FieldTransform

A lista de transformações a serem aplicadas aos campos do documento, em ordem. Este campo não pode ficar vazio.

FieldTransform

Uma transformação de um campo do documento.

Campos
field_path

string

O caminho do campo. Consulte Document.fields para conferir a referência de sintaxe do caminho do campo.

Campo de união transform_type. A transformação a ser aplicada no campo. transform_type pode ser apenas de um dos tipos a seguir:
set_to_server_value

ServerValue

Define o campo para o valor do servidor especificado.

increment

Value

Adiciona o valor informado ao valor atual do campo.

Precisa ser um número inteiro ou um valor duplo. Se o campo não for um número inteiro ou duplo, ou se o campo ainda não existir, a transformação definirá o campo com o valor fornecido. Se um dos valores fornecidos ou o valor do campo atual forem duplicados, ambos os valores serão interpretados como duplos. A aritmética dupla e a representação de valores duplos seguem a semântica IEEE 754. Se houver estouro de números inteiros positivos/negativos, o campo será resolvido para o número inteiro positivo/negativo de maior magnitude.

maximum

Value

Define o campo para o máximo de seu valor atual e o valor informado.

Precisa ser um número inteiro ou um valor duplo. Se o campo não for um número inteiro ou duplo, ou se o campo ainda não existir, a transformação definirá o campo com o valor fornecido. Se uma operação máxima for aplicada em que o campo e o valor de entrada forem de tipos mistos (ou seja, um é um número inteiro e outro é duplo), o campo assumirá o tipo do operando maior. Se os operandos forem equivalentes (por exemplo, 3 e 3.0), o campo não será alterado. 0, 0,0 e -0,0 são todos zero. O máximo de um valor armazenado em zero e um valor de entrada zero é sempre o valor armazenado. O máximo de qualquer valor numérico x e NaN é NaN.

minimum

Value

Define o campo para o mínimo de seu valor atual e o valor informado.

Precisa ser um número inteiro ou um valor duplo. Se o campo não for um número inteiro ou duplo, ou se o campo ainda não existir, a transformação definirá o campo como o valor de entrada. Se uma operação mínima for aplicada em que o campo e o valor de entrada forem de tipos mistos (ou seja, um é um número inteiro e outro é duplo), o campo assumirá o tipo do operando menor. Se os operandos forem equivalentes (por exemplo, 3 e 3.0), o campo não será alterado. 0, 0,0 e -0,0 são todos zero. O mínimo de um valor armazenado em zero e um valor de entrada zero é sempre o valor armazenado. O mínimo de qualquer valor numérico x e NaN é NaN.

append_missing_elements

ArrayValue

Anexe os elementos fornecidos na ordem se eles ainda não estiverem presentes no valor do campo atual. Se o campo não for uma matriz ou se ainda não existir, ele será definido primeiro como a matriz vazia.

Números equivalentes de tipos diferentes (por exemplo, 3L e 3,0) são considerados iguais ao verificar se um valor está ausente. NaN é igual a NaN, e Nulo é igual a Nulo. Se a entrada tiver vários valores equivalentes, apenas o primeiro será considerado.

O transform_result correspondente será o valor nulo.

remove_all_from_array

ArrayValue

Remova todos os elementos fornecidos da matriz no campo. Se o campo não for uma matriz ou ainda não existir, ele será definido como a matriz vazia.

Números equivalentes dos diferentes tipos (por exemplo, 3L e 3.0) são considerados iguais ao decidir se um elemento deve ser removido. NaN é igual a NaN, e Nulo é igual a Nulo. Isso removerá todos os valores equivalentes se houver cópias.

O transform_result correspondente será o valor nulo.

ServerValue

Um valor calculado pelo servidor.

Enums
SERVER_VALUE_UNSPECIFIED Não especificado. Não use esse valor.
REQUEST_TIME O horário em que o servidor processou a solicitação, com precisão de milissegundos. Se usado em vários campos (documentos iguais ou diferentes) em uma transação, todos os campos receberão o mesmo carimbo de data/hora do servidor.

Estatísticas de execução

Estatísticas de execução da consulta.

Campos
results_returned

int64

Número total de resultados retornados, incluindo documentos, projeções, resultados de agregação e chaves.

execution_duration

Duration

Tempo total para executar a consulta no back-end.

read_operations

int64

Total de operações de leitura faturáveis.

debug_stats

Struct

Estatísticas de depuração a partir da execução da consulta. Observe que as estatísticas de depuração estão sujeitas a alterações à medida que o Firestore evolui. Isso pode incluir: { "indexes_ Assistentes_entradas": "1000", "documentos_escravos": "20", "detalhes_faturamento" : { "documents_billable": "20", "index_Entries_billable": "1000", "min_query_cost": "0" }

ExistenceFilter

Um resumo de todos os documentos que correspondem a um determinado destino.

Campos
target_id

int32

O ID de destino ao qual este filtro se aplica.

count

int32

A contagem total de documentos que correspondem a target_id.

Se for diferente da contagem de documentos no cliente correspondente, o cliente precisará determinar manualmente quais documentos não correspondem mais ao destino.

O cliente pode usar o filtro de flores unchanged_names para ajudar na determinação, testando TODOS os nomes de documentos no filtro. se o nome do documento NÃO estiver no filtro, significa que o documento não corresponde mais ao destino.

unchanged_names

BloomFilter

Um filtro Bloom que, apesar do nome, contém as codificações de bytes UTF-8 dos nomes de recursos de TODOS os documentos que correspondem a target_id, no formato projects/{project_id}/databases/{database_id}/documents/{document_path}.

Esse filtro de Bloom pode ser omitido a critério do servidor, como se for considerado que o cliente não vai usá-lo ou se for muito caro em termos computacionais para calcular ou transmitir. Os clientes precisam lidar com esse campo ausente, recorrendo à lógica usada antes da existência desse campo. Ou seja, adicione novamente o destino sem um token de retomada para descobrir quais documentos no cache do cliente estão fora de sincronia.

ExplainMetrics

Explicar as métricas da consulta.

Campos
plan_summary

PlanSummary

Informações da fase de planejamento para a consulta.

execution_stats

ExecutionStats

Estatísticas agregadas da execução da consulta. Presente apenas quando ExplainOptions.analyze está definido como verdadeiro.

ExplainOptions

Explique as opções da consulta.

Campos
analyze

bool

Opcional. Define se a consulta será executada.

Se for falso (o padrão), a consulta será planejada, retornando apenas as métricas das etapas de planejamento.

Quando verdadeiro, a consulta é planejada e executada, retornando os resultados completos da consulta com as métricas do estágio de planejamento e execução.

GetDocumentRequest

A solicitação para Firestore.GetDocument.

Campos
name

string

Obrigatório. O nome do recurso do documento a ser recebido. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

mask

DocumentMask

Os campos a serem retornados. Se não for definido, todos os campos serão retornados.

Se o documento tiver um campo que não esteja presente na máscara, esse campo não será retornado na resposta.

Campo de união consistency_selector. O modo de consistência para esta transação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

bytes

Lê o documento em uma transação.

read_time

Timestamp

Lê a versão do documento no momento especificado.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

ListCollectionIdsRequest

A solicitação para Firestore.ListCollectionIds.

Campos
parent

string

Obrigatório. O documento pai. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. Por exemplo: projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

page_size

int32

O número máximo de resultados a serem retornados.

page_token

string

Um token de página. Precisa ser um valor de ListCollectionIdsResponse.

Campo de união consistency_selector. O modo de consistência dessa solicitação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
read_time

Timestamp

Lê os documentos como estavam no momento especificado.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

ListCollectionIdsResponse

A resposta de Firestore.ListCollectionIds.

Campos
collection_ids[]

string

Os IDs das coleções.

next_page_token

string

Um token de página que pode ser usado para continuar a lista.

ListDocumentsRequest

A solicitação para Firestore.ListDocuments.

Campos
parent

string

Obrigatório. O nome do recurso pai. Use o formato projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}.

Por exemplo: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

collection_id

string

Opcional. O ID da coleção, relativo a parent, para a lista.

Por exemplo: chatrooms ou messages.

Ele é opcional e, quando não informado, o Firestore lista documentos de todas as coleções no parent fornecido.

page_size

int32

Opcional. O número máximo de documentos a serem retornados em uma única resposta.

O Firestore pode retornar menos do que esse valor.

page_token

string

Opcional. Um token de página, recebido de uma resposta ListDocuments anterior.

Forneça isso para recuperar a página subsequente. Ao paginar, todos os outros parâmetros (com exceção de page_size) precisam corresponder aos valores definidos na solicitação que gerou o token da página.

order_by

string

Opcional. A ordem opcional dos documentos a serem retornados.

Por exemplo, priority desc, __name__ desc.

Isso espelha o ORDER BY usado nas consultas do Firestore, mas em uma representação de string. Quando ausente, os documentos são ordenados com base em __name__ ASC.

mask

DocumentMask

Opcional. Os campos a serem retornados. Se não for definido, todos os campos serão retornados.

Se um documento tiver um campo que não esteja presente nessa máscara, esse campo não será retornado na resposta.

show_missing

bool

Se a lista deve mostrar documentos ausentes.

Um documento está ausente se não existe, mas há subdocumentos aninhados abaixo dele. Quando verdadeiro, esses documentos ausentes serão retornados com uma chave, mas não terão os campos, create_time ou update_time definidos.

Solicitações com show_missing não podem especificar where ou order_by.

Campo de união consistency_selector. O modo de consistência para esta transação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

bytes

Executar a leitura como parte de uma transação já ativa.

read_time

Timestamp

Executar a leitura no momento fornecido.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

ListDocumentsResponse

A resposta para Firestore.ListDocuments.

Campos
documents[]

Document

Os documentos encontrados.

next_page_token

string

Um token para recuperar a próxima página de documentos.

Se esse campo for omitido, não haverá páginas subsequentes.

ListenRequest

Uma solicitação de Firestore.Listen

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

labels

map<string, string>

Rótulos associados a essa alteração de destino.

Campo de união target_change. O destino compatível muda. target_change pode ser apenas de um dos tipos a seguir:
add_target

Target

Um destino para adicionar a este stream.

remove_target

int32

O ID de um destino a ser removido do stream.

ListenResponse

A resposta para Firestore.Listen.

Campos
Campo de união response_type. As respostas compatíveis. response_type pode ser apenas de um dos tipos a seguir:
target_change

TargetChange

Os destinos foram alterados.

document_change

DocumentChange

Um Document foi alterado.

document_delete

DocumentDelete

Um Document foi excluído.

document_remove

DocumentRemove

Um Document foi removido de um destino porque não é mais relevante para ele.

filter

ExistenceFilter

Um filtro para aplicar ao conjunto de documentos retornados anteriormente para um determinado destino.

Retornado quando os documentos podem ter sido removidos do destino especificado, mas os documentos exatos são desconhecidos.

Valor do mapa

Um valor de mapa.

Campos
fields

map<string, Value>

Campos do mapa.

As chaves do mapa representam os nomes dos campos. Os nomes de campo que correspondem à expressão regular __.*__ são reservados. Nomes de campo reservados são proibidos, exceto em determinados contextos documentados. As chaves do mapa, representadas como UTF-8, não podem exceder 1.500 bytes nem ficar vazias.

PartitionQueryRequest

A solicitação para Firestore.PartitionQuery.

Campos
parent

string

Obrigatório. O nome do recurso pai. Use o formato: projects/{project_id}/databases/{database_id}/documents. Os nomes de recursos dos documentos não são aceitos. somente nomes de recursos de banco de dados podem ser especificados.

partition_count

int64

O número máximo desejado de pontos de partição. As partições podem ser retornadas em várias páginas de resultados. O número precisa ser positivo. O número real de partições retornadas pode ser menor.

Por exemplo, isso pode ser definido como um a menos do que o número de consultas paralelas a serem executadas ou, na execução de um job de pipeline de dados, um a menos do que o número de workers ou instâncias de computação disponíveis.

page_token

string

O valor next_page_token retornado de uma chamada anterior para PartitionQuery que pode ser usado para receber mais um conjunto de resultados. Não há garantias de ordenação entre conjuntos de resultados. Assim, o uso de vários conjuntos de resultados exigirá a mesclagem de diferentes conjuntos de resultados.

Por exemplo, duas chamadas subsequentes que usam um page_token podem retornar:

  • cursor B, cursor M, cursor Q
  • cursor A, cursor U, cursor W

Para obter um conjunto de resultados completo ordenado em relação aos resultados da consulta fornecida a PartitionQuery, os conjuntos de resultados devem ser mesclados: cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W

page_size

int32

O número máximo de partições a serem retornadas nessa chamada, sujeito a partition_count.

Por exemplo, se partition_count = 10 e page_size = 8, a primeira chamada para PartitionQuery retornará até 8 partições e uma next_page_token se houver mais resultados. Uma segunda chamada para PartitionQuery retornará até duas partições para concluir o total de 10 especificadas em partition_count.

Campo de união query_type. A consulta a ser particionada. query_type pode ser apenas de um dos tipos a seguir:
structured_query

StructuredQuery

Uma consulta estruturada. A consulta precisa especificar a coleção com todos os descendentes e ser ordenada por nome em ordem crescente. Outros filtros, ordenação, limites, deslocamentos e cursores de início/fim não são compatíveis.

Campo de união consistency_selector. O modo de consistência dessa solicitação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
read_time

Timestamp

Lê os documentos como estavam no momento especificado.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

PartitionQueryResponse

A resposta para Firestore.PartitionQuery.

Campos
partitions[]

Cursor

Resultados da partição. Cada partição é um ponto de divisão que pode ser usado pelo RunQuery como ponto inicial ou final para os resultados da consulta. As solicitações RunQuery precisam ser feitas com a mesma consulta fornecida a essa solicitação PartitionQuery. Os cursores de partição serão ordenados de acordo com a mesma ordem dos resultados da consulta fornecida à PartitionQuery.

Por exemplo, se uma solicitação PartitionQuery retornar os cursores de partição A e B, a execução das três consultas a seguir retornará todo o conjunto de resultados da consulta original:

  • consulta, end_at A
  • consulta, início_em A, fim_em B
  • consulta, início_em B

Um resultado vazio pode indicar que a consulta tem poucos resultados para serem particionados ou que ela ainda não é compatível com particionamento.

next_page_token

string

Um token de página que pode ser usado para solicitar um conjunto extra de resultados, até o número especificado por partition_count na solicitação PartitionQuery. Se o campo estiver em branco, não haverá mais resultados.

Resumo do plano

Informações da fase de planejamento para a consulta.

Campos
indexes_used[]

Struct

Os índices selecionados para a consulta. Por exemplo: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

Precondition

Uma pré-condição em um documento, usada para operações condicionais.

Campos
Campo de união condition_type. O tipo de pré-condição. condition_type pode ser apenas de um dos tipos a seguir:
exists

bool

Quando definido como true, o documento de destino precisa existir. Quando definido como false, o documento de destino não pode existir.

update_time

Timestamp

Quando definido, o documento de destino precisa existir e ter sido atualizado pela última vez naquele momento. O carimbo de data/hora precisa estar alinhado em microssegundos.

RollbackRequest

A solicitação para Firestore.Rollback.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}.

transaction

bytes

Obrigatório. A transação a ser revertida.

RunAggregationQueryRequest

A solicitação para Firestore.RunAggregationQuery.

Campos
parent

string

Obrigatório. O nome do recurso pai. Use o formato projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Por exemplo: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Opcional. Explique as opções da consulta. Se definido, serão retornadas estatísticas de consulta adicionais. Caso contrário, apenas os resultados da consulta serão retornados.

Campo de união query_type. A consulta a ser executada. query_type pode ser apenas de um dos tipos a seguir:
structured_aggregation_query

StructuredAggregationQuery

Uma consulta de agregação.

Campo de união consistency_selector. O modo de consistência da consulta tem como padrão a consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

bytes

Execute a agregação em uma transação já ativa.

O valor aqui é o ID da transação opaco para executar a consulta.

new_transaction

TransactionOptions

Inicia uma nova transação como parte da consulta, com o padrão somente para leitura.

O novo ID da transação será retornado como a primeira resposta no fluxo.

read_time

Timestamp

Executa a consulta no carimbo de data/hora fornecido.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

RunAggregationQueryResponse

A resposta para Firestore.RunAggregationQuery.

Campos
result

AggregationResult

Um único resultado de agregação.

Não está presente ao relatar progresso parcial.

transaction

bytes

A transação que foi iniciada como parte da solicitação.

Presente apenas na primeira resposta quando a solicitação pede para iniciar uma nova transação.

read_time

Timestamp

A hora em que o resultado agregado foi calculado. Ela está sempre aumentando monotonicamente. nesse caso, o AggregateResult anterior no stream de resultados não vai ter sido alterado entre o read_time e este.

Se a consulta não retornar resultados, uma resposta com read_time e nenhum result será enviada, o que representa o horário em que a consulta foi executada.

explain_metrics

ExplainMetrics

Explicar as métricas da consulta. Ele só está presente quando o RunAggregationQueryRequest.explain_options é fornecido e é enviado apenas uma vez com a última resposta no stream.

RunQueryRequest

A solicitação para Firestore.RunQuery.

Campos
parent

string

Obrigatório. O nome do recurso pai. Use o formato projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Por exemplo: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Opcional. Explique as opções da consulta. Se definido, serão retornadas estatísticas de consulta adicionais. Caso contrário, apenas os resultados da consulta serão retornados.

Campo de união query_type. A consulta a ser executada. query_type pode ser apenas de um dos tipos a seguir:
structured_query

StructuredQuery

Uma consulta estruturada.

Campo de união consistency_selector. O modo de consistência para esta transação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

bytes

Execute a consulta em uma transação já ativa.

O valor aqui é o ID da transação opaco para executar a consulta.

new_transaction

TransactionOptions

Inicia uma nova transação e lê os documentos. O padrão é uma transação somente leitura. O novo ID da transação será retornado como a primeira resposta no fluxo.

read_time

Timestamp

Lê os documentos como estavam no momento especificado.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

RunQueryResponse

A resposta para Firestore.RunQuery.

Campos
transaction

bytes

A transação que foi iniciada como parte da solicitação. Só pode ser definido na primeira resposta e somente se RunQueryRequest.new_transaction tiver sido definido na solicitação. Se definido, nenhum outro campo será definido nesta resposta.

document

Document

Um resultado de consulta, não definido ao relatar progresso parcial.

read_time

Timestamp

A hora em que o documento foi lido. Isso pode estar aumentando monotonicamente; Nesse caso, os documentos anteriores no fluxo de resultados têm a garantia de não serem alterados entre o read_time e este.

Se a consulta não retornar resultados, uma resposta com read_time e nenhum document será enviada, o que representa o horário em que a consulta foi executada.

skipped_results

int32

O número de resultados que foram ignorados devido a um deslocamento entre a última resposta e a atual.

explain_metrics

ExplainMetrics

Explicar as métricas da consulta. Ele só está presente quando o RunQueryRequest.explain_options é fornecido e é enviado apenas uma vez com a última resposta no stream.

Campo de união continuation_selector. O modo de continuação da consulta. Se presente, indica que o stream de resposta da consulta atual foi concluído. Isso pode ser definido com ou sem um document, mas, quando definido, nenhum outro resultado é retornado. continuation_selector pode ser apenas de um dos tipos a seguir:
done

bool

Se presente, o Firestore concluiu completamente a solicitação e nenhum outro documento será retornado.

ConsultadeAgregação Estruturada

Consulta do Firestore para executar uma agregação em um StructuredQuery.

Campos
aggregations[]

Aggregation

Opcional. Série de agregações a serem aplicadas aos resultados do structured_query.

Requer:

  • Mínimo de uma e máximo de cinco agregações por consulta.
Campo de união query_type. A consulta base sobre a qual a agregação será feita. query_type pode ser apenas de um dos tipos a seguir:
structured_query

StructuredQuery

Consulta estruturada aninhada.

Agregação

Define uma agregação que produz um único resultado.

Campos
alias

string

Opcional. Nome opcional do campo em que o resultado da agregação será armazenado.

Se não for fornecido, o Firestore escolherá um nome padrão seguindo o formato field_<incremental_id++>. Exemplo:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

passa a ser:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

Requer:

  • Precisa ser exclusivo em todos os aliases de agregação.
  • Seguir as limitações de document field name.
Campo de união operator. O tipo de agregação a ser executada (obrigatório). operator pode ser apenas de um dos tipos a seguir:
count

Count

Agregador de contagem.

sum

Sum

Agregador de soma.

avg

Avg

Agregador médio.

Méd.

Média dos valores do campo solicitado.

  • Somente valores numéricos serão agregados. Todos os valores não numéricos, incluindo NULL, são ignorados.

  • Se os valores agregados contiverem NaN, retornará NaN. A matemática do infinito segue os padrões IEEE-754.

  • Se o conjunto de valores agregados estiver vazio, retornará NULL.

  • Sempre retorna o resultado como um valor duplo.

Campos
field

FieldReference

O campo de agregação.

Contagem

Contagem de documentos que correspondem à consulta.

A função de agregação COUNT(*) opera em todo o documento, por isso não requer uma referência de campo.

Campos
up_to

Int64Value

Opcional. Restrição opcional sobre o número máximo de documentos a serem contados.

Isso oferece uma maneira de definir um limite superior para o número de documentos a serem verificados, limitando a latência e o custo.

"Não especificado" é interpretado como sem limite.

Exemplo de alto nível:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

Requer:

  • Precisa ser maior que zero quando presente.

Soma

Soma dos valores do campo solicitado.

  • Somente valores numéricos serão agregados. Todos os valores não numéricos, incluindo NULL, são ignorados.

  • Se os valores agregados contiverem NaN, retornará NaN. A matemática do infinito segue os padrões IEEE-754.

  • Se o conjunto de valores agregados estiver vazio, retornará 0.

  • Retorna um número inteiro de 64 bits se todos os números agregados forem inteiros e o resultado da soma não estourar. Caso contrário, o resultado é retornado como um valor double. Mesmo que todos os valores agregados sejam números inteiros, o resultado será retornado como "double" se não couber em um número inteiro assinado de 64 bits. Quando isso ocorre, o valor retornado perde a precisão.

  • Quando ocorre um subfluxo, a agregação de ponto flutuante não é determinista. Isso significa que executar a mesma consulta repetidamente sem alterações nos valores subjacentes pode produzir resultados um pouco diferentes a cada vez. Nesses casos, os valores precisam ser armazenados como números inteiros sobre números de ponto flutuante.

Campos
field

FieldReference

O campo de agregação.

StructuredQuery

Uma consulta do Firestore.

Os estágios da consulta são executados na seguinte ordem: 1. de 2, em que 3. selecione 4. order_by + start_at + end_at 5. deslocamento 6. limit

Campos
select

Projection

Subconjunto opcional dos campos a serem retornados.

Isso funciona como um DocumentMask nos documentos retornados de uma consulta. Quando não definido, presume que o autor da chamada quer que todos os campos sejam retornados.

from[]

CollectionSelector

As coleções a serem consultadas.

where

Filter

O filtro que será aplicado.

order_by[]

Order

A ordem a ser aplicada aos resultados da consulta.

O Firestore permite que os autores de chamadas forneçam uma ordem completa, uma ordem parcial ou nenhuma ordem. Em todos os casos, o Firestore garante uma ordem estável por meio das seguintes regras:

  • O order_by é obrigatório para referenciar todos os campos usados com um filtro de desigualdade.
  • Todos os campos que precisam estar no order_by, mas que ainda não estão presentes, são anexados na ordem lexicográfica do nome do campo.
  • Se um pedido em __name__ não for especificado, ele será anexado por padrão.

Campos são anexados com a mesma direção de classificação que a última ordem especificada, ou 'ASCENDING' caso nenhum pedido tenha sido especificado. Exemplo:

  • ORDER BY a se torna ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC se torna ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 se torna WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 se torna WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
start_at

Cursor

Um possível prefixo de uma posição no conjunto de resultados para iniciar a consulta.

A ordem do conjunto de resultados é baseada na cláusula ORDER BY da consulta original.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

Os resultados desta consulta são ordenados por (b ASC, __name__ ASC).

Os cursores podem fazer referência à ordem completa ou a um prefixo do local, mas não podem fazer referência a mais campos do que o ORDER BY fornecido.

Continuando com o exemplo acima, anexar os seguintes cursores de início terá um impacto variável:

  • START BEFORE (2, /k/123): inicia a consulta logo antes de a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): inicia a consulta logo após a = 1 AND b > 10.

Ao contrário de OFFSET, que exige a verificação dos primeiros N resultados para pular, um cursor de início permite que a consulta comece em uma posição lógica. Essa posição não precisa corresponder a um resultado real, ela vai avançar dessa posição para encontrar o próximo documento.

Requer:

  • O número de valores não pode ser maior que o número de campos especificado na cláusula ORDER BY.
end_at

Cursor

Um possível prefixo de uma posição no conjunto de resultados em que a consulta será encerrada.

Isso é semelhante à START_AT, mas controla a posição final, e não a inicial.

Requer:

  • O número de valores não pode ser maior que o número de campos especificado na cláusula ORDER BY.
offset

int32

O número de documentos a serem ignorados antes de retornar o primeiro resultado.

Isso se aplica depois das restrições especificadas por WHERE, START AT e END AT, mas antes da cláusula LIMIT.

Requer:

  • Se especificado, o valor precisa ser maior ou igual a zero.
limit

Int32Value

O número máximo de resultados a serem retornados.

Aplica-se após todas as outras restrições.

Requer:

  • Se especificado, o valor precisa ser maior ou igual a zero.
find_nearest

FindNearest

Opcional. Uma pesquisa sobre vizinhos mais próximos em potencial.

Aplica-se depois de todos os outros filtros e ordenação.

Encontra os embeddings de vetor mais próximos do vetor de consulta especificado.

Seletor de coleção

Uma seleção de uma coleção, como messages as m1.

Campos
collection_id

string

O ID da coleção. Quando definido, seleciona apenas coleções com esse ID.

all_descendants

bool

Quando falso, seleciona apenas os conjuntos que são filhos imediatos do parent especificado no RunQueryRequest. Quando verdadeiro, seleciona todas as coleções descendentes.

CompositeFilter

Um filtro que combina vários outros usando o operador especificado.

Campos
op

Operator

O operador para combinar vários filtros.

filters[]

Filter

A lista de filtros a serem combinados.

Requer:

  • Pelo menos um filtro está presente.

Operador

Um operador de filtro composto.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
AND Os documentos precisam atender a todos os filtros combinados.
OR Os documentos precisam atender a pelo menos um dos filtros combinados.

Direção

Uma direção de classificação.

Enums
DIRECTION_UNSPECIFIED Não especificado.
ASCENDING Crescente.
DESCENDING Decrescente.

Filtrodecampo

Um filtro em um campo específico.

Campos
field

FieldReference

O campo a ser filtrado.

op

Operator

O operador a ser filtrado.

value

Value

O valor a ser comparado.

Operador

Um operador de filtro de campo.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
LESS_THAN

O field informado é menor que o value.

Requer:

  • Esse field ficou em primeiro lugar em order_by.
LESS_THAN_OR_EQUAL

O field informado é menor ou igual ao value informado.

Requer:

  • Esse field ficou em primeiro lugar em order_by.
GREATER_THAN

O field informado é maior que o value.

Requer:

  • Esse field ficou em primeiro lugar em order_by.
GREATER_THAN_OR_EQUAL

A field especificada é maior ou igual à value especificada.

Requer:

  • Esse field ficou em primeiro lugar em order_by.
EQUAL O field informado é igual ao value informado.
NOT_EQUAL

O field informado não é igual ao value informado.

Requer:

  • Nenhum outro NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no order_by.
ARRAY_CONTAINS O field é uma matriz que contém o value especificado.
IN

A field especificada é igual a pelo menos um valor na matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio, sujeito a limites de disjunção.
  • Não há filtros NOT_IN na mesma consulta.
ARRAY_CONTAINS_ANY

A field especificada é uma matriz que contém qualquer um dos valores da matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio, sujeito a limites de disjunção.
  • Nenhum outro filtro ARRAY_CONTAINS_ANY na mesma disjunção.
  • Não há filtros NOT_IN na mesma consulta.
NOT_IN

O valor de field não está na matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio com no máximo 10 valores.
  • Nenhum outro OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no order_by.

FieldReference

Uma referência a um campo em um documento, por exemplo: stats.operations.

Campos
field_path

string

Uma referência a um campo em um documento.

Requer:

  • PRECISA ser uma string de segmentos delimitada por ponto (.), em que cada segmento está em conformidade com as limitações de document field name.

Filtro

Um filtro.

Campos
Campo de união filter_type. O tipo de filtro. filter_type pode ser apenas de um dos tipos a seguir:
composite_filter

CompositeFilter

Um filtro composto.

field_filter

FieldFilter

Um filtro em um campo do documento.

unary_filter

UnaryFilter

Um filtro que usa exatamente um argumento.

Encontrar mais próximo

Configuração de pesquisa de vizinhos mais próximos.

Campos
vector_field

FieldReference

Obrigatório. Um campo de vetor indexado para pesquisar. Somente os documentos que contêm vetores com dimensionalidade correspondente a query_vector podem ser retornados.

query_vector

Value

Obrigatório. O vetor de consulta que estamos pesquisando. Precisa ser um vetor com no máximo 2.048 dimensões.

distance_measure

DistanceMeasure

Obrigatório. A medida de distância a ser usada, obrigatória.

limit

Int32Value

Obrigatório. O número de vizinhos mais próximos a serem retornados. Precisa ser um número inteiro positivo de até 1.000.

Medida de distância

A medida de distância a ser usada na comparação de vetores.

Enums
DISTANCE_MEASURE_UNSPECIFIED Não deve ser definido.
EUCLIDEAN Mede a distância EUCLIDEAN entre os vetores. Consulte Euclidiano para saber mais
COSINE Compara vetores com base no ângulo entre eles, o que permite medir a similaridade que não é baseada na magnitude dos vetores. Recomendamos usar DOT_PRODUCT com vetores normalizados de unidade em vez da distância COSINE, que é matematicamente equivalente a um desempenho melhor. Consulte Semelhança de cossenos para saber mais.
DOT_PRODUCT Semelhante ao cosseno, mas é afetado pela magnitude dos vetores. Consulte Dot Product para saber mais.

Pedido

Um pedido em um campo.

Campos
field

FieldReference

O campo pelo qual ordenar.

direction

Direction

A direção pela qual ordenar. O valor padrão é ASCENDING.

Projeção

A projeção dos campos do documento a serem retornados.

Campos
fields[]

FieldReference

Os campos a serem retornados.

Se estiver vazio, todos os campos serão retornados. Para retornar apenas o nome do documento, use ['__name__'].

Filtro Unário

Um filtro com um único operando.

Campos
op

Operator

O operador unário a ser aplicado.

Campo de união operand_type. O argumento para o filtro. operand_type pode ser apenas de um dos tipos a seguir:
field

FieldReference

O campo ao qual aplicar o operador.

Operador

Um operador unário.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
IS_NAN O field fornecido é igual a NaN.
IS_NULL O field fornecido é igual a NULL.
IS_NOT_NAN

O field fornecido não é igual a NaN.

Requer:

  • Nenhum outro NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no order_by.
IS_NOT_NULL

O field fornecido não é igual a NULL.

Requer:

  • Um único NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no order_by.

Segmentar

Uma especificação de um conjunto de documentos a serem ouvidos.

Campos
target_id

int32

O ID que identifica o destino no stream. Precisa ser um número positivo e diferente de zero.

Se target_id for 0 (ou não especificado), o servidor atribuirá um ID a esse destino e o retornará em um evento TargetChange::ADD. Depois que um destino com target_id=0 é adicionado, todos os destinos subsequentes também precisam ter target_id=0. Se uma solicitação AddTarget com target_id != 0 for enviada ao servidor depois que um destino com target_id=0 for adicionado, o servidor enviará imediatamente uma resposta com um evento TargetChange::Remove.

Se o cliente enviar várias solicitações AddTarget sem um ID, a ordem dos IDs retornados em TargetChage.target_ids vai ser indefinida. Portanto, os clientes devem fornecer um ID de destino em vez de depender do servidor para atribuir um.

Se target_id for diferente de zero, não poderá haver um destino ativo nesse stream com o mesmo ID.

once

bool

Se o destino precisar ser removido depois de estar atual e consistente.

expected_count

Int32Value

O número de documentos que corresponderam pela última vez à consulta no token de retomada ou no horário de leitura.

Esse valor só é relevante quando um resume_type é fornecido. A presença de valor maior que zero indica que o cliente quer que ExistenceFilter.unchanged_names seja incluído na resposta.

Campo de união target_type. O tipo de segmento a ser detectado. target_type pode ser apenas de um dos tipos a seguir:
query

QueryTarget

Um destino especificado por uma consulta.

documents

DocumentsTarget

Um destino especificado por um conjunto de nomes de documentos.

Campo de união resume_type. Quando começar a ouvir.

Se especificado, somente os documentos correspondentes que foram atualizados APÓS resume_token ou read_time serão retornados. Caso contrário, todos os documentos correspondentes serão retornados antes de qualquer alteração subsequente. resume_type pode ser apenas de um dos tipos a seguir:

resume_token

bytes

Um token de retomada de um TargetChange anterior para um destino idêntico.

O uso de um token de retomada com um destino diferente não é compatível e pode falhar.

read_time

Timestamp

Comece a ouvir depois de um read_time específico.

O cliente precisa saber o estado dos documentos correspondentes no momento.

DocumentsTarget

Um destino especificado por um conjunto de nomes de documentos.

Campos
documents[]

string

Os nomes dos documentos a serem recuperados. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. A solicitação falhará se algum dos documentos não for um recurso filho da database especificada. Nomes duplicados serão ocultados.

Destino da consulta

Um destino especificado por uma consulta.

Campos
parent

string

O nome do recurso pai. Use o formato projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Por exemplo: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Campo de união query_type. A consulta a ser executada. query_type pode ser apenas de um dos tipos a seguir:
structured_query

StructuredQuery

Uma consulta estruturada.

Mudança desejada

Os destinos que estão sendo observados foram alterados.

Campos
target_change_type

TargetChangeType

O tipo de alteração que ocorreu.

target_ids[]

int32

Os IDs das segmentações que foram alteradas.

Se estiver vazio, a mudança será aplicada a todos os destinos.

A ordem dos IDs de destino não foi definida.

cause

Status

O erro que resultou nessa alteração, se aplicável.

resume_token

bytes

Um token que pode ser usado para retomar o stream para o target_ids especificado ou para todos os destinos se target_ids estiver vazio.

Não é definido em todas as alterações desejadas.

read_time

Timestamp

O read_time consistente para o target_ids especificado (omitido quando os target_ids não estão em um snapshot consistente).

O stream vai enviar um read_time com target_ids vazio sempre que todo o stream chegar a um novo snapshot consistente. As mensagens ADD, CURRENT e RESET certamente resultarão em um novo snapshot consistente (ao contrário das mensagens NO_CHANGE e REMOVE).

Para um determinado stream, o aumento de read_time é garantido monotonicamente.

Tipo de mudança de destino

O tipo de alteração

Enums
NO_CHANGE Nenhuma alteração foi feita. Usado apenas para enviar um resume_token atualizado.
ADD Os destinos foram adicionados.
REMOVE Os destinos foram removidos.
CURRENT

Os destinos refletem todas as alterações confirmadas antes da adição deles ao stream.

Ela será enviada depois ou com uma read_time maior ou igual ao horário em que as segmentações foram adicionadas.

Os listeners podem aguardar essa mudança se a semântica de leitura após gravação for desejada.

RESET

Os destinos foram redefinidos, e um novo estado inicial será retornado nas próximas alterações.

Após a conclusão do estado inicial, CURRENT vai ser retornado mesmo que o valor tenha sido indicado anteriormente como CURRENT.

TransactionOptions

Opções para criar uma nova transação.

Campos
Campo de união mode. O modo da transação. mode pode ser apenas de um dos tipos a seguir:
read_only

ReadOnly

A transação só pode ser usada para operações de leitura.

read_write

ReadWrite

A transação pode ser usada para operações de leitura e gravação.

Somente para leitura

Opções de uma transação que só pode ser usada para ler documentos.

Campos
Campo de união consistency_selector. O modo de consistência para esta transação. Se não for definido, o padrão será consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
read_time

Timestamp

Lê os documentos em um horário determinado.

Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

Leitura/gravação

Opções de uma transação que podem ser usadas para ler e gravar documentos.

O Firestore não permite que solicitações de autenticação de terceiros criem leitura/gravação. transações.

Campos
retry_transaction

bytes

Uma transação opcional para tentar novamente.

UpdateDocumentRequest

A solicitação para Firestore.UpdateDocument.

Campos
document

Document

Obrigatório. O documento atualizado. Cria o documento, se ele ainda não existir.

update_mask

DocumentMask

Os campos a serem atualizados. Nenhum dos caminhos de campo da máscara pode conter um nome reservado.

Se o documento existir no servidor e tiver campos não referenciados na máscara, eles não serão alterados. Os campos referenciados na máscara, mas não presentes no documento de entrada, são excluídos do documento no servidor.

mask

DocumentMask

Os campos a serem retornados. Se não for definido, todos os campos serão retornados.

Se o documento tiver um campo que não esteja presente na máscara, esse campo não será retornado na resposta.

current_document

Precondition

Uma pré-condição opcional no documento. A solicitação falhará se esse valor for definido e não for atendido pelo documento de destino.

Valor

Uma mensagem que pode conter qualquer um dos tipos de valor compatíveis.

Campos
Campo de união value_type. Precisa ter um valor definido. value_type pode ser apenas de um dos tipos a seguir:
null_value

NullValue

Um valor nulo.

boolean_value

bool

Um valor booleano.

integer_value

int64

Um valor inteiro.

double_value

double

Um valor duplo.

timestamp_value

Timestamp

Um valor de carimbo de data/hora.

Precisa apenas até microssegundos. Quando armazenada, qualquer precisão adicional é arredondada para baixo.

string_value

string

Um valor de string.

A string, representada como UTF-8, não pode exceder 1 MiB a 89 bytes. Somente os primeiros 1.500 bytes da representação UTF-8 são considerados nas consultas.

bytes_value

bytes

Um valor de bytes.

Não pode exceder 1 MiB a 89 bytes. Somente os primeiros 1.500 bytes são considerados nas consultas.

reference_value

string

Uma referência a um documento. Por exemplo, projects/{project_id}/databases/{database_id}/documents/{document_path}.

geo_point_value

LatLng

Um valor de ponto geográfico que representa um ponto na superfície da Terra.

array_value

ArrayValue

Um valor de matriz.

Não pode conter diretamente outro valor de matriz, embora possa conter um mapa com outra matriz.

map_value

MapValue

Um valor de mapa.

Gravação

Uma gravação em um documento.

Campos
update_mask

DocumentMask

Os campos a serem atualizados nesta gravação.

Esse campo só pode ser definido quando a operação é update. Se a máscara não estiver definida para um update e o documento existir, todos os dados existentes serão substituídos. Se a máscara estiver definida e o documento no servidor tiver campos não cobertos pela máscara, eles não serão alterados. Os campos referenciados na máscara, mas não presentes no documento de entrada, são excluídos do documento no servidor. Os caminhos de campo dessa máscara não podem conter um nome de campo reservado.

update_transforms[]

FieldTransform

As transformações a serem executadas após a atualização.

Esse campo só pode ser definido quando a operação é update. Se estiver presente, essa gravação será equivalente a executar update e transform no mesmo documento atomicamente e em ordem.

current_document

Precondition

Uma pré-condição opcional no documento.

A gravação falhará se este valor for definido e não for atendido pelo documento de destino.

Campo de união operation. A operação a ser executada. operation pode ser apenas de um dos tipos a seguir:
update

Document

Um documento a ser gravado.

delete

string

Um nome de documento a ser excluído. Use o formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

transform

DocumentTransform

Aplica uma transformação a um documento.

WriteRequest

A solicitação para Firestore.Write.

A primeira solicitação cria um fluxo ou retoma um existente de um token.

Ao criar um novo stream, o servidor responde com uma resposta contendo apenas um ID e um token, para ser usado na próxima solicitação.

Ao retomar um stream, o servidor primeiro transmite todas as respostas posteriores ao token fornecido e, em seguida, uma resposta contendo apenas um token atualizado, para usar na próxima solicitação.

Campos
database

string

Obrigatório. O nome do banco de dados. Use o formato: projects/{project_id}/databases/{database_id}. Isso só é necessário na primeira mensagem.

stream_id

string

O ID do stream de gravação a ser retomado. Isso só pode ser definido na primeira mensagem. Quando esse campo ficar vazio, um novo stream de gravação será criado.

writes[]

Write

As gravações a serem aplicadas.

Sempre executado atomicamente e em ordem. Ele precisa estar vazio na primeira solicitação. Pode estar vazio na última solicitação. Ele não pode ficar vazio em todas as outras solicitações.

stream_token

bytes

Um token de stream enviado anteriormente pelo servidor.

O cliente precisa definir esse campo como o token do WriteResponse mais recente recebido. Isso confirma que o cliente recebeu respostas até esse token. Depois de enviar esse token, os tokens anteriores não poderão mais ser usados.

O servidor poderá fechar o stream se houver muitas respostas não confirmadas.

Deixe esse campo sem definição ao criar uma nova transmissão. Para retomar um stream em um ponto específico, defina este campo e o campo stream_id.

Deixe esse campo sem definição ao criar uma nova transmissão.

labels

map<string, string>

Rótulos associados a esta solicitação de gravação.

Resposta de gravação

A resposta para Firestore.Write.

Campos
stream_id

string

O ID do fluxo. É definida apenas na primeira mensagem, quando uma nova transmissão é criada.

stream_token

bytes

Token que representa a posição dessa resposta no stream. Isso pode ser usado por um cliente para retomar o stream neste momento.

Esse campo está sempre definido.

write_results[]

WriteResult

O resultado da aplicação das gravações.

Esse i-ésimo resultado de gravação corresponde à i-ésima gravação na solicitação.

commit_time

Timestamp

O horário em que a confirmação ocorreu. Qualquer leitura com um read_time igual ou maior garante a visualização dos efeitos da gravação.

WriteResult

O resultado da aplicação de uma gravação.

Campos
update_time

Timestamp

O horário da última atualização do documento depois de aplicar a gravação. Não definido após um delete.

Se a gravação não tiver realmente alterado o documento, este será o update_time anterior.

transform_results[]

Value

Os resultados da aplicação de cada DocumentTransform.FieldTransform, na mesma ordem.