Como carregar arquivos CSV do Cloud Storage
Ao carregar dados CSV do Cloud Storage, você pode anexá-los ou substituir uma tabela ou partição existente. Também é possível carregá-los em uma nova tabela ou partição. Quando os dados são carregados no BigQuery, eles são convertidos para o Capacitor (em inglês), o formato de armazenamento em colunas do BigQuery.
Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que contém a tabela precisa estar na mesma região ou multirregião que o bucket do Cloud Storage.
Para saber mais sobre como carregar dados CSV de um arquivo local, consulte Como carregar dados ao BigQuery de uma fonte de dados local.
Limitações
Ao carregar dados CSV do Cloud Storage ao BigQuery, observe estes pontos:
- Os arquivos CSV não são compatíveis com dados aninhados ou repetidos.
- Se você usa a compactação gzip, o BigQuery não consegue ler os dados em paralelo. O carregamento de dados CSV compactados no BigQuery é mais lento do que os não compactados. Consulte Como carregar dados compactados e descompactados.
- Não é possível incluir arquivos compactados e descompactados no mesmo job de carga.
- O tamanho máximo de um arquivo gzip é de 4 GB.
- Ao carregar dados CSV ou JSON, os valores nas colunas
DATE
precisam usar o traço (-
) e a data precisa estar no seguinte formato:YYYY-MM-DD
(ano-mês-dia). - Ao carregar dados JSON ou CSV, os valores nas colunas
TIMESTAMP
precisam usar um traço (-
) para a parte da data do carimbo de data/hora, e a data precisa estar no seguinte formato:YYYY-MM-DD
(ano-mês-dia). A partehh:mm:ss
(hora-minuto-segundo) do carimbo de data/hora precisa usar um separador de dois pontos (:
).
Permissões exigidas
Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carregamento e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões para acessar o intervalo que contém os dados.
Permissões do BigQuery
Pelo menos as permissões a seguir são obrigatórias para carregar dados no BigQuery. Elas serão necessárias se você estiver carregando dados em uma nova tabela ou partição ou anexando/substituindo uma tabela ou partição.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.create
e bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
O acesso bigquery.dataOwner
permite que o usuário crie e
atualize tabelas no conjunto de dados usando um job de carregamento.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.
Permissões do Cloud Storage
Para carregar dados de um intervalo do Cloud Storage, você precisa ter
permissões storage.objects.get
. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list
.
O papel predefinido storage.objectViewer
do IAM concede as permissões storage.objects.get
e
storage.objects.list
.
Como carregar dados CSV em uma tabela
É possível carregar dados CSV do Cloud Storage em uma nova tabela do BigQuery com um destes métodos:
- Use o Console do Cloud.
- Use o comando
bq load
da ferramenta de linha de comandobq
. - Chame o método da API
jobs.insert
e configure um jobload
. - usando as bibliotecas de cliente.
Para carregar os dados CSV do Cloud Storage em uma nova tabela do BigQuery:
Console
Abra a página do BigQuery no Console do Cloud.
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
Na página Criar tabela, na seção Origem:
Em Criar tabela de, selecione Cloud Storage.
No campo de origem, navegue até o URI do Cloud Storage ou insira-o. Não é possível incluir vários URIs no Console do Cloud, mas os caracteres curinga são compatíveis. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela sendo criada.
Em Formato de arquivo, selecione CSV.
Siga estas etapas na página Criar tabela, na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
Verifique se Tipo de tabela está definido como Tabela nativa.
No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.
Na seção Esquema, em Detectar automaticamente, marque Parâmetros de esquema e entrada para ativar a detecção automática do esquema. Se preferir, insira manualmente a definição do esquema da seguinte maneira:
ative Editar como texto e insira o esquema da tabela como uma matriz JSON.
Use Adicionar campo para inserir manualmente o esquema.
Opcional: para particionar a tabela, escolha as opções em Configurações de particionamento e cluster:
- Para criar uma tabela particionada, clique em Sem particionamento, selecione Partição por campo e escolha uma coluna
DATE
ouTIMESTAMP
. Essa opção ficará indisponível se o esquema não incluir uma colunaDATE
ouTIMESTAMP
. - Para criar uma tabela particionada por tempo de ingestão, clique em Sem particionamento e selecione Partição por tempo de ingestão.
- Para criar uma tabela particionada, clique em Sem particionamento, selecione Partição por campo e escolha uma coluna
(Opcional) Em Filtro de particionamento, clique na caixa Exigir filtro de particionamento para solicitar que os usuários incluam uma cláusula
WHERE
que especifique as partições a serem consultadas. A exigência de um filtro de partição pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas. Essa opção ficará indisponível se a opção Sem particionamento estiver selecionada.Opcional: para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering.
Opcional: clique em Opções avançadas.
- Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
- Em Número de erros permitidos, aceite o valor padrão
0
ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensageminvalid
e falhará. - Em Valores desconhecidos, marque Ignorar valores desconhecidos para ignorar todos os valores em uma linha que não estejam no esquema da tabela.
- Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Personalizado. Se você escolher Personalizado, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
- Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é
0
. - Em Novas linhas com consulta, marque Permitir novas linhas com consulta para permitir seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é
false
. - Em Linhas dentadas, marque Permitir linhas dentadas para aceitar linhas em arquivos CSV em que as colunas opcionais no final estejam faltando. Os valores ausentes são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é
false
. - Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Clique em Criar tabela.
bq
Use o comando bq load
, especifique CSV
usando a sinalização --source_format
e inclua um URI do Cloud Storage.
É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.
Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática de esquemas.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Estas são outras sinalizações opcionais:
--allow_jagged_rows
: quando especificada, aceita linhas em arquivos CSV que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão éfalse
.--allow_quoted_newlines
: quando especificada, permite seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão éfalse
.--field_delimiter
: o caractere que indica o limite entre colunas nos dados.\t
etab
são permitidos como delimitadores de tabulação. O valor padrão é,
.--null_marker
: uma string personalizada opcional que representa um valor NULL nos dados CSV.--skip_leading_rows
: especifica o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é0
.--quote
: o caractere de aspas a ser usado antes e depois dos registros. O valor padrão é"
. Para indicar nenhum caractere de aspas, use uma string vazia.--max_bad_records
: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é0
. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de--max_bad_records
.--ignore_unknown_values
: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.--autodetect
: quando especificada, ativa a detecção automática de esquemas em dados CSV e JSON.--time_partitioning_type
: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis sãoHOUR
,DAY
,MONTH
eYEAR
. Essa sinalização é opcional quando você cria uma tabela particionada em uma colunaDATE
,DATETIME
ouTIMESTAMP
. O tipo de partição padrão para o particionamento baseado em tempo éDAY
.--time_partitioning_expiration
: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.--time_partitioning_field
: a colunaDATE
ouTIMESTAMP
usada para criar uma tabela particionada. Se o particionamento baseado em tempo estiver ativado sem esse valor, uma tabela particionada por tempo de ingestão será criada.--require_partition_filter
: quando ativada, essa opção exige que os usuários incluam uma cláusulaWHERE
que especifica as partições a serem consultadas. A exigência de um filtro de particionamento pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas.--clustering_fields
: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.--destination_kms_key
: a chave do Cloud KMS para criptografia dos dados da tabela.Para mais informações sobre o comando
bq load
, consulte:Para mais informações sobre tabelas particionadas, consulte:
- Como criar e usar tabelas particionadas
- Como criar e usar tabelas particionadas por tempo de ingestão
Para mais informações sobre tabelas em cluster, consulte:
Para mais informações sobre a criptografia de tabelas, consulte:
Para carregar dados CSV no BigQuery, insira o comando a seguir:
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source \ schema
Em que:
- location é o local. A sinalização
--location
é opcional. Por exemplo, se você estiver usando BigQuery na região de Tóquio, defina o valor da sinalização comoasia-northeast1
. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. - format é
CSV
. - dataset é um conjunto de dados atual;
- table é o nome da tabela em que você carregará dados;
- path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.
- schema é um esquema válido. Ele pode ser um arquivo JSON local ou inserido in-line como parte do comando. Também é possível usar a sinalização
--autodetect
em vez de fornecer uma definição de esquema.
Exemplos:
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela chamada mytable
em mydataset
. O esquema é definido em um arquivo de esquema local chamado myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela chamada mytable
em mydataset
. O esquema é definido em um arquivo de esquema local chamado myschema.json
. O arquivo CSV inclui duas linhas de cabeçalho.
Se --skip_leading_rows
não for especificado, o comportamento padrão será supor que o arquivo não contenha cabeçalhos.
bq load \
--source_format=CSV \
--skip_leading_rows=2
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela particionada por tempo de ingestão chamada mytable
em mydataset
. O esquema é definido em um arquivo de esquema local chamado myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela particionada chamada mytable
em mydataset
. A tabela é particionada na coluna mytimestamp
. O esquema é definido em um arquivo de esquema local chamado myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela chamada mytable
em mydataset
. O esquema é detectado automaticamente.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
O comando a seguir carrega dados de gs://mybucket/mydata.csv
em uma tabela chamada mytable
em mydataset
. O esquema é definido in-line no formato field:data_type,field:data_type
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
O seguinte comando carrega dados de vários arquivos em gs://mybucket/
em uma tabela chamada mytable
em mydataset
. O URI do Cloud Storage usa um caractere curinga. O esquema é detectado automaticamente.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata*.csv
O seguinte comando carrega dados de vários arquivos em gs://mybucket/
em uma tabela chamada mytable
em mydataset
. O comando inclui uma lista separada por vírgulas de URIs do Cloud Storage com caracteres curinga. O esquema é definido em um arquivo de esquema local chamado myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
"gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
./myschema.json
API
Crie um job
load
que aponte para os dados de origem no Cloud Storage.(Opcional) Especifique o local na propriedade
location
da seçãojobReference
do recurso do job.A propriedade
source URIs
precisa ser totalmente qualificada no formatogs://bucket/object
. Cada URI pode conter um caractere curinga "*".Defina a propriedade
sourceFormat
comoCSV
para especificar o formato de dados CSV.Para verificar o status do job, chame
jobs.get(job_id*)
, em que job_id é o ID do job retornado pela solicitação inicial.status.state = DONE
indica que o job foi concluído.- A propriedade
status.errorResult
mostra que houve falha na solicitação e o objeto incluirá informações que descrevem o erro. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados. - A ausência de
status.errorResult
indica que o job foi concluído com sucesso. No entanto, é possível que haja alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedadestatus.errors
do objeto do job retornado.
Observações sobre a API:
Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.
Como prática recomendada, gere um ID exclusivo e transmita-o como
jobReference.jobId
ao chamarjobs.insert
para criar um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.Chamar
jobs.insert
em um determinado ID do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID do job e, no máximo, uma das operações será bem-sucedida.
C#
Antes de testar essa amostra, siga as instruções de configuração para C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em C#.
Go
Antes de testar essa amostra, siga as instruções de configuração para Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.
Java
Antes de testar essa amostra, siga as instruções de configuração para Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Node.js.
PHP
Antes de testar esta amostra, siga as instruções de configuração para PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery PHP.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.
Use o método Client.load_table_from_uri() para carregar dados de um arquivo CSV no Cloud Storage. Forneça uma definição de esquema explícita. Para isso, defina a propriedade LoadJobConfig.schema para uma lista de objetos SchemaField (links em inglês).
Ruby
Antes de testar esta amostra, siga as instruções de configuração para Ruby no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de Referência da API BigQuery Ruby.
Como carregar dados CSV em uma tabela que usa o particionamento de tempo baseado em colunas
Para carregar dados CSV do Cloud Storage em uma tabela do BigQuery que usa o particionamento de tempo baseado em colunas, faça o seguinte:
Go
Antes de testar essa amostra, siga as instruções de configuração para Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.
Java
Antes de testar essa amostra, siga as instruções de configuração para Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.
Como anexar ou substituir uma tabela com dados CSV
Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.
No Console do Cloud, use a opção Preferência de gravação para especificar qual ação será realizada ao carregar dados de um arquivo de origem ou de um resultado de consulta.
Você tem as seguintes opções ao carregar mais dados em uma tabela:
Opção do console | Sinalização da ferramenta bq |
Propriedade da API BigQuery | Descrição |
---|---|---|---|
Gravar apenas se a tabela estiver vazia | Nenhuma | WRITE_EMPTY |
Grava dados apenas se a tabela estiver vazia. |
Anexar à tabela | --noreplace ou --replace=false ; se --[no]replace não for especificado, o padrão será anexado |
WRITE_APPEND |
(Padrão) Anexa os dados ao final da tabela. |
Substituir tabela | --replace ou --replace=true |
WRITE_TRUNCATE |
Apaga todos os dados da tabela antes de gravar os novos. Essa ação também exclui o esquema da tabela e remove qualquer chave do Cloud KMS. |
Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.
É possível anexar ou substituir uma tabela com um destes métodos:
- Use o Console do Cloud.
- Use o comando
bq load
da ferramenta de linha de comandobq
. - Chame o método da API
jobs.insert
e configure um jobload
. - Como usar bibliotecas de cliente
Console
Abra a página do BigQuery no Console do Cloud.
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
Na página Criar tabela, na seção Origem:
Em Criar tabela de, selecione Cloud Storage.
No campo de origem, procure ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no Console do Cloud, mas os caracteres curinga são compatíveis. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está anexando ou substituindo.
Em Formato de arquivo, selecione CSV.
Siga estas etapas na página Criar tabela, na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
No campo Nome da tabela, insira o nome da tabela que você está anexando ou substituindo no BigQuery.
Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, em Detectar automaticamente, marque Parâmetros de esquema e entrada para ativar a detecção automática do esquema. Se preferir, insira manualmente a definição do esquema da seguinte maneira:
ative Editar como texto e insira o esquema da tabela como uma matriz JSON.
Use Adicionar campo para inserir manualmente o esquema.
Em Configurações de partição e cluster, use os valores padrão. Não é possível anexar ou substituir uma tabela para convertê-la em uma tabela particionada ou em cluster. Além disso, o Console do Cloud não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
Clique em Opções avançadas.
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Em Número de erros permitidos, aceite o valor padrão
0
ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensageminvalid
e falhará. - Em Valores desconhecidos, marque Ignorar valores desconhecidos para ignorar todos os valores em uma linha que não estejam no esquema da tabela.
- Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Personalizado. Se você escolher Personalizado, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
- Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é
0
. - Em Novas linhas com consulta, marque Permitir novas linhas com consulta para permitir seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é
false
. - Em Linhas dentadas, marque Permitir linhas dentadas para aceitar linhas em arquivos CSV em que as colunas opcionais no final estejam faltando. Os valores ausentes são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é
false
. Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Clique em Criar tabela.
bq
Use o comando bq load
, especifique CSV
usando a sinalização --source_format
e inclua um URI do Cloud Storage.
É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.
Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática do esquema.
Especifique a sinalização --replace
para substituir a tabela. Use a sinalização --noreplace
para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados.
É possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carga, consulte Como modificar esquemas de tabela.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Estas são outras sinalizações opcionais:
--allow_jagged_rows
: quando especificada, aceita linhas em arquivos CSV que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão éfalse
.--allow_quoted_newlines
: quando especificada, permite seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão éfalse
.--field_delimiter
: o caractere que indica o limite entre colunas nos dados.\t
etab
são permitidos como delimitadores de tabulação. O valor padrão é,
.--null_marker
: uma string personalizada opcional que representa um valor NULL nos dados CSV.--skip_leading_rows
: especifica o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é0
.--quote
: o caractere de aspas a ser usado antes e depois dos registros. O valor padrão é"
. Para indicar nenhum caractere de aspas, use uma string vazia.--max_bad_records
: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é0
. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de--max_bad_records
.--ignore_unknown_values
: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.--autodetect
: quando especificado, ativa a detecção automática de esquemas em dados CSV e JSON.--destination_kms_key
: a chave do Cloud KMS para criptografia dos dados da tabela.
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source \ schema
onde:
- location é o local.
A sinalização
--location
é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. - format é
CSV
; - dataset é um conjunto de dados atual;
- table é o nome da tabela em que você carregará dados;
- path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.
- schema é um esquema válido. Ele pode ser um arquivo JSON local ou inserido in-line como parte do comando. Também é possível usar a sinalização
--autodetect
em vez de fornecer uma definição de esquema.
Exemplos:
O comando a seguir carrega dados de gs://mybucket/mydata.csv
e substitui uma tabela chamada mytable
em mydataset
. O esquema é definido por meio da detecção automática de esquemas.
bq load \
--autodetect \
--replace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
O seguinte comando carrega dados de gs://mybucket/mydata.csv
e anexa dados a uma tabela chamada mytable
em mydataset
. O esquema é definido por um arquivo de esquema JSON – myschema.json
.
bq load \
--noreplace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
API
Crie um job
load
que aponte para os dados de origem no Cloud Storage.(Opcional) Especifique o local na propriedade
location
da seçãojobReference
do recurso do job.A propriedade
source URIs
precisa ser totalmente qualificada no formatogs://bucket/object
. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são compatíveis.Especifique o formato de dados definindo a propriedade
configuration.load.sourceFormat
comoCSV
.Especifique a preferência de gravação definindo a propriedade
configuration.load.writeDisposition
comoWRITE_TRUNCATE
ouWRITE_APPEND
.
Go
Antes de testar essa amostra, siga as instruções de configuração para Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.
Java
Antes de testar essa amostra, siga as instruções de configuração para Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Node.js (em inglês).
Para substituir as linhas de uma tabela atual, defina o valor writeDisposition
no parâmetro metadata
como 'WRITE_TRUNCATE'
.
Antes de testar esta amostra, siga as instruções de configuração para PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery PHP.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.
Para substituir linhas em uma tabela, defina a propriedade LoadJobConfig.write_disposition como a constante WRITE_TRUNCATE
do SourceFormat (links em inglês).
Como carregar dados CSV particionados do Hive
Com o BigQuery, é possível carregar dados CSV particionados do Hive que estejam armazenados no Cloud Storage. A ferramenta preenche as colunas particionadas do Hive como colunas na tabela de destino gerenciada pelo BigQuery. Para mais informações, consulte Como carregar dados particionados externamente do Cloud Storage.
Detalhes do carregamento de dados CSV
Nesta seção, descrevemos como o BigQuery lida com várias opções de formatação CSV.
Codificação
Para o BigQuery, é necessário que os dados CSV estejam codificados em UTF-8. Se você tiver arquivos CSV com dados codificados no formato ISO-8859-1 (também conhecido como Latin-1), especifique explicitamente a codificação para que o BigQuery possa converter adequadamente os dados para UTF-8.
Se você não especificar uma codificação ou especificar a codificação UTF-8 quando o arquivo CSV
não estiver codificado em UTF-8, o BigQuery tentará converter os dados
em UTF-8. Geralmente, seus dados são carregados com sucesso, mas podem não corresponder
byte por byte àquilo que você espera. Para evitar isso, especifique a codificação correta
usando a sinalização --encoding
.
Se o BigQuery não conseguir converter um caractere diferente do caractere ASCII 0
,
o BigQuery converterá o caractere para o
caractere de substituição Unicode padrão: �.
Delimitadores de campos
Em arquivos CSV, os delimitadores podem ser qualquer caractere de um byte. Se o arquivo de origem usar a codificação ISO-8859-1, qualquer caractere poderá ser um delimitador. Se o arquivo de origem usar a codificação UTF-8, qualquer caractere no intervalo decimal de 1-127 (U+0001-U+007F) poderá ser usado sem modificação. É possível inserir um caractere ISO-8859-1 fora desse intervalo como um delimitador, e o BigQuery o interpretará corretamente. No entanto, se você usar um caractere de vários bytes como delimitador, alguns dos bytes serão interpretados como parte do valor do campo.
Normalmente, é uma prática recomendada usar um delimitador padrão, como tabulação, barra vertical ou vírgula. O padrão é uma vírgula.
Tipos de dados
Boolean. O BigQuery pode analisar qualquer um dos seguintes pares de dados booleanos: 1 ou 0, true ou false, t ou f, yes ou no e y ou n (indiferente a maiúsculas). A detecção automática de esquema detectará qualquer um desses elementos automaticamente, exceto 0 e 1.
Date. As colunas com tipos DATE precisam estar no formato YYYY-MM-DD
.
Datetime. As colunas com tipos DATETIME precisam estar no formato YYYY-MM-DD
HH:MM:SS[.SSSSSS]
.
Horário. As colunas com tipos TIME precisam estar no formato HH:MM:SS[.SSSSSS]
.
Carimbo de data/hora. O BigQuery aceita vários formatos de carimbo de data/hora. O carimbo de data/hora precisa incluir uma parte de data e de hora.
A parte da data pode ser formatada como
YYYY-MM-DD
ouYYYY/MM/DD
.A parte do carimbo de data/hora precisa ser formatada como
HH:MM[:SS[.SSSSSS]]
(segundos e frações de segundos são opcionais).A data e a hora precisam ser separadas por um espaço ou "T".
Opcionalmente, a data e a hora podem ser seguidas por um deslocamento de UTC ou um regulador de fuso horário do UTC (
Z
). Para mais informações, consulte Fusos horários.
Por exemplo, qualquer um dos valores de carimbo de data/hora a seguir é válido:
- 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
Se você fornecer um esquema, o BigQuery também aceitará o horário Unix para valores de carimbo de data/hora. No entanto, a detecção automática de esquema não detectará esse caso e tratará o valor como um tipo numérico ou string.
Exemplos de valores de carimbo de data/hora do Unix:
- 1534680695
- 1.534680695e11
Opções de CSV
Para alterar a forma como o BigQuery analisa dados CSV, especifique outras opções
no Console do Cloud, na ferramenta de linha de comando bq
ou na API.
Para mais informações sobre o formato CSV, consulte RFC 4180 (em inglês).
Opção de CSV | Opção do console | Sinalização da ferramenta bq |
Propriedade da API BigQuery | Descrição |
---|---|---|---|---|
Delimitador de campo | Delimitador de campo: vírgula, tabulação, barra vertical, personalizado | -F ou --field_delimiter |
fieldDelimiter |
Opcional: o separador de campos em um arquivo CSV. O separador pode ser qualquer caractere de um byte em ISO-8859-1. Para usar um caractere no intervalo 128-255, codifique-o como UTF-8. O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte dela para dividir os dados em estado bruto binário. O BigQuery também aceita a sequência de escape "\t" para especificar um separador de tabulação. O valor padrão é a vírgula (","). |
Linhas de cabeçalho | Linhas de cabeçalho a serem ignoradas | --skip_leading_rows |
skipLeadingRows |
(Opcional) Um número inteiro que indica o número de linhas de cabeçalho nos dados de origem. |
Número de registros corrompidos permitidos | Número de erros permitido | --max_bad_records |
maxBadRecords |
(Opcional) O número máximo de registros corrompidos que o BigQuery pode ignorar ao executar o job. Se o número exceder esse valor, um erro inválido será retornado no resultado do job. O valor padrão é 0, o que exige que todos os registros sejam válidos. |
Caracteres de nova linha | Permitir novas linhas com consulta | --allow_quoted_newlines |
allowQuotedNewlines |
(Opcional) Indica se as seções de dados citados que contêm caracteres de nova linha em um arquivo CSV podem ser permitidas. O valor padrão é falso. |
Valores nulos personalizados | Nenhum | --null_marker |
nullMarker |
(Opcional) Especifica uma string que representa um valor nulo em um arquivo CSV. Por exemplo, se você especificar "\N", o BigQuery o interpretará como um valor nulo ao carregar um arquivo CSV. O valor padrão é a string vazia. Ao definir um valor personalizado, o BigQuery lançará um erro se uma string vazia estiver presente para qualquer tipo de dados, exceto STRING e BYTE. Nessas colunas, o BigQuery interpreta a string vazia como um valor vazio. |
Colunas posteriores opcionais | Permitir linhas dentadas | --allow_jagged_rows |
allowJaggedRows |
(Opcional) Aceita linhas que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se for falso, os registros sem colunas posteriores serão tratados como corrompidos e, se houver muitos dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é falso. Aplicável apenas para CSV, ignorado para outros formatos. |
Valores desconhecidos | Ignorar valores desconhecidos | --ignore_unknown_values |
ignoreUnknownValues |
(Opcional) Indica se o BigQuery permite outros valores que não estão representados no esquema da tabela. Se for verdadeiro, os outros valores serão ignorados. Se for falso, os registros com colunas extras serão tratados como corrompidos e, se houver muitos dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é falso. A propriedade sourceFormat determina o que o BigQuery trata como um valor extra:
|
Citação | Nenhum | --quote |
quote |
(Opcional) O valor usado para citar seções de dados em um arquivo CSV.
O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte da string codificada para dividir os dados no estado bruto binário. O valor padrão são aspas duplas (""). Se os dados não tiverem seções citadas, defina o valor da propriedade como uma string vazia. Se os dados contiverem caracteres de nova linha com consulta, será necessário definir
a propriedade allowQuotedNewlines como true . Para
incluir o caractere de citação específico dentro de um valor entre aspas, coloque
um caractere extra antes dele. Por exemplo, se quiser
inserir o caractere padrão ", use "". |
Codificação | Nenhum | -E ou --encoding |
encoding |
Opcional: a codificação de caracteres dos dados. Os valores aceitos são UTF-8 ou ISO-8859-1. O valor padrão é UTF-8. O BigQuery decodifica os dados depois que os dados binários brutos são divididos usando os valores das propriedades quote e fieldDelimiter . |