Package google.firestore.v1

Index

Firestore

Le service Cloud Firestore

Cloud Firestore est une base de données de documents NoSQL sans serveur, cloud native, entièrement gérée et rapide. Ce service simplifie le stockage, la synchronisation et l'interrogation des données pour les applications Web, mobiles et IoT à l'échelle mondiale. Ses bibliothèques clientes offrent une synchronisation en direct et un fonctionnement hors connexion, tandis que ses fonctionnalités de sécurité et ses intégrations à Firebase et Google Cloud Platform accélèrent le développement d'applications véritablement sans serveur.

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Récupère plusieurs documents.

Il n'est pas garanti que les documents renvoyés par cette méthode s'affichent dans le même ordre que celui demandé.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

BatchWrite

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

Applique un lot d'opérations d'écriture.

La méthode BatchWrite n'applique pas les opérations d'écriture de manière atomique et peut les appliquer dans le désordre. La méthode ne permet pas plusieurs écritures par document. Chaque écriture réussit ou échoue indépendamment. Consultez BatchWriteResponse pour connaître l'état de réussite de chaque écriture.

Si vous avez besoin d'un ensemble d'écritures appliqué de manière atomique, utilisez plutôt Commit.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

BeginTransaction

rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse)

Démarre une nouvelle transaction.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

Commit

rpc Commit(CommitRequest) returns (CommitResponse)

Valide une transaction et met à jour des documents si vous le souhaitez.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

CreateDocument

rpc CreateDocument(CreateDocumentRequest) returns (Document)

Crée un document.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

DeleteDocument

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

Supprime un document.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Récupère un seul document.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

ListCollectionIds

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

Répertorie tous les ID de collection sous un document.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

ListDocuments

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

Répertorie les documents.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

Écouter

rpc Listen(ListenRequest) returns (ListenResponse)

Écoute les modifications. Cette méthode n'est disponible que via gRPC ou WebChannel (pas REST).

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

PartitionQuery

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse)

Partitionne une requête en renvoyant des curseurs de partition pouvant être utilisés pour exécuter la requête en parallèle. Les curseurs de partition renvoyés sont des points de division que RunQuery peut utiliser comme points de départ/d'arrivée pour les résultats de la requête.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

Rollback

rpc Rollback(RollbackRequest) returns (Empty)

Annule une transaction.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse)

Exécute une requête d'agrégation.

Plutôt que de produire des résultats Document comme Firestore.RunQuery, cette API permet d'exécuter une agrégation pour produire une série de résultats AggregationResult côté serveur.

Exemple général:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

RunQuery

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

Exécute une requête.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

UpdateDocument

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

Met à jour ou insère un document.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

Écriture

rpc Write(WriteRequest) returns (WriteResponse)

Diffuse en flux continu des lots de mises à jour et de suppressions de documents, dans l'ordre. Cette méthode n'est disponible que via gRPC ou WebChannel (pas REST).

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

AggregationResult

Résultat d'un seul bucket à partir d'une requête d'agrégation Firestore.

Les clés de aggregate_fields sont les mêmes pour tous les résultats d'une requête d'agrégation, contrairement aux requêtes de document, qui peuvent comporter des champs différents pour chaque résultat.

Champs
aggregate_fields

map<string, Value>

Résultat des fonctions d'agrégation, par exemple: COUNT(*) AS total_docs.

La clé est la alias attribuée à la fonction d'agrégation en entrée. La taille de ce mappage est égale au nombre de fonctions d'agrégation dans la requête.

ArrayValue

Valeur de tableau.

Champs
values[]

Value

Valeurs du tableau.

BatchGetDocumentsRequest

Requête pour Firestore.BatchGetDocuments.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

documents[]

string

Noms des documents à récupérer. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}. La requête échoue si l'un des documents n'est pas une ressource enfant de l'élément database donné. Les noms en double sont supprimés.

mask

DocumentMask

Champs à renvoyer. Si ce champ n'est pas spécifié, tous les champs sont renvoyés.

Si un document comporte un champ qui n'est pas présent dans ce masque, ce champ n'est pas renvoyé dans la réponse.

Champ d'union consistency_selector. Mode de cohérence pour cette transaction. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

bytes

Lit les documents d'une transaction.

new_transaction

TransactionOptions

Démarre une nouvelle transaction et lit les documents. La valeur par défaut est une transaction en lecture seule. Le nouvel ID de transaction est renvoyé en tant que première réponse dans le flux.

read_time

Timestamp

Lit les documents tels qu'ils étaient à l'époque.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

BatchGetDocumentsResponse

Réponse diffusée pour Firestore.BatchGetDocuments.

Champs
transaction

bytes

Transaction démarrée dans le cadre de cette requête. Ne sera défini que dans la première réponse, et uniquement si BatchGetDocumentsRequest.new_transaction a été défini dans la requête.

read_time

Timestamp

Heure à laquelle le document a été lu. Cette valeur peut augmenter de façon linéaire. Dans ce cas, il est garanti que les documents précédents dans le flux de résultats n'ont pas changé entre leur valeur read_time et celui-ci.

Champ d'union result. Un seul résultat. Ce champ peut être vide si le serveur ne fait que renvoyer une transaction. result ne peut être qu'un des éléments suivants :
found

Document

Un document demandé.

missing

string

Nom de document demandé, mais qui n'existe pas. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}.

BatchWriteRequest

Requête pour Firestore.BatchWrite.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

writes[]

Write

Écritures à appliquer.

La méthode n'applique pas les écritures de manière atomique et ne garantit pas l'ordre. Chaque écriture réussit ou échoue indépendamment. Vous ne pouvez pas écrire dans le même document plusieurs fois par requête.

labels

map<string, string>

Étiquettes associées à cette écriture par lot.

BatchWriteResponse

Réponse de Firestore.BatchWrite.

Champs
write_results[]

WriteResult

Résultat de l'application des écritures.

Cette i-ième écriture correspond à l'i-ième écriture de la requête.

status[]

Status

État de l'application des écritures.

Cet état d'écriture i-ième correspond à l'écriture i-ième dans la requête.

BeginTransactionRequest

Requête pour Firestore.BeginTransaction.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

options

TransactionOptions

Options de la transaction. La valeur par défaut est une transaction en lecture-écriture.

BeginTransactionResponse

Réponse pour Firestore.BeginTransaction.

Champs
transaction

bytes

Transaction qui a démarré.

BitSequence

Séquence de bits encodés dans un tableau d'octets.

Chaque octet du tableau d'octets bitmap stocke 8 bits de la séquence. La seule exception est le dernier octet, qui peut stocker 8 bits ou moins. padding définit le nombre de bits du dernier octet à ignorer en tant que "remplissage". Les valeurs de ces bits de "remplissage" ne sont pas spécifiées et doivent être ignorées.

Pour récupérer le premier bit, le bit 0, calculez: (bitmap[0] & 0x01) != 0. Pour récupérer le deuxième bit, le bit 1, calculez: (bitmap[0] & 0x02) != 0. Pour récupérer le troisième bit, le bit 2, calculez: (bitmap[0] & 0x04) != 0. Pour récupérer le quatrième bit, le bit 3, calculez: (bitmap[0] & 0x08) != 0. Pour récupérer le bit n, calculez: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

La "taille" d'une valeur BitSequence (le nombre de bits qu'elle contient) est calculée à l'aide de la formule suivante: (bitmap.length * 8) - padding.

Champs
bitmap

bytes

Octets qui encodent la séquence de bits. Peut avoir une longueur égale à zéro.

padding

int32

Nombre de bits du dernier octet dans bitmap à ignorer en tant que "remplissage". Si la longueur de bitmap est de zéro, cette valeur doit être 0. Sinon, cette valeur doit être comprise entre 0 et 7 inclus.

BloomFilter

Filtre de fleur (https://en.wikipedia.org/wiki/Bloom_filter)).

Le filtre Bloom hache les entrées avec MD5 et traite le hachage de 128 bits résultant comme 2 valeurs de hachage de 64 bits distinctes, interprétées comme des entiers non signés utilisant l’encodage complémentaire de 2.

Ces deux valeurs de hachage, nommées h1 et h2, sont ensuite utilisées pour calculer les valeurs de hachage hash_count à l'aide de la formule, à partir de i=0:

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

Les valeurs obtenues sont ensuite modulo le nombre de bits dans le filtre Bloom pour que les bits du filtre Bloom testent l'entrée donnée.

Champs
bits

BitSequence

Données du filtre de fleur.

hash_count

int32

Nombre de hachages utilisés par l'algorithme.

CommitRequest

Requête pour Firestore.Commit.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

writes[]

Write

Écritures à appliquer.

Toujours exécuté de manière atomique et dans l'ordre.

transaction

bytes

Si cette option est définie, elle applique toutes les écritures de cette transaction et la valide.

CommitResponse

Réponse pour Firestore.Commit.

Champs
write_results[]

WriteResult

Résultat de l'application des écritures.

Cette i-ième écriture correspond à l'i-ième écriture de la requête.

commit_time

Timestamp

Heure à laquelle le commit a été effectué. Toute lecture avec un read_time égal ou supérieur affiche les effets du commit.

CreateDocumentRequest

Requête pour Firestore.CreateDocument.

Champs
parent

string

Obligatoire. Ressource parente. (par exemple, projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}).

collection_id

string

Obligatoire. ID de collection de la liste (par rapport à parent). Exemple : chatrooms.

document_id

string

ID de document attribué par le client à utiliser pour ce document.

Facultatif. S'il n'est pas spécifié, un identifiant sera attribué par le service.

document

Document

Obligatoire. Document à créer. name ne doit pas être défini.

mask

DocumentMask

Champs à renvoyer. Si ce champ n'est pas spécifié, tous les champs sont renvoyés.

Si le document comporte un champ qui n'est pas présent dans ce masque, il ne sera pas renvoyé dans la réponse.

Cursor

Une position dans un ensemble de résultats de requête.

Champs
values[]

Value

Valeurs qui représentent une position, dans l'ordre dans lequel elles apparaissent dans la clause ordre par clause d'une requête.

Peut contenir moins de valeurs que celles spécifiées dans la clause "order by".

before

bool

Si la position est juste avant ou juste après les valeurs données, par rapport à l'ordre de tri défini par la requête.

DeleteDocumentRequest

Requête pour Firestore.DeleteDocument.

Champs
name

string

Obligatoire. Nom de ressource du document à supprimer. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}.

current_document

Precondition

Une condition préalable facultative sur le document. La requête échoue si ce champ est défini et que le document cible n'y répond pas.

Document

Document Firestore.

Ne doit pas dépasser 1 Mio à 4 octets.

Champs
name

string

Nom de ressource du document (par exemple, projects/{project_id}/databases/{database_id}/documents/{document_path}).

fields

map<string, Value>

create_time

Timestamp

Uniquement en sortie. Heure à laquelle le document a été créé.

Cette valeur augmente de façon linéaire lorsqu'un document est supprimé, puis recréé. Il peut également être comparé aux valeurs d'autres documents et aux read_time d'une requête.

update_time

Timestamp

Uniquement en sortie. Heure à laquelle le document a été modifié pour la dernière fois.

Cette valeur est initialement définie sur create_time, puis augmente de façon linéaire à chaque modification du document. Il peut également être comparé aux valeurs d'autres documents et aux read_time d'une requête.

DocumentChange

Document a été modifié.

Peut être le résultat de plusieurs writes, y compris des suppressions, qui ont finalement donné lieu à une nouvelle valeur pour Document.

Plusieurs messages DocumentChange peuvent être renvoyés pour la même modification logique si plusieurs cibles sont affectées.

Champs
document

Document

Nouvel état de Document.

Si mask est défini, ne contient que les champs qui ont été mis à jour ou ajoutés.

target_ids[]

int32

Un ensemble d'ID de cibles correspondant à ce document.

removed_target_ids[]

int32

Un ensemble d'ID de cibles pour les cibles qui ne correspondent plus à ce document.

DocumentDelete

Un(e) Document a été supprimé(e).

Peut être le résultat de plusieurs writes, y compris des mises à jour, dont la dernière a supprimé les Document.

Plusieurs messages DocumentDelete peuvent être renvoyés pour la même suppression logique si plusieurs cibles sont affectées.

Champs
document

string

Nom de la ressource Document qui a été supprimée.

removed_target_ids[]

int32

Un ensemble d'ID cibles pour les cibles qui correspondaient précédemment à cette entité.

read_time

Timestamp

Horodatage de lecture correspondant à la suppression.

Supérieur ou égal à la valeur commit_time de la suppression.

DocumentMask

Ensemble de chemins d'accès de champs dans un document. Permet de limiter une opération "get" ou "update" sur un document à un sous-ensemble de ses champs. Cette méthode est différente des masques de champ standards, car leur champ d'application est toujours limité à un Document et tient compte de la nature dynamique de Value.

Champs
field_paths[]

string

Liste des chemins d'accès des champs dans le masque. Pour obtenir une documentation de référence sur la syntaxe des chemins d'accès à un champ, consultez Document.fields.

DocumentRemove

Un Document a été supprimé de la vue des cibles.

Envoyé si le document n'est plus pertinent pour une cible et n'est pas visible. Peut être envoyé à la place d'une opération DocumentDelete ou DocumentChange si le serveur ne peut pas envoyer la nouvelle valeur du document.

Plusieurs messages DocumentRemove peuvent être renvoyés pour la même écriture ou suppression logique si plusieurs cibles sont affectées.

Champs
document

string

Nom de la ressource Document qui n'est plus visible.

removed_target_ids[]

int32

Un ensemble d'ID cibles pour les cibles qui correspondaient précédemment à ce document.

read_time

Timestamp

Horodatage de lecture correspondant au moment où la suppression a été observée.

Supérieur ou égal à la valeur de commit_time de la modification, de la suppression ou de la suppression.

DocumentTransform

Transformation d'un document.

Champs
document

string

Nom du document à transformer.

field_transforms[]

FieldTransform

Liste des transformations à appliquer aux champs du document, dans l'ordre. Ce champ est obligatoire.

FieldTransform

Transformation d'un champ du document.

Champs
field_path

string

Chemin d'accès du champ. Consultez Document.fields pour obtenir des informations de référence sur la syntaxe des chemins d'accès au champ.

Champ d'union transform_type. Transformation à appliquer sur le champ. transform_type ne peut être qu'un des éléments suivants :
set_to_server_value

ServerValue

Définit le champ sur la valeur de serveur indiquée.

increment

Value

Ajoute la valeur donnée à la valeur actuelle du champ.

Il doit s'agir d'un nombre entier ou d'une valeur double. Si le champ n'est pas un nombre entier ou double, ou si le champ n'existe pas encore, la transformation définira le champ sur la valeur donnée. Si la valeur donnée ou la valeur actuelle du champ sont des doubles, les deux valeurs seront interprétées comme des doubles. La double arithmétique et la représentation des valeurs doubles suivent la sémantique IEEE 754. En cas de dépassement d'entiers positifs/négatifs, le champ est résolu au plus grand nombre entier positif/négatif.

maximum

Value

Définit le champ sur la valeur maximale de sa valeur actuelle et de la valeur donnée.

Il doit s'agir d'un nombre entier ou d'une valeur double. Si le champ n'est pas un nombre entier ou double, ou si le champ n'existe pas encore, la transformation définira le champ sur la valeur donnée. Si une opération maximale est appliquée lorsque le champ et la valeur d'entrée sont de types mixtes (c'est-à-dire que l'un est un entier et l'autre un double), le champ prend le type de l'opérande le plus grand. Si les opérandes sont équivalents (par exemple, 3 et 3.0), le champ ne change pas. 0, 0,0 et -0,0 sont tous nuls. Le maximum d'une valeur stockée nulle et d'une valeur d'entrée égale à zéro correspond toujours à la valeur stockée. Le maximum de toute valeur numérique x et NaN est NaN.

minimum

Value

Définit le champ sur la valeur minimale de sa valeur actuelle et de la valeur donnée.

Il doit s'agir d'un nombre entier ou d'une valeur double. Si le champ n'est pas un nombre entier ni un nombre double, ou si le champ n'existe pas encore, la transformation définira le champ sur la valeur d'entrée. Si une opération minimale est appliquée lorsque le champ et la valeur d'entrée sont de types mixtes (c'est-à-dire, un est un entier et un est un double), le champ prend le type du plus petit opérande. Si les opérandes sont équivalents (par exemple, 3 et 3.0), le champ ne change pas. 0, 0,0 et -0,0 sont tous nuls. La valeur stockée minimale et la valeur d'entrée nulle sont toujours égales à la valeur stockée. Le minimum de toute valeur numérique x et NaN est NaN.

append_missing_elements

ArrayValue

Permet d'ajouter les éléments indiqués dans l'ordre s'ils ne sont pas déjà présents dans la valeur actuelle du champ. Si le champ n'est pas un tableau ou s'il n'existe pas encore, il est d'abord défini sur le tableau vide.

Les nombres équivalents de différents types (par exemple, 3L et 3,0) sont considérés comme égaux lorsque vous vérifiez s'il manque une valeur. NaN est égal à NaN, et Null est égal à Null. Si l'entrée contient plusieurs valeurs équivalentes, seule la première sera prise en compte.

Le résultat transform_result correspondant sera la valeur nulle.

remove_all_from_array

ArrayValue

Supprimez tous les éléments indiqués du tableau du champ. Si le champ n'est pas un tableau ou s'il n'existe pas encore, il est défini sur le tableau vide.

Les nombres équivalents des différents types (par exemple, 3L et 3,0) sont considérés comme égaux au moment de décider si un élément doit être supprimé. NaN est égal à NaN, et Null est égal à Null. Cela supprimera toutes les valeurs équivalentes s'il y a des doublons.

Le résultat transform_result correspondant sera la valeur nulle.

ServerValue

Valeur calculée par le serveur.

Enums
SERVER_VALUE_UNSPECIFIED URL indéterminée. Cette valeur ne doit pas être utilisée.
REQUEST_TIME Heure à laquelle le serveur a traité la requête, avec une précision à la milliseconde. S'ils sont utilisés dans plusieurs champs (mêmes documents ou documents différents) dans une transaction, tous les champs obtiendront le même horodatage de serveur.

ExecutionStats

Statistiques d'exécution de la requête.

Champs
results_returned

int64

Nombre total de résultats renvoyés, y compris les documents, les projections, les résultats d'agrégation et les clés.

execution_duration

Duration

Durée totale d'exécution de la requête dans le backend.

read_operations

int64

Nombre total d'opérations de lecture facturables.

debug_stats

Struct

Déboguer les statistiques de l'exécution de la requête Notez que les statistiques de débogage sont susceptibles de changer à mesure que Firestore évolue. It could include: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } }

ExistenceFilter

Condensé de tous les documents correspondant à une cible donnée.

Champs
target_id

int32

ID de la cible à laquelle s'applique ce filtre.

count

int32

Nombre total de documents correspondant à target_id.

S'il est différent du nombre de documents du client qui correspondent, le client doit déterminer manuellement ceux qui ne correspondent plus à la cible.

Le client peut utiliser le filtre "Bloom" unchanged_names pour faciliter cette identification en testant TOUS les noms de documents par rapport au filtre. Si le nom du document NE figure PAS dans le filtre, cela signifie que le document ne correspond plus à la cible.

unchanged_names

BloomFilter

Filtre de Bloom qui, malgré son nom, contient les encodages d'octets UTF-8 des noms de ressources de TOUS les documents correspondant à target_id, sous la forme projects/{project_id}/databases/{database_id}/documents/{document_path}.

Ce filtre de Bloom peut être omis à la discrétion du serveur, par exemple s'il est considéré que le client ne l'utilisera pas ou s'il est trop coûteux en calcul à calculer ou à transmettre. Les clients doivent gérer correctement l'absence de ce champ en revenant à la logique utilisée avant l'existence de ce champ, c'est-à-dire qu'ils doivent rajouter la cible sans jeton de CV pour déterminer quels documents dans le cache du client sont désynchronisés.

ExplainMetrics

Expliquez les métriques de la requête.

Champs
plan_summary

PlanSummary

Informations sur la phase de planification de la requête.

execution_stats

ExecutionStats

Statistiques agrégées de l'exécution de la requête. Uniquement présente lorsque ExplainOptions.analyze est défini sur "true".

ExplainOptions

Expliquez les options de la requête.

Champs
analyze

bool

Facultatif. Indique si cette requête doit être exécutée.

Si la valeur est "false" (valeur par défaut), la requête est planifiée et ne renvoie que les métriques des étapes de planification.

Si la valeur est "true", la requête est planifiée et exécutée, et elle renvoie les résultats complets de la requête, ainsi que les métriques des étapes de planification et d'exécution.

GetDocumentRequest

Requête pour Firestore.GetDocument.

Champs
name

string

Obligatoire. Nom de ressource du document à récupérer. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}.

mask

DocumentMask

Champs à renvoyer. Si ce champ n'est pas spécifié, tous les champs sont renvoyés.

Si le document comporte un champ qui n'est pas présent dans ce masque, il ne sera pas renvoyé dans la réponse.

Champ d'union consistency_selector. Mode de cohérence pour cette transaction. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

bytes

Lit le document dans une transaction.

read_time

Timestamp

Lit la version du document à l'heure donnée.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

ListCollectionIdsRequest

Requête pour Firestore.ListCollectionIds.

Champs
parent

string

Obligatoire. Document parent. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}. Par exemple : projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

page_size

int32

Nombre maximal de résultats à renvoyer.

page_token

string

Un jeton de page. Doit être une valeur de ListCollectionIdsResponse.

Champ d'union consistency_selector. Mode de cohérence pour cette requête. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
read_time

Timestamp

Lit les documents tels qu'ils étaient à l'époque.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

ListCollectionIdsResponse

Réponse de Firestore.ListCollectionIds.

Champs
collection_ids[]

string

ID des collections.

next_page_token

string

Jeton de page qui peut être utilisé pour poursuivre la liste.

ListDocumentsRequest

Requête pour Firestore.ListDocuments.

Champs
parent

string

Obligatoire. Nom de la ressource parente. Format à respecter: projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}.

(par exemple, projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom).

collection_id

string

Facultatif. ID de collection de la liste (par rapport à parent).

Par exemple, chatrooms ou messages.

Cette option est facultative. Lorsqu'elle n'est pas fournie, Firestore affiche les documents de toutes les collections dans le parent fourni.

page_size

int32

Facultatif. Nombre maximal de documents à renvoyer par réponse.

Firestore peut renvoyer une valeur inférieure à cette valeur.

page_token

string

Facultatif. Jeton de page, provenant d'une réponse ListDocuments précédente.

Fournissez-le pour récupérer la page suivante. Lors de la pagination, tous les autres paramètres (à l'exception de page_size) doivent correspondre aux valeurs définies dans la requête qui a généré le jeton de page.

order_by

string

Facultatif. Ordre facultatif des documents à renvoyer.

Exemple : priority desc, __name__ desc.

Cette valeur reflète la valeur ORDER BY utilisée dans les requêtes Firestore, mais sous la forme d'une représentation sous forme de chaîne. Si ce champ n'est pas renseigné, les documents sont classés en fonction de __name__ ASC.

mask

DocumentMask

Facultatif. Champs à renvoyer. Si ce champ n'est pas spécifié, tous les champs sont renvoyés.

Si un document comporte un champ qui n'est pas présent dans ce masque, ce champ n'est pas renvoyé dans la réponse.

show_missing

bool

Si la liste doit afficher des documents manquants

Un document est manquant s'il n'existe pas, mais des sous-documents sont imbriqués sous celui-ci. Lorsque la valeur est "true", ces documents manquants sont renvoyés avec une clé, mais sans champs, create_time ni update_time définis.

Les requêtes avec show_missing ne peuvent pas spécifier where ni order_by.

Champ d'union consistency_selector. Mode de cohérence pour cette transaction. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

bytes

Effectuez la lecture dans le cadre d'une transaction déjà active.

read_time

Timestamp

Effectuez la lecture au moment indiqué.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

ListDocumentsResponse

Réponse pour Firestore.ListDocuments.

Champs
documents[]

Document

Documents trouvés.

next_page_token

string

Jeton permettant de récupérer la page de documents suivante.

Si ce champ est omis, il n'y a pas d'autres pages.

ListenRequest

Demande de Firestore.Listen

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

labels

map<string, string>

Étiquettes associées à cette modification de cible.

Champ d'union target_change. La cible prise en charge change. target_change ne peut être qu'un des éléments suivants :
add_target

Target

Cible à ajouter à ce flux.

remove_target

int32

ID d'une cible à supprimer de ce flux.

ListenResponse

Réponse pour Firestore.Listen.

Champs
Champ d'union response_type. Réponses acceptées. response_type ne peut être qu'un des éléments suivants :
target_change

TargetChange

Les cibles ont changé.

document_change

DocumentChange

Document a été modifié.

document_delete

DocumentDelete

Un(e) Document a été supprimé(e).

document_remove

DocumentRemove

Un élément Document a été supprimé d'une cible (car il n'est plus pertinent pour cette cible).

filter

ExistenceFilter

Filtre à appliquer à l'ensemble de documents précédemment renvoyés pour la cible donnée.

Est renvoyé lorsque des documents ont peut-être été supprimés de la cible donnée, mais que les documents exacts sont inconnus.

MapValue

Valeur de mappage

Champs
fields

map<string, Value>

Champs de la carte

Les clés de mappage représentent des noms de champs. Les noms de champs correspondant à l'expression régulière __.*__ sont réservés. Les noms de champs réservés sont interdits, sauf dans certains contextes documentés. Les clés de mappage, représentées au format UTF-8, ne doivent pas dépasser 1 500 octets et ne peuvent pas être vides.

PartitionQueryRequest

Requête pour Firestore.PartitionQuery.

Champs
parent

string

Obligatoire. Nom de la ressource parente. Format à respecter: projects/{project_id}/databases/{database_id}/documents. Les noms de ressources de document ne sont pas compatibles. Seuls les noms de ressources de base de données peuvent être spécifiés.

partition_count

int64

Nombre maximal de points de partition souhaité. Les partitions peuvent être renvoyées sur plusieurs pages de résultats. Le nombre doit être positif. Le nombre réel de partitions renvoyées peut être inférieur.

Par exemple, elle peut être définie sur un de moins que le nombre de requêtes parallèles à exécuter, ou, dans le cas de l'exécution d'un job de pipeline de données, sur un de moins que le nombre de nœuds de calcul ou d'instances de calcul disponibles.

page_token

string

Valeur next_page_token renvoyée par un appel précédent à PartitionQuery, qui peut être utilisée pour obtenir un ensemble supplémentaire de résultats. Il n'existe aucune garantie de classement entre les ensembles de résultats. Par conséquent, l'utilisation de plusieurs ensembles de résultats nécessite la fusion des différents ensembles.

Par exemple, deux appels suivants utilisant un jeton page_token peuvent renvoyer:

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

Pour obtenir un ensemble de résultats complet ordonné par rapport aux résultats de la requête fournie à PartitionQuery, vous devez fusionner les ensembles de résultats: curseur A, curseur B, curseur M, curseur Q, curseur U, curseur W

page_size

int32

Nombre maximal de partitions à renvoyer dans cet appel, sous réserve de partition_count.

Par exemple, si partition_count = 10 et page_size = 8, le premier appel à PartitionQuery renvoie jusqu'à 8 partitions et un next_page_token s'il existe d'autres résultats. Un deuxième appel à PartitionQuery renvoie jusqu'à 2 partitions pour effectuer les 10 partitions spécifiées dans partition_count.

Champ d'union query_type. Requête à partitionner. query_type ne peut être qu'un des éléments suivants :
structured_query

StructuredQuery

Une requête structurée La requête doit spécifier une collection avec tous les descendants et être classée par ordre croissant de nom. Les autres filtres, tris, limites, décalages et curseurs de début/fin ne sont pas acceptés.

Champ d'union consistency_selector. Mode de cohérence pour cette requête. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
read_time

Timestamp

Lit les documents tels qu'ils étaient à l'époque.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

PartitionQueryResponse

Réponse pour Firestore.PartitionQuery.

Champs
partitions[]

Cursor

Partitionner les résultats. Chaque partition est un point de division que RunQuery peut utiliser comme point de départ ou d'arrivée pour les résultats de la requête. Les requêtes RunQuery doivent être effectuées avec la même requête fournie à cette requête PartitionQuery. Les curseurs de partition seront classés dans le même ordre que les résultats de la requête fournie à PartitionQuery.

Par exemple, si une requête PartitionQuery renvoie les curseurs de partition A et B, l'exécution des trois requêtes suivantes renvoie l'ensemble de résultats complet de la requête d'origine:

  • requête, fin_à A
  • requête, commencer_à_A, fin_à_B
  • requête, démarrer_à_B

Un résultat vide peut indiquer que la requête a trop peu de résultats pour être partitionnée ou qu'elle n'est pas encore prise en charge pour le partitionnement.

next_page_token

string

Jeton de page pouvant être utilisé pour demander un ensemble de résultats supplémentaire, jusqu'au nombre spécifié par partition_count dans la requête PartitionQuery. Si ce champ est vide, il n'y a plus de résultats.

PlanSummary

Informations sur la phase de planification de la requête.

Champs
indexes_used[]

Struct

Index sélectionnés pour la requête For example: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

Precondition

Condition préalable sur un document, utilisée pour les opérations conditionnelles

Champs
Champ d'union condition_type. Type de condition préalable. condition_type ne peut être qu'un des éléments suivants :
exists

bool

Si ce paramètre est défini sur true, le document cible doit exister. Si ce paramètre est défini sur false, le document cible ne doit pas exister.

update_time

Timestamp

Lorsque ce champ est défini, le document cible doit exister et avoir été mis à jour pour la dernière fois à cette date. Le code temporel doit être aligné en microsecondes.

RollbackRequest

Requête pour Firestore.Rollback.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}.

transaction

bytes

Obligatoire. Transaction à annuler.

RunAggregationQueryRequest

Requête pour Firestore.RunAggregationQuery.

Champs
parent

string

Obligatoire. Nom de la ressource parente. Format à respecter: projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Par exemple: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

explain_options

ExplainOptions

Facultatif. Expliquez les options de la requête. Si cette option est définie, des statistiques de requête supplémentaires sont renvoyées. Si ce n'est pas le cas, seuls les résultats de la requête seront renvoyés.

Champ d'union query_type. Requête à exécuter. query_type ne peut être qu'un des éléments suivants :
structured_aggregation_query

StructuredAggregationQuery

Une requête d'agrégation.

Champ d'union consistency_selector. Par défaut, le mode de cohérence de la requête est une cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

bytes

Exécutez l'agrégation dans une transaction déjà active.

La valeur ici est l'ID de transaction opaque dans lequel exécuter la requête.

new_transaction

TransactionOptions

Démarre une nouvelle transaction dans le cadre de la requête, en lecture seule par défaut.

Le nouvel ID de transaction est renvoyé en tant que première réponse dans le flux.

read_time

Timestamp

Exécute la requête à l'horodatage donné.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

RunAggregationQueryResponse

Réponse pour Firestore.RunAggregationQuery.

Champs
result

AggregationResult

Résultat d'agrégation unique.

Indisponible lorsque vous signalez une progression partielle.

transaction

bytes

Transaction démarrée dans le cadre de cette requête.

Présent uniquement dans la première réponse lorsque la requête a demandé le lancement d'une nouvelle transaction.

read_time

Timestamp

Heure à laquelle le résultat agrégé a été calculé. Ce nombre augmente toujours de manière monotone. Dans ce cas, il est garanti que l'élément AggregationResult précédent dans le flux de résultats n'a pas changé entre leur read_time et celui-ci.

Si la requête ne renvoie aucun résultat, une réponse contenant read_time et aucun result sera envoyée, ce qui représente l'heure à laquelle la requête a été exécutée.

explain_metrics

ExplainMetrics

Métriques d'explication des requêtes. Il n'est présent que lorsque le RunAggregationQueryRequest.explain_options est fourni. Il n'est envoyé qu'une seule fois avec la dernière réponse du flux.

RunQueryRequest

Requête pour Firestore.RunQuery.

Champs
parent

string

Obligatoire. Nom de la ressource parente. Format à respecter: projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Par exemple: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

explain_options

ExplainOptions

Facultatif. Expliquez les options de la requête. Si cette option est définie, des statistiques de requête supplémentaires sont renvoyées. Si ce n'est pas le cas, seuls les résultats de la requête seront renvoyés.

Champ d'union query_type. Requête à exécuter. query_type ne peut être qu'un des éléments suivants :
structured_query

StructuredQuery

Une requête structurée

Champ d'union consistency_selector. Mode de cohérence pour cette transaction. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

bytes

Exécutez la requête dans une transaction déjà active.

La valeur ici est l'ID de transaction opaque dans lequel exécuter la requête.

new_transaction

TransactionOptions

Démarre une nouvelle transaction et lit les documents. La valeur par défaut est une transaction en lecture seule. Le nouvel ID de transaction est renvoyé en tant que première réponse dans le flux.

read_time

Timestamp

Lit les documents tels qu'ils étaient à l'époque.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

RunQueryResponse

Réponse pour Firestore.RunQuery.

Champs
transaction

bytes

Transaction démarrée dans le cadre de cette requête. Ne peut être défini que dans la première réponse, et uniquement si RunQueryRequest.new_transaction a été défini dans la requête. Si cette valeur est définie, aucun autre champ ne sera défini dans cette réponse.

document

Document

Résultat de requête non défini lors de la création de rapports sur une progression partielle.

read_time

Timestamp

Heure à laquelle le document a été lu. L'augmentation peut être monotone. Dans ce cas, il est garanti que les documents précédents dans le flux de résultats n'ont pas changé entre leur read_time et celui-ci.

Si la requête ne renvoie aucun résultat, une réponse contenant read_time et aucun document sera envoyée, ce qui représente l'heure à laquelle la requête a été exécutée.

skipped_results

int32

Nombre de résultats ignorés en raison d'un décalage entre la dernière réponse et la réponse actuelle.

explain_metrics

ExplainMetrics

Métriques d'explication des requêtes. Il n'est présent que lorsque le RunQueryRequest.explain_options est fourni. Il n'est envoyé qu'une seule fois avec la dernière réponse du flux.

Champ d'union continuation_selector. Mode de continuation de la requête. S'il est présent, il indique que le flux de réponse à la requête actuel est terminé. Ce champ peut être défini avec ou sans document, mais lorsqu'il est défini, aucun autre résultat n'est renvoyé. La continuation_selector ne peut être qu'un des éléments suivants :
done

bool

S'il est présent, Firestore a complètement finalisé la requête, et aucun autre document ne sera renvoyé.

StructuredAggregationQuery

Requête Firestore permettant d'exécuter une agrégation sur un StructuredQuery.

Champs
aggregations[]

Aggregation

Facultatif. Série d'agrégations à appliquer aux résultats de structured_query.

Configuration requise:

  • Un minimum d'une et un maximum de cinq agrégations par requête.
Champ d'union query_type. Requête de base sur laquelle effectuer l'agrégation. query_type ne peut être qu'un des éléments suivants :
structured_query

StructuredQuery

Requête structurée imbriquée.

Agrégation

Définit une agrégation qui produit un seul résultat.

Champs
alias

string

Facultatif. Nom facultatif du champ dans lequel stocker le résultat de l'agrégation.

Si ce champ n'est pas fourni, Firestore choisit un nom par défaut au format field_<incremental_id++>. Exemple :

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

devient:

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

Configuration requise:

  • Doit être unique pour tous les alias d'agrégation.
  • Respecter les limites de document field name.
Champ d'union operator. Type d'agrégation à effectuer (obligatoire). operator ne peut être qu'un des éléments suivants :
count

Count

Agrégateur de nombres.

sum

Sum

Agrégateur de somme.

avg

Avg

Agrégateur moyen.

Moy

Moyenne des valeurs du champ demandé.

  • Seules les valeurs numériques seront agrégées. Toutes les valeurs non numériques, y compris NULL, sont ignorées.

  • Si les valeurs agrégées contiennent NaN, renvoie NaN. Les calculs de l'infinité sont conformes aux normes IEEE-754.

  • Si l'ensemble de valeurs agrégées est vide, renvoie NULL.

  • Renvoie toujours le résultat sous la forme d'un double.

Champs
field

FieldReference

Champ à utiliser pour l'agrégation.

Nombre

Nombre de documents correspondant à la requête.

La fonction d'agrégation COUNT(*) opère sur l'ensemble du document. Elle ne nécessite donc pas de référence de champ.

Champs
up_to

Int64Value

Facultatif. Contrainte facultative sur le nombre maximal de documents à compter.

Vous pouvez ainsi limiter le nombre de documents à analyser, et limiter la latence et les coûts.

"Non spécifié" est interprété comme étant sans limite.

Exemple général:

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

Configuration requise:

  • La valeur doit être supérieure à zéro lorsqu'elle est présente.

pondérée

Somme des valeurs du champ demandé.

  • Seules les valeurs numériques seront agrégées. Toutes les valeurs non numériques, y compris NULL, sont ignorées.

  • Si les valeurs agrégées contiennent NaN, renvoie NaN. Les calculs de l'infinité sont conformes aux normes IEEE-754.

  • Si l'ensemble de valeurs agrégées est vide, renvoie 0.

  • Renvoie un entier de 64 bits si tous les nombres agrégés sont des entiers et que la somme ne déborde pas. Sinon, le résultat est renvoyé sous forme de double. Notez que même si toutes les valeurs agrégées sont des entiers, le résultat est renvoyé en tant que double s'il ne peut pas tenir dans un entier signé de 64 bits. Dans ce cas, la valeur renvoyée perd la précision.

  • En cas de dépassement de capacité négatif, l'agrégation à virgule flottante est non déterministe. Cela signifie que l'exécution répétée d'une même requête sans modifier les valeurs sous-jacentes peut produire des résultats légèrement différents à chaque fois. Dans ce cas, les valeurs doivent être stockées sous forme d'entiers et de nombres à virgule flottante.

Champs
field

FieldReference

Champ à utiliser pour l'agrégation.

StructuredQuery

Requête Firestore.

Les étapes de la requête sont exécutées dans l’ordre suivant: 1. à partir de 2. où 3. sélectionnez 4. order_by + start_at + end_at 5. décalage 6. limit

Champs
select

Projection

Sous-ensemble facultatif de champs à renvoyer.

Il agit comme un DocumentMask sur les documents renvoyés par une requête. Si cette règle n'est pas définie, cela suppose que l'appelant souhaite que tous les champs soient renvoyés.

from[]

CollectionSelector

Collections à interroger.

where

Filter

Filtre à appliquer.

order_by[]

Order

Ordre à appliquer aux résultats de la requête.

Firestore permet aux appelants de proposer un tri complet, un ordre partiel ou un ordre nul. Dans tous les cas, Firestore garantit un ordre stable grâce aux règles suivantes:

  • order_by est obligatoire pour référencer tous les champs utilisés avec un filtre d'inégalité.
  • Tous les champs qui doivent figurer dans order_by, mais qui ne sont pas déjà présents sont ajoutés selon l'ordre lexicographique du nom du champ.
  • Si une commande sur __name__ n'est pas spécifiée, elle est ajoutée par défaut.

Les champs sont ajoutés avec le même sens de tri que le dernier ordre spécifié ou "ASCENDING" si aucun ordre n'a été spécifié. Exemple :

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

Cursor

Préfixe potentiel d'une position dans l'ensemble de résultats à laquelle la requête doit commencer.

L'ordre de l'ensemble de résultats est basé sur la clause ORDER BY de la requête d'origine.

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

Les résultats de cette requête sont classés par (b ASC, __name__ ASC).

Les curseurs peuvent faire référence à l'ordre complet ou au préfixe du lieu, bien qu'ils ne puissent pas référencer plus de champs que le ORDER BY fourni.

Pour reprendre l'exemple ci-dessus, l'association des curseurs de début suivants aura un impact variable:

  • START BEFORE (2, /k/123): commencer la requête juste avant a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): lancer la requête juste après a = 1 AND b > 10.

Contrairement à OFFSET, qui nécessite d'analyser les N premiers résultats à ignorer, un curseur de début permet à la requête de commencer à une position logique. Cette position n'est pas obligatoire pour correspondre à un résultat réel. La recherche s'effectue à partir de cette position pour trouver le document suivant.

Configuration requise:

  • Le nombre de valeurs ne peut pas être supérieur au nombre de champs spécifié dans la clause ORDER BY.
end_at

Cursor

Préfixe potentiel d'une position dans l'ensemble de résultats à laquelle terminer la requête.

Cette méthode est semblable à START_AT, mais elle contrôle la position de fin plutôt que la position de départ.

Configuration requise:

  • Le nombre de valeurs ne peut pas être supérieur au nombre de champs spécifié dans la clause ORDER BY.
offset

int32

Nombre de documents à ignorer avant de renvoyer le premier résultat.

Cela s'applique après les contraintes spécifiées par WHERE, START AT et END AT, mais avant la clause LIMIT.

Configuration requise:

  • Si elle est spécifiée, la valeur doit être supérieure ou égale à zéro.
limit

Int32Value

Nombre maximal de résultats à renvoyer.

S'applique après toutes les autres contraintes.

Configuration requise:

  • Si elle est spécifiée, la valeur doit être supérieure ou égale à zéro.
find_nearest

FindNearest

Facultatif. Une recherche de voisins les plus proches potentiels.

S'applique après tous les autres filtres et tris.

Recherche les représentations vectorielles continues les plus proches du vecteur de requête donné.

CollectionSelector

Sélection d'une collection, par exemple messages as m1.

Champs
collection_id

string

ID de collection. Lorsque cet ID est défini, cette option permet de ne sélectionner que les collections associées à cet ID.

all_descendants

bool

Si la valeur est "false", sélectionne uniquement les collections qui sont des enfants immédiats de l'élément parent spécifié dans le conteneur RunQueryRequest. Lorsque la valeur est "true", sélectionne toutes les collections descendantes.

CompositeFilter

Filtre qui fusionne plusieurs autres filtres à l'aide de l'opérateur donné.

Champs
op

Operator

Opérateur permettant de combiner plusieurs filtres.

filters[]

Filter

Liste des filtres à combiner.

Configuration requise:

  • Au moins un filtre est présent.

Opérateur

Opérateur de filtre composite.

Enums
OPERATOR_UNSPECIFIED URL indéterminée. Cette valeur ne doit pas être utilisée.
AND Ils sont obligatoires pour tous les filtres combinés.
OR Les documents doivent correspondre à au moins l'un des filtres combinés.

Sens

Ordre de tri.

Enums
DIRECTION_UNSPECIFIED URL indéterminée.
ASCENDING Croissant.
DESCENDING Décroissant.

FieldFilter

Filtre appliqué à un champ spécifique.

Champs
field

FieldReference

Champ selon lequel filtrer.

op

Operator

Opérateur utilisé pour le filtrage.

value

Value

Valeur à laquelle comparer.

Opérateur

Opérateur de filtrage de champ.

Enums
OPERATOR_UNSPECIFIED URL indéterminée. Cette valeur ne doit pas être utilisée.
LESS_THAN

La valeur field donnée est inférieure à la valeur value indiquée.

Configuration requise:

  • Ces field sont arrivés en premier dans order_by.
LESS_THAN_OR_EQUAL

La valeur field indiquée est inférieure ou égale à la valeur value donnée.

Configuration requise:

  • Ces field sont arrivés en premier dans order_by.
GREATER_THAN

La valeur field donnée est supérieure à la valeur value donnée.

Configuration requise:

  • Ces field sont arrivés en premier dans order_by.
GREATER_THAN_OR_EQUAL

La valeur field indiquée est supérieure ou égale à la valeur value donnée.

Configuration requise:

  • Ces field sont arrivés en premier dans order_by.
EQUAL La valeur field donnée est égale à la valeur value indiquée.
NOT_EQUAL

La valeur field indiquée n'est pas égale à la valeur value indiquée.

Configuration requise:

  • Pas d'autre NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Cette field apparaît en premier dans order_by.
ARRAY_CONTAINS L'élément field indiqué est un tableau contenant l'élément value indiqué.
IN

Le field donné est égal à au moins une valeur dans le tableau donné.

Configuration requise:

  • Ce value est un ArrayValue non vide, soumis aux limites de disjonction.
  • Aucun filtre NOT_IN dans la même requête.
ARRAY_CONTAINS_ANY

La valeur field indiquée est un tableau contenant l'une des valeurs de ce tableau.

Configuration requise:

  • Ce value est un ArrayValue non vide, soumis aux limites de disjonction.
  • Aucun autre filtre ARRAY_CONTAINS_ANY dans la même disjonction.
  • Aucun filtre NOT_IN dans la même requête.
NOT_IN

La valeur de field ne figure pas dans le tableau donné.

Configuration requise:

  • Cet élément value est un ArrayValue non vide comportant au maximum 10 valeurs.
  • Pas d'autre OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL ni IS_NOT_NAN.
  • Cette field apparaît en premier dans order_by.

FieldReference

Référence à un champ dans un document (par exemple, stats.operations).

Champs
field_path

string

Référence à un champ d'un document.

Configuration requise:

  • DOIT être une chaîne de segments délimités par un point (.), où chaque segment est conforme aux limites document field name.

Filtre

Un filtre.

Champs
Champ d'union filter_type. Type de filtre. filter_type ne peut être qu'un des éléments suivants :
composite_filter

CompositeFilter

Filtre composite :

field_filter

FieldFilter

Filtre appliqué à un champ de document.

unary_filter

UnaryFilter

Un filtre qui accepte exactement un argument.

FindNearest

Configuration de la recherche des voisins les plus proches.

Champs
vector_field

FieldReference

Obligatoire. Champ de vecteur indexé à rechercher. Seuls les documents contenant des vecteurs dont la dimensionnalité correspond à query_vector peuvent être renvoyés.

query_vector

Value

Obligatoire. Vecteur de requête que nous recherchons. La valeur doit être un vecteur de 2 048 dimensions au maximum.

distance_measure

DistanceMeasure

Obligatoire. Mesure de distance à utiliser (obligatoire).

limit

Int32Value

Obligatoire. Nombre de voisins les plus proches à renvoyer. La valeur doit être un entier positif inférieur ou égal à 1 000.

DistanceMeasure

Mesure de distance à utiliser pour comparer des vecteurs.

Enums
DISTANCE_MEASURE_UNSPECIFIED Ne doit pas être défini.
EUCLIDEAN Mesure la distance EUCLIDEAN entre les vecteurs. Pour en savoir plus, consultez la page Euclidienne
COSINE Compare des vecteurs en fonction de l'angle qui les sépare, ce qui vous permet de mesurer la similarité qui n'est pas basée sur l'ampleur des vecteurs. Nous vous recommandons d'utiliser DOT_PRODUCT avec des vecteurs normalisés unitaires plutôt que la distance COSINE, qui est mathématiquement équivalente avec de meilleures performances. Pour en savoir plus, consultez la page Similarité cosinus.
DOT_PRODUCT Semblable au cosinus, mais il est affecté par l'amplitude des vecteurs. Pour en savoir plus, consultez la page Dot Product.

Commande

Commande sur un champ.

Champs
field

FieldReference

Champ selon lequel trier.

direction

Direction

Sens de tri. La valeur par défaut est ASCENDING.

Projection

Projection des champs du document à renvoyer.

Champs
fields[]

FieldReference

Champs à renvoyer.

Si ce champ est vide, tous les champs sont renvoyés. Pour ne renvoyer que le nom du document, utilisez ['__name__'].

UnaryFilter

Filtre avec un seul opérande.

Champs
op

Operator

Opérateur unaire à appliquer.

Champ d'union operand_type. Argument du filtre. operand_type ne peut être qu'un des éléments suivants :
field

FieldReference

Champ auquel appliquer l'opérateur.

Opérateur

Opérateur unaire.

Enums
OPERATOR_UNSPECIFIED URL indéterminée. Cette valeur ne doit pas être utilisée.
IS_NAN La valeur field donnée est égale à NaN.
IS_NULL La valeur field donnée est égale à NULL.
IS_NOT_NAN

La valeur field indiquée n'est pas égale à NaN.

Configuration requise:

  • Pas d'autre NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Cette field apparaît en premier dans order_by.
IS_NOT_NULL

La valeur field indiquée n'est pas égale à NULL.

Configuration requise:

  • Un seul élément NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Cette field apparaît en premier dans order_by.

Cible

Spécification d'un ensemble de documents à écouter.

Champs
target_id

int32

ID de la cible dans le flux. La valeur doit être un nombre positif et non nul.

Si target_id est défini sur 0 (ou n'est pas spécifié), le serveur attribue un ID à cette cible et le renvoie dans un événement TargetChange::ADD. Une fois qu'une cible avec target_id=0 est ajoutée, toutes les cibles suivantes doivent également être associées à target_id=0. Si une requête AddTarget avec target_id != 0 est envoyée au serveur après l'ajout d'une cible avec target_id=0, le serveur envoie immédiatement une réponse avec un événement TargetChange::Remove.

Notez que si le client envoie plusieurs requêtes AddTarget sans ID, l'ordre des ID renvoyés dans TargetChage.target_ids n'est pas défini. Par conséquent, les clients doivent fournir un ID cible au lieu de compter sur le serveur pour en attribuer un.

Si la valeur de target_id est non nulle, aucune cible active existante ne doit exister sur ce flux avec le même ID.

once

bool

Si la cible doit être supprimée une fois qu'elle est à jour et cohérente.

expected_count

Int32Value

Nombre de documents correspondant à la dernière requête au moment du jeton de CV ou de la lecture.

Cette valeur n'est pertinente que si resume_type est fourni. Cette valeur étant présente et supérieure à zéro, le client souhaite que ExistenceFilter.unchanged_names soit inclus dans la réponse.

Champ d'union target_type. Type de cible à écouter. target_type ne peut être qu'un des éléments suivants :
query

QueryTarget

Cible spécifiée par une requête.

documents

DocumentsTarget

Cible spécifiée par un ensemble de noms de documents.

Champ d'union resume_type. Quand commencer à écouter

Si vous spécifiez une valeur, seuls les documents correspondants qui ont été mis à jour APRÈS le resume_token ou l'read_time sont renvoyés. Sinon, tous les documents correspondants sont renvoyés avant toute modification ultérieure. La resume_type ne peut être qu'un des éléments suivants :

resume_token

bytes

Jeton de reprise d'une TargetChange précédente pour une cible identique.

L'utilisation d'un jeton de reprise avec une autre cible n'est pas acceptée et peut échouer.

read_time

Timestamp

Commencer l'écoute après un read_time spécifique.

Pour le moment, le client doit connaître l'état des documents correspondants.

DocumentsTarget

Cible spécifiée par un ensemble de noms de documents.

Champs
documents[]

string

Noms des documents à récupérer. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}. La requête échoue si l'un des documents n'est pas une ressource enfant de l'élément database donné. Les noms en double sont supprimés.

QueryTarget

Cible spécifiée par une requête.

Champs
parent

string

Nom de la ressource parente. Format à respecter: projects/{project_id}/databases/{database_id}/documents ou projects/{project_id}/databases/{database_id}/documents/{document_path}. Par exemple: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

Champ d'union query_type. Requête à exécuter. query_type ne peut être qu'un des éléments suivants :
structured_query

StructuredQuery

Une requête structurée

TargetChange

Les cibles surveillées ont changé.

Champs
target_change_type

TargetChangeType

Type de modification apportée.

target_ids[]

int32

ID des cibles modifiées.

Si ce champ est vide, la modification s'applique à toutes les cibles.

L'ordre des ID cibles n'est pas défini.

cause

Status

Erreur à l'origine de cette modification, le cas échéant.

resume_token

bytes

Jeton pouvant être utilisé pour reprendre le flux pour le target_ids donné ou pour toutes les cibles si target_ids est vide.

Pas défini à chaque modification des cibles.

read_time

Timestamp

read_time cohérent pour le target_ids donné (omis lorsque les target_id ne correspondent pas à un instantané cohérent).

Le flux envoie forcément une read_time avec target_ids vide chaque fois que le flux entier atteint un nouvel instantané cohérent. Les messages ADD, CURRENT et RESET génèrent (à terme) un nouvel instantané cohérent (contrairement aux messages NO_CHANGE et REMOVE).

Pour un flux donné, l'augmentation de read_time est garantie de façon monotone.

TargetChangeType

Type de modification

Enums
NO_CHANGE Aucune modification n'a été apportée. Utilisé uniquement pour envoyer un resume_token mis à jour.
ADD Les cibles ont été ajoutées.
REMOVE Les cibles ont été supprimées.
CURRENT

Les cibles reflètent toutes les modifications validées avant leur ajout au flux.

Elle sera envoyée après ou avec une valeur read_time supérieure ou égale à l'heure à laquelle les cibles ont été ajoutées.

Les écouteurs peuvent attendre cette modification si une sémantique de lecture après écriture est souhaitée.

RESET

Les cibles ont été réinitialisées, et un nouvel état initial leur sera renvoyé lors des modifications ultérieures.

Une fois l'état initial terminé, CURRENT est renvoyé, même si la cible était précédemment définie comme CURRENT.

TransactionOptions

Options de création d'une transaction

Champs
Champ d'union mode. Mode de la transaction. mode ne peut être qu'un des éléments suivants :
read_only

ReadOnly

La transaction ne peut être utilisée que pour des opérations de lecture.

read_write

ReadWrite

La transaction peut être utilisée pour les opérations de lecture et d'écriture.

ReadOnly

Options pour une transaction qui ne peut être utilisée que pour lire des documents.

Champs
Champ d'union consistency_selector. Mode de cohérence pour cette transaction. Si ce champ n'est pas spécifié, la valeur par défaut est la cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
read_time

Timestamp

Lit les documents à l'heure indiquée.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

ReadWrite

Options pour une transaction permettant de lire et d'écrire des documents.

Firestore n'autorise pas les requêtes d'authentification tierces à créer des transactions en lecture-écriture.

Champs
retry_transaction

bytes

Transaction facultative à réessayer.

UpdateDocumentRequest

Requête pour Firestore.UpdateDocument.

Champs
document

Document

Obligatoire. Document mis à jour. Crée le document s'il n'existe pas déjà.

update_mask

DocumentMask

Champs à mettre à jour. Aucun des chemins d'accès des champs du masque ne peut contenir de nom réservé.

Si le document existe sur le serveur et qu'il comporte des champs non référencés dans le masque, ils ne sont pas modifiés. Les champs référencés dans le masque, mais non présents dans le document d'entrée, sont supprimés du document sur le serveur.

mask

DocumentMask

Champs à renvoyer. Si ce champ n'est pas spécifié, tous les champs sont renvoyés.

Si le document comporte un champ qui n'est pas présent dans ce masque, il ne sera pas renvoyé dans la réponse.

current_document

Precondition

Une condition préalable facultative sur le document. La requête échoue si ce champ est défini et que le document cible n'y répond pas.

Valeur

Message pouvant contenir n'importe quel type de valeur accepté.

Champs
Champ d'union value_type. Vous devez définir une valeur. value_type ne peut être qu'un des éléments suivants :
null_value

NullValue

Une valeur nulle.

boolean_value

bool

Une valeur booléenne.

integer_value

int64

Valeur entière.

double_value

double

Une valeur double.

timestamp_value

Timestamp

Une valeur d'horodatage.

Précision à la microseconde seulement. En cas de stockage, toute précision supplémentaire est arrondie au chiffre inférieur.

string_value

string

Valeur de chaîne.

La chaîne, représentée au format UTF-8, ne doit pas dépasser 1 Mio et 89 octets. Seuls les 1 500 premiers octets de la représentation UTF-8 sont pris en compte par les requêtes.

bytes_value

bytes

Valeur en octets.

Ne doit pas dépasser entre 1 Mio et 89 octets. Seuls les 1 500 premiers octets sont pris en compte par les requêtes.

reference_value

string

Référence à un document. Exemple : projects/{project_id}/databases/{database_id}/documents/{document_path}.

geo_point_value

LatLng

Valeur de point géographique représentant un point de la surface de la Terre.

array_value

ArrayValue

Valeur de tableau.

Ne peut pas contenir directement une autre valeur de tableau, mais peut contenir un mappage qui contient un autre tableau.

map_value

MapValue

Valeur de mappage

Écriture

Écriture sur un document.

Champs
update_mask

DocumentMask

Champs à mettre à jour dans cette écriture.

Ce champ ne peut être défini que lorsque l'opération est update. Si le masque n'est pas défini pour un update et que le document existe, toutes les données existantes seront écrasées. Si le masque est défini et que le document sur le serveur comporte des champs qui ne sont pas masqués, ceux-ci ne sont pas modifiés. Les champs référencés dans le masque, mais non présents dans le document d'entrée, sont supprimés du document sur le serveur. Les chemins d'accès aux champs de ce masque ne doivent pas contenir de nom de champ réservé.

update_transforms[]

FieldTransform

Transformations à effectuer après la mise à jour.

Ce champ ne peut être défini que lorsque l'opération est update. Si cette écriture est présente, cela équivaut à exécuter update et transform sur le même document de manière atomique et dans l'ordre.

current_document

Precondition

Une condition préalable facultative sur le document.

L'écriture échoue si elle est définie et si le document cible n'atteint pas cette condition.

Champ d'union operation. Opération à exécuter. operation ne peut être qu'un des éléments suivants :
update

Document

Un document à écrire.

delete

string

Nom de document à supprimer. Format à respecter: projects/{project_id}/databases/{database_id}/documents/{document_path}.

transform

DocumentTransform

Applique une transformation à un document.

WriteRequest

Requête pour Firestore.Write.

La première requête crée un flux ou reprend un flux existant à partir d'un jeton.

Lors de la création d'un nouveau flux, le serveur répond avec une réponse ne contenant qu'un ID et un jeton, à utiliser dans la requête suivante.

Lors de la reprise d'un flux, le serveur diffuse d'abord les réponses après le jeton donné, puis une réponse ne contenant qu'un jeton à jour, à utiliser dans la requête suivante.

Champs
database

string

Obligatoire. Nom de la base de données. Format à respecter: projects/{project_id}/databases/{database_id}. Cette étape n'est obligatoire que dans le premier message.

stream_id

string

ID du flux d'écriture à reprendre. Vous ne pouvez définir cette option que dans le premier message. Si vous ne renseignez pas ce champ, un flux d'écriture est créé.

writes[]

Write

Écritures à appliquer.

Toujours exécuté de manière atomique et dans l'ordre. Ce champ doit être vide dans la première requête. Peut être vide dans la dernière requête. Ce champ ne doit pas être vide pour toutes les autres requêtes.

stream_token

bytes

Un jeton de flux précédemment envoyé par le serveur.

Le client doit définir ce champ sur le jeton du dernier WriteResponse qu'il a reçu. Cela confirme que le client a reçu des réponses jusqu'à ce jeton. Une fois ce jeton envoyé, les jetons plus anciens ne seront peut-être plus utilisés.

Le serveur peut fermer le flux si le nombre de réponses non confirmées est trop élevé.

Laissez ce champ non défini lorsque vous créez un flux. Pour reprendre un flux à un point spécifique, définissez ce champ ainsi que le champ stream_id.

Laissez ce champ non défini lorsque vous créez un flux.

labels

map<string, string>

Étiquettes associés à cette requête d'écriture.

WriteResponse

Réponse pour Firestore.Write.

Champs
stream_id

string

ID du flux. Défini uniquement pour le premier message, lorsqu'un flux a été créé.

stream_token

bytes

Jeton qui représente la position de cette réponse dans le flux. Un client peut l'utiliser pour reprendre le flux à ce stade.

Ce champ est toujours défini.

write_results[]

WriteResult

Résultat de l'application des écritures.

Cette i-ième écriture correspond à l'i-ième écriture de la requête.

commit_time

Timestamp

Heure à laquelle le commit a été effectué. Toute lecture avec un read_time égal ou supérieur voit les effets de l'écriture.

WriteResult

Résultat de l'application d'une écriture.

Champs
update_time

Timestamp

Heure de la dernière mise à jour du document après l'application de l'écriture. Non défini après delete.

Si l'écriture n'a pas réellement modifié le document, il s'agit de la valeur update_time précédente.

transform_results[]

Value

Résultats de l'application de chaque DocumentTransform.FieldTransform, dans le même ordre.