Carga datos de exportaciones de Firestore

BigQuery admite la carga de datos de las exportaciones de Firestore creadas con el servicio de importación y exportación administrado de Firestore. Con el servicio de importación y exportación administrado, se exportan documentos de Firestore a un depósito de Cloud Storage. Puedes cargar los datos exportados en una tabla de BigQuery.

Nota: No se pueden cargar todas las exportaciones de Firestore. Haz referencia a las limitaciones de BigQuery para crear una exportación de Firestore que se pueda cargar en una tabla de BigQuery.

Limitaciones

Cuando cargues datos en BigQuery desde una exportación de Firestore, ten en cuenta las restricciones siguientes:

• Tu conjunto de datos debe estar en la misma ubicación regional o multirregional que el depósito de Cloud Storage que contiene tus archivos de exportación.
• Puedes especificar solo un URI de Cloud Storage y no puedes usar un comodín de URI.
• Para que una exportación de Firestore se cargue de forma correcta, los documentos en los datos de exportación deben compartir un esquema coherente con menos de 10,000 nombres de campo únicos.
• Puedes crear una tabla nueva para almacenar los datos o puedes reemplazar los datos de una existente. No puedes adjuntar datos de exportación de Firestore a una tabla existente.
• Tu comando de exportación debe especificar un filtro collection-ids. Los datos exportados sin especificar un filtro de ID de colección no se pueden cargar en BigQuery.

Antes de comenzar

Otorga funciones de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos necesarios

Si deseas cargar datos en BigQuery, necesitas permisos de IAM para ejecutar un trabajo de carga y cargar datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos para acceder al bucket que contiene tus datos.

Permisos para cargar datos en BigQuery

Para cargar datos en una tabla o partición de BigQuery nueva, o agregar o reemplazar una tabla o partición existente, necesitas los siguientes permisos de IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para cargar datos en una tabla o partición de BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (incluye el permiso bigquery.jobs.create)
• bigquery.user (incluye el permiso bigquery.jobs.create)
• bigquery.jobUser (incluye el permiso bigquery.jobs.create)

Además, si tienes el permiso bigquery.datasets.create, puedes crear y actualizar tablas con un trabajo de carga en los conjuntos de datos que crees.

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Permisos para cargar datos desde Cloud Storage

Para cargar datos desde un bucket de Cloud Storage, necesitas los siguientes permisos de IAM:

• storage.objects.get
• storage.objects.list (obligatorio si usas un comodín de URI)

La función predefinida de IAM roles/storage.objectViewer incluye todos los permisos que necesitas para cargar datos desde un bucket de Cloud Storage.

Carga datos del servicio de exportación de Cloud Firestore

Puedes cargar datos de un archivo de metadatos de exportación de Firestore mediante Cloud Console, la herramienta de línea de comandos de bq o la API.

En ocasiones, la terminología de Datastore se usa en Cloud Console y la herramienta de línea de comandos de bq, pero los siguientes procedimientos son compatibles con archivos de exportación de Firestore. Firestore y Datastore comparten un formato de exportación.

Nota: Para cargar campos específicos, usa la marca --projection_fields en la herramienta de línea de comandos de bq o establece la propiedad projectionFields en la configuración de trabajo load.

Console

1. En Cloud Console, abre la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

3. Expande la opción Acciones y haz clic en Abrir.

4. En el panel de detalles, haz clic en Crear tabla  (Create table).

5. En la página Crear tabla, en la sección Fuente haz lo siguiente:

   • En Crear tabla desde, selecciona Cloud Storage.

   • En el campo de origen, ingresa el URI de Cloud Storage. El depósito de Cloud Storage debe estar en la misma ubicación que tu conjunto de datos. El URI del archivo de exportación de Firestore debe terminar con KIND_COLLECTION_ID.export_metadata. Por ejemplo: default_namespace_kind_Book.export_metadata. En este ejemplo, Book es el ID de la colección y default_namespace_kind_Book es el nombre del archivo que Firestore generó.

     Nota: No uses el archivo que termina en overall_export_metadata. BigQuery no puede usar este archivo.

     Verifica que se especifique KIND_COLLECTION_ID en tu URI de Cloud Storage. Si especificas el URI sin KIND_COLLECTION_ID, se generará el siguiente error: does not contain valid backup metadata. (error code: invalid).

   • En Formato del archivo, selecciona Copia de seguridad de Datastore. La copia de seguridad de Datastore es la opción correcta para Firestore. Firestore y Datastore comparten un formato de exportación.

6. En la página Crear tabla, en la sección Destination (Destino), haz lo siguiente:

   • En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.

     

   • En el campo Nombre de la tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

   • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).

7. En la sección Esquema no es necesaria ninguna acción. El esquema se infiere para una exportación de Firestore.

8. Selecciona los elementos aplicables en la sección Opciones avanzadas (Advanced options). Si reemplazas una tabla existente, establece Write preference (Preferencia de escritura) en Overwrite table (Reemplazar tabla).

   

9. Haz clic en Crear tabla.

bq

Usa el comando bq load con source_format configurado como DATASTORE_BACKUP. Proporciona la marca --location y configura el valor según tu ubicación. Si reemplazas una tabla existente, agrega la marca --replace.

Para cargar solo campos específicos, usa la marca --projection_fields.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Reemplaza lo siguiente:

• LOCATION: Es tu ubicación. La marca --location es opcional.
• FORMAT: DATASTORE_BACKUP. La copia de seguridad de Datastore es la opción correcta para Firestore. Firestore y Datastore comparten un formato de exportación.
• DATASET: Es el conjunto de datos que contiene la tabla en la que deseas cargar los datos.
• TABLE: Es la tabla en la que deseas cargar los datos. Si no existe, se crea.
• PATH_TO_SOURCE: Es el URI de Cloud Storage.

Por ejemplo, el siguiente comando carga el archivo de exportación gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata de Firestore en una tabla llamada book_data. mybucket y mydataset se crearon en la ubicación multirregión US.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Configura las propiedades siguientes para cargar los datos de exportación de Firestore con la API.

1. Crea una configuración de trabajo de load que apunte a los datos de origen en Cloud Storage.

2. Especifica tu ubicación en la propiedad location en la sección jobReference del recurso de trabajo.

3. Los sourceUris deben estar completamente calificados y en el formato gs://BUCKET/OBJECT en la configuración del trabajo de carga. El nombre del archivo (objeto) debe terminar en KIND_NAME.export_metadata. Solo se permite un URI para las exportaciones de Firestore, y no puedes usar un comodín.

4. Para especificar el formato de datos, establece la propiedad sourceFormat en DATASTORE_BACKUP en la configuración del trabajo de carga. La copia de seguridad de Datastore es la opción correcta para Firestore. Firestore y Datastore comparten un formato de exportación.

5. Para cargar solo campos específicos, establece la propiedad projectionFields.

6. Si reemplazas una tabla existente, especifica la disposición de escritura mediante la configuración de la propiedad writeDisposition como WRITE_TRUNCATE.

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Ver en GitHubComentarios

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Nota: Si prefieres omitir el proceso de carga, puedes consultar la exportación directamente si la configuras como una fuente de datos externa. Para obtener más información, consulta Introducción a las fuentes de datos externas.

Opciones de Firestore

Para cambiar la forma en la que BigQuery analiza los datos de exportación de Firestore, especifica la siguiente opción:

Opción de Cloud Console	Marca de “bq”	Propiedad de la API de BigQuery	Descripción
No disponible	--projection_fields	projectionFields (Java, Python)	Una lista separada por comas que indica qué campos de documento se deben cargar desde una exportación de Firestore (opcional). BigQuery carga todos los campos de manera predeterminada. Los nombres de los campos distinguen entre mayúsculas y minúsculas y deben estar presentes en la exportación. No puedes especificar rutas de campo dentro de un campo de mapas, como map.foo.

Conversión de tipo de datos

BigQuery convierte los datos de cada documento en los archivos de exportación de Firestore en tipos de datos de BigQuery. En la siguiente tabla, se describe la conversión entre tipos de datos compatibles.

Tipo de datos de Firestore	Tipo de datos de BigQuery
Arreglo	REGISTRO
Booleano	BOOLEANO
Referencia	REGISTRO
Fecha y hora	MARCA DE TIEMPO
Mapa	REGISTRO
Número de punto flotante	FLOTANTE
Punto geográfico	REGISTRO [{"lat","FLOAT"}, {"long","FLOAT"}]
Número entero	NÚMERO ENTERO
String	STRING (truncado a 64 KB)

Propiedades clave de Firestore

Cada documento en Firestore tiene una clave única que contiene información como el ID del documento y la ruta del documento. BigQuery crea un tipo de datos RECORD (también conocido como STRUCT) para la clave, con campos anidados para cada información, como se describe en la tabla siguiente.

Propiedad clave	Descripción	Tipo de datos de BigQuery
__key__.app	El nombre de la app de Firestore.	STRING
__key__.id	El ID del documento o null si se configura __key__.name.	INTEGER
__key__.kind	El ID de la colección del documento.	STRING
__key__.name	El nombre del documento o null si se configuró __key__.id.	STRING
__key__.namespace	Firestore no admite espacios de nombres personalizados. El espacio de nombres predeterminado se presenta mediante una string vacía.	STRING
__key__.path	La ruta del documento: la secuencia del documento y los pares de colección de la colección raíz. Por ejemplo: "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRING