Importa y exporta datos en formato CSV

En esta página, se describe cómo exportar datos de Spanner a archivos CSV o cómo importar datos de archivos CSV a una base de datos de Spanner.

Para el proceso, se usa Dataflow. Puedes exportar datos de Spanner a un bucket de Cloud Storage o importar datos a Spanner desde un bucket de Cloud Storage que contiene un archivo de manifiesto JSON y un conjunto de archivos CSV.

Antes de comenzar

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

Enable the APIs

También necesitas una cuota suficiente y los permisos necesarios de IAM.

Requisitos de cuota

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

  • Spanner: Debes tener capacidad de procesamiento suficiente para admitir la cantidad de datos que deseas importar. No se requiere capacidad de procesamiento adicional para importar o exportar una base de datos, aunque es posible que debas agregar más capacidad de procesamiento a fin de que el trabajo se complete en un tiempo razonable. Consulta la sección Optimiza los trabajos para obtener más detalles.
  • Cloud Storage: Para importar, debes tener un depósito que contenga los archivos exportados con anterioridad. Si deseas exportar, debes crear un bucket para los archivos exportados si aún no tienes uno. Puedes hacerlo en la consola de Google Cloud , a través de la página de Cloud Storage o mientras creas la exportación a través de la página de Spanner. No es necesario que establezcas un tamaño para tu bucket.
  • Dataflow: Los trabajos de importación o exportación están sujetos a las mismas cuotas de Compute Engine de direcciones IP, uso del disco y CPU que otros trabajos de Dataflow.

  • Compute Engine: Antes de ejecutar el trabajo de importación o exportación, debes establecer las cuotas iniciales para Compute Engine, que Dataflow usa. Estas cuotas representan la cantidad máxima de recursos que permites que Dataflow use para tu trabajo. Los valores iniciales recomendados son los siguientes:

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

    Por lo general, no es necesario hacer ningún otro ajuste. Dataflow proporciona ajuste de escala automático para que solo pagues por los recursos reales que se usaron durante la importación o exportación. Si tu trabajo puede usar más recursos, la IU de Dataflow muestra un ícono de advertencia. El trabajo debería completarse incluso si hay un ícono de advertencia.

Roles obligatorios

Para obtener los permisos que necesitas para exportar una base de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM en la cuenta de servicio del trabajador de Dataflow:

Exporta datos de Spanner a archivos CSV

Si deseas exportar datos de Spanner a archivos CSV en Cloud Storage, sigue las instrucciones para usar Google Cloud CLI y ejecutar un trabajo con la plantilla de texto de Spanner a Cloud Storage.

También puedes consultar la información de este documento sobre cómo ver o solucionar problemas de trabajos, cómo optimizar trabajos lentos y factores que afectan el rendimiento del trabajo.

Importa 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 almacena esos archivos en Cloud Storage. No incluyas una línea de encabezado.
  2. Crea un archivo de manifiesto JSON y almacénalo junto con tus 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 para las columnas en tus archivos CSV coincidan con las columnas correspondientes en tus tablas existentes.
  4. Ejecuta tu trabajo de importación.

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

El proceso de importación incluye datos de archivos CSV ubicados en un bucket de Cloud Storage. Puedes exportar datos en formato CSV desde cualquier fuente.

Cuando exportes tus datos, ten en cuenta lo siguiente:

  • Los archivos de texto que se importarán 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 es necesario que incluyas ni generes metadatos cuando exportes los archivos CSV.

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

Si no exportas tus archivos directamente a Cloud Storage, debes subir los archivos CSV a un bucket 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 deseas importar y colocarlo en el mismo bucket de Cloud Storage en el que almacenaste tus archivos CSV. Este archivo de manifiesto contiene un array tables que muestra el nombre y las ubicaciones de los archivos de datos para cada tabla. El archivo también especifica el dialecto de la base de datos receptora. Si se omite el dialecto, se establece de forma predeterminada en GoogleSQL.

El formato del archivo de manifiesto corresponde al siguiente tipo de mensaje, que se muestra 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 denominadas Albums y Singers a una base de datos de dialecto de GoogleSQL. La tabla Albums usa el esquema de columna que el trabajo recupera 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 para tu base de datos de Spanner

Antes de ejecutar la importación, debes crear las tablas de destino en tu 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 en el esquema de la tabla de destino.

Te recomendamos que crees índices secundarios, claves foráneas y flujos de cambios después de importar tus datos a Spanner, no cuando crees la tabla al principio. Si tu tabla ya contiene estas estructuras, te recomendamos que las descartes y que las vuelvas a crear después de importar tus datos.

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

Si deseas iniciar el trabajo de importación, sigue las instrucciones para usar Google Cloud CLI a fin de ejecutar un trabajo con la plantilla de texto de Cloud Storage a Spanner.

Después de iniciar un trabajo de importación, puedes ver los detalles del trabajo en la consola de Google Cloud .

Cuando finalice el trabajo de importación, agrega los índices secundarios, las claves externas y los flujos de cambios necesarios.

Elige una región para tu trabajo de importación

Se recomienda elegir una región diferente en función de la ubicación de tu bucket de Cloud Storage. Para evitar los cargos de transferencia de datos salientes, elige una región que coincida con la ubicación de tu bucket de Cloud Storage.

  • Si la ubicación de tu bucket de Cloud Storage es una región, puedes aprovechar el uso gratuito de la red si eliges la misma región para tu trabajo de importación, siempre que esa región esté disponible.

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

  • Si no hay una región con la misma ubicación para tu trabajo de importación o si la ubicación de tu bucket de Cloud Storage es multirregional, se aplicarán cargos de transferencia de datos salientes. Consulta los precios de transferencia de datos de Cloud Storage para elegir una región que tenga los cargos de transferencia de datos más bajos.

Visualiza o soluciona problemas de trabajos en la IU de Dataflow

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

Cómo ver los detalles del trabajo de Dataflow

Para ver los detalles de cualquier trabajo de importación o exportación que ejecutes durante la última semana, incluidos los trabajos que se estén ejecutando:

  1. Navega hasta la página Descripción general de la base de datos de la base de datos.
  2. Haz clic en el elemento de menú del panel izquierdo Importar/Exportar. En la página Importar/Exportar de la base de datos, se muestra una lista de trabajos recientes.

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

    Mensaje de estado del trabajo en curso

    En la consola de Google Cloud , se muestran 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 Trabajos de Dataflow en la consola de Google Cloud .

    Ir a Trabajos

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

    En la consola de Google Cloud , se muestran los detalles del trabajo de Dataflow.

Visualiza los registros de Dataflow de tu trabajo

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

Si un trabajo falla, busca errores en los registros. Si hay errores, el recuento de errores se muestra junto a Registros (Logs):

Ejemplo de recuento de errores junto al botón Registros (Logs)

Para ver los errores del trabajo, sigue estos pasos:

  1. Haz clic en el recuento de errores junto a Registros (Logs).

    La consola de Google Cloud muestra los registros del trabajo. Es posible que debas desplazarte para ver los errores.

  2. Identifica las entradas con el ícono de error Ícono de error.

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

Para obtener más información sobre cómo solucionar problemas de trabajos de Dataflow, consulta Solución de problemas y depuración.

Soluciona problemas de trabajos de importación o exportación con errores

Si ves los siguientes errores en tus registros de trabajos, haz lo siguiente:

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

--or--

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

Verifica la latencia de lectura o escritura del 99% en la pestaña Supervisión de tu base de datos de Spanner en la consola deGoogle Cloud . Si se muestran valores altos (de varios segundos), eso indica que la instancia está sobrecargada, lo que hace que las lecturas o escrituras agoten el tiempo de espera y fallen.

Una de las causas de la latencia alta es que el trabajo de Dataflow se ejecuta con demasiados trabajadores, lo que pone demasiada carga en la instancia de Spanner.

Para especificar un límite en la cantidad de trabajadores de Dataflow, haz lo siguiente:

Console

Si usas la consola de Dataflow, el parámetro Cantidad máxima de trabajadores se encuentra en la sección Parámetros opcionales de la página Crear trabajo desde 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

Cómo solucionar problemas de red

El siguiente error puede ocurrir cuando exportas 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 ocurre porque Spanner supone que quieres usar una red de 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 esta es de modo personalizado, debes crear un trabajo de Dataflow y especificar una red o subred alternativa.

Optimiza trabajos de importación o exportación que se ejecutan con lentitud

Si seguiste las sugerencias de la configuración inicial, por general, no se debe realizar ningún otro ajuste. Si tu trabajo se ejecuta a poca velocidad, existen otras optimizaciones que puedes probar:

  • Optimiza el trabajo y la ubicación de los datos: Ejecuta tu trabajo de Dataflow en la misma región donde se encuentran tu instancia de Spanner y el bucket de Cloud Storage.

  • Garantiza recursos suficientes de Dataflow: Si las cuotas relevantes de Compute Engine limitan los recursos de tu trabajo de Dataflow, la página de Dataflow del trabajo en la consola de Google Cloud muestra un ícono de advertencia Ícono de advertencia y mensajes de registro:

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

    En esta situación, aumentar las cuotas para CPU, direcciones IP en uso y el disco persistente estándar podría acortar el tiempo de ejecución del trabajo, pero se podrían generar más cargos de Compute Engine.

  • Comprueba el uso de CPU de Spanner: Si ves que el uso de CPU de la instancia supera el 65%, puedes aumentar la capacidad de procesamiento en esa instancia. La capacidad agrega más recursos de Spanner y el trabajo debería acelerarse, pero se te cobrarán más cargos de Spanner.

Factores que afectan el rendimiento del trabajo de importación o exportación

Varios factores influyen en el tiempo que lleva completar un trabajo 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:

    • La cantidad de tablas
    • El tamaño de las filas
    • La cantidad de índices secundarios
    • La cantidad de claves externas
    • La cantidad 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 se ubiquen en la misma región. Si los componentes no están en la misma región, mover los datos entre las regiones hace que la ejecución del trabajo sea más lenta.

  • Cantidad de trabajadores de Dataflow: Los trabajadores óptimos de Dataflow son necesarios para un buen rendimiento. Mediante el ajuste de escala automático, Dataflow elige la cantidad de trabajadores en función de la cantidad de trabajo que se debe realizar. Sin embargo, la cantidad de trabajadores estará limitada por las cuotas de las CPU, las direcciones IP en uso y el disco persistente estándar. La IU de Dataflow muestra un ícono de advertencia si se alcanzan los límites de cuota. En esta situación, el progreso es más lento, pero el trabajo se completará de todos modos. El ajuste de escala automático puede sobrecargar Spanner y generar errores cuando hay una gran cantidad de datos que se pueden importar.

  • Carga existente en Spanner: Un trabajo de importación agrega una carga de CPU significativa en una instancia de Spanner. Por lo general, un trabajo de exportación agrega una carga ligera en una instancia de Spanner. Si la instancia ya tiene una carga sustancial existente, el trabajo se ejecutará más lento.

  • Cantidad de capacidad de procesamiento de Spanner: Si el uso de CPU de la instancia supera el 65%, el trabajo se ejecutará más lento.

Ajusta los trabajadores para obtener un buen rendimiento de importación

Cuando se inicia un trabajo de importación de Spanner, los trabajadores de Dataflow deben configurarse en un valor óptimo para un buen rendimiento. Hay demasiados trabajadores que sobrecargan Spanner y muy pocos causan un rendimiento de importación insuficiente.

La cantidad máxima de trabajadores depende en gran medida del tamaño de los datos, pero lo ideal es que el uso total de CPU de Spanner esté entre el 70% y el 90%. Esto proporciona un buen balance entre la eficiencia de Spanner y la finalización de trabajos sin errores.

Para lograr ese objetivo de uso en la mayoría de los esquemas y situaciones, recomendamos una cantidad máxima de CPU virtuales de trabajador de entre 4 y 6 veces la cantidad de nodos de Spanner.

Por ejemplo, para una instancia de Spanner de 10 nodos, con trabajadores n1-standard-2, deberías establecer el máximo de trabajadores en 25, lo que daría 50 CPU virtuales.