Accéder aux données hors connexion

Cloud Firestore est compatible avec la persistance des données hors connexion. Cette fonctionnalité met en cache une copie des données Cloud Firestore utilisées activement par votre application, afin que votre application puisse accéder aux données lorsque l'appareil est hors connexion. Vous pouvez écrire, lire, écouter et interroger les données mises en cache. Lorsque l'appareil est de nouveau en ligne, Cloud Firestore synchronise toutes les modifications locales apportées par votre application au backend Cloud Firestore.

Remarque : La persistance hors connexion n'est compatible qu'avec les applications Android, Apple et Web.

Pour utiliser la persistance hors connexion, vous n'avez pas besoin d'apporter de modifications au code que vous utilisez pour accéder aux données Cloud Firestore. Si la persistance hors connexion est activée, la bibliothèque cliente Cloud Firestore gère automatiquement l'accès aux données en ligne et hors connexion, et synchronise les données locales lorsque l'appareil est de nouveau connecté.

Configurer la persistance hors connexion

Lorsque vous initialisez Cloud Firestore, vous pouvez activer ou désactiver la persistance hors connexion:

• Pour les plates-formes Android et Apple, la persistance hors connexion est activée par défaut. Pour désactiver la persistance, définissez l'option PersistenceEnabled sur false.
• Pour le Web, la persistance hors connexion est désactivée par défaut. Pour activer la persistance, appelez la méthode enablePersistence. Le cache de Cloud Firestore n'est pas automatiquement vidé entre les sessions. Par conséquent, si votre application Web traite des informations sensibles, demandez à l'utilisateur s'il utilise un appareil fiable avant d'activer la persistance

Important : Pour le Web, la persistance hors connexion n'est compatible qu'avec les navigateurs Chrome, Safari et Firefox.

Web

Apprenez-en plus sur le SDK modulaire Web v9 pouvant être allégé par "tree shaking" et sur la mise à niveau depuis la version 8.

// Memory cache is the default if no config is specified.
initializeFirestore(app);

// This is the default behavior if no persistence is specified.
initializeFirestore(app, {localCache: memoryLocalCache()});

// Defaults to single-tab persistence if no tab manager is specified.
initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})});

// Same as `initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})})`,
// but more explicit about tab management.
initializeFirestore(app, 
  {localCache: 
    persistentLocalCache(/*settings*/{tabManager: persistentSingleTabManager()})
});

// Use multi-tab IndexedDb persistence.
initializeFirestore(app, 
  {localCache: 
    persistentLocalCache(/*settings*/{tabManager: persistentMultipleTabManager()})
  });
  

Web

Apprenez-en plus sur le SDK modulaire Web v9 pouvant être allégé par "tree shaking" et sur la mise à niveau depuis la version 8.

firebase.firestore().enablePersistence()
  .catch((err) => {
      if (err.code == 'failed-precondition') {
          // Multiple tabs open, persistence can only be enabled
          // in one tab at a a time.
          // ...
      } else if (err.code == 'unimplemented') {
          // The current browser does not support all of the
          // features required to enable persistence
          // ...
      }
  });
// Subsequent queries will use persistence, if it was enabled successfully
test.firestore.js

Swift

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

let settings = FirestoreSettings()

// Use memory-only cache
settings.cacheSettings =
MemoryCacheSettings(garbageCollectorSettings: MemoryLRUGCSettings())

// Use persistent disk cache, with 100 MB cache size
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber)

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
ViewController.swift

Objective-C

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];

// Use memory-only cache
settings.cacheSettings = [[FIRMemoryCacheSettings alloc]
    initWithGarbageCollectorSettings:[[FIRMemoryLRUGCSettings alloc] init]];

// Use persistent disk cache (default behavior)
// This example uses 100 MB.
settings.cacheSettings = [[FIRPersistentCacheSettings alloc]
    initWithSizeBytes:@(100 * 1024 * 1024)];

// Any additional options
// ...

// Enable offline data persistence
FIRFirestore *db = [FIRFirestore firestore];
db.settings = settings;
ViewController.m

Kotlin

val settings = firestoreSettings {
    // Use memory cache
    setLocalCacheSettings(memoryCacheSettings {})
    // Use persistent disk cache (default)
    setLocalCacheSettings(persistentCacheSettings {})
}
db.firestoreSettings = settings
DocSnippets.kt

Java

FirebaseFirestoreSettings settings = 
new FirebaseFirestoreSettings.Builder(db.getFirestoreSettings())
    // Use memory-only cache
    .setLocalCacheSettings(MemoryCacheSettings.newBuilder().build())
    // Use persistent disk cache (default)
    .setLocalCacheSettings(PersistentCacheSettings.newBuilder()
                            .build())
    .build();
db.setFirestoreSettings(settings);
DocSnippets.java

Dart

// Apple and Android
db.settings = const Settings(persistenceEnabled: true);

// Web
await db
    .enablePersistence(const PersistenceSettings(synchronizeTabs: true));
firestore.dart

Configurer la taille du cache

Lorsque la persistance est activée, Cloud Firestore met en cache tous les documents reçus du backend pour un accès hors connexion. Cloud Firestore définit un seuil par défaut pour la taille du cache. Une fois la valeur par défaut dépassée, Cloud Firestore tente régulièrement de nettoyer les documents inutilisés. Vous pouvez configurer un autre seuil pour la taille du cache ou désactiver complètement le processus de nettoyage :

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";

const firestoreDb = initializeFirestore(app, {
  cacheSizeBytes: CACHE_SIZE_UNLIMITED
});
fs_setup_cache.js

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js

Swift

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "FirestoreCacheSizeUnlimited"
// to disable clean-up.
let settings = Firestore.firestore().settings
// Set cache size to 100 MB
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber)
Firestore.firestore().settings = settings
ViewController.swift

Objective-C

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "kFIRFirestoreCacheSizeUnlimited"
// to disable clean-up.
FIRFirestoreSettings *settings = [FIRFirestore firestore].settings;
// Set cache size to 100 MB
settings.cacheSettings =
    [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)];
[FIRFirestore firestore].settings = settings;
ViewController.m
  

Kotlin

// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
val settings = FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build()
db.firestoreSettings = settings

Java

// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build();
db.setFirestoreSettings(settings);

Dart

db.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);
firestore.dart

Écouter des données hors connexion

Lorsque l'appareil est hors connexion, si vous avez activé la persistance hors connexion, vos écouteurs reçoivent des événements d'écoute lorsque les données mises en cache localement sont modifiées. Vous pouvez écouter des documents, des collections et des requêtes.

Pour vérifier si vous recevez des données du serveur ou du cache, utilisez la propriété fromCache du SnapshotMetadata de votre événement instantané. Si fromCache correspond à true, les données proviennent du cache et peuvent être obsolètes ou incomplètes. Si fromCache correspond à false, les données sont complètes et actualisées avec les dernières mises à jour sur le serveur.

Par défaut, aucun événement n'est déclenché si seulement le SnapshotMetadata a été modifié. Si vous utilisez les valeurs fromCache, spécifiez l'option d'écoute includeMetadataChanges lorsque vous associez votre gestionnaire d'écoute.

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

import { collection, onSnapshot, where, query } from "firebase/firestore"; 

const q = query(collection(db, "cities"), where("state", "==", "CA"));
onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
    snapshot.docChanges().forEach((change) => {
        if (change.type === "added") {
            console.log("New city: ", change.doc.data());
        }

        const source = snapshot.metadata.fromCache ? "local cache" : "server";
        console.log("Data came from " + source);
    });
});
use_from_cache.js

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

db.collection("cities").where("state", "==", "CA")
  .onSnapshot({ includeMetadataChanges: true }, (snapshot) => {
      snapshot.docChanges().forEach((change) => {
          if (change.type === "added") {
              console.log("New city: ", change.doc.data());
          }

          var source = snapshot.metadata.fromCache ? "local cache" : "server";
          console.log("Data came from " + source);
      });
  });
test.firestore.js

Swift

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
db.collection("cities").whereField("state", isEqualTo: "CA")
  .addSnapshotListener(includeMetadataChanges: true) { querySnapshot, error in
    guard let snapshot = querySnapshot else {
      print("Error retreiving snapshot: \(error!)")
      return
    }

    for diff in snapshot.documentChanges {
      if diff.type == .added {
        print("New city: \(diff.document.data())")
      }
    }

    let source = snapshot.metadata.isFromCache ? "local cache" : "server"
    print("Metadata: Data fetched from \(source)")
  }
ViewController.swift

Objective-C

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
[[[db collectionWithPath:@"cities"] queryWhereField:@"state" isEqualTo:@"CA"]
    addSnapshotListenerWithIncludeMetadataChanges:YES
    listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
      if (snapshot == nil) {
        NSLog(@"Error retreiving snapshot: %@", error);
        return;
      }
      for (FIRDocumentChange *diff in snapshot.documentChanges) {
        if (diff.type == FIRDocumentChangeTypeAdded) {
          NSLog(@"New city: %@", diff.document.data);
        }
      }

      NSString *source = snapshot.metadata.isFromCache ? @"local cache" : @"server";
      NSLog(@"Metadata: Data fetched from %@", source);
    }];
ViewController.m

Kotlin

db.collection("cities").whereEqualTo("state", "CA")
    .addSnapshotListener(MetadataChanges.INCLUDE) { querySnapshot, e ->
        if (e != null) {
            Log.w(TAG, "Listen error", e)
            return@addSnapshotListener
        }

        for (change in querySnapshot!!.documentChanges) {
            if (change.type == DocumentChange.Type.ADDED) {
                Log.d(TAG, "New city: ${change.document.data}")
            }

            val source = if (querySnapshot.metadata.isFromCache) {
                "local cache"
            } else {
                "server"
            }
            Log.d(TAG, "Data fetched from $source")
        }
    }
DocSnippets.kt

Java

db.collection("cities").whereEqualTo("state", "CA")
        .addSnapshotListener(MetadataChanges.INCLUDE, new EventListener<QuerySnapshot>() {
            @Override
            public void onEvent(@Nullable QuerySnapshot querySnapshot,
                                @Nullable FirebaseFirestoreException e) {
                if (e != null) {
                    Log.w(TAG, "Listen error", e);
                    return;
                }

                for (DocumentChange change : querySnapshot.getDocumentChanges()) {
                    if (change.getType() == Type.ADDED) {
                        Log.d(TAG, "New city:" + change.getDocument().getData());
                    }

                    String source = querySnapshot.getMetadata().isFromCache() ?
                            "local cache" : "server";
                    Log.d(TAG, "Data fetched from " + source);
                }

            }
        });
DocSnippets.java

Dart

db
    .collection("cities")
    .where("state", isEqualTo: "CA")
    .snapshots(includeMetadataChanges: true)
    .listen((querySnapshot) {
  for (var change in querySnapshot.docChanges) {
    if (change.type == DocumentChangeType.added) {
      final source =
          (querySnapshot.metadata.isFromCache) ? "local cache" : "server";

      print("Data fetched from $source}");
    }
  }
});
firestore.dart

Obtenir des données hors connexion

Si vous recevez un document alors que l'appareil est hors connexion, Cloud Firestore renvoie les données du cache.

Lorsque vous interrogez une collection, un résultat vide est renvoyé si elle ne contient pas de documents mis en cache. Si vous essayez de récupérer un document spécifique, une erreur est renvoyée.

Interroger les données hors connexion

L'interrogation fonctionne avec la persistance hors connexion. Vous pouvez récupérer les résultats des requêtes à travers un accès direct ou en écoutant, comme décrit dans les sections précédentes. Vous pouvez également créer de nouvelles requêtes sur des données conservées localement lorsque l'appareil est hors connexion, mais les requêtes ne seront exécutées que sur les documents mis en cache.

Configurer des index de requêtes hors connexion

Par défaut, le SDK Firestore analyse tous les documents d'une collection dans son cache local lors de l'exécution de requêtes hors connexion. Avec ce comportement par défaut, les performances des requêtes hors connexion peuvent être affectées lorsque les utilisateurs sont hors connexion pendant de longues périodes.

Lorsque le cache persistant est activé, vous pouvez améliorer les performances des requêtes hors connexion en autorisant le SDK à créer automatiquement des index de requêtes locaux.

L'indexation automatique est désactivée par défaut. Votre application doit activer l'indexation automatique chaque fois qu'elle démarre. Définissez si l'indexation automatique est activée, comme indiqué ci-dessous.

Swift

if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
    

Objective-C

PersistentCacheIndexManager *indexManager = [FIRFirestore firestore].persistentCacheIndexManager;
if (indexManager) {
  // Indexing is disabled by default
  [indexManager enableIndexAutoCreation];
}
    

Kotlin

// return type: PersistentCacheManager?

Firebase.firestore.persistentCacheIndexManager?.apply {
      // Indexing is disabled by default
      enableIndexAutoCreation()
    } ?: println("indexManager is null")
    

Java

// return type: @Nullable PersistentCacheIndexManager
PersistentCacheIndexManager indexManager = FirebaseFirestore.getInstance().getPersistentCacheIndexManager();
if (indexManager != null) {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation();
}

// If not check indexManager != null, IDE shows warning: Method invocation 'enableIndexAutoCreation' may produce 'NullPointerException' 
FirebaseFirestore.getInstance().getPersistentCacheIndexManager().enableIndexAutoCreation();
    

Une fois l'indexation automatique activée, le SDK évalue les collections qui contiennent un grand nombre de documents mis en cache et optimise les performances des requêtes locales.

Le SDK fournit une méthode permettant de supprimer des index de requêtes.

Désactiver et activer l'accès au réseau

Vous pouvez utiliser la méthode ci-dessous pour désactiver l'accès réseau de votre client Cloud Firestore. Lorsque l'accès au réseau est désactivé, tous les écouteurs d'instantanés et les requêtes de documents récupèrent les résultats à partir du cache. Les opérations d'écriture sont mises en attente jusqu'à ce que l'accès au réseau soit réactivé..

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

import { disableNetwork } from "firebase/firestore"; 

await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...
disable_network.js

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js

Swift

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift

Objective-C

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin

db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}
DocSnippets.kt

Java

db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });
DocSnippets.java

Dart

db.disableNetwork().then((_) {
  // Do offline things
});
firestore.dart

Pour réactiver l'accès au réseau, procédez comme suit :

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

import { enableNetwork } from "firebase/firestore"; 

await enableNetwork(db);
// Do online actions
// ...
enable_network.js

Web

En savoir plus sur l'API Web modulaire pouvant être allégée par "tree shaking" et sur la mise à niveau depuis l'API avec espace de noms

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js

Swift

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift

Objective-C

Remarque : Ce produit n'est pas disponible sur les cibles watchOS et App Clip.

[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin

db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}
DocSnippets.kt

Java

db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });
DocSnippets.java

Dart

db.enableNetwork().then((_) {
  // Back online
});
firestore.dart