Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Acceder a datos sin conexión

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Cloud Firestore admite la persistencia de datos sin conexión. Esta característica almacena en caché una copia de los datos de Cloud Firestore que su aplicación está usando activamente, para que su aplicación pueda acceder a los datos cuando el dispositivo está fuera de línea. Puede escribir, leer, escuchar y consultar los datos almacenados en caché. Cuando el dispositivo vuelve a estar en línea, Cloud Firestore sincroniza cualquier cambio local realizado por su aplicación con el backend de Cloud Firestore.

Para usar la persistencia sin conexión, no necesita hacer ningún cambio en el código que usa para acceder a los datos de Cloud Firestore. Con la persistencia fuera de línea habilitada, la biblioteca cliente de Cloud Firestore administra automáticamente el acceso a datos en línea y fuera de línea y sincroniza los datos locales cuando el dispositivo vuelve a estar en línea.

Configurar la persistencia sin conexión

Cuando inicializa Cloud Firestore, puede habilitar o deshabilitar la persistencia sin conexión:

  • Para las plataformas Android y Apple, la persistencia sin conexión está habilitada de manera predeterminada. Para deshabilitar la persistencia, establezca la opción PersistenceEnabled en false .
  • Para la web, la persistencia sin conexión está deshabilitada de forma predeterminada. Para habilitar la persistencia, llame al método enablePersistence . El caché de Cloud Firestore no se borra automáticamente entre sesiones. En consecuencia, si su aplicación web maneja información confidencial, asegúrese de preguntarle al usuario si está en un dispositivo confiable antes de habilitar la persistencia.

Web version 9

import { enableIndexedDbPersistence } from "firebase/firestore"; 

enableIndexedDbPersistence(db)
  .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
initialize_persistence.js

Web 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
Rápido
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
let settings = FirestoreSettings()
settings.isPersistenceEnabled = true

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
ViewController.swift
C objetivo
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];
settings.persistenceEnabled = YES;

// Any additional options
// ...

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

Kotlin+KTX

val settings = firestoreSettings {
    isPersistenceEnabled = true
}
db.firestoreSettings = settings
DocSnippets.kt

Java

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(true)
        .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

Configurar tamaño de caché

Cuando la persistencia está habilitada, Cloud Firestore almacena en caché todos los documentos recibidos del backend para acceso sin conexión. Cloud Firestore establece un umbral predeterminado para el tamaño de caché. Después de exceder el valor predeterminado, Cloud Firestore intenta limpiar periódicamente los documentos más antiguos que no se usan. Puede configurar un umbral de tamaño de caché diferente o deshabilitar el proceso de limpieza por completo:

Web version 9

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

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

Web version 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
Rápido
Nota: este producto no está disponible en los objetivos watchOS y 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
settings.cacheSizeBytes = FirestoreCacheSizeUnlimited
Firestore.firestore().settings = settings
ViewController.swift
C objetivo
Nota: este producto no está disponible en los objetivos watchOS y 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;
settings.cacheSizeBytes = kFIRFirestoreCacheSizeUnlimited;
[FIRFirestore firestore].settings = settings;
ViewController.m

Kotlin+KTX


// 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

Escuche datos sin conexión

Mientras el dispositivo está fuera de línea, si ha habilitado la persistencia fuera de línea, sus oyentes recibirán eventos de escucha cuando cambien los datos almacenados en caché localmente. Puede escuchar documentos, colecciones y consultas.

Para verificar si está recibiendo datos del servidor o del caché, use la propiedad fromCache en SnapshotMetadata en su evento de instantánea. Si fromCache es true , los datos provienen del caché y pueden estar obsoletos o incompletos. Si fromCache es false , los datos están completos y actualizados con las últimas actualizaciones en el servidor.

De forma predeterminada, no se genera ningún evento si solo cambia SnapshotMetadata . Si confía en los valores de fromCache , especifique la opción de escucha includeMetadataChanges cuando adjunte su controlador de escucha.

Web version 9

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 version 8

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
Rápido
Nota: este producto no está disponible en los objetivos watchOS y 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
C objetivo
Nota: este producto no está disponible en los objetivos watchOS y 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+KTX

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

Obtener datos sin conexión

Si obtiene un documento mientras el dispositivo está fuera de línea, Cloud Firestore devuelve datos del caché.

Al consultar una colección, se devuelve un resultado vacío si no hay documentos en caché. Al obtener un documento específico, se devuelve un error.

Consultar datos sin conexión

La consulta funciona con persistencia fuera de línea. Puede recuperar los resultados de las consultas con una obtención directa o escuchando, como se describe en las secciones anteriores. También puede crear nuevas consultas sobre datos persistentes localmente mientras el dispositivo está fuera de línea, pero las consultas se ejecutarán inicialmente solo en los documentos almacenados en caché.

Configurar índices de consultas sin conexión

De forma predeterminada, el SDK de Firestore analiza todos los documentos de una colección en su caché local cuando ejecuta consultas sin conexión. Con este comportamiento predeterminado, el rendimiento de las consultas sin conexión puede verse afectado cuando los usuarios están sin conexión durante largos períodos de tiempo.

Puede mejorar el rendimiento de las consultas sin conexión configurando índices de consultas locales:

Rápido

El SDK de la plataforma Apple proporciona un método setIndexConfiguration que lee la misma configuración con estructura JSON utilizada para configurar índices en el servidor, siguiendo el mismo formato de definición de índice .

// You will normally read this from a file asset or cloud storage.
let indexConfigJson = """
  {
    indexes: [
        ...
    ],
    fieldOverrides: [
        ...
    ]
  }
"""

// Apply the configuration.
Firestore.firestore().setIndexConfiguration(indexConfigJson)
C objetivo

El SDK de la plataforma Apple proporciona setIndexConfiguration : métodos que leen la misma configuración con estructura JSON utilizada para configurar índices en el servidor, siguiendo el mismo formato de definición de índice .

// You will normally read this from a file asset or cloud storage.
NSString *indexConfigJson = @" {                   "
                             "   indexes: [        "
                             "     ...             "
                             "   ],                "
                             "   fieldOverrides: [ "
                             "     ...             "
                             "   ]                 "
                             " }                   ";

// Apply the configuration.
[[FIRFirestore firestore] setIndexConfigurationFromJSON:indexConfigJson
                                             completion:^(NSError * _Nullable error) {
    // ...
}];

Java

El SDK de Android proporciona un método setIndexConfiguration que lee la misma configuración con estructura JSON utilizada para configurar índices en el servidor, siguiendo el mismo formato de definición de índice .

// You will normally read this from a file asset or cloud storage.
String indexConfigJson = " {                   "
                       + "   indexes: [        "
                       + "     ...             "
                       + "   ],                "
                       + "   fieldOverrides: [ "
                       + "     ...             "
                       + "   ]                 "
                       + " }                   ";
// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson);

Kotlin+KTX

El SDK de Android proporciona un método setIndexConfiguration que lee la misma configuración con estructura JSON utilizada para configurar índices en el servidor, siguiendo el mismo formato de definición de índice .

// You will normally read this from a file asset or cloud storage.
val indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
"""

// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson)

Dart

El SDK de Flutter proporciona un método setIndexConfigurationFromJSON que lee la misma configuración con estructura JSON utilizada para configurar índices en el servidor, siguiendo el mismo formato de definición de índice .

// You will normally read this from a file asset or cloud storage.
var indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
""";

// Apply the configuration.
await FirebaseFirestore.instance.setIndexConfigurationFromJSON(json: indexConfigJson);

Como alternativa, puede usar el método setIndexConfiguration para configurar índices con una API basada en clases.

var indexes = [
  Index(
    collectionGroup: "posts",
    queryScope: QueryScope.collection,
    fields: [
      IndexField(fieldPath: "author", arrayConfig: ArrayConfig.contains),
      IndexField(fieldPath: "timestamp", order: Order.descending)
    ],
  ),
];
await FirebaseFirestore.instance.setIndexConfiguration(indexes: indexes);

La configuración del índice sin conexión que se debe usar depende de las colecciones y los documentos a los que accede en gran medida su aplicación mientras está sin conexión y el rendimiento sin conexión que desea. Si bien puede exportar su configuración de índice de back-end para usarla en el cliente, es probable que los patrones de acceso sin conexión de su aplicación difieran significativamente de los patrones de acceso en línea, por lo que es posible que su configuración de índice en línea no sea adecuada para usar sin conexión. ¿A qué colecciones y documentos desea que su aplicación acceda sin conexión con un alto rendimiento? Una vez que haya analizado el comportamiento de su aplicación, siga los principios para la definición de índices de la guía de indexación .

Para hacer que las configuraciones de índice sin conexión estén disponibles para cargarlas en su aplicación cliente:

  • Compílalos y distribúyelos con tu aplicación.
  • descargarlos desde un CDN
  • recójalos de un sistema de almacenamiento como Cloud Storage para Firebase .

Deshabilitar y habilitar el acceso a la red

Puede usar el método a continuación para deshabilitar el acceso a la red para su cliente de Cloud Firestore. Mientras el acceso a la red está deshabilitado, todos los detectores de instantáneas y las solicitudes de documentos recuperan resultados de la memoria caché. Las operaciones de escritura se ponen en cola hasta que se vuelve a habilitar el acceso a la red.

Web version 9

import { disableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Rápido
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
Firestore.firestore().disableNetwork { (error) in
    // Do offline things
    // ...
}
ViewController.swift
C objetivo
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin+KTX

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

Utilice el siguiente método para volver a habilitar el acceso a la red:

Web version 9

import { enableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Rápido
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
Firestore.firestore().enableNetwork { (error) in
    // Do online things
    // ...
}
ViewController.swift
C objetivo
Nota: este producto no está disponible en los objetivos watchOS y App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin+KTX

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