Cargar datos desde exportaciones de Datastore

BigQuery admite la carga de datos de exportaciones de Datastore creadas con el servicio de importación y exportación gestionado de Datastore. Puedes usar el servicio de importación y exportación gestionado para exportar entidades de Datastore a un segmento de Cloud Storage. Después, puedes cargar la exportación en BigQuery como una tabla.

Para saber cómo crear un archivo de exportación de Datastore, consulta el artículo Exportar e importar entidades de la documentación de Datastore. Para obtener información sobre cómo programar exportaciones, consulta el artículo Programar una exportación.

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

Si prefieres saltarte el proceso de carga, puedes consultar la exportación directamente configurándola como 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 segmento de Cloud Storage.

Limitaciones

Cuando cargas 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 especifiques un archivo de exportación de Datastore.
  • Solo puedes especificar un URI de Cloud Storage al cargar datos desde exportaciones de Datastore.
  • No puedes añadir datos de exportación de Datastore a una tabla que ya tenga un esquema definido.
  • Para que una exportación de Datastore se cargue correctamente, las entidades de los datos exportados deben compartir un esquema coherente con menos de 10.000 nombres de propiedades únicos.
  • Los datos exportados sin especificar un filtro de entidad no se pueden cargar en BigQuery. La solicitud de exportación debe incluir uno o varios nombres de tipo en el filtro de entidades.
  • El tamaño máximo de los campos de las exportaciones de Datastore es de 64 KB. Cuando cargas una exportación de Datastore, se trunca cualquier campo que supere los 64 KB.

Antes de empezar

Concede roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos obligatorios

Para cargar datos en BigQuery, necesitas permisos de gestión de identidades y accesos 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 de IAM para acceder al segmento que contiene tus datos.

Permisos para cargar datos en BigQuery

Para cargar datos en una tabla o partición de BigQuery, o bien para añadir o sobrescribir una tabla o partición, necesitas los siguientes permisos de gestión de identidades y accesos:

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

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos 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 mediante un trabajo de carga en los conjuntos de datos que crees.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Permisos para cargar datos desde Cloud Storage

Para obtener los permisos que necesitas para cargar datos desde un segmento de Cloud Storage, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Storage (roles/storage.admin) en el segmento. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para cargar datos desde un segmento de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para cargar datos desde un segmento de Cloud Storage, se necesitan los siguientes permisos:

  • 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 u otros roles predefinidos.

Cargar datos del servicio de exportación de Datastore

Para cargar datos desde un archivo de metadatos de exportación de Datastore, sigue estos pasos:

Consola

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

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona 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, selecciona Google Cloud Storage en la lista Crear tabla a partir de. A continuación, siga estos pasos:
      1. Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage. No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
        El URI del archivo de exportación de Datastore debe terminar en KIND_NAME.export_metadata o export[NUM].export_metadata. Por ejemplo, en default_namespace_kind_Book.export_metadata, Book es el nombre del tipo y default_namespace_kind_Book es el nombre de archivo generado por Datastore. Seleccionar el archivo de origen para crear una tabla de BigQuery
      2. En Formato de archivo, selecciona Copia de seguridad de Cloud Datastore.
    2. En la sección Destino, especifica los siguientes detalles:
      1. En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
      2. En el campo Tabla, introduce el nombre de la tabla que quieras crear.
      3. Verifica que el campo Tipo de tabla sea Tabla nativa.
    3. En la sección Esquema, no es necesario que haga nada. El esquema se infiere para una exportación de Datastore.
    4. Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres.
    5. Haz clic en Opciones avanzadas y haz lo siguiente:
      • En Write preference (Preferencia de escritura), deja seleccionada la opción Write if empty (Escribir si está vacía). Con esta opción se crea una tabla y se cargan los datos en ella.
      • Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
      • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
        • Para obtener información sobre las opciones disponibles, consulta Opciones de Datastore.
    6. Haz clic en Crear tabla.

bq

Usa el comando bq load con source_format definido como DATASTORE_BACKUP. Proporcione la marca --location y asigne el valor de su ubicación.

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

Haz los cambios siguientes:

  • LOCATION: tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes asignar el valor asia-northeast1 a la marca. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: el conjunto de datos que contiene la tabla en la que vas a cargar los datos.
  • TABLE: la tabla en la que está cargando datos. Si la tabla no existe, se crea.
  • PATH_TO_SOURCE: el URI de Cloud Storage.

Por ejemplo, el siguiente comando carga el archivo de exportación de Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata book_data 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

Defina las siguientes propiedades para cargar datos de exportación de Datastore mediante la API.

  1. Crea una tarea de carga que apunte a los datos de origen en Cloud Storage.

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

  3. Los URIs de origen deben ser completos y tener 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 Datastore y no se pueden usar comodines.

  4. Para especificar el formato de los datos, asigna el valor DATASTORE_BACKUP a la propiedad JobConfigurationLoad.sourceFormat.

Añadir datos de Datastore a una tabla o sobrescribirla

Cuando cargas datos de exportación de Datastore en BigQuery, puedes crear una tabla para almacenar los datos o sobrescribir una tabla. No puedes añadir datos de exportación de Datastore a una tabla que ya tengas.

Si intentas añadir datos de exportación de Datastore a una tabla, se producirá 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 sobrescribir una tabla con datos de exportación de Datastore, sigue estos pasos:

Consola

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

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona 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, selecciona Google Cloud Storage en la lista Crear tabla a partir de. A continuación, siga estos pasos:
      1. Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage. No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
        El URI del archivo de exportación de Datastore debe terminar en KIND_NAME.export_metadata o export[NUM].export_metadata. Por ejemplo, en default_namespace_kind_Book.export_metadata, Book es el nombre del tipo y default_namespace_kind_Book es el nombre de archivo generado por Datastore. Seleccionar el archivo de origen para crear una tabla de BigQuery
      2. En Formato de archivo, selecciona Copia de seguridad de Cloud Datastore.
    2. En la sección Destino, especifica los siguientes detalles:
      1. En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
      2. En el campo Tabla, introduce el nombre de la tabla que quieras crear.
      3. Verifica que el campo Tipo de tabla sea Tabla nativa.
    3. En la sección Esquema, no es necesario que haga nada. El esquema se infiere para una exportación de Datastore.
    4. Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres. No puedes convertir una tabla en una tabla particionada o agrupada añadiéndole datos o sobrescribiéndola. La consola de Google Cloud no admite añadir datos a tablas particionadas o agrupadas, ni sobrescribirlas, en una tarea de carga.
    5. Haz clic en Opciones avanzadas y haz lo siguiente:
      • En Preferencia de escritura, elija Añadir a la tabla o Sobrescribir tabla.
      • Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
      • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
        • Para obtener información sobre las opciones disponibles, consulta Opciones de Datastore.
    6. Haz clic en Crear tabla.

bq

Usa el comando bq load con la marca --replace y con source_format asignado a DATASTORE_BACKUP. Indique la marca --location y asigne el valor de su ubicación.

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

Haz los cambios siguientes:

  • LOCATION: tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes asignar el valor asia-northeast1 a la marca. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: el conjunto de datos que contiene la tabla en la que vas a cargar los datos.
  • TABLE: la tabla que vas a sobrescribir.
  • PATH_TO_SOURCE: el URI de Cloud Storage.

Por ejemplo, el siguiente comando carga el archivo de exportación de Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata y sobrescribe 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

Defina las siguientes propiedades para cargar datos de la API.

  1. Crea una tarea de carga que apunte a los datos de origen en Cloud Storage.

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

  3. Los URIs de origen deben ser completos y tener 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 Datastore y no se pueden usar comodines.

  4. Para especificar el formato de los datos, asigna el valor DATASTORE_BACKUP a la propiedad JobConfigurationLoad.sourceFormat.

  5. Especifica la disposición de escritura asignando el valor WRITE_TRUNCATE a la propiedad JobConfigurationLoad.writeDisposition.

Opciones de Datastore

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

Opción de consola Marca de la herramienta bq Propiedad de la API de BigQuery Descripción
No disponible --projection_fields projectionFields Lista separada por comas que indica qué propiedades de entidad se deben cargar en BigQuery desde una exportación de Datastore. Los nombres de las propiedades distinguen entre mayúsculas y minúsculas, y deben ser propiedades de nivel superior. Si no se especifica ninguna propiedad, BigQuery carga todas las propiedades. Si no se encuentra ninguna propiedad con nombre en la exportación de Datastore, se devuelve 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 de los archivos de exportación de Datastore a tipos de datos de BigQuery. En la siguiente tabla se describe la conversión entre tipos de datos.

Tipo de datos de Datastore Tipo de datos de BigQuery
Matriz ARRAY
Blob BYTES
Booleano BOOLEAN
Fecha y hora TIMESTAMP
Entidad insertada RECORD
Número de punto flotante FLOAT
Punto geográfico

RECORD

[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
Entero INTEGER
Clave RECORD
Nulo STRING
Cadena de texto STRING (truncado a 64 KB)

Propiedades de clave de Datastore

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

Propiedad clave Descripción Tipo de datos de BigQuery
__key__.app El nombre de la aplicación Datastore. STRING
__key__.id El ID de la entidad o null si se ha definido __key__.name. INTEGER
__key__.kind Tipo de entidad. STRING
__key__.name El nombre de la entidad o null si __key__.id está definido. STRING
__key__.namespace Si la aplicación Datastore usa un espacio de nombres personalizado, el espacio de nombres de la entidad. De lo contrario, el espacio de nombres predeterminado se representa mediante una cadena vacía. STRING
__key__.path La ruta ancestral de la entidad, que se compone de la secuencia de pares de tipo e identificador desde la entidad raíz hasta la entidad en sí. Por ejemplo: "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING