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.
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.
Permisos necesarios
Cuando cargas datos en BigQuery, necesitas permisos para ejecutar un trabajo de carga y cargar datos en tablas y particiones de BigQuery nuevas o existentes. Si cargas datos desde Cloud Storage, también necesitas permisos para acceder al depósito que contiene tus datos.
Permisos de BigQuery
Para cargar datos en BigQuery, se requieren, como mínimo, los siguientes permisos. Estos permisos son necesarios si los datos se cargan en una tabla o partición nueva, o si se agrega o reemplaza una tabla o partición.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.create
y bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Las siguientes funciones predefinidas de Cloud IAM incluyen permisos bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Además, si un usuario tiene permisos bigquery.datasets.create
, cuando cree un conjunto de datos, se le otorgará acceso bigquery.dataOwner
a este.
El acceso bigquery.dataOwner
permite al usuario crear y actualizar tablas en el conjunto de datos a través de un trabajo de carga.
Para obtener más información sobre las funciones de Cloud IAM y los permisos en BigQuery, consulta Control de acceso.
Permisos de Cloud Storage
Para cargar datos desde un depósito de Cloud Storage, debes tener permisos storage.objects.get
. Si usas un comodín de URI, también debes tener permisos storage.objects.list
.
Se puede otorgar la función predefinida de Cloud IAM storage.objectViewer
para proporcionar los permisos storage.objects.get
y storage.objects.list
.
Carga datos del servicio de exportación de Cloud Firestore
Puedes cargar datos desde un archivo de metadatos de exportación de 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 Datastore se usa en la IU o en los comandos, pero los procedimientos siguientes son compatibles con archivos de exportación de Firestore. Firestore y Datastore comparten un formato de exportación.
Console
- Abre la IU web de BigQuery en Cloud Console.
Ir a la IU web de BigQuery - En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos. Haz clic en Crear tabla (Create table). El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.
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 colección ydefault_namespace_kind_Book
es el nombre del archivo que Firestore generó.Verifica que se especifique
[KIND_COLLECTION_ID]
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)
.En Formato de 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.
En la página Crear tabla, en la sección Destino (Destination), sigue estos pasos:
En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
En el campo Nombre de 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).
No es necesario que realices ninguna acción en la sección Esquema. El esquema se infiere para una exportación de Firestore.
Selecciona los elementos aplicables en la sección Opciones avanzadas (Advanced options). Si reemplazas una tabla existente, configura Preferencia de escritura (Write preference) como Reemplazar tabla (Overwrite table).
Haz clic en Crear tabla (Create table).
IU clásica
- Ve a la IU web clásica de BigQuery.
Ir a la IU web de BigQuery - En el panel de navegación, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo
y, luego, en Crear tabla nueva.
En la página Crear tabla, en la sección Datos de origen, realiza los siguientes pasos:
- Deja seleccionada la opción Crear desde la fuente.
En Ubicación, selecciona 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 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 colección ydefault_namespace_kind_Book
es el nombre del archivo que Firestore generó.Verifica que se especifique
[KIND_COLLECTION_ID]
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)
.En Formato de 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.
En la página Crear tabla, en la sección Tabla de destino, realiza lo siguiente:
- En Nombre de tabla, selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
- Verifica que Tipo de tabla esté configurado como Tabla nativa.
No es necesario que realices ninguna acción en la sección Esquema. El esquema se infiere para una exportación de Firestore.
Selecciona los elementos aplicables en la sección Opciones. Si reemplazas una tabla existente, configura Preferencia de escritura como Reemplazar tabla.
Haz clic en Crear tabla.
CLI
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]
En el comando anterior, se muestra lo siguiente:
[LOCATION]
es tu ubicación. La marca--location
es opcional.[FORMAT]
esDATASTORE_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 cargas datos.[TABLE]
es la tabla en la que cargas los datos. Si la tabla no existe, se creará.[PATH_TO_SOURCE]
es el URI de Cloud Storage.
Por ejemplo, el comando siguiente 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 multirregional 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.
Crea una configuración de trabajo de
load
que apunte a los datos de origen en Cloud Storage.Especifica tu ubicación en la propiedad
location
en la secciónjobReference
del recurso de trabajo.Los
sourceUris
deben tener calificación completa y estar en el formatogs://[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.Para especificar el formato de datos, establece la propiedad
sourceFormat
enDATASTORE_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.Para cargar solo campos específicos, establece la propiedad
projectionFields
.Si reemplazas una tabla existente, especifica la disposición de escritura mediante la configuración de la propiedad
writeDisposition
comoWRITE_TRUNCATE
.
Opciones de Firestore
Para cambiar la forma en la que BigQuery analiza los datos de exportación de Firestore, especifica las opciones siguientes:
Opción de CSV | Opción de la IU clásica | Marcador CLI | Propiedad de la API de BigQuery | Descripción |
---|---|---|---|---|
Campos de proyección | Ninguno | --projection_fields |
projectionFields |
Una lista separada por comas que indica qué campos de documento se deben cargar desde una exportación de Cloud 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 asignación como map.foo .
|
Cantidad de registros incorrectos permitidos | Cantidad de errores permitidos | --max_bad_records |
maxBadRecords |
El número máximo de registros erróneos que BigQuery puede ignorar cuando ejecuta el trabajo (opcional). 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 Firestore a los tipos de datos de BigQuery. En la siguiente tabla, se describe la conversión entre tipos de datos.
Tipo de datos de Firestore | Tipo de datos de BigQuery |
---|---|
Arreglo | RECORD |
Booleano | BOOLEAN |
Referencia | RECORD |
Fecha y hora | TIMESTAMP |
Asignación | RECORD |
Número de punto flotante | FLOAT |
Punto geográfico |
RECORD [{"lat","FLOAT"}, {"long","FLOAT"}] |
Número entero | INTEGER |
String | STRING (truncada 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 |