Ottieni dati con Cloud Firestore

Esistono tre modi per recuperare i dati archiviati in Cloud Firestore. Qualsiasi di questi metodi può essere utilizzato con documenti, raccolte di documenti o risultati di query:

  • Chiama un metodo per recuperare i dati una volta.
  • Imposta un listener per ricevere gli eventi di modifica dei dati.
  • Carica collettivamente i dati degli snapshot di Firestore da un'origine esterna tramite bundle di dati. Per ulteriori dettagli, consulta la documentazione dei pacchetti.

Quando imposti un ascoltatore, Cloud Firestore invia un'istantanea iniziale dei dati e poi un'altra ogni volta che il documento cambia.

Prima di iniziare

Consulta la Guida introduttiva a Cloud Firestore per creare un database Cloud Firestore.

Inizializza Cloud Firestore

Inizializza un'istanza di Cloud Firestore:

import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
    FIREBASE_CONFIGURATION
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);

Sostituisci FIREBASE_CONFIGURATION con il valore firebaseConfig della tua app web.

Per mantenere i dati quando il dispositivo perde la connessione, consulta la documentazione su come abilitare i dati offline.

import firebase from "firebase/app";
import "firebase/firestore";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
    FIREBASE_CONFIGURATION
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Cloud Firestore and get a reference to the service
const db = firebase.firestore();

Sostituisci FIREBASE_CONFIGURATION con il valore firebaseConfig della tua app web.

Per mantenere i dati quando il dispositivo perde la connessione, consulta la documentazione su come abilitare i dati offline.

Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
import FirebaseCore
import FirebaseFirestore
FirebaseApp.configure()

let db = Firestore.firestore()
Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
@import FirebaseCore;
@import FirebaseFirestore;

// Use Firebase library to configure APIs
[FIRApp configure];
  
FIRFirestore *defaultFirestore = [FIRFirestore firestore];
// Access a Cloud Firestore instance from your Activity
val db = Firebase.firestore
// Access a Cloud Firestore instance from your Activity
FirebaseFirestore db = FirebaseFirestore.getInstance();
db = FirebaseFirestore.instance;
L'SDK Cloud Firestore viene inizializzato in modi diversi a seconda del tuo ambiente. Di seguito sono riportati i metodi più comuni. Per un riferimento completo, consulta Inizializzare SDK Admin.
  • Eseguire l'inizializzazione il giorno Google Cloud
    import com.google.auth.oauth2.GoogleCredentials;
    import com.google.cloud.firestore.Firestore;
    
    import com.google.firebase.FirebaseApp;
    import com.google.firebase.FirebaseOptions;
    
    // Use the application default credentials
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
    FirebaseOptions options = new FirebaseOptions.Builder()
        .setCredentials(credentials)
        .setProjectId(projectId)
        .build();
    FirebaseApp.initializeApp(options);
    
    Firestore db = FirestoreClient.getFirestore();
  • Eseguire l'inizializzazione sul tuo server

    Per utilizzare l'SDK Firebase Admin sul tuo server, utilizza un account di servizio.

    Vai a IAM e amministrazione > Account di servizio nella console Google Cloud. Genera una nuova chiave privata e salva il file JSON. Quindi, utilizza il file per inizializzare l'SDK:

    import com.google.auth.oauth2.GoogleCredentials;
    import com.google.cloud.firestore.Firestore;
    
    import com.google.firebase.FirebaseApp;
    import com.google.firebase.FirebaseOptions;
    
    // Use a service account
    InputStream serviceAccount = new FileInputStream("path/to/serviceAccount.json");
    GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount);
    FirebaseOptions options = new FirebaseOptions.Builder()
        .setCredentials(credentials)
        .build();
    FirebaseApp.initializeApp(options);
    
    Firestore db = FirestoreClient.getFirestore();
  • L'SDK Cloud Firestore viene inizializzato in modi diversi a seconda del tuo ambiente. Di seguito sono riportati i metodi più comuni. Per un riferimento completo, consulta Inizializzare l'SDK Admin.
  • Eseguire l'inizializzazione il giorno Google Cloud
    import firebase_admin
    from firebase_admin import firestore
    
    # Application Default credentials are automatically created.
    app = firebase_admin.initialize_app()
    db = firestore.client()

    Per inizializzare l'SDK puoi anche utilizzare una credenziale predefinita dell'applicazione esistente.

    import firebase_admin
    from firebase_admin import credentials
    from firebase_admin import firestore
    
    # Use the application default credentials.
    cred = credentials.ApplicationDefault()
    
    firebase_admin.initialize_app(cred)
    db = firestore.client()
  • Eseguire l'inizializzazione sul tuo server

    Per utilizzare l'SDK Firebase Admin sul tuo server, utilizza un account di servizio.

    Vai a IAM e amministrazione > Account di servizio nella console Google Cloud. Genera una nuova chiave privata e salva il file JSON. Quindi, utilizza il file per inizializzare l'SDK:

    import firebase_admin
    from firebase_admin import credentials
    from firebase_admin import firestore
    
    # Use a service account.
    cred = credentials.Certificate('path/to/serviceAccount.json')
    
    app = firebase_admin.initialize_app(cred)
    
    db = firestore.client()
  • L'SDK Cloud Firestore viene inizializzato in modi diversi a seconda del tuo ambiente. Di seguito sono riportati i metodi più comuni. Per un riferimento completo, consulta Inizializzare l'SDK Admin.
  • Eseguire l'inizializzazione il giorno Google Cloud
    import firebase_admin
    from firebase_admin import firestore_async
    
    # Application Default credentials are automatically created.
    app = firebase_admin.initialize_app()
    db = firestore_async.client()

    Per inizializzare l'SDK puoi anche utilizzare una credenziale predefinita dell'applicazione esistente.

    import firebase_admin
    from firebase_admin import credentials
    from firebase_admin import firestore_async
    
    # Use the application default credentials.
    cred = credentials.ApplicationDefault()
    
    firebase_admin.initialize_app(cred)
    db = firestore_async.client()
  • Eseguire l'inizializzazione sul tuo server

    Per utilizzare l'SDK Firebase Admin sul tuo server, utilizza un account di servizio.

    Vai a IAM e amministrazione > Account di servizio nella console Google Cloud. Genera una nuova chiave privata e salva il file JSON. Quindi, utilizza il file per inizializzare l'SDK:

    import firebase_admin
    from firebase_admin import credentials
    from firebase_admin import firestore_async
    
    # Use a service account.
    cred = credentials.Certificate('path/to/serviceAccount.json')
    
    app = firebase_admin.initialize_app(cred)
    
    db = firestore_async.client()
  • // Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
    App::Create();
    Firestore* db = Firestore::GetInstance();
    L'SDK Cloud Firestore viene inizializzato in modi diversi a seconda del tuo ambiente. Di seguito sono riportati i metodi più comuni. Per un riferimento completo, consulta Inizializzare l'SDK Admin.
    • Eseguire l'inizializzazione il giorno Cloud Functions
      const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
      const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
      initializeApp();
      
      const db = getFirestore();
      
    • Eseguire l'inizializzazione il giorno Google Cloud
      const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
      const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
      initializeApp({
        credential: applicationDefault()
      });
      
      const db = getFirestore();
    • Eseguire l'inizializzazione sul tuo server

      Per utilizzare l'SDK Firebase Admin sul tuo server (o in qualsiasi altro ambiente Node.js), utilizza un account di servizio. Vai a IAM e amministrazione > Account di servizio nella console Google Cloud. Genera una nuova chiave privata e salva il file JSON. Quindi, utilizza il file per inizializzare l'SDK:

      const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
      const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
      const serviceAccount = require('./path/to/serviceAccountKey.json');
      
      initializeApp({
        credential: cert(serviceAccount)
      });
      
      const db = getFirestore();
      
    L'SDK Cloud Firestore viene inizializzato in modi diversi a seconda del tuo ambiente. Di seguito sono riportati i metodi più comuni. Per un riferimento completo, consulta Inizializzare SDK Admin.
  • Eseguire l'inizializzazione il giorno Google Cloud
    import (
      "log"
    
      firebase "firebase.google.com/go"
      "google.golang.org/api/option"
    )
    
    // Use the application default credentials
    ctx := context.Background()
    conf := &firebase.Config{ProjectID: projectID}
    app, err := firebase.NewApp(ctx, conf)
    if err != nil {
      log.Fatalln(err)
    }
    
    client, err := app.Firestore(ctx)
    if err != nil {
      log.Fatalln(err)
    }
    defer client.Close()
  • Eseguire l'inizializzazione sul tuo server

    Per utilizzare l'SDK Firebase Admin sul tuo server, utilizza un account di servizio.

    Vai a IAM e amministrazione > Account di servizio nella console Google Cloud. Genera una nuova chiave privata e salva il file JSON. Quindi, utilizza il file per inizializzare l'SDK:

    import (
      "log"
    
      firebase "firebase.google.com/go"
      "google.golang.org/api/option"
    )
    
    // Use a service account
    ctx := context.Background()
    sa := option.WithCredentialsFile("path/to/serviceAccount.json")
    app, err := firebase.NewApp(ctx, nil, sa)
    if err != nil {
      log.Fatalln(err)
    }
    
    client, err := app.Firestore(ctx)
    if err != nil {
      log.Fatalln(err)
    }
    defer client.Close()
  • PHP

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

    use Google\Cloud\Firestore\FirestoreClient;
    
    /**
     * Initialize Cloud Firestore with default project ID.
     */
    function setup_client_create(string $projectId = null)
    {
        // Create the Cloud Firestore client
        if (empty($projectId)) {
            // The `projectId` parameter is optional and represents which project the
            // client will act on behalf of. If not supplied, the client falls back to
            // the default project inferred from the environment.
            $db = new FirestoreClient();
            printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);
        } else {
            $db = new FirestoreClient([
                'projectId' => $projectId,
            ]);
            printf('Created Cloud Firestore client with project ID: %s' . PHP_EOL, $projectId);
        }
    }
    using Firebase.Firestore;
    using Firebase.Extensions;
    FirebaseFirestore db = FirebaseFirestore.DefaultInstance;

    C#

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

    FirestoreDb db = FirestoreDb.Create(project);
    Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
    require "google/cloud/firestore"
    
    # The `project_id` parameter is optional and represents which project the
    # client will act on behalf of. If not supplied, the client falls back to the
    # default project inferred from the environment.
    firestore = Google::Cloud::Firestore.new project_id: project_id
    
    puts "Created Cloud Firestore client with given project ID."

    Dati di esempio

    Per iniziare, scrivi alcuni dati sulle città in modo da poter esaminare diversi modi per recuperarli:

    import { collection, doc, setDoc } from "firebase/firestore"; 
    
    const citiesRef = collection(db, "cities");
    
    await setDoc(doc(citiesRef, "SF"), {
        name: "San Francisco", state: "CA", country: "USA",
        capital: false, population: 860000,
        regions: ["west_coast", "norcal"] });
    await setDoc(doc(citiesRef, "LA"), {
        name: "Los Angeles", state: "CA", country: "USA",
        capital: false, population: 3900000,
        regions: ["west_coast", "socal"] });
    await setDoc(doc(citiesRef, "DC"), {
        name: "Washington, D.C.", state: null, country: "USA",
        capital: true, population: 680000,
        regions: ["east_coast"] });
    await setDoc(doc(citiesRef, "TOK"), {
        name: "Tokyo", state: null, country: "Japan",
        capital: true, population: 9000000,
        regions: ["kanto", "honshu"] });
    await setDoc(doc(citiesRef, "BJ"), {
        name: "Beijing", state: null, country: "China",
        capital: true, population: 21500000,
        regions: ["jingjinji", "hebei"] });
    var citiesRef = db.collection("cities");
    
    citiesRef.doc("SF").set({
        name: "San Francisco", state: "CA", country: "USA",
        capital: false, population: 860000,
        regions: ["west_coast", "norcal"] });
    citiesRef.doc("LA").set({
        name: "Los Angeles", state: "CA", country: "USA",
        capital: false, population: 3900000,
        regions: ["west_coast", "socal"] });
    citiesRef.doc("DC").set({
        name: "Washington, D.C.", state: null, country: "USA",
        capital: true, population: 680000,
        regions: ["east_coast"] });
    citiesRef.doc("TOK").set({
        name: "Tokyo", state: null, country: "Japan",
        capital: true, population: 9000000,
        regions: ["kanto", "honshu"] });
    citiesRef.doc("BJ").set({
        name: "Beijing", state: null, country: "China",
        capital: true, population: 21500000,
        regions: ["jingjinji", "hebei"] });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    let citiesRef = db.collection("cities")
    
    citiesRef.document("SF").setData([
      "name": "San Francisco",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 860000,
      "regions": ["west_coast", "norcal"]
    ])
    citiesRef.document("LA").setData([
      "name": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 3900000,
      "regions": ["west_coast", "socal"]
    ])
    citiesRef.document("DC").setData([
      "name": "Washington D.C.",
      "country": "USA",
      "capital": true,
      "population": 680000,
      "regions": ["east_coast"]
    ])
    citiesRef.document("TOK").setData([
      "name": "Tokyo",
      "country": "Japan",
      "capital": true,
      "population": 9000000,
      "regions": ["kanto", "honshu"]
    ])
    citiesRef.document("BJ").setData([
      "name": "Beijing",
      "country": "China",
      "capital": true,
      "population": 21500000,
      "regions": ["jingjinji", "hebei"]
    ])
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    FIRCollectionReference *citiesRef = [self.db collectionWithPath:@"cities"];
    [[citiesRef documentWithPath:@"SF"] setData:@{
      @"name": @"San Francisco",
      @"state": @"CA",
      @"country": @"USA",
      @"capital": @(NO),
      @"population": @860000,
      @"regions": @[@"west_coast", @"norcal"]
    }];
    [[citiesRef documentWithPath:@"LA"] setData:@{
      @"name": @"Los Angeles",
      @"state": @"CA",
      @"country": @"USA",
      @"capital": @(NO),
      @"population": @3900000,
      @"regions": @[@"west_coast", @"socal"]
    }];
    [[citiesRef documentWithPath:@"DC"] setData:@{
      @"name": @"Washington D.C.",
      @"country": @"USA",
      @"capital": @(YES),
      @"population": @680000,
      @"regions": @[@"east_coast"]
    }];
    [[citiesRef documentWithPath:@"TOK"] setData:@{
      @"name": @"Tokyo",
      @"country": @"Japan",
      @"capital": @(YES),
      @"population": @9000000,
      @"regions": @[@"kanto", @"honshu"]
    }];
    [[citiesRef documentWithPath:@"BJ"] setData:@{
      @"name": @"Beijing",
      @"country": @"China",
      @"capital": @(YES),
      @"population": @21500000,
      @"regions": @[@"jingjinji", @"hebei"]
    }];
    val cities = db.collection("cities")
    
    val data1 = hashMapOf(
        "name" to "San Francisco",
        "state" to "CA",
        "country" to "USA",
        "capital" to false,
        "population" to 860000,
        "regions" to listOf("west_coast", "norcal"),
    )
    cities.document("SF").set(data1)
    
    val data2 = hashMapOf(
        "name" to "Los Angeles",
        "state" to "CA",
        "country" to "USA",
        "capital" to false,
        "population" to 3900000,
        "regions" to listOf("west_coast", "socal"),
    )
    cities.document("LA").set(data2)
    
    val data3 = hashMapOf(
        "name" to "Washington D.C.",
        "state" to null,
        "country" to "USA",
        "capital" to true,
        "population" to 680000,
        "regions" to listOf("east_coast"),
    )
    cities.document("DC").set(data3)
    
    val data4 = hashMapOf(
        "name" to "Tokyo",
        "state" to null,
        "country" to "Japan",
        "capital" to true,
        "population" to 9000000,
        "regions" to listOf("kanto", "honshu"),
    )
    cities.document("TOK").set(data4)
    
    val data5 = hashMapOf(
        "name" to "Beijing",
        "state" to null,
        "country" to "China",
        "capital" to true,
        "population" to 21500000,
        "regions" to listOf("jingjinji", "hebei"),
    )
    cities.document("BJ").set(data5)
    CollectionReference cities = db.collection("cities");
    
    Map<String, Object> data1 = new HashMap<>();
    data1.put("name", "San Francisco");
    data1.put("state", "CA");
    data1.put("country", "USA");
    data1.put("capital", false);
    data1.put("population", 860000);
    data1.put("regions", Arrays.asList("west_coast", "norcal"));
    cities.document("SF").set(data1);
    
    Map<String, Object> data2 = new HashMap<>();
    data2.put("name", "Los Angeles");
    data2.put("state", "CA");
    data2.put("country", "USA");
    data2.put("capital", false);
    data2.put("population", 3900000);
    data2.put("regions", Arrays.asList("west_coast", "socal"));
    cities.document("LA").set(data2);
    
    Map<String, Object> data3 = new HashMap<>();
    data3.put("name", "Washington D.C.");
    data3.put("state", null);
    data3.put("country", "USA");
    data3.put("capital", true);
    data3.put("population", 680000);
    data3.put("regions", Arrays.asList("east_coast"));
    cities.document("DC").set(data3);
    
    Map<String, Object> data4 = new HashMap<>();
    data4.put("name", "Tokyo");
    data4.put("state", null);
    data4.put("country", "Japan");
    data4.put("capital", true);
    data4.put("population", 9000000);
    data4.put("regions", Arrays.asList("kanto", "honshu"));
    cities.document("TOK").set(data4);
    
    Map<String, Object> data5 = new HashMap<>();
    data5.put("name", "Beijing");
    data5.put("state", null);
    data5.put("country", "China");
    data5.put("capital", true);
    data5.put("population", 21500000);
    data5.put("regions", Arrays.asList("jingjinji", "hebei"));
    cities.document("BJ").set(data5);
    final cities = db.collection("cities");
    final data1 = <String, dynamic>{
      "name": "San Francisco",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 860000,
      "regions": ["west_coast", "norcal"]
    };
    cities.doc("SF").set(data1);
    
    final data2 = <String, dynamic>{
      "name": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 3900000,
      "regions": ["west_coast", "socal"],
    };
    cities.doc("LA").set(data2);
    
    final data3 = <String, dynamic>{
      "name": "Washington D.C.",
      "state": null,
      "country": "USA",
      "capital": true,
      "population": 680000,
      "regions": ["east_coast"]
    };
    cities.doc("DC").set(data3);
    
    final data4 = <String, dynamic>{
      "name": "Tokyo",
      "state": null,
      "country": "Japan",
      "capital": true,
      "population": 9000000,
      "regions": ["kanto", "honshu"]
    };
    cities.doc("TOK").set(data4);
    
    final data5 = <String, dynamic>{
      "name": "Beijing",
      "state": null,
      "country": "China",
      "capital": true,
      "population": 21500000,
      "regions": ["jingjinji", "hebei"],
    };
    cities.doc("BJ").set(data5);
    CollectionReference cities = db.collection("cities");
    List<ApiFuture<WriteResult>> futures = new ArrayList<>();
    futures.add(
        cities
            .document("SF")
            .set(
                new City(
                    "San Francisco",
                    "CA",
                    "USA",
                    false,
                    860000L,
                    Arrays.asList("west_coast", "norcal"))));
    futures.add(
        cities
            .document("LA")
            .set(
                new City(
                    "Los Angeles",
                    "CA",
                    "USA",
                    false,
                    3900000L,
                    Arrays.asList("west_coast", "socal"))));
    futures.add(
        cities
            .document("DC")
            .set(
                new City(
                    "Washington D.C.", null, "USA", true, 680000L, Arrays.asList("east_coast"))));
    futures.add(
        cities
            .document("TOK")
            .set(
                new City(
                    "Tokyo", null, "Japan", true, 9000000L, Arrays.asList("kanto", "honshu"))));
    futures.add(
        cities
            .document("BJ")
            .set(
                new City(
                    "Beijing",
                    null,
                    "China",
                    true,
                    21500000L,
                    Arrays.asList("jingjinji", "hebei"))));
    // (optional) block on operation
    ApiFutures.allAsList(futures).get();
    class City:
        def __init__(self, name, state, country, capital=False, population=0, regions=[]):
            self.name = name
            self.state = state
            self.country = country
            self.capital = capital
            self.population = population
            self.regions = regions
    
        @staticmethod
        def from_dict(source):
            # ...
    
        def to_dict(self):
            # ...
    
        def __repr__(self):
            return f"City(\
                    name={self.name}, \
                    country={self.country}, \
                    population={self.population}, \
                    capital={self.capital}, \
                    regions={self.regions}\
                )"
    cities_ref = db.collection("cities")
    cities_ref.document("BJ").set(
        City("Beijing", None, "China", True, 21500000, ["hebei"]).to_dict()
    )
    cities_ref.document("SF").set(
        City(
            "San Francisco", "CA", "USA", False, 860000, ["west_coast", "norcal"]
        ).to_dict()
    )
    cities_ref.document("LA").set(
        City(
            "Los Angeles", "CA", "USA", False, 3900000, ["west_coast", "socal"]
        ).to_dict()
    )
    cities_ref.document("DC").set(
        City("Washington D.C.", None, "USA", True, 680000, ["east_coast"]).to_dict()
    )
    cities_ref.document("TOK").set(
        City("Tokyo", None, "Japan", True, 9000000, ["kanto", "honshu"]).to_dict()
    )
    cities_ref = db.collection("cities")
    await cities_ref.document("BJ").set(
        City("Beijing", None, "China", True, 21500000, ["hebei"]).to_dict()
    )
    await cities_ref.document("SF").set(
        City(
            "San Francisco", "CA", "USA", False, 860000, ["west_coast", "norcal"]
        ).to_dict()
    )
    await cities_ref.document("LA").set(
        City(
            "Los Angeles", "CA", "USA", False, 3900000, ["west_coast", "socal"]
        ).to_dict()
    )
    await cities_ref.document("DC").set(
        City("Washington D.C.", None, "USA", True, 680000, ["east_coast"]).to_dict()
    )
    await cities_ref.document("TOK").set(
        City("Tokyo", None, "Japan", True, 9000000, ["kanto", "honshu"]).to_dict()
    )
    CollectionReference cities = db->Collection("cities");
    
    cities.Document("SF").Set({
        {"name", FieldValue::String("San Francisco")},
        {"state", FieldValue::String("CA")},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(false)},
        {"population", FieldValue::Integer(860000)},
        {"regions", FieldValue::Array({FieldValue::String("west_coast"),
                                       FieldValue::String("norcal")})},
    });
    
    cities.Document("LA").Set({
        {"name", FieldValue::String("Los Angeles")},
        {"state", FieldValue::String("CA")},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(false)},
        {"population", FieldValue::Integer(3900000)},
        {"regions", FieldValue::Array({FieldValue::String("west_coast"),
                                       FieldValue::String("socal")})},
    });
    
    cities.Document("DC").Set({
        {"name", FieldValue::String("Washington D.C.")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(680000)},
        {"regions",
         FieldValue::Array({FieldValue::String("east_coast")})},
    });
    
    cities.Document("TOK").Set({
        {"name", FieldValue::String("Tokyo")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("Japan")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(9000000)},
        {"regions", FieldValue::Array({FieldValue::String("kanto"),
                                       FieldValue::String("honshu")})},
    });
    
    cities.Document("BJ").Set({
        {"name", FieldValue::String("Beijing")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("China")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(21500000)},
        {"regions", FieldValue::Array({FieldValue::String("jingjinji"),
                                       FieldValue::String("hebei")})},
    });
    const citiesRef = db.collection('cities');
    
    await citiesRef.doc('SF').set({
      name: 'San Francisco', state: 'CA', country: 'USA',
      capital: false, population: 860000
    });
    await citiesRef.doc('LA').set({
      name: 'Los Angeles', state: 'CA', country: 'USA',
      capital: false, population: 3900000
    });
    await citiesRef.doc('DC').set({
      name: 'Washington, D.C.', state: null, country: 'USA',
      capital: true, population: 680000
    });
    await citiesRef.doc('TOK').set({
      name: 'Tokyo', state: null, country: 'Japan',
      capital: true, population: 9000000
    });
    await citiesRef.doc('BJ').set({
      name: 'Beijing', state: null, country: 'China',
      capital: true, population: 21500000
    });
    
    import (
    	"context"
    
    	"cloud.google.com/go/firestore"
    )
    
    func prepareRetrieve(ctx context.Context, client *firestore.Client) error {
    	cities := []struct {
    		id string
    		c  City
    	}{
    		{id: "SF", c: City{Name: "San Francisco", State: "CA", Country: "USA", Capital: false, Population: 860000}},
    		{id: "LA", c: City{Name: "Los Angeles", State: "CA", Country: "USA", Capital: false, Population: 3900000}},
    		{id: "DC", c: City{Name: "Washington D.C.", Country: "USA", Capital: true, Population: 680000}},
    		{id: "TOK", c: City{Name: "Tokyo", Country: "Japan", Capital: true, Population: 9000000}},
    		{id: "BJ", c: City{Name: "Beijing", Country: "China", Capital: true, Population: 21500000}},
    	}
    	for _, c := range cities {
    		_, err := client.Collection("cities").Doc(c.id).Set(ctx, c.c)
    		if err != nil {
    			return err
    		}
    	}
    	return nil
    }
    

    PHP

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

    $citiesRef = $db->collection('samples/php/cities');
    $citiesRef->document('SF')->set([
        'name' => 'San Francisco',
        'state' => 'CA',
        'country' => 'USA',
        'capital' => false,
        'population' => 860000,
        'density' => 18000,
    ]);
    $citiesRef->document('LA')->set([
        'name' => 'Los Angeles',
        'state' => 'CA',
        'country' => 'USA',
        'capital' => false,
        'population' => 3900000,
        'density' => 8000,
    ]);
    $citiesRef->document('DC')->set([
        'name' => 'Washington D.C.',
        'state' => null,
        'country' => 'USA',
        'capital' => true,
        'population' => 680000,
        'density' => 11000,
    ]);
    $citiesRef->document('TOK')->set([
        'name' => 'Tokyo',
        'state' => null,
        'country' => 'Japan',
        'capital' => true,
        'population' => 9000000,
        'density' => 16000,
    
    ]);
    $citiesRef->document('BJ')->set([
        'name' => 'Beijing',
        'state' => null,
        'country' => 'China',
        'capital' => true,
        'population' => 21500000,
        'density' => 3500,
    ]);
    printf('Added example cities data to the cities collection.' . PHP_EOL);
    CollectionReference citiesRef = db.Collection("cities");
    citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){
            { "Name", "San Francisco" },
            { "State", "CA" },
            { "Country", "USA" },
            { "Capital", false },
            { "Population", 860000 }
        }).ContinueWithOnMainThread(task =>
            citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){
                { "Name", "Los Angeles" },
                { "State", "CA" },
                { "Country", "USA" },
                { "Capital", false },
                { "Population", 3900000 }
            })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){
                { "Name", "Washington D.C." },
                { "State", null },
                { "Country", "USA" },
                { "Capital", true },
                { "Population", 680000 }
        })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){
                { "Name", "Tokyo" },
                { "State", null },
                { "Country", "Japan" },
                { "Capital", true },
                { "Population", 9000000 }
        })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){
                { "Name", "Beijing" },
                { "State", null },
                { "Country", "China" },
                { "Capital", true },
                { "Population", 21500000 }
        })
    );
    CollectionReference citiesRef = db.Collection("cities");
    await citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){
        { "Name", "San Francisco" },
        { "State", "CA" },
        { "Country", "USA" },
        { "Capital", false },
        { "Population", 860000 }
    });
    await citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){
        { "Name", "Los Angeles" },
        { "State", "CA" },
        { "Country", "USA" },
        { "Capital", false },
        { "Population", 3900000 }
    });
    await citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){
        { "Name", "Washington D.C." },
        { "State", null },
        { "Country", "USA" },
        { "Capital", true },
        { "Population", 680000 }
    });
    await citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){
        { "Name", "Tokyo" },
        { "State", null },
        { "Country", "Japan" },
        { "Capital", true },
        { "Population", 9000000 }
    });
    await citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){
        { "Name", "Beijing" },
        { "State", null },
        { "Country", "China" },
        { "Capital", true },
        { "Population", 21500000 }
    });
    Console.WriteLine("Added example cities data to the cities collection.");
    cities_ref = firestore.col collection_path
    cities_ref.doc("SF").set(
      {
        name:       "San Francisco",
        state:      "CA",
        country:    "USA",
        capital:    false,
        population: 860_000
      }
    )
    cities_ref.doc("LA").set(
      {
        name:       "Los Angeles",
        state:      "CA",
        country:    "USA",
        capital:    false,
        population: 3_900_000
      }
    )
    cities_ref.doc("DC").set(
      {
        name:       "Washington D.C.",
        state:      nil,
        country:    "USA",
        capital:    true,
        population: 680_000
      }
    )
    cities_ref.doc("TOK").set(
      {
        name:       "Tokyo",
        state:      nil,
        country:    "Japan",
        capital:    true,
        population: 9_000_000
      }
    )
    cities_ref.doc("BJ").set(
      {
        name:       "Beijing",
        state:      nil,
        country:    "China",
        capital:    true,
        population: 21_500_000
      }
    )

    Ricevere un documento

    L'esempio seguente mostra come recuperare i contenuti di un singolo documento utilizzando get():

    import { doc, getDoc } from "firebase/firestore";
    
    const docRef = doc(db, "cities", "SF");
    const docSnap = await getDoc(docRef);
    
    if (docSnap.exists()) {
      console.log("Document data:", docSnap.data());
    } else {
      // docSnap.data() will be undefined in this case
      console.log("No such document!");
    }
    var docRef = db.collection("cities").doc("SF");
    
    docRef.get().then((doc) => {
        if (doc.exists) {
            console.log("Document data:", doc.data());
        } else {
            // doc.data() will be undefined in this case
            console.log("No such document!");
        }
    }).catch((error) => {
        console.log("Error getting document:", error);
    });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    let docRef = db.collection("cities").document("SF")
    
    do {
      let document = try await docRef.getDocument()
      if document.exists {
        let dataDescription = document.data().map(String.init(describing:)) ?? "nil"
        print("Document data: \(dataDescription)")
      } else {
        print("Document does not exist")
      }
    } catch {
      print("Error getting document: \(error)")
    }
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    FIRDocumentReference *docRef =
        [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
    [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      if (snapshot.exists) {
        // Document data may be nil if the document exists but has no keys or values.
        NSLog(@"Document data: %@", snapshot.data);
      } else {
        NSLog(@"Document does not exist");
      }
    }];
    val docRef = db.collection("cities").document("SF")
    docRef.get()
        .addOnSuccessListener { document ->
            if (document != null) {
                Log.d(TAG, "DocumentSnapshot data: ${document.data}")
            } else {
                Log.d(TAG, "No such document")
            }
        }
        .addOnFailureListener { exception ->
            Log.d(TAG, "get failed with ", exception)
        }
    DocumentReference docRef = db.collection("cities").document("SF");
    docRef.get().addOnCompleteListener(new OnCompleteListener<DocumentSnapshot>() {
        @Override
        public void onComplete(@NonNull Task<DocumentSnapshot> task) {
            if (task.isSuccessful()) {
                DocumentSnapshot document = task.getResult();
                if (document.exists()) {
                    Log.d(TAG, "DocumentSnapshot data: " + document.getData());
                } else {
                    Log.d(TAG, "No such document");
                }
            } else {
                Log.d(TAG, "get failed with ", task.getException());
            }
        }
    });
    final docRef = db.collection("cities").doc("SF");
    docRef.get().then(
      (DocumentSnapshot doc) {
        final data = doc.data() as Map<String, dynamic>;
        // ...
      },
      onError: (e) => print("Error getting document: $e"),
    );
    DocumentReference docRef = db.collection("cities").document("SF");
    // asynchronously retrieve the document
    ApiFuture<DocumentSnapshot> future = docRef.get();
    // ...
    // future.get() blocks on response
    DocumentSnapshot document = future.get();
    if (document.exists()) {
      System.out.println("Document data: " + document.getData());
    } else {
      System.out.println("No such document!");
    }
    doc_ref = db.collection("cities").document("SF")
    
    doc = doc_ref.get()
    if doc.exists:
        print(f"Document data: {doc.to_dict()}")
    else:
        print("No such document!")
    doc_ref = db.collection("cities").document("SF")
    
    doc = await doc_ref.get()
    if doc.exists:
        print(f"Document data: {doc.to_dict()}")
    else:
        print("No such document!")
    DocumentReference doc_ref = db->Collection("cities").Document("SF");
    doc_ref.Get().OnCompletion([](const Future<DocumentSnapshot>& future) {
      if (future.error() == Error::kErrorOk) {
        const DocumentSnapshot& document = *future.result();
        if (document.exists()) {
          std::cout << "DocumentSnapshot id: " << document.id() << std::endl;
        } else {
          std::cout << "no such document" << std::endl;
        }
      } else {
        std::cout << "Get failed with: " << future.error_message() << std::endl;
      }
    });
    const cityRef = db.collection('cities').doc('SF');
    const doc = await cityRef.get();
    if (!doc.exists) {
      console.log('No such document!');
    } else {
      console.log('Document data:', doc.data());
    }
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    )
    
    func docAsMap(ctx context.Context, client *firestore.Client) (map[string]interface{}, error) {
    	dsnap, err := client.Collection("cities").Doc("SF").Get(ctx)
    	if err != nil {
    		return nil, err
    	}
    	m := dsnap.Data()
    	fmt.Printf("Document data: %#v\n", m)
    	return m, nil
    }
    

    PHP

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

    $docRef = $db->collection('samples/php/cities')->document('SF');
    $snapshot = $docRef->snapshot();
    
    if ($snapshot->exists()) {
        printf('Document data:' . PHP_EOL);
        print_r($snapshot->data());
    } else {
        printf('Document %s does not exist!' . PHP_EOL, $snapshot->id());
    }
    DocumentReference docRef = db.Collection("cities").Document("SF");
    docRef.GetSnapshotAsync().ContinueWithOnMainThread(task =>
    {
      DocumentSnapshot snapshot = task.Result;
      if (snapshot.Exists) {
        Debug.Log(String.Format("Document data for {0} document:", snapshot.Id));
        Dictionary<string, object> city = snapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city) {
          Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value));
        }
      } else {
        Debug.Log(String.Format("Document {0} does not exist!", snapshot.Id));
      }
    });
    DocumentReference docRef = db.Collection("cities").Document("SF");
    DocumentSnapshot snapshot = await docRef.GetSnapshotAsync();
    if (snapshot.Exists)
    {
        Console.WriteLine("Document data for {0} document:", snapshot.Id);
        Dictionary<string, object> city = snapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city)
        {
            Console.WriteLine("{0}: {1}", pair.Key, pair.Value);
        }
    }
    else
    {
        Console.WriteLine("Document {0} does not exist!", snapshot.Id);
    }
    doc_ref  = firestore.doc "#{collection_path}/SF"
    snapshot = doc_ref.get
    if snapshot.exists?
      puts "#{snapshot.document_id} data: #{snapshot.data}."
    else
      puts "Document #{snapshot.document_id} does not exist!"
    end

    Opzioni di origine

    Per le piattaforme con supporto offline, puoi impostare l'opzione source per controllare come una chiamata get utilizza la cache offline.

    Per impostazione predefinita, una chiamata get tenterà di recuperare l'ultimo snapshot del documento dal tuo database. Sulle piattaforme con supporto offline, la libreria client utilizzerà la cache offline se la rete non è disponibile o se la richiesta scade.

    Puoi specificare l'opzione source in una chiamata get() per modificare il comportamento predefinito. Puoi recuperare i dati solo dal database e ignorare la cache offline oppure solo dalla cache offline. Ad esempio:

    import { doc, getDocFromCache } from "firebase/firestore";
    
    const docRef = doc(db, "cities", "SF");
    
    // Get a document, forcing the SDK to fetch from the offline cache.
    try {
      const doc = await getDocFromCache(docRef);
    
      // Document was found in the cache. If no cached document exists,
      // an error will be returned to the 'catch' block below.
      console.log("Cached document data:", doc.data());
    } catch (e) {
      console.log("Error getting cached document:", e);
    }
    var docRef = db.collection("cities").doc("SF");
    
    // Valid options for source are 'server', 'cache', or
    // 'default'. See https://firebase.google.com/docs/reference/js/v8/firebase.firestore.GetOptions
    // for more information.
    var getOptions = {
        source: 'cache'
    };
    
    // Get a document, forcing the SDK to fetch from the offline cache.
    docRef.get(getOptions).then((doc) => {
        // Document was found in the cache. If no cached document exists,
        // an error will be returned to the 'catch' block below.
        console.log("Cached document data:", doc.data());
    }).catch((error) => {
        console.log("Error getting cached document:", error);
    });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    let docRef = db.collection("cities").document("SF")
    
    do {
      // Force the SDK to fetch the document from the cache. Could also specify
      // FirestoreSource.server or FirestoreSource.default.
      let document = try await docRef.getDocument(source: .cache)
      if document.exists {
        let dataDescription = document.data().map(String.init(describing:)) ?? "nil"
        print("Cached document data: \(dataDescription)")
      } else {
        print("Document does not exist in cache")
      }
    } catch {
      print("Error getting document: \(error)")
    }
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    FIRDocumentReference *docRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
    
    // Force the SDK to fetch the document from the cache. Could also specify
    // FIRFirestoreSourceServer or FIRFirestoreSourceDefault.
    [docRef getDocumentWithSource:FIRFirestoreSourceCache
                       completion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      if (snapshot != NULL) {
        // The document data was found in the cache.
        NSLog(@"Cached document data: %@", snapshot.data);
      } else {
        // The document data was not found in the cache.
        NSLog(@"Document does not exist in cache: %@", error);
      }
    }];
    val docRef = db.collection("cities").document("SF")
    
    // Source can be CACHE, SERVER, or DEFAULT.
    val source = Source.CACHE
    
    // Get the document, forcing the SDK to use the offline cache
    docRef.get(source).addOnCompleteListener { task ->
        if (task.isSuccessful) {
            // Document found in the offline cache
            val document = task.result
            Log.d(TAG, "Cached document data: ${document?.data}")
        } else {
            Log.d(TAG, "Cached get failed: ", task.exception)
        }
    }
    DocumentReference docRef = db.collection("cities").document("SF");
    
    // Source can be CACHE, SERVER, or DEFAULT.
    Source source = Source.CACHE;
    
    // Get the document, forcing the SDK to use the offline cache
    docRef.get(source).addOnCompleteListener(new OnCompleteListener<DocumentSnapshot>() {
        @Override
        public void onComplete(@NonNull Task<DocumentSnapshot> task) {
            if (task.isSuccessful()) {
                // Document found in the offline cache
                DocumentSnapshot document = task.getResult();
                Log.d(TAG, "Cached document data: " + document.getData());
            } else {
                Log.d(TAG, "Cached get failed: ", task.getException());
            }
        }
    });
    final docRef = db.collection("cities").doc("SF");
    
    // Source can be CACHE, SERVER, or DEFAULT.
    const source = Source.cache;
    
    docRef.get(const GetOptions(source: source)).then(
          (res) => print("Successfully completed"),
          onError: (e) => print("Error completing: $e"),
        );

    Non supportato nell'SDK Java.

    Non supportato nell'SDK Python.

    DocumentReference doc_ref = db->Collection("cities").Document("SF");
    Source source = Source::kCache;
    doc_ref.Get(source).OnCompletion([](const Future<DocumentSnapshot>& future) {
      if (future.error() == Error::kErrorOk) {
        const DocumentSnapshot& document = *future.result();
        if (document.exists()) {
          std::cout << "Cached document id: " << document.id() << std::endl;
        } else {
        }
      } else {
        std::cout << "Cached get failed: " << future.error_message() << std::endl;
      }
    });

    Non supportato nell'SDK Node.js.

    Non supportato nell'SDK Go.

    Non supportato nell'SDK PHP.

    Non supportato nell'SDK Unity.

    Non supportato nell'SDK C#.

    Non supportato nell'SDK Ruby.

    Oggetti personalizzati

    L'esempio precedente ha recuperato i contenuti del documento come mappa, ma in alcune lingue è spesso più pratico utilizzare un tipo di oggetto personalizzato. In Aggiungi dati, hai definito una classe City che hai utilizzato per definire ogni città. Puoi ripristinare il documento in un oggetto City:

    Per utilizzare oggetti personalizzati, devi definire una funzione FirestoreDataConverter per la tua classe. Ad esempio:

    class City {
        constructor (name, state, country ) {
            this.name = name;
            this.state = state;
            this.country = country;
        }
        toString() {
            return this.name + ', ' + this.state + ', ' + this.country;
        }
    }
    
    // Firestore data converter
    const cityConverter = {
        toFirestore: (city) => {
            return {
                name: city.name,
                state: city.state,
                country: city.country
                };
        },
        fromFirestore: (snapshot, options) => {
            const data = snapshot.data(options);
            return new City(data.name, data.state, data.country);
        }
    };

    Per utilizzare oggetti personalizzati, devi definire una funzione FirestoreDataConverter per la tua classe. Ad esempio:

    class City {
        constructor (name, state, country ) {
            this.name = name;
            this.state = state;
            this.country = country;
        }
        toString() {
            return this.name + ', ' + this.state + ', ' + this.country;
        }
    }
    
    // Firestore data converter
    var cityConverter = {
        toFirestore: function(city) {
            return {
                name: city.name,
                state: city.state,
                country: city.country
                };
        },
        fromFirestore: function(snapshot, options){
            const data = snapshot.data(options);
            return new City(data.name, data.state, data.country);
        }
    };

    Chiama il convertitore di dati con le operazioni di lettura. Dopo la conversione, puoi accedere ai metodi degli oggetti personalizzati:

    import { doc, getDoc} from "firebase/firestore"; 
    
    const ref = doc(db, "cities", "LA").withConverter(cityConverter);
    const docSnap = await getDoc(ref);
    if (docSnap.exists()) {
      // Convert to City object
      const city = docSnap.data();
      // Use a City instance method
      console.log(city.toString());
    } else {
      console.log("No such document!");
    }

    Chiama il convertitore di dati con le operazioni di lettura. Dopo la conversione, puoi accedere ai metodi degli oggetti personalizzati:

    db.collection("cities").doc("LA")
      .withConverter(cityConverter)
      .get().then((doc) => {
        if (doc.exists){
          // Convert to City object
          var city = doc.data();
          // Use a City instance method
          console.log(city.toString());
        } else {
          console.log("No such document!");
        }}).catch((error) => {
          console.log("Error getting document:", error);
        });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

    Per supportare la serializzazione automatica dei tipi in Swift, il tipo deve essere conforme al protocollo Codable.

    let docRef = db.collection("cities").document("BJ")
    
    do {
      let city = try await docRef.getDocument(as: City.self)
      print("City: \(city)")
    } catch {
      print("Error decoding city: \(error)")
    }
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.

    In Objective-C devi farlo manualmente.

    FIRDocumentReference *docRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"];
    [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      FSTCity *city = [[FSTCity alloc] initWithDictionary:snapshot.data];
      if (city != nil) {
        NSLog(@"City: %@", city);
      } else {
        NSLog(@"Document does not exist");
      }
    }];
    val docRef = db.collection("cities").document("BJ")
    docRef.get().addOnSuccessListener { documentSnapshot ->
        val city = documentSnapshot.toObject<City>()
    }

    Importante: ogni classe personalizzata deve avere un costruttore pubblico che non accetta argomenti. Inoltre, la classe deve includere un getter pubblico per ogni proprietà.

    DocumentReference docRef = db.collection("cities").document("BJ");
    docRef.get().addOnSuccessListener(new OnSuccessListener<DocumentSnapshot>() {
        @Override
        public void onSuccess(DocumentSnapshot documentSnapshot) {
            City city = documentSnapshot.toObject(City.class);
        }
    });

    Per utilizzare oggetti personalizzati, devi definire le funzioni di conversione dei dati di Firestore per la tua classe. Ad esempio:

    class City {
      final String? name;
      final String? state;
      final String? country;
      final bool? capital;
      final int? population;
      final List<String>? regions;
    
      City({
        this.name,
        this.state,
        this.country,
        this.capital,
        this.population,
        this.regions,
      });
    
      factory City.fromFirestore(
        DocumentSnapshot<Map<String, dynamic>> snapshot,
        SnapshotOptions? options,
      ) {
        final data = snapshot.data();
        return City(
          name: data?['name'],
          state: data?['state'],
          country: data?['country'],
          capital: data?['capital'],
          population: data?['population'],
          regions:
              data?['regions'] is Iterable ? List.from(data?['regions']) : null,
        );
      }
    
      Map<String, dynamic> toFirestore() {
        return {
          if (name != null) "name": name,
          if (state != null) "state": state,
          if (country != null) "country": country,
          if (capital != null) "capital": capital,
          if (population != null) "population": population,
          if (regions != null) "regions": regions,
        };
      }
    }

    Quindi, crea un riferimento a un documento con le funzioni di conversione dei dati. Eventuali operazioni di lettura eseguite utilizzando questo riferimento restituiranno istanze della tua classe personalizzata:

    final ref = db.collection("cities").doc("LA").withConverter(
          fromFirestore: City.fromFirestore,
          toFirestore: (City city, _) => city.toFirestore(),
        );
    final docSnap = await ref.get();
    final city = docSnap.data(); // Convert to City object
    if (city != null) {
      print(city);
    } else {
      print("No such document.");
    }

    Ogni classe personalizzata deve avere un costruttore pubblico che non accetta argomenti. Inoltre, la classe deve includere un getter pubblico per ogni proprietà.

    DocumentReference docRef = db.collection("cities").document("BJ");
    // asynchronously retrieve the document
    ApiFuture<DocumentSnapshot> future = docRef.get();
    // block on response
    DocumentSnapshot document = future.get();
    City city = null;
    if (document.exists()) {
      // convert document to POJO
      city = document.toObject(City.class);
      System.out.println(city);
    } else {
      System.out.println("No such document!");
    }
    doc_ref = db.collection("cities").document("BJ")
    
    doc = doc_ref.get()
    city = City.from_dict(doc.to_dict())
    print(city)
    doc_ref = db.collection("cities").document("BJ")
    
    doc = await doc_ref.get()
    city = City.from_dict(doc.to_dict())
    print(city)
    // This is not yet supported.

    Node.js utilizza oggetti JavaScript.

    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    )
    
    func docAsEntity(ctx context.Context, client *firestore.Client) (*City, error) {
    	dsnap, err := client.Collection("cities").Doc("BJ").Get(ctx)
    	if err != nil {
    		return nil, err
    	}
    	var c City
    	dsnap.DataTo(&c)
    	fmt.Printf("Document data: %#v\n", c)
    	return &c, nil
    }
    

    PHP

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

    $docRef = $db->collection('samples/php/cities')->document('SF');
    $snapshot = $docRef->snapshot();
    $city = City::fromArray($snapshot->data());
    
    if ($snapshot->exists()) {
        printf('Document data:' . PHP_EOL);
        print((string) $city);
    } else {
        printf('Document %s does not exist!' . PHP_EOL, $snapshot->id());
    }
    DocumentReference docRef = db.Collection("cities").Document("BJ");
    
    docRef.GetSnapshotAsync().ContinueWith((task) =>
    {
      var snapshot = task.Result;
      if (snapshot.Exists)
      {
        Debug.Log(String.Format("Document data for {0} document:", snapshot.Id));
        City city = snapshot.ConvertTo<City>();
        Debug.Log(String.Format("Name: {0}", city.Name));
        Debug.Log(String.Format("State: {0}", city.State));
        Debug.Log(String.Format("Country: {0}", city.Country));
        Debug.Log(String.Format("Capital: {0}", city.Capital));
        Debug.Log(String.Format("Population: {0}", city.Population));
      }
      else
      {
        Debug.Log(String.Format("Document {0} does not exist!", snapshot.Id));
      }
    });
    DocumentReference docRef = db.Collection("cities").Document("BJ");
    DocumentSnapshot snapshot = await docRef.GetSnapshotAsync();
    if (snapshot.Exists)
    {
        Console.WriteLine("Document data for {0} document:", snapshot.Id);
        City city = snapshot.ConvertTo<City>();
        Console.WriteLine("Name: {0}", city.Name);
        Console.WriteLine("State: {0}", city.State);
        Console.WriteLine("Country: {0}", city.Country);
        Console.WriteLine("Capital: {0}", city.Capital);
        Console.WriteLine("Population: {0}", city.Population);
    }
    else
    {
        Console.WriteLine("Document {0} does not exist!", snapshot.Id);
    }

    Non applicabile a Ruby.

    Recuperare più documenti da una raccolta

    Puoi anche recuperare più documenti con una sola richiesta eseguendo query sui documenti in una raccolta. Ad esempio, puoi utilizzare where() per eseguire una query su tutti i documenti che soddisfano una determinata condizione, quindi utilizzare get() per recuperare i risultati:

    import { collection, query, where, getDocs } from "firebase/firestore";
    
    const q = query(collection(db, "cities"), where("capital", "==", true));
    
    const querySnapshot = await getDocs(q);
    querySnapshot.forEach((doc) => {
      // doc.data() is never undefined for query doc snapshots
      console.log(doc.id, " => ", doc.data());
    });
    db.collection("cities").where("capital", "==", true)
        .get()
        .then((querySnapshot) => {
            querySnapshot.forEach((doc) => {
                // doc.data() is never undefined for query doc snapshots
                console.log(doc.id, " => ", doc.data());
            });
        })
        .catch((error) => {
            console.log("Error getting documents: ", error);
        });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    do {
      let querySnapshot = try await db.collection("cities").whereField("capital", isEqualTo: true)
        .getDocuments()
      for document in querySnapshot.documents {
        print("\(document.documentID) => \(document.data())")
      }
    } catch {
      print("Error getting documents: \(error)")
    }
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    [[[self.db collectionWithPath:@"cities"] queryWhereField:@"capital" isEqualTo:@(YES)]
        getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) {
          if (error != nil) {
            NSLog(@"Error getting documents: %@", error);
          } else {
            for (FIRDocumentSnapshot *document in snapshot.documents) {
              NSLog(@"%@ => %@", document.documentID, document.data);
            }
          }
        }];
    db.collection("cities")
        .whereEqualTo("capital", true)
        .get()
        .addOnSuccessListener { documents ->
            for (document in documents) {
                Log.d(TAG, "${document.id} => ${document.data}")
            }
        }
        .addOnFailureListener { exception ->
            Log.w(TAG, "Error getting documents: ", exception)
        }
    db.collection("cities")
            .whereEqualTo("capital", true)
            .get()
            .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
                @Override
                public void onComplete(@NonNull Task<QuerySnapshot> task) {
                    if (task.isSuccessful()) {
                        for (QueryDocumentSnapshot document : task.getResult()) {
                            Log.d(TAG, document.getId() + " => " + document.getData());
                        }
                    } else {
                        Log.d(TAG, "Error getting documents: ", task.getException());
                    }
                }
            });
    db.collection("cities").where("capital", isEqualTo: true).get().then(
      (querySnapshot) {
        print("Successfully completed");
        for (var docSnapshot in querySnapshot.docs) {
          print('${docSnapshot.id} => ${docSnapshot.data()}');
        }
      },
      onError: (e) => print("Error completing: $e"),
    );
    // asynchronously retrieve multiple documents
    ApiFuture<QuerySnapshot> future = db.collection("cities").whereEqualTo("capital", true).get();
    // future.get() blocks on response
    List<QueryDocumentSnapshot> documents = future.get().getDocuments();
    for (DocumentSnapshot document : documents) {
      System.out.println(document.getId() + " => " + document.toObject(City.class));
    }
    # Note: Use of CollectionRef stream() is prefered to get()
    docs = (
        db.collection("cities")
        .where(filter=FieldFilter("capital", "==", True))
        .stream()
    )
    
    for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")
    # Note: Use of CollectionRef stream() is prefered to get()
    docs = (
        db.collection("cities")
        .where(filter=FieldFilter("capital", "==", True))
        .stream()
    )
    
    async for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")
    db->Collection("cities")
        .WhereEqualTo("capital", FieldValue::Boolean(true))
        .Get()
        .OnCompletion([](const Future<QuerySnapshot>& future) {
          if (future.error() == Error::kErrorOk) {
            for (const DocumentSnapshot& document :
                 future.result()->documents()) {
              std::cout << document << std::endl;
            }
          } else {
            std::cout << "Error getting documents: " << future.error_message()
                      << std::endl;
          }
        });
    const citiesRef = db.collection('cities');
    const snapshot = await citiesRef.where('capital', '==', true).get();
    if (snapshot.empty) {
      console.log('No matching documents.');
      return;
    }  
    
    snapshot.forEach(doc => {
      console.log(doc.id, '=>', doc.data());
    });
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    	"google.golang.org/api/iterator"
    )
    
    func multipleDocs(ctx context.Context, client *firestore.Client) error {
    	fmt.Println("All capital cities:")
    	iter := client.Collection("cities").Where("capital", "==", true).Documents(ctx)
    	for {
    		doc, err := iter.Next()
    		if err == iterator.Done {
    			break
    		}
    		if err != nil {
    			return err
    		}
    		fmt.Println(doc.Data())
    	}
    	return nil
    }
    

    PHP

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

    $citiesRef = $db->collection('samples/php/cities');
    $query = $citiesRef->where('capital', '=', true);
    $documents = $query->documents();
    foreach ($documents as $document) {
        if ($document->exists()) {
            printf('Document data for document %s:' . PHP_EOL, $document->id());
            print_r($document->data());
            printf(PHP_EOL);
        } else {
            printf('Document %s does not exist!' . PHP_EOL, $document->id());
        }
    }
    Query capitalQuery = db.Collection("cities").WhereEqualTo("Capital", true);
    capitalQuery.GetSnapshotAsync().ContinueWithOnMainThread(task => {
      QuerySnapshot capitalQuerySnapshot = task.Result;
      foreach (DocumentSnapshot documentSnapshot in capitalQuerySnapshot.Documents) {
        Debug.Log(String.Format("Document data for {0} document:", documentSnapshot.Id));
        Dictionary<string, object> city = documentSnapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city) {
          Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value));
        }
    
        // Newline to separate entries
        Debug.Log("");
      };
    });
    Query capitalQuery = db.Collection("cities").WhereEqualTo("Capital", true);
    QuerySnapshot capitalQuerySnapshot = await capitalQuery.GetSnapshotAsync();
    foreach (DocumentSnapshot documentSnapshot in capitalQuerySnapshot.Documents)
    {
        Console.WriteLine("Document data for {0} document:", documentSnapshot.Id);
        Dictionary<string, object> city = documentSnapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city)
        {
            Console.WriteLine("{0}: {1}", pair.Key, pair.Value);
        }
        Console.WriteLine("");
    }
    cities_ref = firestore.col collection_path
    
    query = cities_ref.where "capital", "=", true
    
    query.get do |city|
      puts "#{city.document_id} data: #{city.data}."
    end

    Per impostazione predefinita, Cloud Firestore recupera tutti i documenti che soddisfano la query in ordine crescente per ID documento, ma puoi ordinare e limitare i dati restituiti.

    Recuperare tutti i documenti di una raccolta

    Inoltre, puoi recuperare tutti i documenti di una raccolta omettendo del tutto il where() filtro:

    import { collection, getDocs } from "firebase/firestore";
    
    const querySnapshot = await getDocs(collection(db, "cities"));
    querySnapshot.forEach((doc) => {
      // doc.data() is never undefined for query doc snapshots
      console.log(doc.id, " => ", doc.data());
    });
    db.collection("cities").get().then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    });
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    do {
      let querySnapshot = try await db.collection("cities").getDocuments()
      for document in querySnapshot.documents {
        print("\(document.documentID) => \(document.data())")
      }
    } catch {
      print("Error getting documents: \(error)")
    }
    Nota:questo prodotto non è disponibile come target per watchOS e App Clip.
    [[self.db collectionWithPath:@"cities"]
        getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) {
          if (error != nil) {
            NSLog(@"Error getting documents: %@", error);
          } else {
            for (FIRDocumentSnapshot *document in snapshot.documents) {
              NSLog(@"%@ => %@", document.documentID, document.data);
            }
          }
        }];
    db.collection("cities")
        .get()
        .addOnSuccessListener { result ->
            for (document in result) {
                Log.d(TAG, "${document.id} => ${document.data}")
            }
        }
        .addOnFailureListener { exception ->
            Log.d(TAG, "Error getting documents: ", exception)
        }
    db.collection("cities")
            .get()
            .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
                @Override
                public void onComplete(@NonNull Task<QuerySnapshot> task) {
                    if (task.isSuccessful()) {
                        for (QueryDocumentSnapshot document : task.getResult()) {
                            Log.d(TAG, document.getId() + " => " + document.getData());
                        }
                    } else {
                        Log.d(TAG, "Error getting documents: ", task.getException());
                    }
                }
            });
    db.collection("cities").get().then(
      (querySnapshot) {
        print("Successfully completed");
        for (var docSnapshot in querySnapshot.docs) {
          print('${docSnapshot.id} => ${docSnapshot.data()}');
        }
      },
      onError: (e) => print("Error completing: $e"),
    );
    // asynchronously retrieve all documents
    ApiFuture<QuerySnapshot> future = db.collection("cities").get();
    // future.get() blocks on response
    List<QueryDocumentSnapshot> documents = future.get().getDocuments();
    for (QueryDocumentSnapshot document : documents) {
      System.out.println(document.getId() + " => " + document.toObject(City.class));
    }
    docs = db.collection("cities").stream()
    
    for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")
    docs = db.collection("cities").stream()
    
    async for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")
    db->Collection("cities").Get().OnCompletion(
        [](const Future<QuerySnapshot>& future) {
          if (future.error() == Error::kErrorOk) {
            for (const DocumentSnapshot& document :
                 future.result()->documents()) {
              std::cout << document << std::endl;
            }
          } else {
            std::cout << "Error getting documents: " << future.error_message()
                      << std::endl;
          }
        });
    const citiesRef = db.collection('cities');
    const snapshot = await citiesRef.get();
    snapshot.forEach(doc => {
      console.log(doc.id, '=>', doc.data());
    });
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    	"google.golang.org/api/iterator"
    )
    
    func allDocs(ctx context.Context, client *firestore.Client) error {
    	fmt.Println("All cities:")
    	iter := client.Collection("cities").Documents(ctx)
    	defer iter.Stop()
    	for {
    		doc, err := iter.Next()
    		if err == iterator.Done {
    			break
    		}
    		if err != nil {
    			return err
    		}
    		fmt.Println(doc.Data())
    	}
    	return nil
    }
    

    PHP

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

    $citiesRef = $db->collection('samples/php/cities');
    $documents = $citiesRef->documents();
    foreach ($documents as $document) {
        if ($document->exists()) {
            printf('Document data for document %s:' . PHP_EOL, $document->id());
            print_r($document->data());
            printf(PHP_EOL);
        } else {
            printf('Document %s does not exist!' . PHP_EOL, $document->id());
        }
    }
    Query allCitiesQuery = db.Collection("cities");
    allCitiesQuery.GetSnapshotAsync().ContinueWithOnMainThread(task =>
    {
      QuerySnapshot allCitiesQuerySnapshot = task.Result;
      foreach (DocumentSnapshot documentSnapshot in allCitiesQuerySnapshot.Documents)
      {
        Debug.Log(String.Format("Document data for {0} document:", documentSnapshot.Id));
        Dictionary<string, object> city = documentSnapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city)
        {
          Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value));
        }
    
        // Newline to separate entries
        Debug.Log("");
      }
    });
    Query allCitiesQuery = db.Collection("cities");
    QuerySnapshot allCitiesQuerySnapshot = await allCitiesQuery.GetSnapshotAsync();
    foreach (DocumentSnapshot documentSnapshot in allCitiesQuerySnapshot.Documents)
    {
        Console.WriteLine("Document data for {0} document:", documentSnapshot.Id);
        Dictionary<string, object> city = documentSnapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city)
        {
            Console.WriteLine("{0}: {1}", pair.Key, pair.Value);
        }
        Console.WriteLine("");
    }
    cities_ref = firestore.col collection_path
    cities_ref.get do |city|
      puts "#{city.document_id} data: #{city.data}."
    end

    Recupera tutti i documenti di una sottoraccolta

    Per recuperare tutti i documenti di una sottoraccolta, crea un riferimento con il percorso completo della sottoraccolta:

    const { collection, getDocs } = require("firebase/firestore");
    // Query a reference to a subcollection
    const querySnapshot = await getDocs(collection(db, "cities", "SF", "landmarks"));
    querySnapshot.forEach((doc) => {
      // doc.data() is never undefined for query doc snapshots
      console.log(doc.id, " => ", doc.data());
    });
    // Snippet not available
    do {
      let querySnapshot = try await db.collection("cities/SF/landmarks").getDocuments()
      for document in querySnapshot.documents {
        print("\(document.documentID) => \(document.data())")
      }
    } catch {
      print("Error getting documents: \(error)")
    }
    [[self.db collectionWithPath:@"cities/SF/landmarks"]
        getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) {
          if (error != nil) {
            NSLog(@"Error getting documents: %@", error);
          } else {
            for (FIRDocumentSnapshot *document in snapshot.documents) {
              NSLog(@"%@ => %@", document.documentID, document.data);
            }
          }
        }];
    db.collection("cities")
        .document("SF")
        .collection("landmarks")
        .get()
        .addOnSuccessListener { result ->
            for (document in result) {
                Log.d(TAG, "${document.id} => ${document.data}")
            }
        }
        .addOnFailureListener { exception ->
            Log.d(TAG, "Error getting documents: ", exception)
        }
    db.collection("cities")
            .document("SF")
            .collection("landmarks")
            .get()
            .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
                @Override
                public void onComplete(@NonNull Task<QuerySnapshot> task) {
                    if (task.isSuccessful()) {
                        for (QueryDocumentSnapshot document : task.getResult()) {
                            Log.d(TAG, document.getId() + " => " + document.getData());
                        }
                    } else {
                        Log.d(TAG, "Error getting documents: ", task.getException());
                    }
                }
            });
    db.collection("cities").doc("SF").collection("landmarks").get().then(
      (querySnapshot) {
        print("Successfully completed");
        for (var docSnapshot in querySnapshot.docs) {
          print('${docSnapshot.id} => ${docSnapshot.data()}');
        }
      },
      onError: (e) => print("Error completing: $e"),
    );
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available
    // Snippet not available

    Recuperare più documenti da un gruppo di raccolte

    Un gruppo di raccolte è costituito da tutte le raccolte con lo stesso ID. Ad esempio, se ogni documento della raccolta cities ha una raccolta secondaria denominata landmarks, tutte le raccolte secondarie landmarks appartengono allo stesso gruppo di raccolte. Per impostazione predefinita, le query recuperano i risultati da una singola raccolta nel database. Utilizza una query sul gruppo di raccolte per recuperare i risultati da un gruppo di raccolte anziché da una singola raccolta.

    Elenca le sottocollezioni di un documento

    Il metodo listCollections() delle librerie client server Cloud Firestore elenca tutte le sottoraccolte di un riferimento a un documento.

    Non è possibile recuperare un elenco di raccolte con le librerie client web/per dispositivi mobili. Devi cercare i nomi delle raccolte solo nell'ambito delle attività amministrative in ambienti di server attendibili. Se ritieni di aver bisogno di questa funzionalità nelle librerie client mobile/web, ti consigliamo di ristrutturare i dati in modo che i nomi delle sottocollezioni siano prevedibili.

    Non disponibile nella raccolta dei client web.

    Non disponibile nella libreria client Swift.

    Non disponibile nella libreria client Objective-C.

    Non disponibile nella libreria client Android.

    Non disponibile nella libreria client Android.

    Non disponibile nella libreria client Flutter.

    Iterable<CollectionReference> collections =
        db.collection("cities").document("SF").listCollections();
    
    for (CollectionReference collRef : collections) {
      System.out.println("Found subcollection with id: " + collRef.getId());
    }
    city_ref = db.collection("cities").document("SF")
    collections = city_ref.collections()
    for collection in collections:
        for doc in collection.stream():
            print(f"{doc.id} => {doc.to_dict()}")
    collections = db.collection("cities").document("SF").collections()
    async for collection in collections:
        async for doc in collection.stream():
            print(f"{doc.id} => {doc.to_dict()}")

    Non disponibile nella libreria client C++.

    const sfRef = db.collection('cities').doc('SF');
    const collections = await sfRef.listCollections();
    collections.forEach(collection => {
      console.log('Found subcollection with id:', collection.id);
    });
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    	"google.golang.org/api/iterator"
    )
    
    func getCollections(ctx context.Context, client *firestore.Client) error {
    	iter := client.Collection("cities").Doc("SF").Collections(ctx)
    	for {
    		collRef, err := iter.Next()
    		if err == iterator.Done {
    			break
    		}
    		if err != nil {
    			return err
    		}
    		fmt.Printf("Found collection with id: %s\n", collRef.ID)
    	}
    	return nil
    }
    

    PHP

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

    $cityRef = $db->collection('samples/php/cities')->document('SF');
    $collections = $cityRef->collections();
    foreach ($collections as $collection) {
        printf('Found subcollection with id: %s' . PHP_EOL, $collection->id());
    }
    // This is not yet supported in the Unity SDK.
    DocumentReference cityRef = db.Collection("cities").Document("SF");
    IAsyncEnumerable<CollectionReference> subcollections = cityRef.ListCollectionsAsync();
    IAsyncEnumerator<CollectionReference> subcollectionsEnumerator = subcollections.GetAsyncEnumerator(default);
    while (await subcollectionsEnumerator.MoveNextAsync())
    {
        CollectionReference subcollectionRef = subcollectionsEnumerator.Current;
        Console.WriteLine("Found subcollection with ID: {0}", subcollectionRef.Id);
    }
    city_ref = firestore.doc "#{collection_path}/SF"
    city_ref.cols do |col|
      puts col.collection_id
    end

    Scopri di più sui diversi tipi di query.

    Per ulteriori informazioni sui codici di errore e su come risolvere i problemi di latenza durante l'ottenimento dei dati, consulta la pagina relativa alla risoluzione dei problemi.