Importar y exportar datos

Puedes usar el servicio gestionado de exportación e importación para recuperar datos que hayas eliminado por accidente y para exportar datos para procesarlos sin conexión. Puedes exportar todos los documentos o solo colecciones concretas. Del mismo modo, puedes importar todos los datos de una exportación o solo colecciones específicas. Los datos exportados de una base de datos de Firestore con compatibilidad con MongoDB se pueden importar a otra base de datos de Firestore con compatibilidad con MongoDB. También puede cargar en BigQuery las exportaciones de Firestore con compatibilidad con MongoDB.

En esta página se describe cómo exportar e importar documentos de Firestore con compatibilidad con MongoDB mediante el servicio de exportación e importación gestionado y Cloud Storage. El servicio de exportación e importación gestionado de Firestore con compatibilidad con MongoDB está disponible a través de la herramienta de línea de comandos gcloud y de la API de Firestore con compatibilidad con MongoDB (REST y RPC).

Antes de empezar

Para poder usar el servicio de exportación e importación gestionado, debes completar las siguientes tareas:

  1. Habilita la facturación de tu Google Cloud proyecto. Solo los Google Cloud proyectos con la facturación habilitada pueden usar las funciones de exportación e importación.
  2. Crea un segmento de Cloud Storage para tu proyecto en una ubicación cercana a la ubicación de tu base de datos de Firestore con compatibilidad con MongoDB. No puedes usar un cubo de pago del solicitante para las operaciones de exportación e importación.

  3. Asegúrate de que tu cuenta tiene los permisos necesarios para usar Firestore con compatibilidad con MongoDB y Cloud Storage. Si eres el propietario del proyecto, tu cuenta tiene los permisos necesarios. De lo contrario, los siguientes roles conceden los permisos necesarios para las operaciones de exportación e importación y para acceder a Cloud Storage:

Permisos de agente de servicio

Las operaciones de exportación e importación usan un agente de servicio de Firestore para autorizar las operaciones de Cloud Storage. El agente de servicio de Firestore usa la siguiente convención de nomenclatura:

Agente de servicio de Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Para obtener más información sobre los agentes de servicio, consulta el artículo Agentes de servicio.

El agente de servicio de Firestore necesita acceder al segmento de Cloud Storage que se usa en una operación de exportación o importación. Si tu segmento de Cloud Storage está en el mismo proyecto que tu base de datos de Firestore, el agente de servicio de Firestore podrá acceder al segmento de forma predeterminada.

Si el segmento de Cloud Storage está en otro proyecto, debes dar acceso al agente de servicio de Firestore al segmento de Cloud Storage.

Asignar roles al agente de servicio

Puede usar la herramienta de línea de comandos gsutil para asignar uno de los roles que se indican a continuación. Por ejemplo, para asignar el rol Administrador de almacenamiento al agente de servicio de Firestore, ejecuta lo siguiente:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Sustituye PROJECT_NUMBER por el número de tu proyecto, que se usa para asignar un nombre al agente de servicio de Firestore. Para ver el nombre del agente de servicio, consulta Ver el nombre del agente de servicio.

También puedes asignar este rol mediante la Google Cloud consola.

Ver el nombre del agente de servicio

Puede ver la cuenta que usan sus operaciones de importación y exportación para autorizar solicitudes en la página Importar/Exportar de la consola de Google Cloud . También puedes ver si tu base de datos usa el agente de servicio de Firestore o la cuenta de servicio antigua de App Engine.

  1. Consulta la cuenta de autorización junto a la etiqueta Las tareas de importación o exportación se ejecutan como.

El agente de servicio necesita el rol Storage Admin para el segmento de Cloud Storage que se va a usar en la operación de exportación o importación.

Configurar gcloud en tu proyecto

Puedes iniciar operaciones de importación y exportación a través de la Google Cloud consola o de la herramienta de línea de comandos gcloud. Para usar gcloud, configura la herramienta de línea de comandos y conéctate a tu proyecto de una de las siguientes formas:

Importación de datos

Una vez que tengas los archivos de exportación en Cloud Storage, podrás importar los documentos de esos archivos a tu proyecto o a otro. Ten en cuenta los siguientes puntos sobre las operaciones de importación:

  • Cuando importa datos, los índices obligatorios se actualizan con las definiciones de índice actuales de su base de datos. Una exportación no contiene definiciones de índice.

  • Las importaciones no asignan nuevos IDs de documento. Las importaciones usan los IDs capturados en el momento de la exportación. Mientras se importa un documento, se reserva su ID para evitar colisiones de IDs. Si ya existe un documento con el mismo ID, la importación sobrescribe el documento.

  • Si un documento de tu base de datos no se ve afectado por una importación, permanecerá en ella después de la importación.

  • El nombre de archivo .overall_export_metadata debe coincidir con el nombre de su carpeta principal:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    Si mueves o copias los archivos de salida de una exportación, mantén el mismo nombre de archivo PARENT_FOLDER_NAME y .overall_export_metadata.

  • Se produce un error al importar a una base de datos de Firestore con compatibilidad con MongoDB desde una exportación con subcolecciones, ya que estas no se admiten en Firestore con compatibilidad con MongoDB.

  • No se puede importar a una base de datos de la edición Estándar de Firestore desde una exportación con tipos BSON, ya que estos tipos no se admiten en la edición Estándar de Firestore.

  • No se pueden importar datos de espacios de nombres no predeterminados (API de Datastore) a una base de datos de Firestore con compatibilidad con MongoDB.

    Solo se permite importar a una base de datos de Firestore con compatibilidad con MongoDB desde archivos de datos que contengan espacios de nombres no predeterminados si la operación de exportación ha incluido un filtro --namespace-ids con el espacio de nombres predeterminado. Solo se importan los datos del espacio de nombres predeterminado.

Importar todos los documentos de una exportación

Consola de Google Cloud

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Selecciona una base de datos de la lista.

  3. En el menú de navegación, haga clic en Importar/Exportar.

  4. Haz clic en Importar.

  5. En el campo Nombre de archivo, introduce el nombre de un archivo .overall_export_metadata de una operación de exportación completada. Puedes usar el botón Examinar para seleccionar el archivo.

  6. Haz clic en Importar.

La consola vuelve a la página Importar/Exportar. Si la operación se inicia correctamente, la página añade una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Usa el comando firestore import para importar documentos de una operación de exportación anterior.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

Haz los cambios siguientes:

  • BUCKET_NAME/EXPORT_PREFIX: ubicación de tus archivos de exportación.

  • DATABASE: nombre de la base de datos.

Por ejemplo:

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Puede confirmar la ubicación de los archivos de exportación en el explorador de Cloud Storage de la Google Cloud consola:

Abrir el navegador de Cloud Storage

Una vez que inicies una operación de importación, cerrar la terminal no la cancelará. Consulta cómo cancelar una operación.

Importar colecciones específicas

Consola de Google Cloud

No puede seleccionar colecciones específicas en la consola. En su lugar, usa gcloud.

gcloud

Para importar colecciones específicas de un conjunto de archivos de exportación, usa la marca --collection-ids. La operación importa solo las colecciones con los IDs de colección especificados. Especifica el nombre de la base de datos con la marca --database.

Solo se pueden importar colecciones específicas si se han exportado colecciones específicas. No puedes importar colecciones específicas de una exportación de todos los documentos.

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
  --database=[DATABASE]

Importar desde una exportación con datos de PITR

Sigue los mismos pasos que en Importar todos los documentos o Importar colecciones específicas para importar datos de PITR. Si ya existe algún documento en tu base de datos, se sobrescribirá.

Exportar datos

Una operación de exportación copia los documentos de tu base de datos en un conjunto de archivos de un segmento de Cloud Storage. Ten en cuenta que una exportación no es una instantánea exacta de la base de datos tomada en el momento en que se inicia la exportación. Una exportación puede incluir los cambios realizados mientras se ejecutaba la operación.

Exportación de todos los documentos

Consola de Google Cloud

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Seleccione la base de datos que necesite de la lista de bases de datos.

  3. En el menú de navegación, haga clic en Importar/Exportar.

  4. Haz clic en Exportar.

  5. Haz clic en la opción Exportar toda la base de datos.

  6. Selecciona Exportar estado actual de la base de datos para exportar los datos actuales.

  7. En la sección Destino, introduce el nombre de un segmento de Cloud Storage o usa el botón Buscar para seleccionar un segmento.

  8. Haz clic en Exportar.

La consola vuelve a la página Importar/Exportar. Si la operación se inicia correctamente, la página añade una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Usa el comando firestore export para exportar todos los documentos de tu base de datos. Sustituye [BUCKET_NAME] por el nombre de tu segmento de Cloud Storage. Añade la marca --async para evitar que la herramienta gcloud espere a que se complete la operación.

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Haz los cambios siguientes:

  • BUCKET_NAME: organiza tus exportaciones añadiendo un prefijo de archivo después del nombre del contenedor. Por ejemplo, BUCKET_NAME/my-exports-folder/export-name. Si no proporcionas un prefijo de archivo, el servicio de exportación gestionado creará uno basado en la marca de tiempo actual.

  • DATABASE: nombre de la base de datos de la que quieres exportar los documentos.

Una vez que inicies una operación de exportación, cerrar la terminal no cancelará la operación. Consulta cómo cancelar una operación.

Exportar colecciones específicas

Consola de Google Cloud

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Seleccione la base de datos que necesite de la lista de bases de datos.

  3. En el menú de navegación, haga clic en Importar/Exportar.

  4. Haz clic en Exportar.

  5. Haz clic en la opción Exportar uno o varios grupos de colecciones. Usa el menú desplegable para seleccionar una o varias colecciones.

  6. Selecciona Exportar estado actual de la base de datos para exportar los datos actuales.

  7. En la sección Destino, introduce el nombre de un segmento de Cloud Storage o usa el botón Buscar para seleccionar un segmento.

  8. Haz clic en Exportar.

La consola vuelve a la página Importar/Exportar. Si la operación se inicia correctamente, la página añade una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Para exportar colecciones específicas, usa la marca --collection-ids. La operación solo exporta las colecciones con los IDs de colección proporcionados.

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
--database=[DATABASE]

Por ejemplo, puedes diseñar una colección restaurants en la base de datos foo para incluir colecciones adicionales, como ratings, reviews o outlets. Para exportar colecciones restaurants y reviews específicas, el comando debe tener el siguiente formato:

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Exportar desde una marca de tiempo de PITR

Puedes exportar tu base de datos a Cloud Storage desde datos de PITR. Puede exportar datos de PITR cuya marca de tiempo sea una marca de tiempo de un minuto completo de los últimos siete días, pero no anterior al earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, la operación de exportación fallará.

La operación de exportación de PITR admite todos los filtros, incluida la exportación de todos los documentos y de colecciones específicas.

Ten en cuenta los siguientes puntos antes de exportar datos de PITR:

  • Especifica la marca de tiempo en formato RFC 3339. Por ejemplo, 2020-09-01T23:59:30.234233Z.
  • Asegúrate de que la marca de tiempo que especifiques sea una marca de tiempo de un minuto completo de los últimos siete días, pero no anterior a la earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, se genera un error.
  • No se te cobrará por una exportación de PITR fallida.

Consola

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos
  2. Selecciona una base de datos de la lista.
  3. En el menú de navegación, haga clic en Importar/Exportar.
  4. Haz clic en Exportar.
  5. Configure la fuente de exportación para que exporte toda la base de datos o solo colecciones específicas.

  6. En la sección Elige el estado de la base de datos que quieres exportar, selecciona Exportar desde un momento anterior.

    Selecciona la hora de la captura que quieras usar para la exportación

  7. En la sección Destino, introduce el nombre de un segmento de Cloud Storage o usa el botón Buscar para seleccionar un segmento.

  8. Haz clic en Exportar.

    La consola vuelve a la página Importar/Exportar. Si la operación se inicia correctamente, la página añade una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Puedes exportar tu base de datos a Cloud Storage desde datos de PITR mediante el comando gcloud firestore export.

Exporta la base de datos y especifica el parámetro snapshot-time con una marca de tiempo de recuperación. Ejecuta el siguiente comando para exportar la base de datos a tu bucket.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Donde PITR_TIMESTAMP es una marca de tiempo de PITR con una granularidad de minutos, por ejemplo, 2023-05-26T10:20:00.00Z.

Añade la marca --collection-ids para exportar colecciones específicas.

Gestionar operaciones de exportación e importación

Después de iniciar una operación de exportación o importación, Firestore con compatibilidad con MongoDB asigna un nombre único a la operación. Puedes usar el nombre de la operación para eliminarla, cancelarla o comprobar su estado.

Los nombres de las operaciones van precedidos de projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, por ejemplo:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Sin embargo, puedes omitir el prefijo al especificar un nombre de operación para los comandos describe, cancel y delete.

Mostrar todas las operaciones de exportación e importación

Consola de Google Cloud

Puedes ver una lista de las operaciones de importación y exportación recientes en la página Importar/Exportar de la consola de Google Cloud .

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Seleccione la base de datos que necesite de la lista de bases de datos.

  3. En el menú de navegación, haga clic en Importar/Exportar.

gcloud

Usa el comando operations list para ver todas las operaciones de importación y exportación en curso y completadas recientemente:

gcloud firestore operations list

Comprobar el estado de la operación

Consola de Google Cloud

Puedes ver el estado de una operación de importación o exportación reciente en la página Importar/Exportar de la consola Google Cloud .

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Seleccione la base de datos que necesite de la lista de bases de datos.

  3. En el menú de navegación, haga clic en Importar/Exportar.

gcloud

Usa el comando operations describe para mostrar el estado de una operación de exportación o importación.

gcloud firestore operations describe [OPERATION_NAME]

Estimar el tiempo de finalización

Una solicitud del estado de una operación de larga duración devuelve las métricas workEstimated y workCompleted. Cada una de estas métricas se devuelve tanto en número de bytes como en número de entidades:

  • workEstimated muestra el número total estimado de bytes y documentos que procesará una operación. Es posible que Firestore con compatibilidad con MongoDB omita esta métrica si no puede hacer una estimación.

  • workCompleted muestra el número de bytes y documentos procesados hasta el momento. Una vez completada la operación, el valor muestra el número total de bytes y documentos que se han procesado, que puede ser superior al valor de workEstimated.

Divide workCompleted entre workEstimated para obtener una estimación aproximada del progreso. Esta estimación puede ser imprecisa, ya que depende de la recogida de estadísticas con retraso.

Cancelar una operación

Consola de Google Cloud

Puedes cancelar una operación de importación o exportación en curso en la página Importar/Exportar de la Google Cloud consola.

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Seleccione la base de datos que necesite de la lista de bases de datos.

  3. En el menú de navegación, haga clic en Importar/Exportar.

En la tabla Importaciones y exportaciones recientes, las operaciones en curso incluyen un botón Cancelar en la columna Completado. Haz clic en el botón Cancelar para detener la operación. El botón cambia a Cancelando y, a continuación, a Cancelado cuando la operación se detiene por completo.

Tabla de importaciones y exportaciones recientes en la consola que muestra una importación de datos en curso con una opción Cancelar para detener la operación.

gcloud

Usa el comando operations cancel para detener una operación en curso:

gcloud firestore operations cancel [OPERATION_NAME]

Si cancelas una operación en curso, no se deshace la operación. Si cancelas una operación de exportación, los documentos que ya se hayan exportado permanecerán en Cloud Storage. Si cancelas una operación de importación, las actualizaciones que ya se hayan realizado en tu base de datos se mantendrán. No puedes importar una exportación que no se haya completado.

Eliminar una operación

Usa el comando gcloud firestore operations delete para quitar una operación de la lista de operaciones recientes. Este comando no eliminará los archivos de exportación de Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Facturación y precios de las operaciones de exportación e importación

Debes habilitar la facturación en tu proyecto Google Cloud para usar el servicio de exportación e importación gestionado.

Las operaciones de exportación e importación se cobran por unidades de lectura y escritura según las tarifas indicadas en la página Precios de Firestore con compatibilidad con MongoDB.

Los archivos de salida almacenados en Cloud Storage se tienen en cuenta para los costes de almacenamiento de datos de Cloud Storage.

Las operaciones de exportación o importación no activarán las alertas de Google Cloud presupuesto hasta que se completen. Las operaciones de exportación e importación no afectarán al uso que se muestra en la sección de uso de la consola.

Ver los costes de exportación e importación

Las operaciones de importación y exportación aplican la etiqueta goog-firestoremanaged:exportimport a las operaciones facturadas. En la página Informes de Facturación de Cloud, puede usar esta etiqueta para ver los costes relacionados con las operaciones de importación y exportación:

Accede a la etiqueta goog-firestoremanaged desde el menú de filtros.

Exportar a BigQuery

Puede cargar datos de una exportación de Firestore con compatibilidad con MongoDB en BigQuery, pero solo si ha especificado un collection-ids filtro. Consulta Cargar datos desde exportaciones de Firestore con compatibilidad con MongoDB.

Al cargar datos de Firestore con compatibilidad con MongoDB en BigQuery, los tipos de datos BSON se representan con el tipo de datos STRING.

Límite de columnas de BigQuery

BigQuery impone un límite de 10.000 columnas por tabla. Las operaciones de exportación de Firestore con compatibilidad con MongoDB generan un esquema de tabla de BigQuery para cada colección. En este esquema, cada nombre de campo único de una colección se convierte en una columna del esquema.

Si el esquema de BigQuery de una colección supera las 10.000 columnas, la operación de exportación de Firestore con compatibilidad con MongoDB intentará no superar el límite de columnas tratando los campos de mapa como bytes. Si esta conversión reduce el número de columnas a menos de 10.000, puede cargar los datos en BigQuery, pero no puede consultar los subcampos de los campos de mapa. Si el número de columnas sigue siendo superior a 10.000, la operación de exportación no generará un esquema de BigQuery para la colección y no podrá cargar sus datos en BigQuery.

Exportar archivos de formato y metadatos

La salida de una exportación gestionada usa el formato de registro de LevelDB.

Archivos de metadatos

Una operación de exportación crea un archivo de metadatos por cada colección que especifiques. Los archivos de metadatos suelen llamarse ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Los archivos de metadatos son búferes de protocolo y puedes decodificarlos con el protoccompilador de protocolos. Por ejemplo, puedes decodificar un archivo de metadatos para determinar las colecciones que contienen los archivos de exportación:

protoc --decode_raw < export0.export_metadata