Carga archivos CSV desde Cloud Storage
Cuando cargas datos de CSV desde Cloud Storage, puedes cargarlos en una tabla o partición nuevas. También puedes adjuntarlos a una tabla o partición existentes o reemplazar los datos de ellas. Cuando tus datos se cargan en BigQuery, se convierten en formato de columnas para Capacitor (formato de almacenamiento de BigQuery).
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 bucket de Cloud Storage.
Para obtener información sobre la carga de datos de CSV desde un archivo local, consulta la sección sobre Cómo cargar datos en BigQuery desde una fuente de datos local.
Limitaciones
Cuando cargues datos de CSV de Cloud Storage en BigQuery, ten en cuenta lo siguiente:
- Los archivos CSV no admiten datos anidados o repetidos.
- Si usas la compresión gzip, BigQuery no puede leer los datos en paralelo. Cargar datos de CSV comprimidos en BigQuery es más lento que subir datos sin comprimir. Consulta Cómo cargar datos comprimidos y sin comprimir.
- No puedes incluir archivos comprimidos y descomprimidos en el mismo trabajo de carga.
- El tamaño máximo de un archivo gzip es de 4 GB.
- Cuando cargues datos CSV o JSON, en los valores de las columnas
DATE
, se debe usar el separador de guion (-
), y la fecha debe estar en el siguiente formato:YYYY-MM-DD
(año-mes-día). - Cuando cargues datos JSON o CSV, en los valores de las columnas
TIMESTAMP
, se debe usar un separador de guion (-
) para la parte de fecha de la marca de tiempo, y la fecha debe tener el siguiente formato:YYYY-MM-DD
(año-mes-día). En la parte dehh:mm:ss
(horas-minutos-segundos) de la marca de tiempo, se debe usar un separador de dos puntos (:
).
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 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 CSV en una tabla
Puedes cargar datos de CSV de Cloud Storage en una tabla de BigQuery nueva de las siguientes maneras:
- Mediante Cloud Console
- Mediante el comando
bq load
de la herramienta de línea de comandos debq
- Con una llamada al método
jobs.insert
de la API y la configuración de un trabajoload
- Con las bibliotecas cliente
Para cargar datos de CSV de Cloud Storage en una tabla nueva de BigQuery, sigue estos pasos:
Console
Abre la página de BigQuery en Cloud Console.
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
En el panel de detalles, haz clic en Crear tabla (Create table).
En la página Crear tabla, en la sección Fuente haz lo siguiente:
En Create table from (Crear tabla desde), selecciona Cloud Storage.
En el campo de fuente, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en Cloud Console, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
Para Formato de archivo (File format), selecciona CSV.
En la página Crear tabla, en la sección Destino (Destination), realiza lo siguiente:
En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
En la sección Esquema, en Detección automática, marca la opción Esquema y parámetros de entrada para habilitar la detección automática de esquemas. También puedes ingresar de forma manual la definición de esquema, como se indica a continuación:
Habilita Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo JSON.
Usa Agregar campo (Add field) para ingresar el esquema de forma manual.
Para particionar la tabla, elige las opciones en la Configuración de partición y agrupamiento en clústeres (opcional):
- Para crear una tabla particionada, haz clic en Sin particionar (No partitioning), selecciona Particionar por campo (Partition by field) y elige una columna
DATE
oTIMESTAMP
. Esta opción no estará disponible si el esquema no incluye una columnaDATE
oTIMESTAMP
. - Para crear una tabla particionada por tiempo de transferencia, haz clic en Sin particionar y selecciona Particionar por tiempo de transferencia.
- Para crear una tabla particionada, haz clic en Sin particionar (No partitioning), selecciona Particionar por campo (Partition by field) y elige una columna
Para el Filtro de partición, haz clic en la casilla Exigir filtro de partición a fin de solicitar a los usuarios que incluyan una cláusula
WHERE
que especifique las particiones que deben consultarse (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas. Esta opción no está disponible si se selecciona Sin particionar (No partitioning).Para agrupar en clústeres la tabla, en la casilla Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de campo (opcional).
Haz clic en Opciones avanzadas (opcional).
- En Preferencia de escritura (Write preference), deja seleccionado Escribir si está vacía (Write if empty). Esta opción crea una tabla nueva y carga los datos en ella.
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de
0
o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensajeinvalid
y fallará. - En Valores desconocidos, marca Ignorar valores desconocidos para ignorar cualquier valor en una fila que no esté presente en el esquema de la tabla.
- En Delimitador de campos, elige el carácter que separa las celdas en tu archivo CSV: Coma, Tabulación, Barra vertical o Personalizado. Si eliges Personalizado, debes ingresar el delimitador en la casilla Delimitador de campos personalizado. El valor predeterminado es Coma.
- En Filas de encabezado que se omitirán, ingresa la cantidad de filas de encabezado que se omitirán en la parte superior del archivo CSV. El valor predeterminado es
0
. - En Saltos de línea entrecomillados, marca Permitir saltos de línea entrecomillados para permitir secciones de datos entrecomillados que contengan caracteres de salto de línea en un archivo CSV. El valor predeterminado es
false
. - En Filas irregulares, marca Permitir filas irregulares para aceptar filas en archivos de CSV a las que les falten columnas opcionales finales. Los valores faltantes se consideran nulos. Si no se marca esta opción, los registros en los que faltan columnas finales se tratan como registros incorrectos y, si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es
false
- En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.
bq
Usa el comando bq load
, especifica CSV
con la marca --source_format
e incluye un URI de Cloud Storage.
Puedes incluir un único URI, una lista de URI separados por comas o un URI que contenga un comodín.
Proporciona el esquema intercalado con un archivo de definición de esquema o usa la detección automática de esquemas.
Opcional: Proporciona la marca --location
y configura el valor en tu ubicación.
Las siguientes son otras marcas opcionales:
--allow_jagged_rows
: Cuando se especifica, se aceptan filas de archivos CSV a las que les faltan columnas opcionales finales. Los valores faltantes se consideran nulos. Si no se marca esta opción, los registros en los que faltan columnas finales se tratan como registros incorrectos y, si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado esfalse
.--allow_quoted_newlines
: cuando se especifica, permite secciones de datos entrecomillados que contienen caracteres de salto de línea en un archivo CSV. El valor predeterminado esfalse
.--field_delimiter
: el carácter que indica el límite entre las columnas en los datos.\t
ytab
pueden ser delimitadores de tabulación. El valor predeterminado es,
.--null_marker
: una string personalizada opcional que representa un valor NULL en los datos de CSV.--skip_leading_rows
: especifica la cantidad de filas de encabezado que se omiten en la parte superior del archivo CSV. El valor predeterminado es0
.--quote
: el carácter de comillas que se usará para encerrar registros. El valor predeterminado es"
. Para indicar que no hay ningún carácter de comilla, usa una string vacía.--max_bad_records
: un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es0
. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor--max_bad_records
.--ignore_unknown_values
: Cuando se especifica, permite y también ignora valores extras no reconocidos en datos CSV o JSON.--autodetect
: Cuando se especifica, se habilita la detección automática de esquemas para los datos de formato CSV y JSON.--time_partitioning_type
: habilita las particiones basadas en el tiempo en una tabla y establece el tipo de partición. Los valores posibles sonHOUR
,DAY
,MONTH
yYEAR
. Esta marca es opcional cuando se crea una tabla particionada en una columnaDATE
,DATETIME
oTIMESTAMP
. El tipo de partición predeterminado para la partición basada en el tiempo esDAY
.--time_partitioning_expiration
: Un número entero que especifica (en segundos) cuándo se debe borrar una partición basada en el tiempo. La hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero.--time_partitioning_field
: La columnaDATE
oTIMESTAMP
que se usa para crear una tabla particionada. Si la partición basada en el tiempo se habilita sin este valor, se creará una tabla particionada por tiempo de transferencia.--require_partition_filter
: Cuando se habilita esta opción, se solicita a los usuarios que incluyan una cláusulaWHERE
que especifique las particiones que se desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Consulta tablas particionadas.--clustering_fields
: Una lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres.--destination_kms_key
: Es la clave de Cloud KMS para la encriptación de los datos de la tabla.Para obtener más información sobre el comando
bq load
, consulta:Para obtener más información sobre tablas particionadas, consulta los siguientes artículos:
Para obtener más información sobre tablas agrupadas, consulta el siguiente artículo:
Para obtener más información sobre la encriptación de tablas, consulta el siguiente artículo:
Para cargar datos de CSV en BigQuery, ingresa el siguiente comando:
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source \ schema
Aquí:
- location es tu ubicación. La marca
--location
es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca comoasia-northeast1
. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc. - format es
CSV
. - dataset es un conjunto de datos existente.
- table es el nombre de la tabla en la que cargas datos.
- path_to_source es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.
- schema es un esquema válido. El esquema puede ser un archivo JSON local o se puede escribir intercalado como parte del comando. También puedes usar la marca
--autodetect
en lugar de proporcionar una definición de esquema.
Ejemplos:
El siguiente comando carga datos de gs://mybucket/mydata.csv
a una tabla llamada mytable
en mydataset
. El esquema se define en un archivo de esquema local llamado myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
El siguiente comando carga datos de gs://mybucket/mydata.csv
en una tabla llamada mytable
en mydataset
. El esquema se define en un archivo de esquema local llamado myschema.json
. El archivo CSV incluye dos filas de encabezado.
Si no se especifica --skip_leading_rows
, el comportamiento predeterminado es suponer que el archivo no contiene encabezados.
bq load \
--source_format=CSV \
--skip_leading_rows=2
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
El siguiente comando carga datos de gs://mybucket/mydata.csv
a una tabla particionada por tiempo de transferencia llamada mytable
en mydataset
. El esquema se define en un archivo de esquema local llamado myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
El siguiente comando carga datos de gs://mybucket/mydata.csv
a una tabla particionada llamada mytable
en mydataset
. La tabla está particionada en la columna mytimestamp
. El esquema se define en un archivo de esquema local llamado myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
El siguiente comando carga datos de gs://mybucket/mydata.csv
a una tabla llamada mytable
en mydataset
. El esquema se detecta de forma automática.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
El siguiente comando carga datos de gs://mybucket/mydata.csv
a una tabla llamada mytable
en mydataset
. El esquema se define intercalado en el formato field:data_type,field:data_type
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
El siguiente comando carga datos de varios archivos en gs://mybucket/
en una tabla llamada mytable
en mydataset
. El URI de Cloud Storage usa un comodín. El esquema se detecta de forma automática.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata*.csv
El siguiente comando carga datos de varios archivos en gs://mybucket/
en una tabla llamada mytable
en mydataset
. El comando incluye una lista separada por comas de URI de Cloud Storage con comodines. El esquema se define en un archivo de esquema local llamado myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
"gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
./myschema.json
API
Crea un trabajo
load
que apunte a los datos de origen en Cloud Storage.Especifica tu ubicación en la propiedad
location
de la secciónjobReference
del recurso de trabajo (opcional).La propiedad
source URIs
debe estar completamente calificada en el formatogs://bucket/object
. Cada URI puede contener un carácter comodín “*”.Configura la propiedad
sourceFormat
comoCSV
para especificar el formato de datos de CSV.Para verificar el estado del trabajo, llama a
jobs.get(job_id*)
. job_id es el ID del trabajo que muestra la solicitud inicial.- Si se muestra
status.state = DONE
, el trabajo se completó de forma correcta. - Si la propiedad
status.errorResult
está presente, la solicitud falló, y ese objeto incluirá información que describirá qué salió mal. Cuando una solicitud falla, no se crea ninguna tabla ni se cargan datos. - Si
status.errorResult
está ausente, el trabajo se completó con éxito, aunque puede haber algunos errores recuperables, como problemas cuando se importan algunas filas. Se enumeran los errores recuperables en la propiedadstatus.errors
del objeto de trabajo que se muestra.
- Si se muestra
Notas sobre la API:
Los trabajos de carga son atómicos y coherentes. Es decir, si falla uno, ninguno de los datos estará disponible, y, si uno se realiza con éxito, todos los datos estarán disponibles.
Como práctica recomendada, genera un ID único y pásalo como
jobReference.jobId
cuando llames ajobs.insert
para crear un trabajo de carga. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.Llamar a
jobs.insert
en un ID de trabajo determinado es idempotente. Puedes intentar tantas veces como desees en el mismo ID de trabajo y, como máximo, una de esas operaciones tendrá éxito.
C#
Antes de probar este ejemplo, sigue las instrucciones de configuración para C# incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de C# de BigQuery.
Comienza a usarlo
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Node.js de BigQuery.
PHP
Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de PHP de BigQuery.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración para Python incluidas en la Guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.
Usa el método Client.load_table_from_uri() para cargar datos desde un archivo de CSV a Cloud Storage. Proporciona una definición de esquema explícita. Para ello, define la propiedad LoadJobConfig.schema en una lista de objetos SchemaField.
Ruby
Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.
Carga datos CSV en una tabla que usa partición de tiempo basada en columnas
Para cargar datos CSV de Cloud Storage en una tabla de BigQuery que usa partición de tiempo basada en columnas, haz lo siguiente:
Comienza a usarlo
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Node.js de BigQuery.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración para Python incluidas en la Guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.
Anexa o reemplaza una tabla con datos CSV
Puedes cargar datos adicionales a una tabla desde los archivos de origen o mediante la incorporación de resultados de consultas.
En Cloud Console, usa la opción de Preferencia de escritura para especificar qué acción se debe tomar cuando cargues datos desde un archivo de origen o desde un resultado de consulta.
Cuando cargas datos adicionales en una tabla, tienes las siguientes opciones:
Opción de Console | Marca de la herramienta de bq |
Propiedad de la API de BigQuery | Descripción |
---|---|---|---|
Escribir si está vacía | Ninguna | WRITE_EMPTY |
Solo escribe los datos si la tabla está vacía. |
Agregar a la tabla | --noreplace o --replace=false ; si no se especifica --[no]replace , la opción predeterminada es agregar |
WRITE_APPEND |
Agrega los datos al final de la tabla (predeterminado). |
Reemplazar tabla | --replace o --replace=true |
WRITE_TRUNCATE |
Borra todos los datos existentes de una tabla antes de escribir los datos nuevos. Esta acción también borra el esquema de la tabla y quita cualquier clave de Cloud KMS. |
Si cargas datos en una tabla existente, el trabajo de carga puede agregar datos a la tabla o reemplazarlos.
Puedes agregar datos a una tabla o reemplazarlos de la siguiente manera:
- Mediante Cloud Console
- Mediante el comando
bq load
de la herramienta de línea de comandos debq
- Con una llamada al método
jobs.insert
de la API y la configuración de un trabajoload
- Usa bibliotecas cliente.
Console
Abre la página de BigQuery en Cloud Console.
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
En el panel de detalles, haz clic en Crear tabla (Create table).
En la página Crear tabla, en la sección Fuente haz lo siguiente:
En Create table from (Crear tabla desde), selecciona Cloud Storage.
En el campo de fuente, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en Cloud Console, pero se admiten comodines. El bucket de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla en la que agregas datos o los reemplazas.
Para Formato de archivo (File format), selecciona CSV.
En la página Crear tabla, en la sección Destino (Destination), realiza lo siguiente:
En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
En el campo Nombre de la tabla (Table name), ingresa el nombre de la tabla a la que quieres agregar datos o que quieres reemplazar en BigQuery.
Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
En la sección Esquema, en Detección automática, marca la opción Esquema y parámetros de entrada para habilitar la detección automática de esquemas. También puedes ingresar de forma manual la definición de esquema, como se indica a continuación:
Habilita Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo JSON.
Usa Agregar campo para ingresar el esquema de forma manual.
En Configuración de partición y agrupamiento en clústeres (Partition and cluster settings), deja los valores predeterminados. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres; Cloud Console no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
Haz clic en Opciones avanzadas (Advanced options).
- En Preferencia de escritura (Write preference), elige Agregar a la tabla (Append to table) o Reemplazar tabla (Overwrite table).
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de
0
o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensajeinvalid
y fallará. - En Valores desconocidos, marca Ignorar valores desconocidos para ignorar cualquier valor en una fila que no esté presente en el esquema de la tabla.
- En Delimitador de campos, elige el carácter que separa las celdas en tu archivo CSV: Coma, Tabulación, Barra vertical o Personalizado. Si eliges Personalizado, debes ingresar el delimitador en la casilla Delimitador de campos personalizado. El valor predeterminado es Coma.
- En Filas de encabezado que se omitirán, ingresa la cantidad de filas de encabezado que se omitirán en la parte superior del archivo CSV. El valor predeterminado es
0
. - En Saltos de línea entrecomillados, marca Permitir saltos de línea entrecomillados para permitir secciones de datos entrecomillados que contengan caracteres de salto de línea en un archivo CSV. El valor predeterminado es
false
. - En Filas irregulares, marca Permitir filas irregulares para aceptar filas en archivos de CSV a las que les falten columnas opcionales finales. Los valores faltantes se consideran nulos. Si no se marca esta opción, los registros en los que faltan columnas finales se tratan como registros incorrectos y, si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es
false
En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.
bq
Usa el comando bq load
, especifica CSV
con la marca --source_format
e incluye un URI de Cloud Storage.
Puedes incluir un único URI, una lista de URI separados por comas o un URI que contenga un comodín.
Proporciona el esquema intercalado con un archivo de definición de esquema o usa la detección automática de esquemas.
Especifica la marca --replace
para reemplazar la tabla. Usa la marca --noreplace
para adjuntar datos a la tabla. Si no se especifica ninguna marca, se agregan datos de manera predeterminada.
Es posible modificar el esquema de la tabla cuando adjuntas datos a ella o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
Opcional: Proporciona la marca --location
y configura el valor en tu ubicación.
Las siguientes son otras marcas opcionales:
--allow_jagged_rows
: Cuando se especifica, se aceptan filas de archivos CSV a las que les faltan columnas opcionales finales. Los valores faltantes se consideran nulos. Si no se marca esta opción, los registros en los que faltan columnas finales se tratan como registros incorrectos y, si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado esfalse
.--allow_quoted_newlines
: cuando se especifica, permite secciones de datos entrecomillados que contienen caracteres de salto de línea en un archivo CSV. El valor predeterminado esfalse
.--field_delimiter
: el carácter que indica el límite entre las columnas en los datos.\t
ytab
pueden ser delimitadores de tabulación. El valor predeterminado es,
.--null_marker
: una string personalizada opcional que representa un valor NULL en los datos de CSV.--skip_leading_rows
: especifica la cantidad de filas de encabezado que se omiten en la parte superior del archivo CSV. El valor predeterminado es0
.--quote
: el carácter de comillas que se usará para encerrar registros. El valor predeterminado es"
. Para indicar que no hay ningún carácter de comilla, usa una string vacía.--max_bad_records
: un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es0
. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor--max_bad_records
.--ignore_unknown_values
: Cuando se especifica, permite y también ignora valores extras no reconocidos en datos CSV o JSON.--autodetect
: Cuando se especifica, se habilita la detección automática de esquemas para los datos de formato CSV y JSON.--destination_kms_key
: Es la clave de Cloud KMS para la encriptación de los datos de la tabla.
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source \ schema
Donde:
- location es tu ubicación.
La marca
--location
es opcional. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc. - format es
CSV
. - dataset es un conjunto de datos existente.
- table es el nombre de la tabla en la que cargas datos.
- path_to_source es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.
- schema es un esquema válido. El esquema puede ser un archivo JSON local o se puede escribir intercalado como parte del comando. También puedes usar la marca
--autodetect
en lugar de proporcionar una definición de esquema.
Ejemplos:
Con el siguiente comando, se cargan datos de gs://mybucket/mydata.csv
y se reemplazan los datos de una tabla llamada mytable
en mydataset
. El esquema se define mediante la detección automática de esquemas.
bq load \
--autodetect \
--replace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
Con el siguiente comando, se cargan datos de gs://mybucket/mydata.csv
y se adjuntan datos a una tabla llamada mytable
en mydataset
. El esquema se define mediante un archivo de esquema JSON: myschema.json
.
bq load \
--noreplace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
API
Crea un trabajo
load
que apunte a los datos de origen en Cloud Storage.Especifica tu ubicación en la propiedad
location
de la secciónjobReference
del recurso de trabajo (opcional).La propiedad
source URIs
debe estar completamente calificada en el formatogs://bucket/object
. Puedes incluir varios URI en una lista separada por comas. Ten en cuenta que también se admiten comodines.Para especificar el formato de los datos, establece la propiedad
configuration.load.sourceFormat
enCSV
.Para especificar la preferencia de escritura, establece la propiedad
configuration.load.writeDisposition
enWRITE_TRUNCATE
oWRITE_APPEND
.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Para reemplazar las filas en una tabla existente, establece el valor writeDisposition
en el parámetro metadata
en 'WRITE_TRUNCATE'
.
Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de PHP de BigQuery.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración para Python incluidas en la Guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.
Para reemplazar las filas de una tabla existente, configura la propiedad LoadJobConfig.write_disposition como la constante WRITE_TRUNCATE
de SourceFormat.
Carga datos CSV con particiones de subárbol
BigQuery admite la carga de datos de CSV con particiones de subárbol almacenados en Cloud Storage y propagará las columnas de partición de subárbol como columnas en la tabla administrada de BigQuery de destino. Para obtener más información, consulta Carga datos particionados de forma externa de Cloud Storage.
Detalles de la carga de datos de CSV
En esta sección, se describe cómo BigQuery maneja varias opciones de formato CSV.
Codificación
BigQuery espera que los datos CSV estén codificados en UTF-8. Si tienes archivos CSV con datos codificados en formato ISO-8859-1 (también conocido como Latin-1), debes especificar la codificación de forma explícita para que BigQuery pueda convertir los datos en UTF-8 de manera correcta.
Si no especificas una codificación o si especificas la codificación UTF-8 cuando el archivo CSV no está codificado en UTF-8, BigQuery intentará convertir los datos en UTF-8. Por lo general, los datos se cargarán con éxito, pero es posible que no coincidan en cada byte con el resultado esperado. Para evitar esto, especifica la codificación correcta con la marca --encoding
.
Si BigQuery no puede convertir un carácter que no sea el carácter ASCII 0
, BigQuery convierte el carácter en el carácter de reemplazo estándar de Unicode: �.
Delimitadores de campo
Los delimitadores en archivos CSV pueden ser cualquier carácter de un solo byte. Si el archivo de origen usa la codificación ISO-8859-1, cualquier carácter puede ser un delimitador. Si el archivo de origen usa la codificación UTF-8, se puede usar cualquier carácter en el rango decimal 1-127 (U+0001-U+007F) sin modificaciones. Puedes insertar un carácter ISO-8859-1 fuera de este rango como delimitador y BigQuery lo interpretará de forma correcta. Sin embargo, si usas un carácter de varios bytes como delimitador, algunos de los bytes se interpretarán de manera incorrecta como parte del valor del campo.
Por lo general, se recomienda usar un delimitador estándar, como una tabulación, una barra vertical o una coma. El valor predeterminado es una coma.
Tipos de datos
Booleano. BigQuery puede analizar cualquiera de los siguientes pares para datos booleanos: 1 o 0, true o false, t o f, yes o no, y o n (todos distinguen entre mayúsculas y minúsculas). La detección automática de esquemas detectará de forma automática cualquiera de estas opciones, excepto 0 y 1.
Fecha. Las columnas con tipos DATE (fecha) deben tener el formato YYYY-MM-DD
.
Fecha y hora. Las columnas con los tipos DATETIME (fecha y hora) deben tener el formato YYYY-MM-DD
HH:MM:SS[.SSSSSS]
.
Hora. Las columnas con tipos TIME (hora) deben tener el formato HH:MM:SS[.SSSSSS]
.
Marca de tiempo. BigQuery acepta una variedad de formatos de marca de tiempo. La marca de tiempo debe incluir una parte de la fecha y una de la hora.
La parte de la fecha puede tener el formato
YYYY-MM-DD
oYYYY/MM/DD
.La parte de la marca de tiempo debe tener el formato
HH:MM[:SS[.SSSSSS]]
(los segundos y las fracciones de segundos son opcionales).La fecha y la hora deben estar separadas por un espacio o “T”.
De forma opcional, la fecha y la hora pueden estar seguidas por una compensación UTC o el designador de zona UTC (
Z
). Para obtener más información, consulta Zonas horarias.
Por ejemplo, cualquiera de los siguientes son valores de marca de tiempo válidos:
- 2018-08-19 12:11
- 2018-08-19 12:11:35
- 2018-08-19 12:11:35.22
- 2018/08/19 12:11
- 2018-07-05 12:54:00 UTC
- 2018-08-19 07:11:35.220 -05:00
- 2018-08-19T12:11:35.220Z
Si proporcionas un esquema, BigQuery también acepta la hora de Unix para los valores de marca de tiempo. Sin embargo, la detección automática de esquemas no detectará este caso y tratará el valor como un tipo numérico o de string en su lugar.
Ejemplos de valores de marca de tiempo de hora de Unix:
- 1534680695
- 1.534680695e11
Opciones de CSV
Para cambiar la forma en que BigQuery analiza los datos de CSV, especifica opciones adicionales en Cloud Console, la herramienta de línea de comandos de bq
o la API.
Para obtener más información sobre el formato CSV, consulta RFC 4180.
Opción CSV | Opción de Console | Marca de la herramienta de bq |
Propiedad de la API de BigQuery | Descripción |
---|---|---|---|---|
Delimitador de campos | Delimitador de campos: coma, tabulador, barra vertical, o uno personalizado | -F o --field_delimiter |
fieldDelimiter |
El separador de campos de un archivo CSV (opcional). El separador puede ser cualquier carácter ISO-8859-1 de un solo byte. Para usar un carácter del rango 128-255, debes codificar el carácter como UTF8. BigQuery convierte la string en codificación ISO-8859-1 y usa el primer byte de la string codificada para dividir los datos en su estado binario sin procesar. BigQuery también admite la secuencia de escape “\t” para especificar un separador de tabulador. El valor predeterminado es una coma (“,”). |
Filas del encabezado | Filas del encabezado que se omitirán | --skip_leading_rows |
skipLeadingRows |
Un número entero que indica la cantidad de filas de encabezado en los datos de origen (opcional). |
Cantidad de registros incorrectos permitidos | Cantidad de errores permitidos | --max_bad_records |
maxBadRecords |
La cantidad máxima de registros erróneos 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. |
Caracteres de saltos de línea | Permitir saltos de línea en secciones entrecomilladas | --allow_quoted_newlines |
allowQuotedNewlines |
Indica si se deben permitir las secciones de datos entrecomillados que contienen caracteres de saltos de línea en un archivo de CSV (opcional). El valor predeterminado es falso. |
Valores nulos personalizados | Ninguna | --null_marker |
nullMarker |
Especifica una string que representa un valor nulo en un archivo de CSV (opcional). Por ejemplo, si especificas “\N”, BigQuery interpreta “\N” como un valor nulo cuando se carga un archivo CSV. El valor predeterminado es una string vacía. Si estableces esta propiedad como un valor personalizado, BigQuery muestra un error si hay una string vacía para todos los tipos de datos, excepto STRING y BYTE. Para las columnas STRING y BYTE, BigQuery interpreta la string vacía como un valor vacío. |
Columnas opcionales finales | Permitir filas irregulares | --allow_jagged_rows |
allowJaggedRows |
Acepta las filas que no contienen columnas opcionales finales (opcional). Los valores que faltan se consideran nulos. Si es falso, los registros en los que faltan columnas finales se tratan como registros incorrectos, y si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es falso. Aplica solo a CSV, se ignora para otros formatos. |
Valores desconocidos | Ignorar valores desconocidos | --ignore_unknown_values |
ignoreUnknownValues |
Indica si BigQuery debe permitir valores adicionales que no estén representados en el esquema de la tabla (opcional). Si es verdadero, los valores adicionales se ignoran. Si es falso, los registros con columnas adicionales se tratan como registros incorrectos, y si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es falso. Con la propiedad sourceFormat , se determina qué es lo que BigQuery trata como un valor adicional:
|
Comillas | Ninguna | --quote |
quote |
El valor que se usa para entrecomillar secciones de datos en un archivo de CSV (opcional).
BigQuery convierte la string en codificación ISO-8859-1 y, luego, usa el primer byte de la string codificada para dividir los datos en su estado binario sin procesar. El valor predeterminado es una comilla doble (“”). Si tus datos no contienen secciones entrecomilladas, establece el valor de la propiedad en una string vacía. Si los datos contienen caracteres de salto de línea entrecomillados, también debes establecer la propiedad allowQuotedNewlines en true . Para incluir el carácter de comillas específico dentro de un valor entrecomillado, coloca un carácter de comillas que coincida antes de él. Por ejemplo, si deseas escapar del carácter predeterminado ‘ " ’, usa ‘ "" ’. |
Codificación | Ninguna | -E o --encoding |
encoding |
La codificación de caracteres de los datos (opcional). Los valores admitidos son UTF-8 o ISO-8859-1. El valor predeterminado es UTF-8. BigQuery decodifica los datos luego de la división de los datos binarios sin procesar mediante los valores de las propiedades quote y fieldDelimiter . |