Package google.firestore.v1beta1

Indice

Firestore

Il servizio Cloud Firestore.

Cloud Firestore è un database di documenti NoSQL cloud-native, serverless, veloce e completamente gestito che semplifica l'archiviazione, la sincronizzazione e l'esecuzione di query sui dati per app IoT, web e per dispositivi mobili a livello globale. Le librerie client offrono sincronizzazione in tempo reale e supporto offline, mentre le funzionalità di sicurezza e le integrazioni con Firebase e Google Cloud Platform accelerano la creazione di app realmente serverless.

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Recupera più documenti.

Non è garantito che i documenti restituiti con questo metodo vengano restituiti nello stesso ordine in cui sono stati richiesti.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

BatchWrite

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

Applica un gruppo di operazioni di scrittura.

Il metodo BatchWrite non applica le operazioni di scrittura a livello atomico e può applicarle in modo non ordinato. Il metodo non consente più di una scrittura per documento. Ogni scrittura ha esito positivo o negativo in modo indipendente. Consulta il BatchWriteResponse per lo stato di ogni scrittura.

Se hai bisogno di un set di scritture applicate a livello atomico, utilizza invece Commit.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

BeginTransaction

rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse)

Avvia una nuova transazione.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

Esegui il commit

rpc Commit(CommitRequest) returns (CommitResponse)

Esegue il commit di una transazione e, facoltativamente, aggiorna i documenti.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

CreateDocument

rpc CreateDocument(CreateDocumentRequest) returns (Document)

Crea un nuovo documento.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

DeleteDocument

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

Elimina un documento.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Recupera un singolo documento.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

ListCollectionIds

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

Elenca tutti gli ID raccolta sotto un documento.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

ListDocuments

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

Elenca i documenti.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

Ascolto

rpc Listen(ListenRequest) returns (ListenResponse)

Ascolta i cambiamenti. Questo metodo è disponibile solo tramite gRPC o WebChannel (non REST).

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

PartitionQuery

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse)

Esegue il partizionamento di una query restituendo cursori di partizione che possono essere utilizzati per eseguire la query in parallelo. I cursori di partizione restituiti sono punti di suddivisione che possono essere utilizzati da RunQuery come punti di inizio/fine per i risultati della query.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

Esegui il rollback

rpc Rollback(RollbackRequest) returns (Empty)

Esegue il rollback di una transazione.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse)

Esegue una query di aggregazione.

Anziché produrre risultati Document come Firestore.RunQuery, questa API consente di eseguire un'aggregazione per produrre una serie di AggregationResult lato server.

Esempio generale:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

RunQuery

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

Esegue una query.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

UpdateDocument

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

Aggiorna o inserisce un documento.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

Scrittura

rpc Write(WriteRequest) returns (WriteResponse)

Trasmette i flussi di batch di aggiornamenti ed eliminazioni di documenti in ordine. Questo metodo è disponibile solo tramite gRPC o WebChannel (non REST).

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

AggregationResult

Il risultato di un singolo bucket da una query di aggregazione Firestore.

Le chiavi di aggregate_fields sono le stesse per tutti i risultati in una query di aggregazione, a differenza delle query sui documenti che possono avere campi diversi per ogni risultato.

Campi
aggregate_fields

map<string, Value>

Il risultato delle funzioni di aggregazione, ad esempio COUNT(*) AS total_docs.

La chiave è la chiave alias assegnata alla funzione di aggregazione al momento dell'input e le dimensioni di questa mappa corrispondono al numero di funzioni di aggregazione nella query.

ArrayValue

Un valore array.

Campi
values[]

Value

Valori nell'array.

BatchGetDocumentsRequest

La richiesta di Firestore.BatchGetDocuments.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

documents[]

string

I nomi dei documenti da recuperare. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. La richiesta avrà esito negativo se uno qualsiasi del documento non è una risorsa secondaria del database specificato. I nomi duplicati verranno eliminati.

mask

DocumentMask

I campi da restituire. Se non viene configurato, restituisce tutti i campi.

Se un documento ha un campo che non è presente in questa maschera, quel campo non verrà restituito nella risposta.

Campo di unione consistency_selector. La modalità di coerenza per questa transazione. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

bytes

Legge i documenti di una transazione.

new_transaction

TransactionOptions

Avvia una nuova transazione e legge i documenti. Il valore predefinito è una transazione di sola lettura. Il nuovo ID transazione verrà restituito come prima risposta nel flusso.

read_time

Timestamp

Legge i documenti così come erano al momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

BatchGetDocumentsResponse

La risposta riprodotta in streaming per Firestore.BatchGetDocuments.

Campi
transaction

bytes

La transazione avviata nell'ambito di questa richiesta. Verrà impostato solo nella prima risposta e solo se BatchGetDocumentsRequest.new_transaction è stato impostato nella richiesta.

read_time

Timestamp

L'ora in cui il documento è stato letto. La variazione potrebbe aumentare monoticamente. In questo caso, infatti, i documenti precedenti nel flusso dei risultati sono garantiti che non siano cambiati tra il tempo di lettura e quello attuale.

Campo di unione result. Un unico risultato. Questo campo può essere vuoto se il server restituisce solo una transazione. result può essere solo uno dei seguenti:
found

Document

Un documento richiesto.

missing

string

Un nome documento che è stato richiesto, ma non esiste. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

BatchWriteRequest

La richiesta di Firestore.BatchWrite.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

writes[]

Write

Le operazioni di scrittura da applicare.

Il metodo non si applica a livello atomico e non garantisce l'ordinamento. Ogni scrittura ha esito positivo o negativo in modo indipendente. Non puoi scrivere sullo stesso documento più di una volta per richiesta.

labels

map<string, string>

Etichette associate alla scrittura in batch.

BatchWriteResponse

La risposta di Firestore.BatchWrite.

Campi
write_results[]

WriteResult

Il risultato dell'applicazione delle scritture.

Questo risultato di scrittura i-th corrisponde alla scrittura i-esima nella richiesta.

status[]

Status

Lo stato delle scritture.

Questo stato di scrittura i-esima corrisponde alla scrittura i-esima nella richiesta.

BeginTransactionRequest

La richiesta di Firestore.BeginTransaction.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

options

TransactionOptions

Le opzioni per la transazione. Il valore predefinito è una transazione di lettura-scrittura.

BeginTransactionResponse

La risposta per Firestore.BeginTransaction.

Campi
transaction

bytes

La transazione avviata.

BitSequence

Una sequenza di bit codificata in un array di byte.

Ogni byte nell'array di byte bitmap archivia 8 bit della sequenza. L'unica eccezione è l'ultimo byte, che può archiviare 8 bit o meno. padding definisce il numero di bit dell'ultimo byte da ignorare come "spaziatura interna". I valori di questi bit di "spaziatura" non sono specificati e devono essere ignorati.

Per recuperare il primo bit, bit 0, calcola: (bitmap[0] & 0x01) != 0. Per recuperare il secondo bit, bit 1, calcola: (bitmap[0] & 0x02) != 0. Per recuperare il terzo bit, bit 2, calcola: (bitmap[0] & 0x04) != 0. Per recuperare il quarto bit, bit 3, calcola: (bitmap[0] & 0x08) != 0. Per recuperare il bit n, calcola: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

La "dimensione" di BitSequence (il numero di bit che contiene) viene calcolata con questa formula: (bitmap.length * 8) - padding.

Campi
bitmap

bytes

I byte che codificano la sequenza di bit. Può avere una lunghezza pari a zero.

padding

int32

Il numero di bit dell'ultimo byte in bitmap da ignorare come "spaziatura interna". Se la lunghezza di bitmap è zero, questo valore deve essere 0. In caso contrario, questo valore deve essere compreso tra 0 e 7 inclusi.

BloomFilter

Un filtro Bloom (https://en.wikipedia.org/wiki/Bloom_filter).

Il filtro bloom esegue l'hashing delle voci con MD5 e tratta l'hash a 128 bit risultante come 2 valori hash distinti a 64 bit, interpretati come numeri interi senza segno utilizzando la codifica del complemento a 2.

Questi due valori hash, denominati h1 e h2, vengono quindi utilizzati per calcolare i valori hash hash_count utilizzando la formula, a partire da i=0:

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

Questi valori risultanti vengono quindi presi modulo del numero di bit nel filtro Bloom per ottenere i bit del filtro Bloom da testare per la voce specificata.

Campi
bits

BitSequence

I dati del filtro Bloom.

hash_count

int32

Il numero di hash utilizzati dall'algoritmo.

CommitRequest

La richiesta di Firestore.Commit.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

writes[]

Write

Le operazioni di scrittura da applicare.

Esegui sempre a livello atomico e in ordine.

transaction

bytes

Se impostato, applica tutte le scritture in questa transazione ed esegue il commit.

CommitResponse

La risposta per Firestore.Commit.

Campi
write_results[]

WriteResult

Il risultato dell'applicazione delle scritture.

Questo risultato di scrittura i-th corrisponde alla scrittura i-esima nella richiesta.

commit_time

Timestamp

L'ora in cui si è verificato il commit. Qualsiasi lettura con un valore read_time uguale o maggiore è garantito per vedere gli effetti del commit.

CreateDocumentRequest

La richiesta di Firestore.CreateDocument.

Campi
parent

string

obbligatorio. La risorsa padre. Ad esempio: projects/{project_id}/databases/{database_id}/documents o projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}

collection_id

string

obbligatorio. L'ID raccolta, relativo a parent, dell'elenco. Ad esempio: chatrooms.

document_id

string

L'ID documento assegnato dal cliente da utilizzare per questo documento.

Campo facoltativo. Se non specificato, il servizio verrà assegnato un ID.

document

Document

obbligatorio. Il documento da creare. Non è necessario impostare name.

mask

DocumentMask

I campi da restituire. Se non viene configurato, restituisce tutti i campi.

Se il documento ha un campo che non è presente in questa maschera, quel campo non verrà restituito nella risposta.

Cursor

Una posizione in un insieme di risultati di query.

Campi
values[]

Value

I valori che rappresentano una posizione, nell'ordine in cui appaiono in ordine per clausola di una query.

Può contenere meno valori di quelli specificati nell'ordine per clausola.

before

bool

Se la posizione è immediatamente precedente o immediatamente successiva ai valori specificati, in base all'ordinamento definito dalla query.

DeleteDocumentRequest

La richiesta di Firestore.DeleteDocument.

Campi
name

string

obbligatorio. Il nome della risorsa del documento da eliminare. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

current_document

Precondition

Una condizione preliminare facoltativa sul documento. La richiesta avrà esito negativo se questa impostazione viene impostata e non viene soddisfatta dal documento di destinazione.

Documento

Un documento Firestore.

Non deve superare 1 MiB-4 byte.

Campi
name

string

Il nome della risorsa del documento, ad esempio projects/{project_id}/databases/{database_id}/documents/{document_path}.

fields

map<string, Value>

create_time

Timestamp

Solo output. L'ora in cui è stato creato il documento.

Questo valore aumenta monotonicamente quando un documento viene eliminato e poi ricreato. Può anche essere confrontato con i valori di altri documenti e con l'read_time di una query.

update_time

Timestamp

Solo output. L'ora dell'ultima modifica del documento.

Questo valore viene inizialmente impostato su create_time e poi aumenta in modo monotonico a ogni modifica al documento. Può anche essere confrontato con i valori di altri documenti e con l'read_time di una query.

DocumentChange

Un Document è cambiato.

Può essere il risultato di più writes, incluse delle eliminazioni, che hanno portato a un nuovo valore per Document.

È possibile restituire più messaggi DocumentChange per la stessa modifica logica, se sono interessati più target.

Campi
document

Document

Il nuovo stato dell'Document.

Se mask è impostato, contiene solo i campi che sono stati aggiornati o aggiunti.

target_ids[]

int32

Un insieme di ID target dei target che corrispondono a questo documento.

removed_target_ids[]

int32

Un insieme di ID target per i target che non corrispondono più a questo documento.

DocumentDelete

È stato eliminato un elemento Document.

Potrebbe essere il risultato di più writes, inclusi aggiornamenti, l'ultimo dei quali ha eliminato Document.

È possibile restituire più messaggi DocumentDelete per la stessa eliminazione logica, se sono interessati più target.

Campi
document

string

Il nome della risorsa Document che è stata eliminata.

removed_target_ids[]

int32

Un insieme di ID target per i target che in precedenza corrispondevano a questa entità.

read_time

Timestamp

Il timestamp di lettura in cui è stata osservata l'eliminazione.

Maggiore o uguale al valore commit_time dell'eliminazione.

DocumentMask

Un insieme di percorsi di campo su un documento. Utilizzato per limitare un'operazione di recupero o aggiornamento su un documento a un sottoinsieme dei suoi campi. È diversa dalle maschere di campo standard, che hanno sempre come ambito un Document e tiene conto della natura dinamica di Value.

Campi
field_paths[]

string

L'elenco dei percorsi di campo nella maschera. Consulta Document.fields per un riferimento alla sintassi dei percorsi dei campi.

DocumentRemove

È stato rimosso un elemento Document dalla visualizzazione dei target.

Inviata se il documento non è più pertinente per un target e non è visibile. Possono essere inviati invece di DocumentDelete o DocumentChange se il server non può inviare il nuovo valore del documento.

È possibile restituire più messaggi DocumentRemove per la stessa scrittura o eliminazione logica, se sono interessati più target.

Campi
document

string

Il nome della risorsa Document che non è più visibile.

removed_target_ids[]

int32

Un insieme di ID target per i target che corrispondono in precedenza a questo documento.

read_time

Timestamp

Il timestamp di lettura in cui è stata osservata la rimozione.

Maggiore o uguale al commit_time della modifica/eliminazione/rimozione.

DocumentTransform

La trasformazione di un documento.

Campi
document

string

Il nome del documento da trasformare.

field_transforms[]

FieldTransform

L'elenco delle trasformazioni da applicare ai campi del documento, in ordine. Questo campo non deve essere vuoto.

FieldTransform

La trasformazione di un campo del documento.

Campi
field_path

string

Il percorso del campo. Consulta Document.fields per il riferimento alla sintassi del percorso del campo.

Campo di unione transform_type. La trasformazione da applicare al campo. transform_type può essere solo uno dei seguenti:
set_to_server_value

ServerValue

Imposta il campo sul valore del server specificato.

increment

Value

Aggiunge il valore specificato al valore attuale del campo.

Deve essere un numero intero o un valore doppio. Se il campo non è un numero intero o un doppio oppure il campo non esiste ancora, la trasformazione lo imposterà sul valore specificato. Se uno dei valori specificati o quelli del campo corrente sono doppi, entrambi verranno interpretati come doppi. L'aritmetica doppia e la rappresentazione di valori doppi seguono la semantica dello standard IEEE 754. In caso di overflow di numero intero positivo/negativo, il campo viene risolto nel numero intero positivo/negativo di magnitudo più grande.

maximum

Value

Consente di impostare il campo al massimo del valore attuale e del valore specificato.

Deve essere un numero intero o un valore doppio. Se il campo non è un numero intero o un doppio oppure il campo non esiste ancora, la trasformazione lo imposterà sul valore specificato. Se viene applicata un'operazione massima in cui il campo e il valore di input sono di tipo misto (ovvero uno è un numero intero e uno è il doppio), il campo assume il tipo dell'operando più grande. Se gli operandi sono equivalenti (ad es. 3 e 3.0), il campo non viene modificato. 0, 0,0 e -0,0 sono tutti zero. Il valore massimo tra un valore memorizzato e uno di input pari a zero è sempre il valore memorizzato. Il massimo di qualsiasi valore numerico x e NaN è NaN.

minimum

Value

Imposta il campo al minimo del suo valore attuale e del valore specificato.

Deve essere un numero intero o un valore doppio. Se il campo non è un numero intero o un doppio oppure il campo non esiste ancora, la trasformazione lo imposterà sul valore di input. Se viene applicata un'operazione minima in cui il campo e il valore di input sono di tipo misto (ovvero uno è un numero intero e uno è un doppio), il campo assume il tipo dell'operando più piccolo. Se gli operandi sono equivalenti (ad es. 3 e 3.0), il campo non viene modificato. 0, 0,0 e -0,0 sono tutti zero. Il valore minimo tra un valore memorizzato e uno di input pari a zero è sempre il valore memorizzato. Il minimo di qualsiasi valore numerico x e NaN è NaN.

append_missing_elements

ArrayValue

Aggiungi gli elementi specificati in ordine se non sono già presenti nel valore del campo corrente. Se il campo non è un array o se il campo non esiste ancora, viene prima impostato sull'array vuoto.

Numeri equivalenti di tipi diversi (ad es. 3L e 3,0) sono considerati uguali quando si controlla se un valore è mancante. NaN è uguale a NaN e null è uguale a null. Se l'input contiene più valori equivalenti, verrà preso in considerazione solo il primo.

Il valore Transform_result corrispondente sarà il valore null.

remove_all_from_array

ArrayValue

Rimuovi tutti gli elementi specificati dall'array nel campo. Se il campo non è un array o se il campo non esiste ancora, viene impostato sull'array vuoto.

I numeri equivalenti dei diversi tipi (ad es. 3L e 3.0) sono considerati uguali quando decidi se un elemento deve essere rimosso. NaN è uguale a NaN e null è uguale a null. Verranno rimossi tutti i valori equivalenti se sono presenti duplicati.

Il valore Transform_result corrispondente sarà il valore null.

ServerValue

Valore calcolato dal server.

Enum
SERVER_VALUE_UNSPECIFIED Non specificato. Questo valore non deve essere utilizzato.
REQUEST_TIME L'ora in cui il server ha elaborato la richiesta, con una precisione di un millisecondo. Se utilizzati in più campi (documenti uguali o diversi) in una transazione, tutti i campi avranno lo stesso timestamp del server.

ExecutionStats

Statistiche di esecuzione della query.

Campi
results_returned

int64

Numero totale di risultati restituiti, inclusi documenti, proiezioni, risultati dell'aggregazione e chiavi.

execution_duration

Duration

Tempo totale per l'esecuzione della query nel backend.

read_operations

int64

Operazioni di lettura fatturabili totali.

debug_stats

Struct

Statistiche di debug relative all'esecuzione della query. Tieni presente che le statistiche di debug sono soggette a variazioni man mano che Firestore si evolve. It could include: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } }

ExistenceFilter

Una sintesi di tutti i documenti che corrispondono a un determinato target.

Campi
target_id

int32

L'ID target a cui si applica il filtro.

count

int32

Il numero totale di documenti che corrispondono a target_id.

Se è diverso dal numero di documenti nel client che corrispondono, il cliente deve determinare manualmente quali documenti non corrispondono più al target.

Il client può utilizzare il filtro unchanged_names Bloom per facilitare questa determinazione, testando TUTTI i nomi dei documenti rispetto al filtro. Se il nome del documento NON è presente nel filtro, significa che il documento non corrisponde più alla destinazione.

unchanged_names

BloomFilter

Un filtro Bloom che, nonostante il nome, contiene le codifiche di byte UTF-8 dei nomi delle risorse di TUTTI i documenti che corrispondono a target_id, nel formato projects/{project_id}/databases/{database_id}/documents/{document_path}.

Questo filtro Bloom può essere omesso a discrezione del server, ad esempio se si ritiene che il client non lo utilizzi o se è troppo costoso da calcolare o trasmettere. I client devono gestire agevolmente l'assenza di questo campo tornando alla logica utilizzata prima che questo campo esistesse, ovvero devono aggiungere nuovamente la destinazione senza un token di ripristino per capire quali documenti nella cache del client non sono sincronizzati.

ExplainMetrics

Spiegare le metriche della query.

Campi
plan_summary

PlanSummary

Informazioni sulla fase di pianificazione della query.

execution_stats

ExecutionStats

Statistiche aggregate relative all'esecuzione della query. Presente solo quando ExplainOptions.analyze è impostato su true.

ExplainOptions

Spiega le opzioni della query.

Campi
analyze

bool

Campo facoltativo. Se eseguire questa query.

Se il valore è false (valore predefinito), la query viene pianificata e vengono restituite solo le metriche delle fasi di pianificazione.

Se il valore è true, la query verrà pianificata ed eseguita, restituendo i risultati completi della query insieme alle metriche della fase di pianificazione ed esecuzione.

GetDocumentRequest

La richiesta di Firestore.GetDocument.

Campi
name

string

obbligatorio. Il nome della risorsa del documento da recuperare. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

mask

DocumentMask

I campi da restituire. Se non viene configurato, restituisce tutti i campi.

Se il documento ha un campo che non è presente in questa maschera, quel campo non verrà restituito nella risposta.

Campo di unione consistency_selector. La modalità di coerenza per questa transazione. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

bytes

Legge il documento in una transazione.

read_time

Timestamp

Legge la versione del documento nel momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

ListCollectionIdsRequest

La richiesta di Firestore.ListCollectionIds.

Campi
parent

string

obbligatorio. Il documento principale. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. Ad esempio: projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

page_size

int32

Il numero massimo di risultati da restituire.

page_token

string

Un token di pagina. Deve essere un valore compreso tra ListCollectionIdsResponse.

Campo di unione consistency_selector. La modalità di coerenza per questa richiesta. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
read_time

Timestamp

Legge i documenti così come erano al momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

ListCollectionIdsResponse

La risposta di Firestore.ListCollectionIds.

Campi
collection_ids[]

string

Gli ID raccolta.

next_page_token

string

Un token di pagina che può essere utilizzato per continuare l'elenco.

ListDocumentsRequest

La richiesta di Firestore.ListDocuments.

Campi
parent

string

obbligatorio. Il nome della risorsa padre. Nel formato: projects/{project_id}/databases/{database_id}/documents o projects/{project_id}/databases/{database_id}/documents/{document_path}.

Ad esempio: projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

collection_id

string

Campo facoltativo. L'ID raccolta, relativo a parent, dell'elenco.

Ad esempio: chatrooms o messages.

Questo campo è facoltativo e, se non viene fornito, Firestore elencherà i documenti di tutte le raccolte che rientrano nell'attributo parent fornito.

page_size

int32

Campo facoltativo. Il numero massimo di documenti da restituire in una singola risposta.

Firestore potrebbe restituire un numero inferiore a questo valore.

page_token

string

Campo facoltativo. Un token di pagina, ricevuto da una precedente risposta ListDocuments.

Specifica questo valore per recuperare la pagina successiva. Durante l'impaginazione, tutti gli altri parametri (ad eccezione di page_size) devono corrispondere ai valori impostati nella richiesta che ha generato il token della pagina.

order_by

string

Campo facoltativo. L'ordine facoltativo dei documenti da restituire.

Ad esempio: priority desc, __name__ desc.

Questo rispecchia il valore ORDER BY utilizzato nelle query di Firestore, ma in una rappresentazione stringa. Se non sono presenti, i documenti vengono ordinati in base a __name__ ASC.

mask

DocumentMask

Campo facoltativo. I campi da restituire. Se non viene configurato, restituisce tutti i campi.

Se un documento ha un campo che non è presente in questa maschera, quel campo non verrà restituito nella risposta.

show_missing

bool

Indica se nell'elenco devono essere presenti documenti mancanti.

Un documento non esiste se non esiste, ma sono presenti documenti secondari nidificati. Se il valore è true, i documenti mancanti verranno restituiti con una chiave, ma non avranno campi, create_time o update_time impostati.

Le richieste con show_missing non possono specificare where o order_by.

Campo di unione consistency_selector. La modalità di coerenza per questa transazione. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

bytes

Esegui la lettura come parte di una transazione già attiva.

read_time

Timestamp

Esegui la lettura all'ora indicata.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

ListDocumentsResponse

La risposta per Firestore.ListDocuments.

Campi
documents[]

Document

I documenti trovati.

next_page_token

string

Un token per recuperare la pagina successiva dei documenti.

Se questo campo viene omesso, non verranno visualizzate altre pagine.

ListenRequest

Una richiesta per Firestore.Listen

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

labels

map<string, string>

Etichette associate a questa modifica della destinazione.

Campo di unione target_change. Il target supportato viene modificato. target_change può essere solo uno dei seguenti:
add_target

Target

Un target da aggiungere a questo stream.

remove_target

int32

L'ID di un target da rimuovere dallo stream.

ListenResponse

La risposta per Firestore.Listen.

Campi
Campo di unione response_type. Le risposte supportate. response_type può essere solo uno dei seguenti:
target_change

TargetChange

Gli obiettivi sono cambiati.

document_change

DocumentChange

Un Document è cambiato.

document_delete

DocumentDelete

È stato eliminato un elemento Document.

document_remove

DocumentRemove

Un elemento Document è stato rimosso da un target (perché non è più pertinente per tale target).

filter

ExistenceFilter

Un filtro da applicare all'insieme di documenti restituiti in precedenza per il target specificato.

Errore restituito quando i documenti potrebbero essere stati rimossi dalla destinazione specificata, ma i documenti esatti sono sconosciuti.

MapValue

Un valore della mappa.

Campi
fields

map<string, Value>

I campi della mappa.

Le chiavi della mappa rappresentano i nomi dei campi. I nomi dei campi corrispondenti all'espressione regolare __.*__ sono riservati. I nomi di campi riservati sono vietati, tranne in alcuni contesti documentati. Le chiavi di mappa, rappresentate come UTF-8, non devono superare i 1500 byte e non possono essere vuote.

PartitionQueryRequest

La richiesta di Firestore.PartitionQuery.

Campi
parent

string

obbligatorio. Il nome della risorsa padre. Nel formato: projects/{project_id}/databases/{database_id}/documents. I nomi delle risorse del documento non sono supportati; è possibile specificare solo i nomi delle risorse di database.

partition_count

int64

Il numero massimo di punti di partizione desiderato. Le partizioni possono essere restituite su più pagine di risultati. Il numero deve essere positivo. Il numero effettivo di partizioni restituite potrebbe essere inferiore.

Ad esempio, questo valore potrebbe essere impostato su uno in meno rispetto al numero di query parallele da eseguire o, durante l'esecuzione di un job di pipeline di dati, su uno in meno rispetto al numero di worker o istanze di calcolo disponibili.

page_token

string

Il valore next_page_token restituito da una chiamata precedente a PartitionQuery che può essere utilizzato per ottenere un ulteriore insieme di risultati. L'ordinamento tra i vari insiemi di risultati non è garantito. Pertanto, l'utilizzo di più insiemi di risultati richiederà l'unione dei diversi insiemi di risultati.

Ad esempio, due chiamate successive che utilizzano un page_token potrebbero restituire:

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

Per ottenere un set di risultati completo ordinato rispetto ai risultati della query fornita a PartitionQuery, gli insiemi di risultati devono essere uniti: cursore A, cursore B, cursore M, cursore Q, cursore U, cursore W

page_size

int32

Il numero massimo di partizioni da restituire in questa chiamata, soggetto a partition_count.

Ad esempio, se partition_count = 10 e page_size = 8, la prima chiamata a PartitionQuery restituirà fino a 8 partizioni e un next_page_token se sono presenti più risultati. Una seconda chiamata a PartitionQuery restituirà fino a 2 partizioni, per completare il totale di 10 specificate in partition_count.

Campo di unione query_type. La query da partizionare. query_type può essere solo uno dei seguenti:
structured_query

StructuredQuery

Una query strutturata. La query deve specificare la raccolta con tutti i discendenti ed essere ordinata in base al nome in ordine crescente. Altri filtri, Ordina per, limiti, offset e cursori di inizio e fine non sono supportati.

Campo di unione consistency_selector. La modalità di coerenza per questa richiesta. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
read_time

Timestamp

Legge i documenti così come erano al momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

PartitionQueryResponse

La risposta per Firestore.PartitionQuery.

Campi
partitions[]

Cursor

Risultati del partizionamento. Ogni partizione è un punto di suddivisione che può essere utilizzato da RunQuery come punto iniziale o finale per i risultati della query. Le richieste RunQuery devono essere effettuate con la stessa query fornita a questa richiesta PartitionQuery. I cursori di partizione verranno ordinati secondo lo stesso ordine dei risultati della query fornita a PartitionQuery.

Ad esempio, se una richiesta PartitionQuery restituisce i cursori di partizione A e B, l'esecuzione delle tre query seguenti restituirà l'intero set di risultati della query originale:

  • query, end_at A
  • query, inizio_da A, fine_at B
  • query, start_at B

Un risultato vuoto potrebbe indicare che la query ha un numero insufficiente di risultati per essere partizionata o che la query non è ancora supportata per il partizionamento.

next_page_token

string

Un token di pagina che può essere utilizzato per richiedere un insieme aggiuntivo di risultati, fino al numero specificato da partition_count nella richiesta PartitionQuery. Se vuoto, non ci sono altri risultati.

PlanSummary

Informazioni sulla fase di pianificazione della query.

Campi
indexes_used[]

Struct

Gli indici selezionati per la query. For example: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

Precondition

Una condizione preliminare per un documento, utilizzata per le operazioni condizionali.

Campi
Campo di unione condition_type. Il tipo di precondizione. condition_type può essere solo uno dei seguenti:
exists

bool

Se impostato su true, il documento di destinazione deve esistere. Se impostato su false, il documento di destinazione non deve esistere.

update_time

Timestamp

Una volta impostato, il documento di destinazione deve esistere ed essere stato aggiornato l'ultima volta a quella data. Il timestamp deve essere allineato in microsecondi.

RollbackRequest

La richiesta di Firestore.Rollback.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}.

transaction

bytes

obbligatorio. La transazione di cui eseguire il rollback.

RunAggregationQueryRequest

La richiesta di Firestore.RunAggregationQuery.

Campi
parent

string

obbligatorio. Il nome della risorsa padre. Nel formato: projects/{project_id}/databases/{database_id}/documents o projects/{project_id}/databases/{database_id}/documents/{document_path}. Ad esempio: projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Campo facoltativo. Spiega le opzioni della query. Se impostato, verranno restituite ulteriori statistiche sulle query. In caso contrario, verranno restituiti solo i risultati della query.

Campo di unione query_type. La query da eseguire. query_type può essere solo uno dei seguenti:
structured_aggregation_query

StructuredAggregationQuery

Una query di aggregazione.

Campo di unione consistency_selector. La modalità di coerenza per la query è impostata in modo predefinito su elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

bytes

Eseguire l'aggregazione in una transazione già attiva.

Il valore qui è l'ID transazione opaco in cui eseguire la query.

new_transaction

TransactionOptions

Avvia una nuova transazione come parte della query. L'impostazione predefinita è di sola lettura.

Il nuovo ID transazione verrà restituito come prima risposta nel flusso.

read_time

Timestamp

Esegue la query al timestamp specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

RunAggregationQueryResponse

La risposta per Firestore.RunAggregationQuery.

Campi
result

AggregationResult

Un singolo risultato dell'aggregazione.

Non presente quando segnali l'avanzamento parziale.

transaction

bytes

La transazione avviata nell'ambito di questa richiesta.

Presente solo nella prima risposta quando la richiesta ha richiesto di avviare una nuova transazione.

read_time

Timestamp

L'ora in cui è stato calcolato il risultato aggregato. Questo valore aumenta sempre in modo monotonico; in questo caso, i valori di AggregationResult precedente nel flusso di risultati sono garantiti che non siano cambiati tra l'elemento read_time e questo.

Se la query non restituisce risultati, verrà inviata una risposta con read_time e nessun result, che rappresenta il momento in cui è stata eseguita la query.

explain_metrics

ExplainMetrics

La query spiega le metriche. È presente solo quando viene fornito il RunAggregationQueryRequest.explain_options e viene inviato solo una volta con l'ultima risposta nello stream.

RunQueryRequest

La richiesta di Firestore.RunQuery.

Campi
parent

string

obbligatorio. Il nome della risorsa padre. Nel formato: projects/{project_id}/databases/{database_id}/documents o projects/{project_id}/databases/{database_id}/documents/{document_path}. Ad esempio: projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Campo facoltativo. Spiega le opzioni della query. Se impostato, verranno restituite ulteriori statistiche sulle query. In caso contrario, verranno restituiti solo i risultati della query.

Campo di unione query_type. La query da eseguire. query_type può essere solo uno dei seguenti:
structured_query

StructuredQuery

Una query strutturata.

Campo di unione consistency_selector. La modalità di coerenza per questa transazione. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

bytes

Eseguire la query all'interno di una transazione già attiva.

Il valore qui è l'ID transazione opaco in cui eseguire la query.

new_transaction

TransactionOptions

Avvia una nuova transazione e legge i documenti. Il valore predefinito è una transazione di sola lettura. Il nuovo ID transazione verrà restituito come prima risposta nel flusso.

read_time

Timestamp

Legge i documenti così come erano al momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

RunQueryResponse

La risposta per Firestore.RunQuery.

Campi
transaction

bytes

La transazione avviata nell'ambito di questa richiesta. Può essere impostato solo nella prima risposta e solo se nella richiesta è stato impostato RunQueryRequest.new_transaction. Se impostato, non verranno impostati altri campi in questa risposta.

document

Document

Risultato della query, non impostato quando segnali l'avanzamento parziale.

read_time

Timestamp

L'ora in cui il documento è stato letto. Questo valore potrebbe aumentare monotonicamente; in questo caso, i documenti precedenti nel flusso di risultati sono garantiti che non siano cambiati tra il relativo read_time e questo.

Se la query non restituisce risultati, verrà inviata una risposta con read_time e nessun document, che rappresenta il momento in cui è stata eseguita la query.

skipped_results

int32

Il numero di risultati che sono stati ignorati a causa di un offset tra l'ultima risposta e la risposta corrente.

explain_metrics

ExplainMetrics

La query spiega le metriche. È presente solo quando viene fornito il RunQueryRequest.explain_options e viene inviato solo una volta con l'ultima risposta nello stream.

Campo di unione continuation_selector. La modalità di continuazione della query. Se presente, indica che l'attuale flusso di risposta alla query è terminato. Può essere impostato con o senza un document presente, ma se impostato non vengono restituiti altri risultati. continuation_selector può essere solo uno dei seguenti:
done

bool

Se presente, Firestore ha completato completamente la richiesta e non verranno restituiti altri documenti.

StructuredAggregationQuery

Query Firestore per eseguire un'aggregazione su un StructuredQuery.

Campi
aggregations[]

Aggregation

Campo facoltativo. Serie di aggregazioni da applicare ai risultati di structured_query.

Richiede:

  • Da un minimo di una a un massimo di cinque aggregazioni per query.
Campo di unione query_type. La query di base da aggregare. query_type può essere solo uno dei seguenti:
structured_query

StructuredQuery

Query strutturata nidificata.

Aggregazione

Definisce un'aggregazione che produce un singolo risultato.

Campi
alias

string

Campo facoltativo. Nome facoltativo del campo in cui archiviare il risultato dell'aggregazione.

Se non viene specificato, Firestore sceglierà un nome predefinito nel formato field_<incremental_id++>. Ad esempio:

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 (
  ...
);

diventa:

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 (
  ...
);

Richiede:

  • Deve essere univoco in tutti gli alias di aggregazione.
  • Rispetta le limitazioni di document field name.
Campo di unione operator. Il tipo di aggregazione da eseguire, obbligatorio. operator può essere solo uno dei seguenti:
count

Count

Conteggio aggregatore.

sum

Sum

Somma aggregatore.

avg

Avg

Aggregatore medio.

Med

Media dei valori del campo richiesto.

  • Verranno aggregati solo valori numerici. Tutti i valori non numerici, incluso NULL, vengono ignorati.

  • Se i valori aggregati contengono NaN, restituisce NaN. I calcoli matematici Infinity seguono gli standard IEEE-754.

  • Se il set di valori aggregati è vuoto, restituisce NULL.

  • Restituisce sempre il risultato come doppio.

Campi
field

FieldReference

Il campo in base al quale aggregare.

Conteggio

Numero di documenti che corrispondono alla query.

La funzione di aggregazione COUNT(*) opera sull'intero documento, quindi non richiede un riferimento di campo.

Campi
up_to

Int64Value

Campo facoltativo. Vincolo facoltativo al numero massimo di documenti da conteggiare.

Ciò fornisce un modo per impostare un limite superiore per il numero di documenti da scansionare, limitando la latenza e il costo.

Un valore non specificato viene interpretato come nessun limite.

Esempio generale:

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

Richiede:

  • Deve essere maggiore di zero se presente.

Somma

Somma dei valori del campo richiesto.

  • Verranno aggregati solo valori numerici. Tutti i valori non numerici, incluso NULL, vengono ignorati.

  • Se i valori aggregati contengono NaN, restituisce NaN. I calcoli matematici Infinity seguono gli standard IEEE-754.

  • Se il set di valori aggregati è vuoto, restituisce 0.

  • Restituisce un numero intero a 64 bit se tutti i numeri aggregati sono numeri interi e il risultato della somma non ha un overflow. In caso contrario, il risultato viene restituito come doppio. Tieni presente che anche se tutti i valori aggregati sono numeri interi, il risultato viene restituito come doppio se non può rientrare in un valore Integer a 64 bit con segno. In questo caso, il valore restituito perderà precisione.

  • Quando si verifica un underflow, l'aggregazione in virgola mobile non è deterministica. Ciò significa che l'esecuzione della stessa query più volte senza modifiche ai valori sottostanti potrebbe produrre risultati leggermente diversi ogni volta. In questi casi, i valori devono essere archiviati come numeri interi anziché in virgola mobile.

Campi
field

FieldReference

Il campo in base al quale aggregare.

StructuredQuery

Una query Firestore.

Le fasi di query vengono eseguite nel seguente ordine: 1. da 2. dove 3. selezionare 4. order_by + start_at + end_at 5. offset 6. limite

Campi
select

Projection

Sottoinsieme facoltativo dei campi da restituire.

Agisce come DocumentMask per i documenti restituiti da una query. Se non impostato, presuppone che il chiamante voglia restituire tutti i campi.

from[]

CollectionSelector

Le raccolte su cui eseguire una query.

where

Filter

Il filtro da applicare.

order_by[]

Order

L'ordine da applicare ai risultati della query.

Firestore consente ai chiamanti di fornire un ordinamento completo, parziale o nessun ordinamento. In tutti i casi, Firestore garantisce un ordinamento stabile tramite le seguenti regole:

  • order_by è obbligatorio per fare riferimento a tutti i campi utilizzati con un filtro di disuguaglianza.
  • Tutti i campi che devono essere in order_by, ma non sono già presenti, vengono aggiunti in ordine lessicografico del nome del campo.
  • Se un ordine su __name__ non è specificato, viene aggiunto per impostazione predefinita.

Ai campi viene aggiunta la stessa direzione di ordinamento dell'ultimo ordine specificato, oppure "ASCENDENTE" se non è stato specificato alcun ordine. Ad esempio:

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

Cursor

Un potenziale prefisso di una posizione nel set di risultati da cui iniziare la query.

L'ordine del set di risultati si basa sulla clausola ORDER BY della query originale.

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

I risultati di questa query sono ordinati per (b ASC, __name__ ASC).

I cursori possono fare riferimento all'ordine completo o a un prefisso della posizione, anche se non possono fare riferimento a più campi rispetto a quelli dell'elemento ORDER BY fornito.

Proseguendo con l'esempio precedente, l'aggiunta dei seguenti cursori di avvio avrà un impatto diverso:

  • START BEFORE (2, /k/123): avvia la query subito prima di a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): avvia la query subito dopo a = 1 AND b > 10.

A differenza di OFFSET, che richiede la scansione dei primi N risultati per saltare, un cursore di avvio consente alla query di iniziare in una posizione logica. Questa posizione non è necessaria per corrispondere a un risultato effettivo, verrà eseguita la scansione in avanti da questa posizione per trovare il documento successivo.

Richiede:

  • Il numero di valori non può essere maggiore del numero di campi specificati nella clausola ORDER BY.
end_at

Cursor

Un potenziale prefisso di una posizione nel set di risultati in cui terminare la query.

È simile a START_AT, ma controlla la posizione finale anziché la posizione iniziale.

Richiede:

  • Il numero di valori non può essere maggiore del numero di campi specificati nella clausola ORDER BY.
offset

int32

Il numero di documenti da saltare prima di restituire il primo risultato.

Questo si applica dopo i vincoli specificati da WHERE, START AT e END AT, ma prima della clausola LIMIT.

Richiede:

  • Il valore deve essere maggiore o uguale a zero, se specificato.
limit

Int32Value

Il numero massimo di risultati da restituire.

Si applica dopo tutti gli altri vincoli.

Richiede:

  • Il valore deve essere maggiore o uguale a zero, se specificato.
find_nearest

FindNearest

Campo facoltativo. Una potenziale ricerca di vicini più vicini.

Si applica dopo tutti gli altri filtri e ordine.

Trova gli incorporamenti vettoriali più vicini al vettore di query specificato.

CollectionSelector

Una selezione di una raccolta, ad esempio messages as m1.

Campi
collection_id

string

L'ID raccolta. Se impostato, vengono selezionate solo le collezioni con questo ID.

all_descendants

bool

Quando il valore è false, vengono selezionate solo le raccolte che sono elementi secondari immediati del valore di parent specificato nella sezione RunQueryRequest contenitore. Se il valore è true, vengono selezionate tutte le raccolte discendenti.

CompositeFilter

Un filtro che unisce più filtri utilizzando l'operatore specificato.

Campi
op

Operator

L'operatore per combinare più filtri.

filters[]

Filter

L'elenco di filtri da combinare.

Richiede:

  • È presente almeno un filtro.

Operatore

Un operatore di filtro composto.

Enum
OPERATOR_UNSPECIFIED Non specificato. Questo valore non deve essere utilizzato.
AND I documenti devono soddisfare tutti i filtri combinati.
OR I documenti devono soddisfare almeno uno dei filtri combinati.

Direzione

Una direzione di ordinamento.

Enum
DIRECTION_UNSPECIFIED Non specificato.
ASCENDING Crescente.
DESCENDING Decrescente.

FieldFilter

Un filtro su un campo specifico.

Campi
field

FieldReference

Il campo in base al quale applicare il filtro.

op

Operator

L'operatore in base al quale applicare il filtro.

value

Value

Il valore con cui eseguire il confronto.

Operatore

Un operatore di filtro di campo.

Enum
OPERATOR_UNSPECIFIED Non specificato. Questo valore non deve essere utilizzato.
LESS_THAN

Il valore field specificato è inferiore al valore value specificato.

Richiede:

  • Quel field al primo posto nel mese di order_by.
LESS_THAN_OR_EQUAL

Il valore field specificato è inferiore o uguale al valore value specificato.

Richiede:

  • Quel field al primo posto nel mese di order_by.
GREATER_THAN

Il valore field specificato è maggiore del valore value specificato.

Richiede:

  • Quel field al primo posto nel mese di order_by.
GREATER_THAN_OR_EQUAL

Il valore field specificato è maggiore o uguale al valore value specificato.

Richiede:

  • Quel field al primo posto nel mese di order_by.
EQUAL Il valore field specificato è uguale al valore value specificato.
NOT_EQUAL

Il valore field specificato non è uguale al valore value specificato.

Richiede:

  • Nessun altro elemento NOT_EQUAL, NOT_IN, IS_NOT_NULL o IS_NOT_NAN.
  • Quel field viene prima nel order_by.
ARRAY_CONTAINS Il valore field specificato è un array che contiene il valore value specificato.
IN

Il valore field specificato è uguale ad almeno un valore nell'array specificato.

Richiede:

  • Questo value è un ArrayValue non vuoto, soggetto a limiti di disgiunzione.
  • Nessun filtro NOT_IN nella stessa query.
ARRAY_CONTAINS_ANY

Il valore field specificato è un array che contiene uno qualsiasi dei valori nell'array indicato.

Richiede:

  • Questo value è un ArrayValue non vuoto, soggetto a limiti di disgiunzione.
  • Nessun altro filtro ARRAY_CONTAINS_ANY all'interno della stessa disgiunzione.
  • Nessun filtro NOT_IN nella stessa query.
NOT_IN

Il valore di field non è nell'array specificato.

Richiede:

  • Questo value è un valore ArrayValue non vuoto con al massimo 10 valori.
  • Nessun altro elemento OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL o IS_NOT_NAN.
  • Quel field viene prima nel order_by.

FieldReference

Un riferimento a un campo in un documento, ad esempio stats.operations.

Campi
field_path

string

Un riferimento a un campo in un documento.

Richiede:

  • DEVE essere una stringa di segmenti delimitata da punti (.), in cui ogni segmento è conforme alle limitazioni di document field name.

Filtro

Un filtro.

Campi
Campo di unione filter_type. Il tipo di filtro. filter_type può essere solo uno dei seguenti:
composite_filter

CompositeFilter

Un filtro composto.

field_filter

FieldFilter

Un filtro su un campo documento.

unary_filter

UnaryFilter

Un filtro che accetta esattamente un argomento.

FindNearest

Configurazione di ricerca dei vicini più vicini.

Campi
vector_field

FieldReference

obbligatorio. Un campo del vettore indicizzato in cui eseguire la ricerca. È possibile restituire solo i documenti che contengono vettori la cui dimensionalità corrisponde a query_vector.

query_vector

Value

obbligatorio. Il vettore di query su cui stiamo effettuando la ricerca. Deve essere un vettore di massimo 2048 dimensioni.

distance_measure

DistanceMeasure

obbligatorio. La misurazione della distanza da utilizzare, obbligatoria.

limit

Int32Value

obbligatorio. Il numero di vicini più prossimi da restituire. Deve essere un numero intero positivo non superiore a 1000.

DistanceMeasure

La misurazione della distanza da utilizzare per il confronto dei vettori.

Enum
DISTANCE_MEASURE_UNSPECIFIED Non deve essere impostato.
EUCLIDEAN Misura la distanza EUCLIDEAN tra i vettori. Per scoprire di più, vedi la sezione euclidea
COSINE Confronta i vettori in base all'angolo tra loro, consentendoti di misurare la somiglianza non basata sulla grandezza dei vettori. Consigliamo di utilizzare DOT_PRODUCT con vettori normalizzati unitari anziché la distanza COSINE, che è matematicamente equivalente con prestazioni migliori. Per scoprire di più, consulta la sezione Cosine Similarity.
DOT_PRODUCT Simile al coseno, ma è influenzato dalla grandezza dei vettori. Per saperne di più, consulta la sezione Prodotto punto.

Ordine

Un ordine in un campo.

Campi
field

FieldReference

Il campo in base al quale ordinare.

direction

Direction

La direzione in base alla quale ordinare. Il valore predefinito è ASCENDING.

Projection

La proiezione dei campi del documento da restituire.

Campi
fields[]

FieldReference

I campi da restituire.

Se è vuoto, vengono restituiti tutti i campi. Per restituire solo il nome del documento, utilizza ['__name__'].

UnaryFilter

Un filtro con un singolo operando.

Campi
op

Operator

L'operatore unario da applicare.

Campo di unione operand_type. L'argomento del filtro. operand_type può essere solo uno dei seguenti:
field

FieldReference

Il campo a cui applicare l'operatore.

Operatore

Un operatore unario.

Enum
OPERATOR_UNSPECIFIED Non specificato. Questo valore non deve essere utilizzato.
IS_NAN Il valore field specificato è uguale a NaN.
IS_NULL Il valore field specificato è uguale a NULL.
IS_NOT_NAN

Il valore field specificato non è uguale a NaN.

Richiede:

  • Nessun altro elemento NOT_EQUAL, NOT_IN, IS_NOT_NULL o IS_NOT_NAN.
  • Quel field viene prima nel order_by.
IS_NOT_NULL

Il valore field specificato non è uguale a NULL.

Richiede:

  • Un singolo elemento NOT_EQUAL, NOT_IN, IS_NOT_NULL o IS_NOT_NAN.
  • Quel field viene prima nel order_by.

Target

La specifica di un insieme di documenti da ascoltare.

Campi
target_id

int32

L'ID target che identifica il target nello stream. Deve essere un numero positivo e diverso da zero.

Se target_id è 0 (o non specificato), il server assegnerà un ID per questo target e lo restituirà in un evento TargetChange::ADD. Una volta aggiunto un target con target_id=0, tutti i target successivi devono avere anche target_id=0. Se una richiesta AddTarget con target_id != 0 viene inviata al server dopo l'aggiunta di una destinazione con target_id=0, il server invia immediatamente una risposta con un evento TargetChange::Remove.

Tieni presente che se il client invia più richieste AddTarget senza un ID, l'ordine degli ID restituiti in TargetChage.target_ids non è definito. Di conseguenza, i client dovrebbero fornire un ID target invece di affidarsi al server per assegnarne uno.

Se target_id è diverso da zero, non deve esistere un target attivo per questo stream con lo stesso ID.

once

bool

Se il target deve essere rimosso quando è attuale e coerente.

expected_count

Int32Value

Il numero di documenti che corrispondono per ultimo alla query al momento del token di ripristino o di lettura.

Questo valore è pertinente solo se viene fornito un resume_type. Questo valore è presente e indica un indicatore maggiore di zero che il client vuole che ExistenceFilter.unchanged_names venga incluso nella risposta.

Campo di unione target_type. Il tipo di target da ascoltare. target_type può essere solo uno dei seguenti:
query

QueryTarget

Un target specificato da una query.

documents

DocumentsTarget

Un target specificato da un insieme di nomi di documenti.

Campo di unione resume_type. Quando iniziare l'ascolto.

Se specificato, verranno restituiti solo i documenti corrispondenti che sono stati aggiornati DOPO resume_token o read_time. In caso contrario, tutti i documenti corrispondenti vengono restituiti prima di qualsiasi modifica successiva. resume_type può essere solo uno dei seguenti:

resume_token

bytes

Un token di ripristino di un TargetChange precedente per un target identico.

L'utilizzo di un token di ripristino con una destinazione diversa non è supportato e potrebbe non riuscire.

read_time

Timestamp

Inizia l'ascolto dopo un intervallo di tempo specifico di read_time.

Al momento il cliente deve conoscere lo stato dei documenti corrispondenti.

DocumentsTarget

Un target specificato da un insieme di nomi di documenti.

Campi
documents[]

string

I nomi dei documenti da recuperare. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}. La richiesta avrà esito negativo se uno qualsiasi del documento non è una risorsa secondaria del database specificato. I nomi duplicati verranno eliminati.

QueryTarget

Un target specificato da una query.

Campi
parent

string

Il nome della risorsa padre. Nel formato: projects/{project_id}/databases/{database_id}/documents o projects/{project_id}/databases/{database_id}/documents/{document_path}. Ad esempio: projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Campo di unione query_type. La query da eseguire. query_type può essere solo uno dei seguenti:
structured_query

StructuredQuery

Una query strutturata.

TargetChange

I target guardati sono cambiati.

Campi
target_change_type

TargetChangeType

Il tipo di modifica che si è verificata.

target_ids[]

int32

Gli ID dei target che sono stati modificati.

Se vuoto, la modifica si applica a tutti i target.

L'ordine degli ID target non è definito.

cause

Status

L'errore che ha generato questa modifica, se applicabile.

resume_token

bytes

Un token che può essere utilizzato per riprendere lo streaming per il valore target_ids specificato o per tutti i target se il campo target_ids è vuoto.

Non impostato a ogni modifica del target.

read_time

Timestamp

Il valore read_time coerente per il valore target_ids specificato (omesso quando gli ID target non sono presenti in uno snapshot coerente).

È garantito che lo stream invii read_time con target_ids vuoto ogni volta che l'intero stream raggiunge un nuovo snapshot coerente. I messaggi ADD, CURRENT e RESET garantiscono (alla fine) un nuovo snapshot coerente, mentre i messaggi NO_CHANGE e REMOVE non lo saranno.

È garantito che read_time aumenterà monotonicamente per un determinato stream.

TargetChangeType

Il tipo di modifica.

Enum
NO_CHANGE Non è stata apportata alcuna modifica. Utilizzato solo per inviare un resume_token aggiornato.
ADD I target sono stati aggiunti.
REMOVE Le destinazioni sono state rimosse.
CURRENT

I target riflettono tutte le modifiche apportate prima dell'aggiunta dei target allo stream.

Verrà inviato dopo o con un valore read_time maggiore o uguale al momento in cui sono stati aggiunti i target.

I listener possono attendere questa modifica se si desidera la semantica read-after-write.

RESET

I target sono stati reimpostati e nelle modifiche successive verrà restituito un nuovo stato iniziale dei target.

Una volta completato lo stato iniziale, verrà restituito CURRENT anche se in precedenza il target era stato indicato come CURRENT.

TransactionOptions

Opzioni per la creazione di una nuova transazione.

Campi
Campo di unione mode. La modalità della transazione. mode può essere solo uno dei seguenti:
read_only

ReadOnly

La transazione può essere utilizzata solo per le operazioni di lettura.

read_write

ReadWrite

La transazione può essere utilizzata per le operazioni di lettura e scrittura.

ReadOnly

Opzioni per una transazione che può essere utilizzata solo per leggere documenti.

Campi
Campo di unione consistency_selector. La modalità di coerenza per questa transazione. Se non viene configurato, il valore predefinito è elevata coerenza. consistency_selector può essere solo uno dei seguenti:
read_time

Timestamp

Legge i documenti nel momento specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

ReadWrite

Opzioni per una transazione che può essere utilizzata per leggere e scrivere documenti.

Firestore non consente alle richieste di autenticazione di terze parti di creare transazioni di lettura e scrittura.

Campi
retry_transaction

bytes

Transazione facoltativa per riprovare.

UpdateDocumentRequest

La richiesta di Firestore.UpdateDocument.

Campi
document

Document

obbligatorio. Documento aggiornato. Crea il documento se non esiste già.

update_mask

DocumentMask

I campi da aggiornare. Nessuno dei percorsi di campo nella maschera può contenere un nome riservato.

Se il documento esiste sul server e contiene campi a cui non viene fatto riferimento nella maschera, questi vengono lasciati invariati. I campi a cui viene fatto riferimento nella maschera, ma non presenti nel documento di input, vengono eliminati dal documento sul server.

mask

DocumentMask

I campi da restituire. Se non viene configurato, restituisce tutti i campi.

Se il documento ha un campo che non è presente in questa maschera, quel campo non verrà restituito nella risposta.

current_document

Precondition

Una condizione preliminare facoltativa sul documento. La richiesta avrà esito negativo se questa impostazione viene impostata e non viene soddisfatta dal documento di destinazione.

Valore

Messaggio che può contenere uno qualsiasi dei tipi di valori supportati.

Campi
Campo di unione value_type. È necessario impostare un valore. value_type può essere solo uno dei seguenti:
null_value

NullValue

Un valore nullo.

boolean_value

bool

Un valore booleano.

integer_value

int64

Un valore intero.

double_value

double

Un valore doppio.

timestamp_value

Timestamp

Un valore di timestamp.

Precisione solo in microsecondi. Una volta archiviata, la precisione aggiuntiva viene arrotondata per difetto.

string_value

string

Un valore stringa.

La stringa, rappresentata come UTF-8, non deve superare 1 MiB-89 byte. Solo i primi 1500 byte della rappresentazione UTF-8 vengono considerati dalle query.

bytes_value

bytes

Un valore di byte.

Non deve superare 1 MiB - 89 byte. Solo i primi 1500 byte vengono considerati dalle query.

reference_value

string

Un riferimento a un documento. Ad esempio: projects/{project_id}/databases/{database_id}/documents/{document_path}.

geo_point_value

LatLng

Un valore punto geografico che rappresenta un punto sulla superficie della Terra.

array_value

ArrayValue

Un valore array.

Non può contenere direttamente un altro valore dell'array, anche se può contenere una mappa contenente un altro array.

map_value

MapValue

Un valore della mappa.

Scrittura

Una scrittura su un documento.

Campi
update_mask

DocumentMask

I campi da aggiornare in questa scrittura.

Questo campo può essere impostato solo quando l'operazione è update. Se la maschera non è impostata per un update ed esiste il documento, i dati esistenti verranno sovrascritti. Se la maschera è impostata e il documento sul server ha campi non coperti dalla maschera, questi rimangono invariati. I campi a cui viene fatto riferimento nella maschera, ma non presenti nel documento di input, vengono eliminati dal documento sul server. I percorsi dei campi in questa maschera non devono contenere un nome di campo riservato.

update_transforms[]

FieldTransform

Le trasformazioni da eseguire dopo l'aggiornamento.

Questo campo può essere impostato solo quando l'operazione è update. Se presente, questa scrittura equivale a eseguire update e transform per lo stesso documento a livello atomico e in ordine.

current_document

Precondition

Una condizione preliminare facoltativa sul documento.

La scrittura avrà esito negativo se questo viene impostato e non viene soddisfatto dal documento di destinazione.

Campo di unione operation. L'operazione da eseguire. operation può essere solo uno dei seguenti:
update

Document

Un documento da scrivere.

delete

string

Il nome di un documento da eliminare. Nel formato: projects/{project_id}/databases/{database_id}/documents/{document_path}.

transform

DocumentTransform

Applica una trasformazione a un documento.

WriteRequest

La richiesta di Firestore.Write.

La prima richiesta crea un flusso o ne ripristina uno esistente da un token.

Quando crea un nuovo stream, il server risponde con una risposta contenente solo un ID e un token, da utilizzare nella richiesta successiva.

Quando riprende un flusso, il server trasmette prima le risposte dopo il token specificato, quindi una risposta contenente solo un token aggiornato, da utilizzare nella richiesta successiva.

Campi
database

string

obbligatorio. Il nome del database. Nel formato: projects/{project_id}/databases/{database_id}. Questo campo è obbligatorio solo nel primo messaggio.

stream_id

string

L'ID del flusso di scrittura da riprendere. Può essere impostato solo nel primo messaggio. Se il campo viene lasciato vuoto, verrà creato un nuovo flusso di scrittura.

writes[]

Write

Le operazioni di scrittura da applicare.

Esegui sempre a livello atomico e in ordine. Deve essere vuoto nella prima richiesta. Questo campo potrebbe essere vuoto nell'ultima richiesta. Questo campo non deve essere vuoto in tutte le altre richieste.

stream_token

bytes

Un token stream precedentemente inviato dal server.

Il client deve impostare questo campo sul token dell'ultimo WriteResponse che ha ricevuto. Questo conferma che il client ha ricevuto risposte fino a questo token. Dopo l'invio di questo token, i token precedenti potrebbero non essere più utilizzati.

Il server potrebbe chiudere il flusso se ci sono troppe risposte non confermate.

Lascia questo campo non impostato quando crei un nuovo stream. Per riprendere uno stream in un momento specifico, imposta questo campo e il campo stream_id.

Lascia questo campo non impostato quando crei un nuovo stream.

labels

map<string, string>

Etichette associate a questa richiesta di scrittura.

WriteResponse

La risposta per Firestore.Write.

Campi
stream_id

string

L'ID dello stream. Impostata solo sul primo messaggio, quando è stato creato un nuovo stream.

stream_token

bytes

Un token che rappresenta la posizione di questa risposta nel flusso. Questa opzione può essere utilizzata da un client per riprendere lo streaming a questo punto.

Questo campo è sempre impostato.

write_results[]

WriteResult

Il risultato dell'applicazione delle scritture.

Questo risultato di scrittura i-th corrisponde alla scrittura i-esima nella richiesta.

commit_time

Timestamp

L'ora in cui si è verificato il commit. Qualsiasi lettura con un valore read_time uguale o maggiore è garantito per vedere gli effetti della scrittura.

WriteResult

Il risultato di una scrittura.

Campi
update_time

Timestamp

L'ora dell'ultimo aggiornamento del documento dopo l'applicazione della scrittura. Non impostato dopo delete.

Se la scrittura non ha effettivamente modificato il documento, si tratta del valore update_time precedente.

transform_results[]

Value

I risultati dell'applicazione di ogni DocumentTransform.FieldTransform, nello stesso ordine.