Modello dei dati di Cloud Firestore

Cloud Firestore è un database NoSQL orientato ai documenti. A differenza di un database SQL, non sono presenti tabelle o righe. Invece, memorizzi i dati in documenti, che sono organizzati in raccolte.

Ogni documento contiene una serie di coppie chiave-valore. Cloud Firestore è ottimizzato per l'archiviazione di grandi raccolte di piccoli documenti.

Tutti i documenti devono essere archiviati in raccolte. I documenti possono contenere sottoraccolte e oggetti nidificati, che possono includere entrambi campi primitivi come stringhe o oggetti complessi come gli elenchi.

Le raccolte e i documenti vengono creati implicitamente in Cloud Firestore. Basta assegnare i dati a un documento all'interno di una raccolta. Se la raccolta o il documento non esistono, Cloud Firestore li crea.

Documenti

In Cloud Firestore, l'unità di misura dello spazio di archiviazione è il documento. Un documento è un record leggero contenente campi che mappano a valori. Ogni documento è identificate da un nome.

Un documento che rappresenta un utente alovelace potrebbe avere il seguente aspetto:

• alovelace

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

Nota: Cloud Firestore supporta diversi tipi di dati per i valori: booleano, numero, stringa, punto geografico, blob binario e timestamp. Puoi anche utilizzare آرایه‌ها o oggetti nidificati, chiamati mappe, per strutturare i dati all'interno di un documento.

Gli oggetti nidificati complessi in un documento sono chiamati mappe. Ad esempio, potresti strutturare il nome dell'utente dell'esempio precedente con una mappa, come questa:

• alovelace

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

Potresti notare che i documenti assomigliano molto a JSON. In effetti, lo sono. Esistono alcune differenze (ad esempio, i documenti supportano tipi di dati aggiuntivi e hanno una dimensione massima di 1 MB), ma in generale puoi trattare i documenti come record JSON leggeri.

Raccolte

I documenti si trovano nelle raccolte, che sono semplicemente contenitori per i documenti. Ad esempio, potresti avere una raccolta users per contenere i vari utenti, ciascuno rappresentato da un documento:

• utenti

  • alovelace

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

  • aturing

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

Cloud Firestore è senza schema, quindi hai completa libertà su quali campi inserire in ogni documento e su quali tipi di dati archiviare in questi campi. I documenti all'interno della stessa raccolta possono contenere tutti campi diversi o archiviare tipi diversi di dati in questi campi. Tuttavia, è buona norma utilizzare gli stessi campi e tipi di dati in più documenti, in modo da poter eseguire query sui documenti più facilmente.

Una raccolta contiene solo documenti. Non può contenere direttamente campi non elaborati con valori e non può contenere altre raccolte. (Consulta la sezione Dati gerarchici per una spiegazione su come strutturare i dati più complessi in Cloud Firestore.)

I nomi dei documenti all'interno di una raccolta sono univoci. Puoi fornire le tue chiavi, ad esempio gli ID utente, oppure puoi lasciare che sia Cloud Firestore a creare automaticamente ID casuali per te.

Non è necessario "creare" o "eliminare" le raccolte. Dopo aver creato il primo documento in una raccolta, la raccolta esiste. Se elimini tutti i documenti di una raccolta, questa non esiste più.

Riferimenti

Ogni documento in Cloud Firestore è identificato in modo univoco dalla sua posizione all'interno del database. L'esempio precedente mostrava un documento alovelace all'interno della raccolta users. Per fare riferimento a questa posizione nel codice, puoi creare un riferimento.

WebWebSwiftObjective-CKotlinJavaDartPythonPythonC++Node.jsVaiPHPUnityC#Ruby

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

import { doc } from "firebase/firestore";

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

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

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

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

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

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

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

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

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

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

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

func createDocReference(client *firestore.Client) {

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

	_ = alovelaceRef
}
retrieve_data_reference_document.go

PHP

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

C#

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

Un riferimento è un oggetto leggero che punta a una posizione nel database. Puoi creare un riferimento indipendentemente dal fatto che i dati esistano o meno e la creazione di un riferimento non esegue operazioni di rete.

Puoi anche creare riferimenti alle collezioni:

WebWebSwiftObjective-CKotlinJavaDartJavaPythonPythonC++Node.jsVaiPHPUnityC#Ruby

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

import { collection } from "firebase/firestore";

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

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

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

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

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

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

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

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

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

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

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

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

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

C#

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

collection_ref = firestore.col "users"
data_model.rb

Nota: i riferimenti alle raccolte e i riferimenti ai documenti sono due tipi distinti di riferimenti e ti consentono di eseguire operazioni diverse. Ad esempio, potresti utilizzare un riferimento alla raccolta per eseguire query sui documenti al suo interno e potresti utilizzare un riferimento a un documento per leggere o scrivere un singolo documento.

Per comodità, puoi anche creare riferimenti specificando il percorso di un documento o di una raccolta come stringa, con i componenti del percorso separati da una barra (/). Ad esempio, per creare un riferimento al documento alovelace:

WebWebSwiftObjective-CKotlinJavaDartJavaPythonPythonC++Node.jsVaiPHPUnityC#Ruby

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

import { doc } from "firebase/firestore"; 

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

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

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

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

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

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

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

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

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

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

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

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

C#

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

Dati gerarchici

Per capire come funzionano le strutture di dati gerarchiche in Cloud Firestore, considera un esempio di app di chat con messaggi e chat room.

Puoi creare una raccolta denominata rooms per archiviare diverse chat room:

• stanze

  • stanzaA

    name : "my chat room"
    

  • stanzaB

    ...
    

Ora che hai creato le stanze di chat, decidi come archiviare i messaggi. Potresti non volerli memorizzare nel documento della chat room. I documenti in Cloud Firestore devono essere leggeri e una chat room potrebbe contenere un numero elevato di messaggi. Tuttavia, puoi creare raccolte aggiuntive all'interno del documento della tua stanza virtuale come sottoraccolte.

Sottoraccolte

Il modo migliore per archiviare i messaggi in questo scenario è utilizzare le sottocollezioni. Una subraccolta è una raccolta associata a un documento specifico.

Nota: puoi eseguire query sulle sottocollezioni con lo stesso ID raccolta utilizzando le query sui gruppi di raccolte.

Puoi creare una sottoraccolta denominata messages per ogni documento della sala nella raccolta rooms:

• stanze

  • stanzaA

    name : "my chat room"
    

    • messaggi

      • message1

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

      • message2

        ...
        

  • stanzaB

    ...
    

In questo esempio, creerai un riferimento a un messaggio nella sottoraccolta con il seguente codice:

WebWebSwiftObjective-CKotlinJavaDartJavaPythonPythonC++Node.jsVaiPHPUnityC#Ruby

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

import { doc } from "firebase/firestore"; 

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

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

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

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

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

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

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

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

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

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

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

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

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

C#

Per saperne di più sull'installazione e sulla creazione di un client Cloud Firestore, consulta Librerie client Cloud Firestore.

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

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

Nota il pattern alternato di collezioni e documenti. Le collezioni e i documenti devono sempre seguire questo schema. Non puoi fare riferimento a una raccolta in una raccolta o a un documento in un documento.

Le sottocollezioni ti consentono di strutturare i dati in modo gerarchico, semplificandone l'accesso. Per recuperare tutti i messaggi in roomA, puoi creare un riferimento alla raccolta messages e interagire con esso come con qualsiasi altro riferimento alla raccolta.

I documenti nelle sottoraccolte possono contenere anche sottoraccolte, il che ti consente di nidificare ulteriormente i dati. Puoi nidificare i dati fino a 100 livelli di profondità.

Avviso: l'eliminazione di un documento non comporta l'eliminazione delle relative sottoraccolte.

Quando elimini un documento contenente sottoraccolte, queste ultime non vengono eliminate. Ad esempio, potrebbe esserci un documento in coll/doc/subcoll/subdoc anche se il documento coll/doc non esiste più. Se vuoi eliminare i documenti nelle sottocollezioni quando elimini un documento principale, devi farlo manualmente, come mostrato in Eliminare le collezioni.