Cargar datos de exportaciones de Cloud Firestore

Google BigQuery admite la carga de datos de las exportaciones de Cloud Firestore creadas mediante el servicio de importación y exportación administrado de Cloud Firestore. El servicio de importación y exportación administrado exporta documentos de Cloud Firestore a un depósito de Cloud Storage. A continuación, puedes cargar los datos exportados en una tabla de BigQuery.

Permisos necesarios

Cuando cargas datos en BigQuery, necesitas permisos de proyecto o de nivel de conjunto de datos que te permitan cargar datos en tablas y particiones de BigQuery nuevas o existentes. Si cargas datos de Cloud Storage, también necesitas acceso al depósito que contiene tus datos.

Permisos de BigQuery

Cuando cargas datos en BigQuery desde Cloud Storage, se te debe otorgar la función bigquery.dataOwner o bigquery.dataEditor a nivel de proyecto o a nivel de conjunto de datos. Ambas funciones otorgan a los usuarios y grupos el permiso para cargar datos en una tabla nueva o agregar o reemplazar una tabla existente.

Otorgar las funciones a nivel de proyecto le da al usuario o al grupo permiso para cargar datos en tablas en cada conjunto de datos del proyecto. Otorgar las funciones a nivel de conjunto de datos le da al usuario o al grupo la capacidad para cargar datos solo en las tablas de ese conjunto de datos.

Para obtener más información sobre cómo configurar el acceso al conjunto de datos, consulta Control de acceso al conjunto de datos. A fin de obtener más información sobre las funciones IAM en BigQuery, consulta Control de acceso.

Permisos de Cloud Storage

Para cargar datos desde un depósito de Cloud Storage, se te deben otorgar permisos de storage.objects.get en el nivel del proyecto o en ese depósito individual. Si usas un comodín URI, también debes tener permisos storage.objects.list.

La función predefinida de IAM storage.objectViewer se puede otorgar para proporcionar permisos storage.objects.get y storage.objects.list.

Nota: Algunas de las funciones descritas anteriormente no son compatibles cuando se cargan las exportaciones de Cloud Firestore. No puedes usar comodines URI ni agregar datos a una tabla existente cuando cargas datos de una exportación de Cloud Firestore.

Limitaciones

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

• 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 URI.
• Para que una exportación de Cloud Firestore se cargue correctamente, los documentos en los datos de exportación deben compartir un esquema coherente con menos de 10,000 nombres de campo único.
• Puedes crear una tabla nueva para almacenar los datos o puedes reemplazar una tabla existente. No puedes agregar datos de exportación de Cloud Firestore a una tabla existente.
• Si planeas cargar una exportación de Cloud Firestore en BigQuery, debes especificar un filtro collection-ids en tu comando de exportación. Los datos exportados sin especificar un filtro de ID de colección no se pueden cargar en BigQuery.

Cómo cargar datos del servicio de exportación de Cloud Firestore

Puedes cargar datos de un archivo de metadatos de exportación de Cloud Firestore con la IU web de BigQuery, la herramienta de línea de comandos de bq o la API.

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

Nota: Puedes cargar campos específicos usando la marca --projection_fields en la CLI o configurando la propiedad projectionFields en la API. Esta característica no está disponible en la IU web de BigQuery.

IU web clásica

1. Ve a la IU web de BigQuery.
   Ir a la IU web de BigQuery
2. En el panel de navegación, desplázate sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y haz clic en Crear tabla nueva.

3. En la página Crear tabla, en la sección Datos de origen:

   • Deja seleccionada la opción Crear desde la fuente.

   • Para la Ubicación, selecciona Google Cloud Storage y 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 para tu archivo de exportación de Cloud 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 generado por Cloud Firestore.

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

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

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

4. En la página Crear tabla, en la sección Tabla de destino:

   • Para el Nombre de tabla, elige el conjunto de datos apropiado. Luego, ingresa el nombre de la tabla que quieres crear en BigQuery en el campo correspondiente.
   • Verifica que el Tipo de tabla esté configurado en Tabla nativa.

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

6. Selecciona los elementos aplicables en la sección Opciones. Si reemplazas una tabla existente, establece la Preferencia de escritura en Reemplazar tabla.

7. Haz clic en Crear tabla.

Línea de comandos

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

Para cargar solo campos específicos, usa el indicador --projection_fields.

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

Donde:

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

Por ejemplo, el siguiente comando carga el archivo de exportación de Cloud Firestore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata en una tabla llamada book_data. mybucket y mydataset se crearon en la ubicación de varias regiones de 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 siguientes propiedades para cargar los datos de exportación de Cloud Firestore con la API.

1. Crea un trabajo de carga que apunte a los datos de origen en Google Cloud Storage.

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

3. Los URI de origen deben estar completamente calificados en el formato gs://[BUCKET]/[OBJECT]. El nombre del archivo (objeto) debe terminar en [KIND_NAME].export_metadata. Solo se permite un URI para las exportaciones de Cloud Firestore, y no puede usar un comodín.

4. Especifica el formato de datos configurando la propiedad configuration.load.sourceFormat en DATASTORE_BACKUP. La copia de seguridad de Cloud Datastore Backup es la opción correcta para Cloud Firestore. Cloud Firestore y Cloud 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 configurando la propiedad configuration.load.writeDisposition en WRITE_TRUNCATE.

Nota: Si prefieres omitir el proceso de carga, puedes consultar la exportación directamente configurándola como una fuente de datos externa. Para obtener más información, consulta Fuentes de datos externas.

Opciones de Cloud Firestore

Para cambiar la forma en que BigQuery analiza los datos de exportación de Cloud Firestore, especifica las siguientes opciones:

Opción CSV	Opción de IU web	Marca CLI	Propiedad de la API de BigQuery	Descripción
Campos de proyección	Ninguno	--projection_fields	projectionFields	(Opcional) Una lista separada por comas que indica qué campos de documento se deben cargar desde una exportación de Cloud Firestore. 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 mapa como map.foo.
Cantidad de registros incorrectos permitidos	Cantidad de errores permitidos	--max_bad_records	maxBadRecords	(Opcional) El número máximo de registros erróneos que BigQuery puede ignorar cuando ejecuta el trabajo. Si el número de registros incorrectos excede este valor, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es 0, por lo que es obligatorio que todos los registros sean válidos.

Conversión de tipo de datos

BigQuery convierte los datos de cada documento en los archivos de exportación de Cloud Firestore a los tipos de datos de BigQuery. La siguiente tabla describe la conversión entre tipos de datos.

Tipos de datos de Cloud Firestore	Tipos de datos de BigQuery
Arreglo	REGISTRO
Booleano	BOOLEANO
Referencia	REGISTRO
Fecha y hora	MARCA DE TIEMPO
Mapa	REGISTRO
Número de coma flotante	FLOAT
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 Cloud 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 de cada información, como se describe en la siguiente tabla.

Propiedad clave	Descripción	Tipos de datos de BigQuery
__key__.app	El nombre de la aplicación de Cloud Firestore.	STRING
__key__.id	El ID del documento o null si __key__.name está configurado.	NÚMERO ENTERO
__key__.kind	El ID de la colección del documento.	STRING
__key__.name	El nombre del documento o null si __key__.id está configurado.	STRING
__key__.namespace	Cloud Firestore no admite espacio de nombres personalizado. El espacio de nombres predeterminado está representado por una string vacía.	STRING
__key__.path	La ruta del documento: La secuencia del documento y los pares de la colección de la colección raíz. Por ejemplo: "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRING