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.

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 directamente mediante su configuración como una fuente de datos externa. Para obtener más información, consulta Introducción a las 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 ubicación regional o multirregional que el depósito 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.

Permisos necesarios

Cuando cargas datos en BigQuery, necesitas permisos para ejecutar un trabajo de carga y permisos que te habiliten a cargar datos en tablas y particiones nuevas o existentes de BigQuery. 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 obligatorios si los datos se cargan en una tabla o partición nueva, o si se reemplaza una tabla o partición o se agregan datos a esta.

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

Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.tables.create y bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso bigquery.dataOwner permite que el usuario cree y actualice tablas en el conjunto de datos mediante un trabajo de carga.

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Control de acceso.

Permisos de Cloud Storage

Para cargar datos desde un bucket 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 IAM storage.objectViewer para proporcionar los permisos storage.objects.get y storage.objects.list.

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. Abre la página de BigQuery en Cloud Console.

    Ir a la página de BigQuery

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto de Google Cloud 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.

    Crear tabla.

  3. 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 el conjunto de datos que contiene la tabla que deseas crear. El URI para tu archivo de exportación de Datastore debe terminar con [KIND_NAME].export_metadata o export[NUM].export_metadata. Por ejemplo: default_namespace_kind_Book.export_metadata. En este ejemplo, Book es el nombre de la categoría y default_namespace_kind_Book es el nombre del archivo que generó Datastore.
    • En Formato del archivo, selecciona Copia de seguridad de Datastore.
  4. En la página Crear tabla, en la sección Destino (Destination), haz lo siguiente:

    • En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.

      Seleccionar conjunto de datos.

    • En el campo Nombre de la 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).

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

  6. Selecciona los elementos aplicables en la sección Opciones avanzadas y haz clic en Crear tabla. Para obtener más información sobre las opciones disponibles, consulta las opciones de Datastore.

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. Especifica el formato de datos mediante la configuración de la propiedad configuration.load.sourceFormat como DATASTORE_BACKUP.

Copias de seguridad del administrador de Datastore

Si usas la función de copia de seguridad del administrador de Datastore para exportar tus datos de Datastore, ten en cuenta que la extensión del archivo será .backup_info en lugar de .export_metadata. Cuando importas tus datos a BigQuery, puedes usar un archivo .backup_info o .export_metadata hasta que el servicio de copias de seguridad del administrador de Datastore deje de estar disponible.

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. Abre la página de BigQuery en Cloud Console. Ir a la página de BigQuery
  2. En el panel de navegación, en la sección Recursos, expande tu proyecto de Cloud 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. Crear tabla.
  3. En la página Crear tabla, en la sección Origen, realiza 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 el conjunto de datos que contiene la tabla que deseas crear. El URI del archivo de exportación de Datastore debe terminar con [KIND_NAME].export_metadata. Por ejemplo: default_namespace_kind_Book.export_metadata. En este ejemplo, Book es el nombre de la categoría y default_namespace_kind_Book es el nombre del archivo que generó Datastore.

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

    • En Formato de archivo, selecciona Copia de seguridad de Datastore.

  4. En la página Crear tabla, en la sección Destino (Destination), haz lo siguiente:

    • En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.

      Seleccionar conjunto de datos.

    • En el campo Nombre de la 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).

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

  6. En la sección Opciones avanzadas, en Preferencia de escritura, selecciona Reemplazar tabla.

  7. 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. Especifica el formato de datos mediante la configuración de la propiedad configuration.load.sourceFormat como DATASTORE_BACKUP.

  5. Configura la propiedad configuration.load.writeDisposition como WRITE_TRUNCATE.

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
BLOB BYTES
Clave de blobstore STRING
Booleano BOOLEANO
Categoría STRING
Clave de Datastore REGISTRO
Fecha y hora MARCA DE TIEMPO
Correo electrónico STRING
Entidad incorporada REGISTRO
Número de punto flotante FLOTANTE
Punto geográfico

REGISTRO


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
Controlador de IM STRING
Número entero NÚMERO ENTERO
Vínculo STRING
Número de teléfono STRING
Dirección postal STRING
Calificación NÚMERO ENTERO
BLOB corto BYTES
String STRING (truncado a 64 KB)
Usuario

REGISTRO


[{"email","STRING"}
 {"userid","STRING"}]
        

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, que 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