Cómo cargar 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 CLI.

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.
  • 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 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 necesarios si cargas los datos en una tabla o partición nueva, o si adjuntas o reemplazas 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 los 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á el 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 y los permisos de Cloud IAM en BigQuery, consulta la página sobre el 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 Datastore

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

Console

  1. Abre la IU web de BigQuery en Cloud Console.

    Ir a la IU web de BigQuery

  2. 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.

    Crear tabla

  3. En la página Crear tabla, en la sección Fuente haz lo siguiente:

    • En Crear una 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 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 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 hace falta que realices 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.

IU clásica

  1. Ve a la IU web clásica de BigQuery.
    Ir a la IU web de BigQuery
  2. En el panel de navegación, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo imagen del ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.
  3. En la página Crear tabla, en la sección Datos de origen, sigue estos 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 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 Tabla de destino, realiza lo siguiente:
    • En Nombre de tabla, selecciona el conjunto de datos apropiado y, en el campo de nombre de tabla, ingresa el nombre de la tabla que deseas crear en BigQuery.
    • Verifica que Tipo de tabla esté configurado como Tabla nativa.
  5. En la sección Esquema, no hace falta que realices ninguna acción. El esquema se infiere de una exportación de Datastore.
  6. Selecciona los elementos aplicables en la sección Opciones y haz clic en Crear tabla. Para obtener más información sobre las opciones disponibles, consulta las opciones de Datastore.

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.

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

en el que:

  • [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 con el archivo .bigqueryrc.
  • [FORMAT] es DATASTORE_BACKUP.
  • [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 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 IU web de BigQuery en Cloud Console. Ir a la IU web de BigQuery
  2. 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. Crear tabla
  3. En la página Crear tabla, en la sección Fuente haz lo siguiente:

    • En Crear una 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 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 hace falta que realices 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.

IU clásica

  1. Ve a la IU web clásica de BigQuery.
    Ir a la IU web de BigQuery
  2. En el panel de navegación, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo imagen del ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.
  3. En la página Crear tabla, en la sección Datos de origen, sigue estos 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 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 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 deseas reemplazar.
    • Verifica que Tipo de tabla esté configurado como Tabla nativa.
  5. En la sección Esquema, no hace falta que realices ninguna acción. El esquema se infiere de una exportación de Datastore.
  6. En la sección Opciones, en Preferencia de escritura, selecciona Reemplazar tabla.
  7. Haz clic en Crear tabla.

CLI

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]

en el que:

  • [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 con el archivo .bigqueryrc.
  • [FORMAT] es DATASTORE_BACKUP.
  • [DATASET] es el conjunto de datos que contiene la tabla en la que cargas 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 que BigQuery analiza los datos de exportación de Datastore, especifica opciones adicionales en la IU web clásica, la CLI o la API.

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 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 ''.
Cantidad de registros incorrectos permitidos Cantidad de errores permitidos --max_bad_records maxBadRecords La cantidad máxima de registros incorrectos que BigQuery puede ignorar cuando ejecuta el trabajo (opcional). Si la cantidad 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 entidad en los archivos de exportación de Datastore en 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
BLOB BigQuery descarta estos valores cuando se cargan los datos.
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 BigQuery descarta estos valores cuando se cargan los datos.
String STRING (truncada 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 NÚMERO ENTERO
__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
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.