Modello dei dati di Cloud Firestore

Cloud Firestore è un database NoSQL orientato ai documenti. A differenza di un database SQL, non ci sono tabelle o righe. I dati vengono invece archiviati in documenti, che sono organizzate 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. È sufficiente 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 archiviazione è il documento. Un documento è un record leggero contenente campi che mappano a valori. Ogni documento è identificati da un nome.

Un documento che rappresenta l'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 complessi e nidificati 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 sembrano molto simili 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. Per Ad esempio, potresti avere una raccolta users che contiene i vari utenti, rappresentati 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 memorizzare in questi campi. I documenti all'interno della stessa raccolta possono contenere tutti campi diversi o archiviare diversi tipi 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 documenti e nient'altro. Non può contenere direttamente campi non elaborati con valori e non può contenere altre raccolte. (Vedi la sezione Dati per una spiegazione su come strutturare i dati più complessi dati 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 la prima documento in una raccolta, la raccolta esiste. Se elimini tutti i documenti in una raccolta, 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 località nel tuo codice, puoi creare un riferimento.

Web

Impara Scopri di più sull'API web modulare con gestione ad albero e upgrade da l'API con spazio dei nomi.

import { doc } from "firebase/firestore";

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

Web

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

Swift

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

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e sui target di 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

Python

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

Vai

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

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

Unity

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

C#

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

Ruby

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

Un riferimento è un oggetto leggero che punta a una posizione nel tuo per configurare un database. Puoi creare un riferimento indipendentemente dal fatto che esista o meno dei dati al suo interno la creazione di un riferimento non esegue alcuna operazione di rete.

Puoi anche creare riferimenti alle raccolte:

Web

Impara Scopri di più sull'API web modulare con gestione ad albero e upgrade da l'API con spazio dei nomi.

import { collection } from "firebase/firestore";

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

Web

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

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

Swift

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

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e sui target di 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

Python

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

Vai

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

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

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

PHP

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

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

Unity

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

C#

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

Ruby

collection_ref = firestore.col "users"
data_model.rb

Nota: i riferimenti alla raccolta e i riferimenti ai documenti sono due tipi distinti di riferimenti e ti consentono di eseguire diverse operazioni. Ad esempio, potresti utilizzare un riferimento a una raccolta per eseguire query sui documenti al suo interno e possono 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:

Web

Impara Scopri di più sull'API web modulare con gestione ad albero e upgrade da l'API con spazio dei nomi.

import { doc } from "firebase/firestore"; 

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

Web

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

Swift

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

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e sui target di 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

Python

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

Vai

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

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

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

Unity

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

C#

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

Ruby

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 stanze virtuali:

• stanze

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

Ora che hai creato le stanze di chat, decidi come archiviare i messaggi. Potresti non nel documento della chat room. Documenti in Cloud Firestore dovrebbe essere leggero e una chat room potrebbe contenere un gran numero di messaggi. Tuttavia, puoi creare raccolte aggiuntive all'interno del documento della stanza virtuale, come sottoraccolte.

Raccolte secondarie

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

Nota: puoi eseguire query tra sottoraccolte con lo stesso ID raccolta utilizzando Query del gruppo 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

        ...
        

  • roomB

    ...
    

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

Web

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

Web

Impara Scopri di più sull'API web modulare con gestione ad albero e upgrade da l'API con spazio dei nomi.

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

Swift

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e sui target di 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

Python

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

Vai

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

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

Unity

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

C#

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

Ruby

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

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

Le sottoraccolte consentono di strutturare i dati in modo gerarchico, semplificando 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.

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

Quando elimini un documento che contiene sottoraccolte, queste vengono non eliminato. Ad esempio, un documento potrebbe trovarsi all'indirizzo 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.