Modelo de dados

Modelo de dados

O Firestore é uma base de dados NoSQL orientada para documentos. Ao contrário de uma base de dados SQL, não existem tabelas nem linhas. Em vez disso, armazena dados em documentos, que são organizados em coleções.

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

Todos os documentos têm de ser 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.

As coleções e os documentos são criados implicitamente no Firestore. Basta atribuir dados a um documento numa coleção. Se a coleção ou o documento não existir, o Firestore cria-o.

Documentos

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

Um documento que representa um utilizador alovelace pode ter o seguinte aspeto:

• alovelace

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

Nota: o Firestore suporta uma variedade de tipos de dados para valores: booleano, número, string, ponto geográfico, blob binário e data/hora. Também pode usar matrizes ou objetos aninhados, denominados mapas, para estruturar dados num documento.

Os objetos complexos e aninhados num documento são denominados mapas. Por exemplo, pode estruturar o nome do utilizador do exemplo acima com um mapa, da seguinte forma:

• alovelace

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

Pode reparar que os documentos se assemelham muito ao JSON. Na verdade, são basicamente a mesma coisa. Existem algumas diferenças (por exemplo, os documentos suportam tipos de dados adicionais e têm um limite de tamanho de 1 MB), mas, em geral, pode tratar os documentos como registos JSON simples.

Coleções

Os documentos residem em coleções, que são simplesmente contentores de documentos. Por exemplo, pode ter uma coleção users para conter os seus vários utilizadores, cada um representado por um documento:

• utilizadores

  • alovelace

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

  • aturing

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

O Firestore não tem esquemas, pelo que tem total liberdade sobre os campos que coloca em cada documento e os tipos de dados que armazena nesses campos. Os documentos na mesma coleção podem conter campos diferentes 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 poder consultar os documentos mais facilmente.

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

Os nomes dos documentos numa coleção são exclusivos. Pode fornecer as suas próprias chaves, como IDs de utilizadores, ou permitir que o Firestore crie IDs aleatórios automaticamente.

Não precisa de "criar" nem "eliminar" coleções. Depois de criar o primeiro documento numa coleção, a coleção existe. Se eliminar todos os documentos numa coleção, esta deixa de existir.

Referências

Cada documento no Firestore é identificado de forma exclusiva pela respetiva localização na base de dados. O exemplo anterior mostrava um documento alovelace na coleção users. Para fazer referência a esta localização no seu código, pode criar uma referência à mesma.

Versão Web 9

import { doc } from "firebase/firestore";

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

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Kotlin
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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 simples que apenas aponta para uma localização na sua base de dados. Pode criar uma referência independentemente de existirem ou não dados e a criação de uma referência não executa operações de rede.

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

Versão Web 9

import { collection } from "firebase/firestore";

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

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Kotlin
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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Ruby

collection_ref = firestore.col "users"
data_model.rb

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

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

Versão Web 9

import { doc } from "firebase/firestore"; 

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

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Kotlin
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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Unity

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

C#

C#

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 compreender como funcionam as estruturas de dados hierárquicas no Firestore, considere uma app de chat de exemplo com mensagens e salas de chat.

Pode criar uma coleção denominada rooms para armazenar diferentes salas de chat:

• salas

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

Agora que tem salas de chat, decida como armazenar as suas mensagens. Pode não querer armazená-las no documento da sala de chat. Os documentos no Firestore devem ser simples e uma sala de chat pode conter um grande número de mensagens. No entanto, pode criar coleções adicionais no documento da sala de chat, como subcoleções.

Subcoleções

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

Nota: pode consultar subcoleções com o mesmo ID da coleção usando consultas de grupo de coleções.

Pode criar uma subcoleção denominada messages para cada documento de sala na sua coleção rooms:

• salas

  • roomA

    name : "my chat room"
    

    • mensagens

      • message1

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

      • message2

        ...
        

  • roomB

    ...
    

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

Versão Web 9

import { doc } from "firebase/firestore"; 

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

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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

Kotlin
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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

Repare no padrão alternado de coleções e documentos. As suas coleções e documentos têm sempre de seguir este padrão. Não pode fazer referência a uma coleção numa coleção nem a um documento num documento.

As subcoleções permitem-lhe estruturar os dados hierarquicamente, o que facilita o acesso aos dados. Para receber todas as mensagens no roomA, pode criar uma referência de coleção para a subcoleção messages 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, o que lhe permite aninhar ainda mais os dados. Pode aninhar dados até 100 níveis de profundidade.

Aviso: a eliminação de um documento não elimina as respetivas subcoleções!

Quando elimina um documento que tem subcoleções, essas subcoleções não são eliminadas. Por exemplo, pode existir um documento localizado em coll/doc/subcoll/subdoc, mesmo que o documento coll/doc já não exista. Se quiser eliminar documentos em subcoleções quando elimina um documento principal, tem de o fazer manualmente, conforme mostrado em Eliminar coleções.