Modelo de dados do Cloud Firestore

Cloud Firestore é um banco de dados NoSQL orientado a documentos. Ao contrário de um banco de dados SQL, não existem tabelas ou linhas. Em vez disso, você armazena dados em documentos , que são organizados em coleções .

Cada documento contém um conjunto de pares de valores-chave. O Cloud Firestore é otimizado para armazenar grandes coleções de pequenos documentos.

Todos os documentos devem ser armazenados em coleções. Os documentos podem conter subcoleções e objetos aninhados, ambos os quais podem incluir campos primitivos como strings ou objetos complexos como listas.

Coleções e documentos são criados implicitamente no Cloud Firestore. Basta atribuir dados a um documento dentro de uma coleção. Se a coleção ou o documento não existir, o Cloud Firestore o criará.

Documentos

No Cloud Firestore, a unidade de armazenamento é o documento. Um documento é um registro leve que contém campos que são mapeados para valores. Cada documento é identificado por um nome.

Um documento representando um usuário alovelace pode ter esta aparência:

• alovelace

  first : "Ada"
last : "Lovelace"
born : 1815
  

Observação: o Cloud Firestore oferece suporte a vários tipos de dados para valores: booleano, número, string, ponto geográfico, blob binário e carimbo de data/hora. Você também pode usar matrizes ou objetos aninhados, chamados mapas, para estruturar dados em um documento.

Objetos complexos e aninhados em um documento são chamados de mapas. Por exemplo, você poderia estruturar o nome do usuário do exemplo acima com um mapa, assim:

• alovelace

  name :
first : "Ada"
last : "Lovelace"
born : 1815
  

Você pode notar que os documentos se parecem muito com JSON. Na verdade, eles basicamente são. Existem algumas diferenças (por exemplo, os documentos suportam tipos de dados extras e têm tamanho limitado a 1 MB), mas, em geral, você pode tratar os documentos como registros JSON leves.

Coleções

Os documentos vivem em coleções, que são simplesmente recipientes para documentos. Por exemplo, você poderia ter uma coleção users para conter vários usuários, cada um representado por um documento:

• usuários

  • alovelace

    first : "Ada"
last : "Lovelace"
born : 1815
    

  • first : "Alan"
last : "Turing"
born : 1912
    

O Cloud Firestore não tem esquema, então você tem total liberdade sobre quais campos colocar em cada documento e quais tipos de dados armazenar nesses campos. Todos os documentos da mesma coleção podem conter campos diferentes ou armazenar diferentes tipos de dados nesses campos. No entanto, é uma boa ideia usar os mesmos campos e tipos de dados em vários documentos, para que você possa consultar os documentos com mais facilidade.

Uma coleção contém documentos e nada mais. Ele não pode conter diretamente campos brutos com valores e não pode conter outras coleções. (Consulte Dados hierárquicos para obter uma explicação sobre como estruturar dados mais complexos no Cloud Firestore.)

Os nomes dos documentos de uma coleção são exclusivos. Você pode fornecer suas próprias chaves, como IDs de usuário, ou deixar que o Cloud Firestore crie IDs aleatórios para você automaticamente.

Você não precisa “criar” ou “excluir” coleções. Depois de criar o primeiro documento em uma coleção, a coleção existirá. Se você excluir todos os documentos de uma coleção, ela não existirá mais.

Referências

Cada documento no Cloud Firestore é identificado exclusivamente por sua localização no banco de dados. O exemplo anterior mostrou um documento alovelace dentro da coleção users . Para fazer referência a esse local em seu código, você pode criar uma referência a ele.

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { doc } from "firebase/firestore";

const alovelaceDocumentRef = doc(db, 'users', 'alovelace');
doc_reference.js

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

var alovelaceDocumentRef = db.collection('users').doc('alovelace');
test.firestore.js

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

let alovelaceDocumentRef = db.collection("users").document("alovelace")
ViewController.swift

Objetivo-C

Observação: este produto não está disponível em destinos watchOS e App Clip.

FIRDocumentReference *alovelaceDocumentRef =
    [[self.db collectionWithPath:@"users"] documentWithPath:@"alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.collection("users").document("alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.collection("users").document("alovelace");
DocSnippets.java

Dart

final alovelaceDocumentRef = db.collection("users").doc("alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.collection("users").document("alovelace");
References.java

Pitão

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

Python

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

C++

DocumentReference alovelace_document_reference =
    db->Collection("users").Document("alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.collection('users').doc('alovelace');
index.js

Ir

import (
	"cloud.google.com/go/firestore"
)

func createDocReference(client *firestore.Client) {

	alovelaceRef := client.Collection("users").Doc("alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document.go

PHP

PHP

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

$document = $db->collection('samples/php/users')->document('alovelace');
data_reference_document.php

Unidade

DocumentReference documentRef = db.Collection("users").Document("alovelace");

C#

C#

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

DocumentReference documentRef = db.Collection("users").Document("alovelace");
Program.cs

Rubi

document_ref = firestore.col("users").doc("alovelace")
data_model.rb

Uma referência é um objeto leve que apenas aponta para um local no seu banco de dados. Você pode criar uma referência independentemente de existirem dados lá ou não, e a criação de uma referência não executa nenhuma operação de rede.

Você também pode criar referências para coleções :

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { collection } from "firebase/firestore";

const usersCollectionRef = collection(db, 'users');
collection_reference.js

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

var usersCollectionRef = db.collection('users');
test.firestore.js

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

let usersCollectionRef = db.collection("users")
ViewController.swift

Objetivo-C

Observação: este produto não está disponível em destinos watchOS e App Clip.

FIRCollectionReference *usersCollectionRef = [self.db collectionWithPath:@"users"];
ViewController.m

Kotlin+KTX

val usersCollectionRef = db.collection("users")
DocSnippets.kt

Java

CollectionReference usersCollectionRef = db.collection("users");
DocSnippets.java

Dart

final usersCollectionRef = db.collection("users");
firestore.dart

Java

// Reference to the collection "users"
CollectionReference collection = db.collection("users");
References.java

Pitão

users_ref = db.collection("users")
snippets.py

Python

users_ref = db.collection("users")
snippets.py

C++

CollectionReference users_collection_reference = db->Collection("users");
snippets.cpp

Node.js

const usersCollectionRef = db.collection('users');
index.js

Ir

import (
	"cloud.google.com/go/firestore"
)

func createCollectionReference(client *firestore.Client) {
	usersRef := client.Collection("users")

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

PHP

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

$collection = $db->collection('samples/php/users');
data_reference_collection.php

Unidade

CollectionReference collectionRef = db.Collection("users");

C#

C#

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

CollectionReference collectionRef = db.Collection("users");
Program.cs

Rubi

collection_ref = firestore.col "users"
data_model.rb

Nota: As referências de coleção e as referências de documento são dois tipos distintos de referências e permitem executar operações diferentes. Por exemplo, você poderia usar uma referência de coleção para consultar os documentos na coleção e poderia usar uma referência de documento para ler ou escrever um documento individual.

Por conveniência, você também pode criar referências especificando o caminho para um documento ou coleção como uma string, com componentes de caminho separados por uma barra ( / ). Por exemplo, para criar uma referência ao documento alovelace :

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { doc } from "firebase/firestore"; 

const alovelaceDocumentRef = doc(db, 'users/alovelace');
doc_reference_alternative.js

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

var alovelaceDocumentRef = db.doc('users/alovelace');
test.firestore.js

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

let aLovelaceDocumentReference = db.document("users/alovelace")
ViewController.swift

Objetivo-C

Observação: este produto não está disponível em destinos watchOS e App Clip.

FIRDocumentReference *aLovelaceDocumentReference =
    [self.db documentWithPath:@"users/alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.document("users/alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.document("users/alovelace");
DocSnippets.java

Dart

final aLovelaceDocRef = db.doc("users/alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.document("users/alovelace");
References.java

Pitão

a_lovelace_ref = db.document("users/alovelace")
snippets.py

Python

a_lovelace_ref = db.document("users/alovelace")
snippets.py

C++

DocumentReference alovelace_document = db->Document("users/alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.doc('users/alovelace');
index.js

Ir

import (
	"cloud.google.com/go/firestore"
)

func createDocReferenceFromString(client *firestore.Client) {
	// Reference to a document with id "alovelace" in the collection "users"
	alovelaceRef := client.Doc("users/alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document_path.go

PHP

PHP

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

$document = $db->document('users/alovelace');
data_reference_document_path.php

Unidade

DocumentReference documentRef = db.Document("users/alovelace");

C#

C#

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

DocumentReference documentRef = db.Document("users/alovelace");
Program.cs

Rubi

document_path_ref = firestore.doc "users/alovelace"
data_model.rb

Dados Hierárquicos

Para entender como funcionam as estruturas de dados hierárquicas no Cloud Firestore, considere um exemplo de aplicativo de chat com mensagens e salas de chat.

Você pode criar uma coleção chamada rooms para armazenar diferentes salas de chat:

• salas

  • sala

    name : "my chat room"
    

  • sala de

    ...
    

Agora que você tem salas de chat, decida como armazenar suas mensagens. Talvez você não queira armazená-los no documento da sala de chat. Os documentos no Cloud Firestore devem ser leves e uma sala de chat pode conter um grande número de mensagens. No entanto, você pode criar coleções adicionais no documento da sua sala de chat, como subcoleções.

Subcoleções

A melhor maneira de armazenar mensagens nesse cenário é usando subcoleções. Uma subcoleção é uma coleção associada a um documento específico.

Observação: você pode consultar subcoleções com o mesmo ID de coleção usando Collection Group Queries .

Você pode criar uma subcoleção chamada messages para cada documento de sala na sua coleção rooms :

• salas

  • sala

    name : "my chat room"
    

    • mensagens

      • mensagem

        from : "alex"
msg : "Hello World!"
        

      • mensagem

        ...
        

  • sala de

    ...
    

Neste exemplo, você criaria uma referência a uma mensagem na subcoleção com o seguinte código:

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { doc } from "firebase/firestore"; 

const messageRef = doc(db, "rooms", "roomA", "messages", "message1");
subcollection_reference.js

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

var messageRef = db.collection('rooms').doc('roomA')
                .collection('messages').doc('message1');
test.firestore.js

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

let messageRef = db
  .collection("rooms").document("roomA")
  .collection("messages").document("message1")
ViewController.swift

Objetivo-C

Observação: este produto não está disponível em destinos watchOS e App Clip.

FIRDocumentReference *messageRef =
    [[[[self.db collectionWithPath:@"rooms"] documentWithPath:@"roomA"]
    collectionWithPath:@"messages"] documentWithPath:@"message1"];
ViewController.m

Kotlin+KTX

val messageRef = db
    .collection("rooms").document("roomA")
    .collection("messages").document("message1")
DocSnippets.kt

Java

DocumentReference messageRef = db
        .collection("rooms").document("roomA")
        .collection("messages").document("message1");
DocSnippets.java

Dart

final messageRef = db
    .collection("rooms")
    .doc("roomA")
    .collection("messages")
    .doc("message1");
firestore.dart

Java

// Reference to a document in subcollection "messages"
DocumentReference document =
    db.collection("rooms").document("roomA").collection("messages").document("message1");
References.java

Pitão

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

Python

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

C++

DocumentReference message_reference = db->Collection("rooms")
    .Document("roomA")
    .Collection("messages")
    .Document("message1");
snippets.cpp

Node.js

const messageRef = db.collection('rooms').doc('roomA')
  .collection('messages').doc('message1');
index.js

Ir

import (
	"cloud.google.com/go/firestore"
)

func createSubcollectionReference(client *firestore.Client) {
	messageRef := client.Collection("rooms").Doc("roomA").
		Collection("messages").Doc("message1")

	_ = messageRef
}
retrieve_data_reference_subcollection.go

PHP

PHP

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

$document = $db
    ->collection('rooms')
    ->document('roomA')
    ->collection('messages')
    ->document('message1');
data_reference_subcollection.php

Unidade

DocumentReference documentRef = db
	.Collection("Rooms").Document("RoomA")
	.Collection("Messages").Document("Message1");

C#

C#

Para obter mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore .

DocumentReference documentRef = db
    .Collection("Rooms").Document("RoomA")
    .Collection("Messages").Document("Message1");
Program.cs

Rubi

message_ref = firestore.col("rooms").doc("roomA").col("messages").doc("message1")
data_model.rb

Observe o padrão alternado de coleções e documentos. Suas coleções e documentos devem sempre seguir esse padrão. Você não pode fazer referência a uma coleção em uma coleção ou a um documento em um documento.

As subcoleções permitem estruturar os dados hierarquicamente, facilitando o acesso aos dados. Para obter todas as mensagens em roomA , você pode criar uma referência de coleção para as messages da subcoleção e interagir com ela como faria com qualquer outra referência de coleção.

Os documentos em subcoleções também podem conter subcoleções, permitindo aninhar ainda mais os dados. Você pode aninhar dados com até 100 níveis de profundidade.

Aviso: Excluir um documento não exclui suas subcoleções!

Quando você exclui um documento que possui subcoleções, essas subcoleções não são excluídas. Por exemplo, pode haver um documento localizado em coll/doc/subcoll/subdoc mesmo que o documento coll/doc não exista mais. Se desejar excluir documentos em subcoleções ao excluir um documento pai, você deverá fazer isso manualmente, conforme mostrado em Excluir coleções .