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.
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 que el bucket 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 roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para hacer cada tarea de este documento.
Permisos necesarios
Si deseas cargar datos en BigQuery, necesitas permisos de IAM para ejecutar un trabajo de carga y subir datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos de IAM para acceder al bucket que contiene tus datos.
Permisos para cargar datos a BigQuery
Para cargar datos en una tabla o partición de BigQuery nueva o bien 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 permisobigquery.jobs.create
)bigquery.user
(incluye el permisobigquery.jobs.create
)bigquery.jobUser
(incluye el permisobigquery.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 subir datos desde Cloud Storage
Para obtener los permisos que necesitas para cargar datos desde un bucket de Cloud Storage,
pídele a tu administrador que te otorgue el rol de IAM
Administrador de almacenamiento (roles/storage.admin
) en el bucket.
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Este rol predefinido contiene los permisos necesarios para cargar datos desde un bucket de Cloud Storage. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios
Los siguientes permisos son necesarios para cargar datos desde un bucket de Cloud Storage:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.
Carga datos del servicio de exportación de Cloud Firestore
Puedes cargar datos de un archivo de metadatos de exportación de Firestore mediante la consola de Google Cloud, la, herramienta de línea de comandos de bql o la API.
En ocasiones, la terminología de Datastore se usa en la consola de Google Cloud 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.
Console
En la consola de Google Cloud, ve a la página de BigQuery.
- En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
- En la sección Información del conjunto de datos, haz clic en Crear tabla.
- En el panel Crear tabla, especifica los siguientes detalles:
- En la sección Fuente, elige Google Cloud Storage en la lista Crear tabla desde.
A continuación, sigue estos pasos:
- Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage.
No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
El URI del archivo de exportación de Firestore debe terminar conKIND_COLLECTION_ID.export_metadata
. Por ejemplo, endefault_namespace_kind_Book.export_metadata
,Book
es el ID de colección ydefault_namespace_kind_Book
es el nombre del archivo que Firestore generó. Si el URI no termina conKIND_COLLECTION_ID.export_metadata
, recibirás el siguiente mensaje de error: does not contain valid backup metadata. (error code: invalid). - En Formato del archivo, selecciona Copia de seguridad de Cloud Datastore Firestore y Datastore comparten el formato de exportación.
- Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage.
No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
- En la sección Destino, especifica los siguientes detalles:
- En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
- En el campo Tabla, escribe el nombre de la tabla que deseas crear.
- Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
- En la sección Esquema (Schema), no es necesaria ninguna acción. El esquema se infiere para una exportación de Firestore.
- Opcional: Especifica Configuración de particiones y clústeres. Para obtener más información, consulta Crea tablas particionadas y Crea y usa tablas agrupadas en clústeres.
- Haz clic en Opciones avanzadas y haz lo siguiente:
- En Preferencia de escritura, deja elegido Escribir si está vacía. Con esta opción, se crea una tabla nueva y se cargan los datos en ella.
- Si deseas ignorar los valores de una fila que no están presentes en el esquema de la tabla, elige Valores desconocidos.
- En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración del parámetro Clave administrada por Google, BigQuery encripta los datos en reposo.
- Haga clic en Create table.
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.
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 estar completamente calificados y en el formatogs://BUCKET/OBJECT
en la configuración del trabajo de carga. El nombre del archivo (objeto) debe terminar enKIND_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
.
Python
Antes de probar este ejemplo, 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. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
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 la consola de Google Cloud | 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 mayúsculas de 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 | RECORD |
Booleano | BOOLEAN |
Referencia | RECORD |
Fecha y hora | TIMESTAMP |
Mapa | RECORD |
Número de punto flotante | FLOAT |
Punto geográfico |
RECORD [{"lat","FLOAT"}, {"long","FLOAT"}] |
Número entero | INTEGER |
Cadena | 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 |