Modello dati

Modello dati

Firestore è un database NoSQL orientato ai documenti. A differenza dei database SQL, non ci sono tabelle o righe. I dati vengono invece archiviati in documenti, organizzati in raccolte.

Ogni documento contiene un insieme di coppie chiave-valore. 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, entrambi che possono includere campi primitivi come stringhe o oggetti complessi come elenchi.

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

Documenti

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

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

• bacio

  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, denominati mappe, per strutturare i dati all'interno di un documento.

Gli oggetti complessi e nidificati in un documento sono chiamati mappe. Ad esempio, puoi strutturare il nome dell'utente prendendo come riferimento l'esempio precedente con una mappa, come in questo esempio:

• bacio

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

Potresti notare che i documenti sembrano molto simili a JSON. In sostanza, lo sono. Esistono alcune differenze (ad esempio, i documenti supportano tipi di dati aggiuntivi e hanno dimensioni limitate a 1 MB), ma in generale, puoi trattare i documenti come record JSON leggeri.

Raccolte

I documenti risiedono in raccolte, che sono semplicemente container di documenti. Ad esempio, potresti avere una raccolta users che contenga i vari utenti, ognuno dei quali è rappresentato da un documento:

• di utenti

  • bacio

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

  • in tour

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

Firestore è senza schema, quindi hai piena libertà sui campi che inserisci in ogni documento e sui tipi di dati archiviati al loro interno. I documenti all'interno della stessa raccolta possono contenere campi diversi o archiviare tipi di dati diversi al loro interno. Tuttavia, è una buona idea 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 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, come gli ID utente, oppure lasciare che sia Firestore a creare ID casuali per te automaticamente.

Non è necessario "creare" o "eliminare" le raccolte. Dopo aver creato il primo documento in una raccolta, la raccolta esiste. Se elimini tutti i documenti in una raccolta, 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.

Versione web 9

Scopri di più sull'API Web modulare con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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 struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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

Swift

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

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

Java
Android

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

Darte

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

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

Per eseguire l'autenticazione su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 a una posizione nel tuo database. Puoi creare un riferimento indipendentemente dal fatto che esista o meno dei dati e la creazione di un riferimento non esegue alcuna operazione di rete.

Puoi anche creare riferimenti alle raccolte:

Versione web 9

Scopri di più sull'API Web modulare con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

import { collection } from "firebase/firestore";

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

Versione web 8

Scopri di più sull'API Web modulare con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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

Swift

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

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

Java
Android

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

Darte

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

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

Per eseguire l'autenticazione su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 alla raccolta e i riferimenti ai documenti sono due tipi distinti di riferimenti e consentono di eseguire operazioni diverse. Ad esempio, potresti utilizzare un riferimento a una raccolta per eseguire query sui documenti al suo interno e un riferimento a un 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:

Versione web 9

Scopri di più sull'API Web modulare con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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 con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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

Swift

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

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

Java
Android

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

Darte

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

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

Per eseguire l'autenticazione su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

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

Raccolte secondarie

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

Nota: puoi eseguire query su sottoraccolte con lo stesso ID raccolta utilizzando le query del gruppo di raccolte.

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

• stanze

  • roomA

    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:

Versione web 9

Scopri di più sull'API Web modulare con struttura ad albero e sull'upgrade dall'API con spazio dei nomi.

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 con struttura ad albero e sull'upgrade dall'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 sui target di 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
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

Darte

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

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

Per eseguire l'autenticazione su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 su Firestore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 raccolte e i documenti devono sempre seguire questo pattern. Non puoi fare riferimento a una raccolta in una raccolta o a un documento di un documento.

Le sottoraccolte consentono di strutturare i dati in modo gerarchico, semplificando l'accesso ai dati. Per ricevere tutti i messaggi in roomA, puoi creare un riferimento di raccolta alla sottoraccolta messages e interagire con quest'ultimo come faresti con qualsiasi altro riferimento di raccolta.

I documenti delle sottoraccolte possono contenere anche sottoraccolte, consentendoti 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 non vengono eliminate. Ad esempio, un documento potrebbe trovarsi 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 padre, devi farlo manualmente, come mostrato in Eliminare le raccolte.