Carga datos de exportaciones de Datastore

BigQuery admite la carga de datos de exportaciones de Datastore que se crearon mediante el servicio de importación y exportación administrado de Datastore. Puedes usar el servicio de importación y exportación administrado para exportar entidades de Datastore en un depósito de Cloud Storage. Luego, puedes cargar la exportación en BigQuery como una tabla.

Para obtener información sobre cómo crear un archivo de exportación de Datastore, consulta Importa y exporta entidades en la documentación de Datastore. Para obtener información sobre cómo programar las exportaciones, consulta Programa una exportación.

Nota: Si quieres cargar una exportación de Datastore en BigQuery, debes especificar un filtro de entidad en tu comando de exportación. Los datos que se exportan sin especificar un filtro de entidad no se pueden cargar en BigQuery.

Puedes controlar qué propiedades debe cargar BigQuery si configuras la propiedad projectionFields en la API o si usas la marca --projection_fields en la herramienta de línea de comandos de bq.

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

Cuando cargas datos de Cloud Storage en una tabla de BigQuery, el conjunto de datos que contiene la tabla debe estar en la misma región o multirregión que el bucket de Cloud Storage.

Limitaciones

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

• No puedes usar un comodín en el URI de Cloud Storage cuando especificas un archivo de exportación de Datastore.
• Puedes especificar solo un URI de Cloud Storage cuando cargas datos de exportaciones de Datastore.
• No se pueden adjuntar datos de exportación de Datastore a una tabla existente con un esquema definido.
• Para que una exportación de Datastore se cargue de forma correcta, las entidades en los datos de exportación deben compartir un esquema coherente con menos de 10,000 nombres de propiedad únicos.
• Los datos que se exportan sin especificar un filtro de entidad no pueden cargarse en BigQuery. La solicitud de exportación debe incluir uno o más nombres de categorías en el filtro de entidad.
• El tamaño máximo de campo para las exportaciones de Datastore es de 64 KB. Cuando cargas una exportación de Datastore, cualquier campo superior a 64 KB se trunca.

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 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 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 Datastore

Para cargar datos desde un archivo de metadatos de exportación de Datastore, haz lo siguiente:

Console

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

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
4. En el panel Crear tabla, especifica los siguientes detalles:
1. En la sección Fuente, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. 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 de tu archivo de exportación de Datastore debe terminar con KIND_NAME.export_metadata o export[NUM].export_metadata. Por ejemplo, en default_namespace_kind_Book.export_metadata, Book es el nombre de la categoría y default_namespace_kind_Book es el nombre de archivo que generó Datastore.
   2. En Formato del archivo, selecciona Copia de seguridad de Cloud Datastore
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, no es necesaria ninguna acción. El esquema se infiere de una exportación de Datastore.
4. 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.
5. 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.
   Para obtener más información sobre las opciones disponibles, consulta las opciones de Datastore.
6. 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.

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. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• 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 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 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata de Datastore 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 siguientes propiedades para cargar los datos de exportación de Datastore con la API.

1. Crea un trabajo de carga 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 URI de origen deben estar completamente calificados en el formato gs://[BUCKET]/[OBJECT]. El nombre del archivo (objeto) debe terminar con [KIND_NAME].export_metadata. Solo se permite un URI para las exportaciones de Datastore y no puedes usar un comodín.

4. Para especificar el formato de los datos, establece la propiedad JobConfigurationLoad.sourceFormat como DATASTORE_BACKUP.

Reemplaza una tabla con datos de Datastore o adjúntalos a una nueva

Cuando cargas datos de exportación de Datastore en BigQuery, puedes crear una tabla nueva para almacenar los datos o puedes reemplazar una existente. No puedes adjuntar datos de exportación de Datastore a una tabla existente.

Si intentas adjuntar datos de exportación de Datastore a una tabla existente, se produce el siguiente error: Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

Para reemplazar una tabla existente con datos de exportación de Datastore, haz lo siguiente:

Console

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

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
4. En el panel Crear tabla, especifica los siguientes detalles:
1. En la sección Fuente, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. 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 de tu archivo de exportación de Datastore debe terminar con KIND_NAME.export_metadata o export[NUM].export_metadata. Por ejemplo, en default_namespace_kind_Book.export_metadata, Book es el nombre de la categoría y default_namespace_kind_Book es el nombre de archivo que generó Datastore.
   2. En Formato del archivo, selecciona Copia de seguridad de Cloud Datastore
Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, no es necesaria ninguna acción. El esquema se infiere de una exportación de Datastore.
Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
4. 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. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres. La consola de Google Cloud no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
5. Haz clic en Opciones avanzadas y haz lo siguiente:
   • En Preferencia de escritura, elige Agregar a la tabla o Reemplazar tabla.
   • 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.
   Para obtener más información sobre las opciones disponibles, consulta las opciones de Datastore.
6. Haz clic en Crear tabla.

bq

Usa el comando bq load con la marca --replace y con source_format configurado como DATASTORE_BACKUP. Proporciona la marca --location y configura el valor según tu ubicación.

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

Reemplaza lo siguiente:

• LOCATION: Es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• DATASET: Es el conjunto de datos que contiene la tabla en la que deseas cargar los datos.
• TABLE: Es la tabla que deseas reemplazar.
• 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 Datastore y reemplaza una tabla llamada book_data:

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

API

Configura las siguientes propiedades para cargar datos desde la API.

1. Crea un trabajo de carga 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 URI de origen deben estar completamente calificados en el formato gs://[BUCKET]/[OBJECT]. El nombre del archivo (objeto) debe terminar con [KIND_NAME].export_metadata. Solo se permite un URI para las exportaciones de Datastore y no puedes usar un comodín.

4. Para especificar el formato de los datos, establece la propiedad JobConfigurationLoad.sourceFormat como DATASTORE_BACKUP.

5. Configura la propiedad JobConfigurationLoad.writeDisposition como WRITE_TRUNCATE para especificar la disposición de escritura.

Opciones de Datastore

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

Opción de Console	Marca de la herramienta de bq	Propiedad de la API de BigQuery	Descripción
No disponible	--projection_fields	projectionFields	Una lista separada por comas en la que se indica qué propiedades de la entidad se cargan en BigQuery desde una exportación de Datastore. Los nombres de propiedades distinguen entre mayúsculas y minúsculas, y deben ser propiedades de nivel superior. Si no se especifican propiedades, BigQuery carga todas las propiedades. Si alguna de las propiedades nombradas no se encuentra en la exportación de Datastore, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es ''.

Conversión de tipo de datos

BigQuery convierte los datos de cada entidad en los archivos de exportación de Datastore en tipos de datos de BigQuery. La siguiente tabla describe la conversión entre tipos de datos.

Tipo de datos de Datastore	Tipo de datos de BigQuery
Array	ARRAY
BLOB	BYTES
Booleano	BOOLEAN
Fecha y hora	TIMESTAMP
Entidad incorporada	RECORD
Número de punto flotante	FLOAT
Punto geográfico	RECORD [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Número entero	INTEGER
Clave	RECORD
Null	STRING
String de texto	STRING (truncado a 64 KB)

Propiedades de la clave de Datastore

Cada entidad en Datastore tiene una clave única que contiene información como el espacio de nombres y la ruta de acceso. BigQuery crea un tipo de dato RECORD para la clave, con campos anidados para cada tipo de información, como se describe en la siguiente tabla.

Propiedad clave	Descripción	Tipo de datos de BigQuery
__key__.app	El nombre de la app de Datastore	STRING
__key__.id	El ID de la entidad o null si se configura __key__.name	INTEGER
__key__.kind	La categoría de la entidad.	STRING
__key__.name	El nombre de la entidad o null si se configura __key__.id	STRING
__key__.namespace	Si la app de Datastore usa un espacio de nombres personalizado, debe ser el espacio de nombres de la entidad. De lo contrario, el espacio de nombres predeterminado estará representado por una string vacía	STRING
__key__.path	La ruta ancestral de la entidad acoplada, consiste en una secuencia de pares de identificadores de categoría desde la entidad raíz hasta la entidad misma. Por ejemplo: "Country", "USA", "PostalCode", 10011, "Route", 1234	STRING