Importar y exportar datos en formato CSV

En esta página se describe cómo exportar datos de Spanner a archivos CSV o importar datos de archivos CSV a bases de datos con dialecto GoogleSQL o PostgreSQL de Spanner.

El proceso usa Dataflow. Puede exportar datos de Spanner a un segmento de Cloud Storage o importar datos a Spanner desde un segmento de Cloud Storage que contenga un archivo de manifiesto JSON y un conjunto de archivos CSV.

Antes de empezar

Para importar o exportar una base de datos de Spanner, primero debes habilitar las APIs de Spanner, Cloud Storage, Compute Engine y Dataflow:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

También necesitas suficiente cuota y los permisos de gestión de identidades y accesos necesarios.

Requisitos de cuota

Los requisitos de cuota para las tareas de importación o exportación son los siguientes:

  • Spanner: debes tener suficiente capacidad de computación para admitir la cantidad de datos que vas a importar. No se necesita capacidad de computación adicional para importar o exportar una base de datos, aunque es posible que tengas que añadir más capacidad de computación para que tu tarea se complete en un tiempo razonable. Para obtener más información, consulta Trabajos de Optimize.
  • Cloud Storage: para importar, debes tener un segmento que contenga los archivos que hayas exportado anteriormente. Para exportar, debe crear un segmento para los archivos exportados si aún no tiene ninguno. Puede hacerlo en la Google Cloud consola, ya sea en la página de Cloud Storage o al crear la exportación en la página de Spanner. No es necesario que defina un tamaño para el segmento.
  • Dataflow: las tareas de importación o exportación están sujetas a las mismas cuotas de CPU, uso de disco y dirección IP de Compute Engine que otras tareas de Dataflow.

  • Compute Engine: antes de ejecutar la tarea de importación o exportación, debes configurar las cuotas iniciales de Compute Engine, que utiliza Dataflow. Estas cuotas representan el número máximo de recursos que permites que Dataflow use en tu trabajo. Los valores iniciales recomendados son los siguientes:

    • CPUs: 200
    • Direcciones IP en uso: 200
    • Disco persistente estándar: 50 TB

    Por lo general, no tienes que hacer ningún otro ajuste. Dataflow proporciona escalado automático para que solo pagues por los recursos reales que se usen durante la importación o la exportación. Si tu trabajo puede usar más recursos, la interfaz de usuario de Dataflow muestra un icono de advertencia. El trabajo debería finalizar aunque haya un icono de advertencia.

Roles obligatorios

Para obtener los permisos que necesitas para exportar una base de datos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en la cuenta de servicio de trabajador de Dataflow:

Exportar datos de Spanner a archivos CSV

Para exportar datos de Spanner a archivos CSV en Cloud Storage, sigue las instrucciones para usar la CLI de Google Cloud y ejecutar una tarea con la plantilla de texto de Spanner a Cloud Storage.

También puedes consultar la información de esta página sobre cómo optimizar los trabajos lentos y los factores que afectan al rendimiento de los trabajos.

Importar datos de archivos CSV a Spanner

El proceso para importar datos de archivos CSV incluye los siguientes pasos:

  1. Exporta tus datos a archivos CSV y almacénalos en Cloud Storage. No incluyas una línea de encabezado.
  2. Crea un archivo de manifiesto JSON y almacénalo junto con los archivos CSV.
  3. Crea tablas de destino vacías en tu base de datos de Spanner o asegúrate de que los tipos de datos de las columnas de tus archivos CSV coincidan con los de las columnas correspondientes de tus tablas.
  4. Ejecuta la tarea de importación.

Paso 1: Exportar datos de una base de datos que no sea de Spanner a archivos CSV

El proceso de importación incorpora datos de archivos CSV ubicados en un segmento de Cloud Storage. Puede exportar datos en formato CSV desde cualquier fuente.

Cuando exporte sus datos, tenga en cuenta lo siguiente:

  • Los archivos de texto que se importen deben estar en formato CSV.

  • Los datos deben coincidir con uno de los siguientes tipos:

GoogleSQL 

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL 

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea

  • No tienes que incluir ni generar metadatos al exportar los archivos CSV.

  • No es necesario que sigas ninguna convención de nomenclatura específica para tus archivos.

Si no exportas los archivos directamente a Cloud Storage, debes subir los archivos CSV a un segmento de Cloud Storage.

Paso 2: Crea un archivo de manifiesto JSON

También debes crear un archivo de manifiesto con una descripción JSON de los archivos que quieras importar y colocarlo en el mismo segmento de Cloud Storage en el que hayas almacenado los archivos CSV. Este archivo de manifiesto contiene una matriz tables que incluye el nombre y las ubicaciones de los archivos de datos de cada tabla. El archivo también especifica el dialecto de la base de datos receptora. Si se omite el dialecto, se usará GoogleSQL de forma predeterminada.

El formato del archivo de manifiesto corresponde al siguiente tipo de mensaje, que se muestra aquí en formato de búfer de protocolo: 

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

En el siguiente ejemplo se muestra un archivo de manifiesto para importar tablas llamadas Albums y Singers en una base de datos con dialecto GoogleSQL. La tabla Albums usa el esquema de columna que obtiene el trabajo de la base de datos, y la tabla Singers usa el esquema que especifica el archivo de manifiesto: 

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

Paso 3: Crea la tabla de tu base de datos de Spanner

Antes de ejecutar la importación, debe crear las tablas de destino en su base de datos de Spanner. Si la tabla de Spanner de destino ya tiene un esquema, las columnas especificadas en el archivo de manifiesto deben tener los mismos tipos de datos que las columnas correspondientes del esquema de la tabla de destino.

Te recomendamos que crees índices secundarios, claves externas y flujos de cambios después de importar los datos a Spanner, no cuando crees la tabla inicialmente. Si tu tabla ya contiene estas estructuras, te recomendamos que las elimines y las vuelvas a crear después de importar los datos.

Paso 4: Ejecuta un trabajo de importación de Dataflow con gcloud

Para iniciar la tarea de importación, sigue las instrucciones para usar la CLI de Google Cloud para ejecutar una tarea con la plantilla de texto de Cloud Storage a Spanner.

Una vez que hayas iniciado un trabajo de importación, puedes ver los detalles del trabajo en la Google Cloud consola.

Una vez que se haya completado la tarea de importación, añade los índices secundarios, las claves externas y los flujos de cambios que necesites.

Selecciona una región para la tarea de importación

Puede que quieras elegir otra región en función de la ubicación de tu segmento de Cloud Storage. Para evitar cargos por transferencia de datos saliente, elige una región que coincida con la ubicación de tu segmento de Cloud Storage.

  • Si la ubicación de tu segmento de Cloud Storage es una región, puedes aprovechar el uso de red gratuito eligiendo la misma región para tu tarea de importación, siempre que esté disponible.

  • Si la ubicación de tu segmento de Cloud Storage es una región doble, puedes aprovechar el uso de red gratuito eligiendo una de las dos regiones que componen la región doble para tu tarea de importación, siempre que una de las regiones esté disponible.

  • Si no hay ninguna región colocada disponible para tu tarea de importación o si la ubicación de tu segmento de Cloud Storage es una multirregión, se aplicarán cargos por transferencia de datos saliente. Consulta los precios de la transferencia de datos de Cloud Storage para elegir una región que genere los cargos más bajos por transferencia de datos.

Ver o solucionar problemas de trabajos en la interfaz de Dataflow

Después de iniciar una tarea de importación o exportación, puedes ver los detalles de la tarea, incluidos los registros, en la sección Dataflow de la Google Cloud consola.

Ver los detalles de una tarea de Dataflow

Para ver los detalles de las tareas de importación o exportación que hayas ejecutado en la última semana, incluidas las que se estén ejecutando en este momento, sigue estos pasos:

  1. Vaya a la página Resumen de la base de datos de la base de datos.
  2. Haz clic en la opción de menú Importar/Exportar del panel de la izquierda. En la página Importar/Exportar de la base de datos se muestra una lista de las tareas recientes.

  3. En la página Importar/Exportar de la base de datos, haga clic en el nombre del trabajo de la columna Nombre del trabajo de Dataflow:

    Mensaje de estado de la tarea en curso

    La consola Google Cloud muestra los detalles del trabajo de Dataflow.

Para ver un trabajo que ejecutaste hace más de una semana, sigue estos pasos:

  1. Ve a la página de trabajos de Dataflow de la Google Cloud consola.

    Ir a Tareas

  2. Busca el trabajo en la lista y haz clic en su nombre.

    La consola Google Cloud muestra los detalles del trabajo de Dataflow.

Ver los registros de Dataflow de tu trabajo

Para ver los registros de un trabajo de Dataflow, ve a la página de detalles del trabajo y haz clic en Registros a la derecha del nombre del trabajo.

Si una tarea falla, busca errores en los registros. Si hay errores, el número de errores se mostrará junto a Registros:

Ejemplo de número de errores junto al botón Registros

Para ver los errores de las tareas, sigue estos pasos:

  1. Haz clic en el número de errores situado junto a Registros.

    La Google Cloud consola muestra los registros del trabajo. Puede que tengas que desplazarte para ver los errores.

  2. Busca las entradas que tengan el icono de error Icono de Error.

  3. Haz clic en una entrada de registro para ver su contenido.

Para obtener más información sobre cómo solucionar problemas de trabajos de Dataflow, consulta el artículo Solucionar problemas de una canalización.

Solucionar problemas con tareas de importación o exportación fallidas

Si ves los siguientes errores en los registros de tu trabajo:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Consulta la latencia de lectura/escritura del 99% en la pestaña Monitorización de tu base de datos de Spanner en la consola.Google Cloud Si muestra valores altos (varios segundos), significa que la instancia está sobrecargada, lo que provoca que las lecturas o escrituras se agoten y fallen.

Una de las causas de la alta latencia es que la tarea de Dataflow se ejecuta con demasiados trabajadores, lo que supone una carga excesiva para la instancia de Spanner.

Para especificar un límite en el número de trabajadores de Dataflow, sigue estos pasos:

Consola

Si usas la consola de Dataflow, el parámetro Máximo de trabajadores se encuentra en la sección Parámetros opcionales de la página Crear trabajo a partir de plantilla.

Ir a Dataflow

gcloud

Ejecuta el comando gcloud dataflow jobs run y especifica el argumento max-workers. Por ejemplo:

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Text_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Solucionar un error de red

Puede que se produzca el siguiente error al exportar tus bases de datos de Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Este error se produce porque Spanner da por hecho que quieres usar una red VPC de modo automático llamada default en el mismo proyecto que el trabajo de Dataflow. Si no tienes una red de VPC predeterminada en el proyecto o si tu red de VPC está en una red de VPC de modo personalizado, debes crear un trabajo de Dataflow y especificar una red o subred alternativa.

Optimizar tareas de importación o exportación lentas

Si has seguido las sugerencias de la sección Configuración inicial, no deberías tener que hacer ningún otro ajuste. Si tu trabajo se ejecuta lentamente, puedes probar otras optimizaciones:

  • Optimizar la ubicación de la tarea y de los datos: ejecuta la tarea de Dataflow en la misma región en la que se encuentran tu instancia de Spanner y tu segmento de Cloud Storage.

  • Asegúrate de que haya suficientes recursos de Dataflow: si las cuotas de Compute Engine pertinentes limitan los recursos de tu tarea de Dataflow, en la página de Dataflow de la Google Cloud consola se mostrará un icono de advertencia Icono de advertencia y mensajes de registro:

    Captura de pantalla de la advertencia sobre el límite de cuota

    En esta situación, aumentar las cuotas de CPUs, direcciones IP en uso y discos persistentes estándar podría acortar el tiempo de ejecución del trabajo, pero es posible que incurras en más cargos de Compute Engine.

  • Comprueba la utilización de la CPU de Spanner: si ves que la utilización de la CPU de la instancia supera el 65%, puedes aumentar la capacidad de computación de esa instancia. La capacidad añade más recursos de Spanner y el trabajo debería acelerarse, pero incurrirás en más cargos de Spanner.

Factores que afectan al rendimiento de las tareas de importación o exportación

Hay varios factores que influyen en el tiempo que se tarda en completar una tarea de importación o exportación.

  • Tamaño de la base de datos de Spanner: procesar más datos requiere más tiempo y recursos.

  • Esquema de la base de datos de Spanner, que incluye lo siguiente:

    • El número de tablas
    • El tamaño de las filas
    • Número de índices secundarios
    • Número de claves externas
    • El número de flujos de cambios

  • Ubicación de los datos: los datos se transfieren entre Spanner y Cloud Storage mediante Dataflow. Lo ideal es que los tres componentes estén en la misma región. Si los componentes no están en la misma región, mover los datos entre regiones ralentiza el trabajo.

  • Número de trabajadores de Dataflow: se necesitan trabajadores de Dataflow óptimos para conseguir un buen rendimiento. Con el autoescalado, Dataflow elige el número de trabajadores de la tarea en función de la cantidad de trabajo que se debe realizar. Sin embargo, el número de trabajadores estará limitado por las cuotas de CPUs, direcciones IP en uso y discos persistentes estándar. La interfaz de usuario de Dataflow muestra un icono de advertencia si se encuentra con límites de cuota. En esta situación, el progreso es más lento, pero el trabajo debería completarse igualmente. El autoescalado puede sobrecargar Spanner, lo que provoca errores cuando hay una gran cantidad de datos que importar.

  • Carga existente en Spanner: una tarea de importación añade una carga de CPU significativa a una instancia de Spanner. Una tarea de exportación suele añadir una carga ligera a una instancia de Spanner. Si la instancia ya tiene una carga considerable, la tarea se ejecutará más lentamente.

  • Cantidad de capacidad de computación de Spanner: si la utilización de la CPU de la instancia supera el 65%, el trabajo se ejecuta más lentamente.

Ajustar los workers para que el rendimiento de la importación sea bueno

Al iniciar una tarea de importación de Spanner, los trabajadores de Dataflow deben tener un valor óptimo para que el rendimiento sea bueno. Si hay demasiados trabajadores, se sobrecarga Spanner, y si hay muy pocos, el rendimiento de la importación es mediocre.

El número máximo de trabajadores depende en gran medida del tamaño de los datos, pero, idealmente, el uso total de la CPU de Spanner debería estar entre el 70% y el 90%. De esta forma, se consigue un buen equilibrio entre la eficiencia de Spanner y la finalización de los trabajos sin errores.

Para alcanzar ese objetivo de utilización en la mayoría de los esquemas y las situaciones, recomendamos que el número máximo de vCPUs de trabajador sea entre 4 y 6 veces el número de nodos de Spanner.

Por ejemplo, en una instancia de Spanner de 10 nodos, si usas trabajadores n1-standard-2, deberías definir el número máximo de trabajadores en 25, lo que te daría 50 vCPUs.