Modelo de dados do Cloud Firestore

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

class alovelace

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

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, como este:

class alovelace

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

Você pode notar que os documentos se parecem muito com a JSON. Na verdade, eles basicamente 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), mas, em geral, você pode tratar os documentos como registros JSON leves.

Coleções

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

Usuários collections_bookmark
- class alovelace
  
  first : "Ada"
  last : "Lovelace"
  born : 1815
- class
  
  first : "Alan"
  last : "Turing"
  born : 1912

O Cloud 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 Cloud Firestore.)

Os nomes dos documentos dentro de uma coleção são únicos. Você pode fornecer suas próprias chaves, como IDs de usuário, ou pode permitir que o Cloud Firestore crie IDs aleatórios automaticamente (por exemplo, chamando add()).

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 Cloud Firestore é identificado de maneira exclusiva pela sua 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, você pode criar uma referência a ele.

Web

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

Swift

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

Objective-C

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

Android

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

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(u'users').document(u'alovelace')snippets.py

Node.js

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

Go

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

PHP

$document = $db->collection('users')->document('lovelace');document_ref.php

Uma referência é um objeto leve que aponta apenas para uma localização no banco de dados. Você pode criar uma referência independentemente da existência de dados no banco de dados. Além disso, criar uma referência não executa nenhuma operação de rede.

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

Web

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

Swift

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

Objective-C

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

Android

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

Java

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

Python

users_ref = db.collection(u'users')snippets.py

Node.js

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

Go

usersRef := client.Collection("users")retrieve.go

PHP

$collection = $db->collection('users');collection_ref.php

Por conveniência, você 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:

Web

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

Swift

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

Objective-C

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

Android

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

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(u'users/alovelace')snippets.py

Node.js

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

Go

alovelaceRef := client.Doc("users/alovelace")retrieve.go

PHP

$document = $db->document('users/lovelace');document_path_ref.php

Dados hierárquicos

Para entender como as estruturas hierárquicas de dados funcionam no Cloud Firestore, pense em um exemplo de app de bate-papo com mensagens e salas de bate-papo.

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

collections_bookmark rooms
- class roomA
  
  name : "my chat room"
- class 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 Cloud Firestore precisam ser leves, e uma sala de bate-papo pode conter um grande número de mensagens. No entanto, você pode 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.

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

collections_bookmark rooms
- class roomA
  
  name : "my chat room"
  - collections_bookmark messages
    - class message1
      
      from : "alex"
      msg : "Hello World!"
    - class message2
      
      ...
- class roomB
  
  ...

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

Web

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

Swift

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

Objective-C

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

Android

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

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(u'rooms').document(u'roomA')
message_ref = room_a_ref.collection(u'messages').document(u'message1')snippets.py

Node.js

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

Go

messageRef := client.Collection("rooms").Doc("roomA").
	Collection("messages").Doc("message1")retrieve.go

PHP

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

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 fazer referência 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, basta acessar a coleção db.collection('rooms').doc('roomA').collection('messages').

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.