Modello dei dati

Modello dei dati

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, organizzati in raccolte.

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

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

Le raccolte e i documenti vengono creati in modo implicito in Firestore. Basta assegnare i dati a un documento all'interno di una raccolta. Se la raccolta o il documento non esiste, Firestore lo crea.

Documenti

In Firestore, l'unità di archiviazione è il documento. Un documento è un record leggero che contiene campi, che vengono mappati ai valori. Ogni documento è identificato da un nome.

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

• alovelace

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

Nota: Firestore supporta diversi tipi di dati per i valori: booleano, numero, stringa, punto geografico, blob binario e timestamp. Puoi anche utilizzare array 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, puoi strutturare il nome dell'utente dell'esempio precedente con una mappa, in questo modo:

• alovelace

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

Potresti notare che i documenti assomigliano molto a JSON. In effetti, sono praticamente la stessa cosa. Esistono alcune differenze (ad esempio, i documenti supportano tipi di dati aggiuntivi e sono limitati al limite di dimensione del documento), ma in generale puoi trattare i documenti come record JSON leggeri.

Raccolte

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

• utenti

  • alovelace

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

  • aturing

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

Firestore è privo di schema, quindi hai la massima libertà sui campi da inserire in ogni documento e sui tipi di dati da archiviare in questi campi. I documenti all'interno della stessa raccolta possono contenere campi diversi o archiviare tipi di dati diversi in questi campi. Tuttavia, è consigliabile 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, né altre raccolte. (Consulta Dati gerarchici per una spiegazione su come strutturare dati più complessi in Firestore.)

I nomi dei documenti all'interno di una raccolta sono univoci. Puoi fornire le tue chiavi, ad esempio gli ID utente, o lasciare che Firestore crei 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 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.

Web version 9

import { doc } from "firebase/firestore";

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

Versione web 8

Scopri di più sull'API web modulare con tree shaking e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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
(Async)

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 eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Unity

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

C#

C#

Per eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Ruby

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

Un riferimento è un oggetto leggero che punta semplicemente a una posizione nel tuo database. Puoi creare un riferimento indipendentemente dalla presenza o meno di dati e la creazione di un riferimento non esegue alcuna operazione di rete.

Puoi anche creare riferimenti alle raccolte:

Web version 9

import { collection } from "firebase/firestore";

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

Versione web 8

Scopri di più sull'API web modulare con tree shaking e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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
(Async)

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 eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Unity

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

C#

C#

Per eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Ruby

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, puoi utilizzare un riferimento alla raccolta per eseguire query sui documenti della raccolta e un riferimento al documento per leggere o scrivere un singolo documento.

Per praticità, 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 version 9

import { doc } from "firebase/firestore"; 

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

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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

Objective-C

Nota: questo prodotto non è disponibile su watchOS e App Clip.

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
(Async)

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 eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Unity

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

C#

C#

Per eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Ruby

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

Dati gerarchici

Per capire come funzionano le strutture di dati gerarchiche in Firestore, prendi in considerazione un'app di chat di esempio con messaggi e stanze virtuali.

Puoi creare una raccolta denominata rooms per archiviare diverse stanze virtuali:

• stanze

  • stanzaA

    name : "my chat room"
    

  • roomB

    ...
    

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

Sottoraccolte

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

Nota: puoi eseguire query su raccolte secondarie con lo stesso ID raccolta utilizzando le query dei gruppi di raccolte.

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

• stanze

  • stanzaA

    name : "my chat room"
    

    • messaggi

      • message1

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

      • message2

        ...
        

  • roomB

    ...
    

In questo esempio, creeresti un riferimento a un messaggio nella raccolta secondaria con il seguente codice:

Web version 9

import { doc } from "firebase/firestore"; 

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

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'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 su 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 App Clip.

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
(Async)

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 eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Unity

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

C#

C#

Per eseguire l'autenticazione in Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

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

Le raccolte secondarie 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 secondaria messages e interagire con questo riferimento come faresti con qualsiasi altro riferimento alla raccolta.

Anche i documenti nelle sottoraccolte possono contenere 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 con sottoraccolte, queste 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 raccolte secondarie quando elimini un documento principale, devi farlo manualmente, come mostrato in Elimina raccolte.

Gruppi di raccolte

Un gruppo di raccolte è costituito da tutte le raccolte di un database che condividono lo stesso ID raccolta, indipendentemente dalla loro posizione nella gerarchia dei documenti. Sono incluse sia le raccolte a livello principale sia le sottoraccolte nidificate a qualsiasi profondità.

Ad esempio, se il tuo database ha una raccolta messages a livello di root e sia roomA che roomB nella raccolta rooms contengono anche sottoraccolte messages, tutte le seguenti appartengono al gruppo di raccolte messages:

• messages
• rooms/roomA/messages
• rooms/roomB/messages

Per impostazione predefinita, le query recuperano i risultati da una singola raccolta. Per recuperare contemporaneamente i documenti di tutte le raccolte di un gruppo di raccolte, utilizza le query dei gruppi di raccolte.