Modelo de dados

Modelo de dados

O Firestore é um banco de dados NoSQL orientado a documentos. Ao contrário de um banco de dados SQL, não há tabelas nem linhas. Em vez disso, os dados são armazenados em documentos, que são organizados em coleções.

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

É necessário que todos os documentos sejam armazenados em coleções. Os documentos podem conter subcoleções e objetos aninhados, que podem incluir campos primitivos, como strings, ou objetos complexos, como listas.

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

Documentos

No 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 que representa um usuário alovelace pode ser assim:

• alovelace

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

Observação: o Firestore é compatível com vários tipos de dados de valores: booleano, número, string, ponto geográfico, blob binário e carimbo de data/hora. Use arrays 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, é possível estruturar o nome do usuário do exemplo acima com um mapa, como este:

• alovelace

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

Observe que os documentos parecem muito com documentos JSON. Na verdade, basicamente eles são. Há algumas diferenças, por exemplo, os documentos são compatíveis com tipos de dados extras e têm o tamanho limitado a 1 MB, no entanto, geralmente eles podem ser tratados como registros JSON leves.

Coleções

Os documentos pertencem a coleções, que são simplesmente recipientes para documentos. Por exemplo, é possível ter uma coleção users para conter seus vários usuários, cada um representado por um documento:

• users

  • alovelace

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

  • aturing

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

O Firestore não usa esquemas. Portanto, você tem total liberdade sobre quais os campos colocar em cada documento e que tipos de dados armazenar nesses campos. Os documentos dentro da mesma coleção podem conter diferentes campos ou armazenar diferentes tipos de dados nesses campos. No entanto, é recomendável usar os mesmos campos e tipos de dados em vários documentos para que seja possível consultar os documentos com mais facilidade.

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

Os nomes dos documentos dentro de uma coleção são únicos. Forneça suas próprias chaves, como IDs de usuário, ou permita que o Firestore crie automaticamente IDs aleatórios para você.

Não é preciso "criar" ou "excluir" coleções. Depois de criar o primeiro documento em uma coleção, ela passa a existir. Se você excluir todos os documentos em uma coleção, ela deixará de existir.

Referências

Cada documento no Firestore é identificado de maneira exclusiva pela respectiva localização no banco de dados. O exemplo anterior mostrou um documento alovelace na coleção users. Para se referir a este local no seu código, crie uma referência a ele.

Versão 9 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

import { doc } from "firebase/firestore";

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

Versão 8 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

Swift

Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.

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

Objective-C

Observação: este produto não está disponível para watchOS e destinos de clipes de apps.

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

Kotlin+KTX
Android

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

Java
Android

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

Python

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

Python
(assíncrono)

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

Go

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 autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Ruby

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

Uma referência é um objeto leve que aponta apenas para um local no banco de dados. É possível criar uma referência independentemente da existência de dados no banco de dados. A criação de uma referência não executa nenhuma operação de rede.

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

Versão 9 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

import { collection } from "firebase/firestore";

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

Versão 8 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

Swift

Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.

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

Objective-C

Observação: este produto não está disponível para watchOS e destinos de clipes de apps.

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

Kotlin+KTX
Android

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

Java
Android

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

Python

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

Python
(assíncrono)

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

Go

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

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

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

PHP

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Ruby

collection_ref = firestore.col "users"
data_model.rb

Observação: referências de coleções e referências de documentos são dois tipos diferentes de referências que permitem a execução de operações distintas. Por exemplo, é possível usar uma referência de coleção para consultar os documentos na coleção e utilizar uma de documento para ler ou gravar um documento individual.

Por conveniência, também é possível criar referências especificando o caminho para um documento ou conjunto como uma string, com componentes de caminho separados por uma barra (/). Por exemplo, para criar uma referência ao documento alovelace:

Versão 9 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

import { doc } from "firebase/firestore"; 

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

Versão 8 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

Swift

Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.

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

Objective-C

Observação: este produto não está disponível para watchOS e destinos de clipes de apps.

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

Kotlin+KTX
Android

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

Java
Android

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

Python

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

Python
(assíncrono)

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

Go

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 autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Ruby

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

Dados hierárquicos

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

Crie um conjunto chamado rooms para armazenar salas de bate-papo diferentes:

• rooms

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

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

Subcoleções

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

Observação: é possível consultar as subcoleções com o mesmo ID de coleção usando Consultas de grupo de coleções.

É possível criar uma subcoleção chamada messages para cada documento da sala em sua coleção rooms:

• rooms

  • roomA

    name : "my chat room"
    

    • messages

      • message1

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

      • message2

        ...
        

  • roomB

    ...
    

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

Versão 9 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

import { doc } from "firebase/firestore"; 

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

Versão 8 para a Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

Swift

Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.

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

Objective-C

Observação: este produto não está disponível para watchOS e destinos de clipes de apps.

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

Kotlin+KTX
Android

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

Java
Android

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

Python

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

Python
(assíncrono)

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

Go

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 autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Ruby

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

Observe o padrão alternado de coleções e documentos. É importante que suas coleções e documentos sigam sempre esse padrão. Você não pode se referir a uma coleção em uma coleção ou a um documento em um documento.

As subcoleções permitem que você estruture os dados hierarquicamente, facilitando o acesso a eles. Para receber todas as mensagens em roomA, é possível criar uma referência de coleção para a subcoleção messages e interagir com ela como faria com outra referência de coleção.

Documentos em subcoleções também podem conter subcoleções, permitindo que os dados sejam mais aninhados. Você pode aninhar dados até 100 níveis.

Aviso: a exclusão de um documento não remove as subcoleções.

Ao excluir um documento que tem subcoleções, elas não são removidas. Por exemplo, pode haver um documento localizado em coll/doc/subcoll/subdoc mesmo que o documento coll/doc não exista mais. Remova manualmente os documentos nas subcoleções ao excluir um documento pai, conforme explicado em Excluir coleções.