Como carregar arquivos JSON do Cloud Storage
Ao carregar dados JSON delimitados por linha nova do Cloud Storage, é possível carregar os dados em uma tabela ou partição nova, ou anexar ou substituir uma tabela ou partição atual. Quando os dados são carregados no BigQuery, eles são convertidos no formato de colunas Capacitor (em inglês), o formato de armazenamento 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 no mesmo local regional ou multirregional que o intervalo do Cloud Storage.
O formato JSON delimitado por nova linha é igual ao formato Linhas JSON (em inglês).
Para informações sobre como carregar dados JSON de um arquivo local, consulte Como carregar dados no BigQuery de uma fonte de dados local.
Limitações
Ao carregar dados JSON do Cloud Storage para o BigQuery, observe os itens a seguir:
- Os dados JSON precisam ser delimitados por nova linha. Cada objeto JSON precisa estar em uma linha separada no arquivo.
- Se você usa a compactação Gzip, o BigQuery não pode ler os dados em paralelo. O carregamento de dados JSON compactados no BigQuery é mais lento do que o carregamento de dados não compactados.
- Não é possível incluir arquivos compactados e descompactados no mesmo job de carga.
- O BigQuery não é compatível com mapas ou dicionários em JSON. Por exemplo,
"product_categories": {"my_product": 40.0}
não é válido, mas"product_categories": {"column1": "my_product" , "column2": 40.0}
, sim. - Quando você carrega dados CSV ou JSON, os valores nas colunas
DATE
precisam usar o separador traço (-
) e a data precisa estar no formato:YYYY-MM-DD
(ano-mês-dia). - Quando você carrega dados JSON ou CSV, os valores nas colunas
TIMESTAMP
precisam usar o separador de traço (-
) na parte de 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 o separador dois-pontos (:
).
Permissões necessárias
Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carga 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 papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.tables.create
e bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Além disso, quando um usuário com permissões bigquery.datasets.create
cria um conjunto de dados, recebe o acesso bigquery.dataOwner
a ele.
Com o acesso bigquery.dataOwner
, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carga.
Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.
Permissões do Cloud Storage
Para carregar dados de um intervalo do Cloud Storage, é necessário ter permissões storage.objects.get
. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list
.
É possível conceder o papel predefinido storage.objectViewer
do Cloud IAM para fornecer as permissões storage.objects.get
e storage.objects.list
.
Como carregar dados JSON em uma nova tabela
Para carregar dados JSON delimitados por nova linha do Cloud Storage em uma nova tabela do BigQuery:
- Use o Console do GCP ou a IU da Web clássica.
- Com o uso do comando
bq load
da CLI. - Chamando o método de API
jobs.insert
e configurando um jobload
. - Use bibliotecas de cliente.
Para carregar dados JSON do Cloud Storage em uma nova tabela do BigQuery:
Console
Abra a IU da Web do BigQuery no Console do GCP.
Acessar o Console do GCPNa seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Siga estas etapas na página Criar tabela, 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 GCP, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.
Em Formato de arquivo, selecione JSON (delimitado por nova linha).
Siga estas etapas na página Criar tabela, seção Destino:
Em Nome do conjunto de dados, escolha o conjunto apropriado.
Verifique se o 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. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:
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 Particionar por campo e escolha uma coluna
DATE
ouTIMESTAMP
. Essa opção estará 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 Particionar 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 reduz os custos e melhora o desempenho. Para mais informações, consulte Como consultar tabelas particionadas. Essa opção estará indisponível se Sem particionamento estiver selecionado.Opcional: para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering. Atualmente, o clustering é compatível apenas com tabelas particionadas.
(Opcional) Clique em Opções avançadas.
- Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Essa opção 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 quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
- 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.
IU clássica
Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQueryNo painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo
e selecione Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Na página Criar tabela, na seção Dados de origem:
- Clique em Criar da origem.
- Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.
- Em Formato de arquivo, selecione JSON (delimitado por nova linha).
Na seção Tabela de destino:
- Em Nome da tabela, escolha o conjunto de dados apropriado. No campo do nome da tabela, insira um nome para a tabela que você está criando 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. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:
Clique em Editar como texto e insira o esquema da tabela como uma matriz JSON.
Use Adicionar campo para inserir manualmente o esquema:
Opcional: na seção Opções:
- 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 Preferência de gravação, mantenha selecionada a opção Gravar apenas se a tabela estiver vazia. Essa opção cria uma nova tabela e carrega seus dados nela.
- Para particionar a tabela:
- Em Tipo de particionamento, clique em Nenhum e escolha Dia.
- No Campo de particionamento:
- Para criar uma tabela particionada, escolha uma coluna
DATE
ouTIMESTAMP
. Essa opção estará indisponível se o esquema não incluir uma colunaDATE
ouTIMESTAMP
. - Para criar uma tabela particionada por tempo de ingestão, use o valor padrão:
_PARTITIONTIME
. - Clique na caixa Exigir filtro de partição 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 reduz os custos e melhora o desempenho. Para mais informações, consulte Como consultar tabelas particionadas. Essa opção estará indisponível se Tipo de particionamento estiver definido como Nenhum.
- Para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Campos em cluster.
- Em Criptografia de destino, escolha Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração
Default
, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
- Em Número de erros permitidos, aceite o valor padrão
Clique em Criar tabela.
CLI
Use o comando bq load
, especifique NEWLINE_DELIMITED_JSON
usando a sinalização --source_format
e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separada por vírgulas ou um URI contendo 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.
Opcional: forneça a sinalização --location
e defina o valor do local.
Estas são outras sinalizações opcionais:
--max_bad_records
: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes que o job inteiro falhe. 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 especificada, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.--autodetect
: quando especificada, ativa a detecção automática de esquema para dados CSV e JSON.--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.--time_partitioning_type
: ativa o particionamento baseado em tempo em uma tabela e define o tipo de partição. Atualmente, o único valor possível éDAY
, que gera uma partição por dia. Essa sinalização é opcional quando você cria uma tabela particionada em uma colunaDATE
ouTIMESTAMP
.--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 especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte 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. Só é possível usar essa sinalização com tabelas particionadas.--destination_kms_key
: a chave do Cloud KMS para criptografia dos dados da tabela.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 JSON 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 o 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 é
NEWLINE_DELIMITED_JSON
. - dataset é um conjunto de dados atual.
- table é o nome da tabela em que os dados serão carregados;
- path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis;
- 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.json
em uma tabela denominada mytable
em mydataset
. O esquema é definido em um arquivo de esquema local denominado myschema.json
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.json
em uma tabela particionada por tempo de ingestão denominada mytable
em mydataset
. O esquema é definido em um arquivo de esquema local denominado myschema.json
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.json
em uma tabela particionada denominada mytable
em mydataset
. A tabela é particionada na coluna mytimestamp
. O esquema é definido em um arquivo de esquema local denominado myschema.json
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema.json
O comando a seguir carrega dados de gs://mybucket/mydata.json
em uma tabela denominada mytable
em mydataset
. O esquema é detectado automaticamente.
bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json
O comando a seguir carrega dados de gs://mybucket/mydata.json
em uma tabela denominada mytable
em mydataset
. O esquema é definido in-line no formato field:data_type, field:data_type
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
qtr:STRING,sales:FLOAT,year:STRING
O comando a seguir carrega dados de vários arquivos em gs://mybucket/
em uma tabela denominada mytable
em mydataset
. O URI do Cloud Storage usa um caractere curinga. O esquema é detectado automaticamente.
bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata*.json
O comando a seguir carrega dados de vários arquivos em gs://mybucket/
em uma tabela denominada 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 denominado myschema.json
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
"gs://mybucket/00/*.json","gs://mybucket/01/*.json" \
./myschema.json
API
Crie um job
load
que aponte para os dados de origem no Cloud Storage.Opcional: especifique o local na propriedade
location
na seçãojobReference
do recurso de job.A propriedade
source URIs
precisa ser totalmente qualificada no formatogs://bucket/object
. Cada URI pode conter um caractere curinga "*".Especifique o formato de dados JSON definindo a propriedade
sourceFormat
comoNEWLINE_DELIMITED_JSON
.Para verificar o status do job, chame
jobs.get(job_id*)
, em que job_id é o ID do job retornado pela solicitação inicial.- O resultado
status.state = DONE
mostra que o job foi concluído com sucesso. - 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. - Se
status.errorResult
não for exibido, o job terá sido concluído com sucesso, mas é 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.
- O resultado
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 o transmita 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 de job é idempotente. É possível tentar novamente quantas vezes quiser com o mesmo código e, no máximo, uma das operações será bem-sucedida.
C#
Antes de testar esta amostra, siga as instruções de configuração do 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 do BigQuery para C#.
Use o métodoBigQueryClient.CreateLoadJob()
(em inglês) para iniciar um job de carga do Cloud Storage. Para usar o JSON delimitado por nova linha, crie um objeto CreateLoadJobOptions
e defina a respectiva propriedade SourceFormat
como FileFormat.NewlineDelimitedJson
.
Go
Antes de testar este exemplo, siga as instruções de configuração do 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 Go.
Java
Antes de testar este exemplo, siga as instruções de configuração do 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 do BigQuery para Java.
Use o método LoadJobConfiguration.builder(tableId, sourceUri) (em inglês) para iniciar um job de carga no Cloud Storage. Para usar o JSON delimitado por nova linha, use o LoadJobConfiguration.setFormatOptions(FormatOptions.json()).
Node.js
Antes de testar esta amostra, siga as instruções de configuração do 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 do 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 esta amostra, siga as instruções de configuração do 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 Python.
Use o método Client.load_table_from_uri () (em inglês) para iniciar um job de carga no Cloud Storage. Para usar o JSON delimitado por nova linha, defina a propriedade LoadJobConfig.source_format (em inglês) com a stringNEWLINE_DELIMITED_JSON
e transmita a configuração do job como o argumento job_config
para o método load_table_from_uri()
.
Ruby
Antes de testar este exemplo, siga as instruções de configuração do 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.
Use o método Dataset.load_job() para iniciar um job de carregamento no Cloud Storage. Para usar o JSON delimitado por nova linha, defina o parâmetroformat
como "json"
.
Como carregar dados JSON aninhados e repetidos
O BigQuery permite o carregamento de dados aninhados e repetidos de formatos de origem compatíveis com esquemas baseados em objeto, como JSON, Avro, ORC, Parquet, Cloud Firestore e Cloud Datastore.
Cada linha precisa ter um objeto JSON, incluindo campos aninhados/repetidos.
No exemplo a seguir, veja exemplos de dados aninhados/repetidos. Esta tabela contém informações sobre pessoas. Ela consiste nos campos abaixo:
id
first_name
last_name
dob
(data de nascimento)addresses
(um campo aninhado e repetido)addresses.status
(atual ou anterior)addresses.address
addresses.city
addresses.state
addresses.zip
addresses.numberOfYears
(anos no endereço)
O arquivo de dados JSON se parece com o exemplo a seguir. Observe que o campo de endereço contém uma matriz de valores (indicada por [ ]
).
{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]} {"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}
O esquema dessa tabela se parece com este:
[ { "name": "id", "type": "STRING", "mode": "NULLABLE" }, { "name": "first_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "last_name", "type": "STRING", "mode": "NULLABLE" }, { "name": "dob", "type": "DATE", "mode": "NULLABLE" }, { "name": "addresses", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "status", "type": "STRING", "mode": "NULLABLE" }, { "name": "address", "type": "STRING", "mode": "NULLABLE" }, { "name": "city", "type": "STRING", "mode": "NULLABLE" }, { "name": "state", "type": "STRING", "mode": "NULLABLE" }, { "name": "zip", "type": "STRING", "mode": "NULLABLE" }, { "name": "numberOfYears", "type": "STRING", "mode": "NULLABLE" } ] } ]
Para informações sobre como especificar um esquema aninhado e repetido, consulte Como especificar campos aninhados e repetidos.
Como anexar ou substituir uma tabela com dados JSON
É possível carregar mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.
No Console ou na IU da Web clássica do BigQuery, use a opção Gravar preferência para especificar a ação a ser executada ao carregar dados de um arquivo de origem ou de um resultado de consulta.
Você tem as seguintes opções ao carregar dados adicionais em uma tabela:
Opção de console | Opção da IU da Web clássica | Sinalização da CLI | Propriedade da API BigQuery | Descrição |
---|---|---|---|---|
Gravar apenas se a tabela estiver vazia | Gravar apenas se a tabela estiver vazia | Nenhuma | WRITE_EMPTY |
Grava dados apenas se a tabela estiver vazia. |
Anexar à tabela | Anexar à tabela | --noreplace ou --replace=false . Se --[no]replace não estiver especificado, o padrão será anexar |
WRITE_APPEND |
(Padrão) Anexa os dados ao final da tabela. |
Substituir tabela | Substituir tabela | --replace ou --replace=true |
WRITE_TRUNCATE |
Apaga todos os dados em uma tabela antes de gravar os novos. |
Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.
É possível anexar ou substituir uma tabela destas maneiras:
- Com o uso do Console do GCP ou da IU da Web clássica.
- Com o uso do comando
bq load
da CLI. - Chamando o método de API
jobs.insert
e configurando um jobload
. - Com o uso de bibliotecas de cliente.
Console
Abra a IU da Web do BigQuery no Console do GCP.
Acessar o Console do GCPNa seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma 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 na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo 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 JSON (delimitado por nova linha).
Siga estas etapas na página Criar tabela, seção Destino:
Em Nome do conjunto de dados, escolha o conjunto 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. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:
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 GCP 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 quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
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.
IU clássica
Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQueryNo painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo
e selecione Criar nova tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.
Na página Criar tabela, na seção Dados de origem:
- Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU, mas há compatibilidade com caracteres curinga. O intervalo 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 JSON (delimitado por nova linha).
Na página Criar tabela, na seção Tabela de destino:
- Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo de nome, insira o nome da tabela que você está anexando ou substituindo.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, insira a definição do esquema.
Em arquivos JSON, é possível marcar a opção Detectar automaticamente para ativar a detecção automática do esquema.
Outra opção é inserir informações de esquema manualmente:
Clique em Editar como texto e insira o esquema da tabela como uma matriz JSON:
Use Adicionar campo para inserir manualmente o esquema:
Na seção Opções:
- 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 Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Use os valores padrão de Tipo de particionamento, Campo de particionamento, Exigir filtro de partição e Campos de clustering. Não é possível anexar ou substituir uma tabela para convertê-la em uma tabela particionada ou em cluster. Além disso, a IU da Web não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
- Em Criptografia de destino, escolha Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração
Default
, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
- Em Número de erros permitidos, aceite o valor padrão
Clique em Criar tabela.
CLI
Use o comando bq load
, especifique NEWLINE_DELIMITED_JSON
usando a sinalização --source_format
e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separada por vírgulas ou um URI contendo 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:
--max_bad_records
: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes que o job inteiro falhe. 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 especificada, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.--autodetect
: quando especificada, ativa a detecção automática de esquema para 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
Em que:
- location é o local.
A sinalização
--location
é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. - format é
NEWLINE_DELIMITED_JSON
. - dataset é um conjunto de dados atual.
- table é o nome da tabela em que os dados serão carregados;
- path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis;
- 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.json
e substitui uma tabela denominada mytable
em mydataset
. O esquema é definido por meio da detecção automática de esquema.
bq load \
--autodetect \
--replace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json
O comando a seguir carrega dados de gs://mybucket/mydata.json
e os anexa a uma tabela denominada mytable
em mydataset
. O esquema é definido por um arquivo de esquema JSON, myschema.json
.
bq load \
--noreplace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
./myschema.json
API
Crie um job
load
que aponte para os dados de origem no Cloud Storage.Opcional: especifique o local na propriedade
location
na seçãojobReference
do recurso de 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 aceitos.Defina a propriedade
configuration.load.sourceFormat
comoNEWLINE_DELIMITED_JSON
para especificar o formato dos dados.Especifique a preferência de gravação definindo a propriedade
configuration.load.writeDisposition
comoWRITE_TRUNCATE
ouWRITE_APPEND
.
Go
Antes de testar este exemplo, siga as instruções de configuração do 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 Go.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do 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 do 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
Para substituir as linhas em uma tabela atual, defina a propriedade LoadJobConfig.write_disposition (em inglês) com a string WRITE_TRUNCATE
.
Antes de testar esta amostra, siga as instruções de configuração do 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 Python.
Ruby
Para substituir as linhas de uma tabela atual, defina o parâmetro write
de Table.load_job() (em inglês) como "WRITE_TRUNCATE"
.
Antes de testar esta amostra, siga as instruções de configuração do 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 (em inglês).
Opções do JSON
Para alterar a forma como o BigQuery analisa os dados JSON, especifique outras opções no console, na IU clássica, na CLI, na API ou nas bibliotecas de cliente.
Opção do JSON | Opção do console | Opção da IU clássica | Sinalização da CLI | Propriedade da API BigQuery | Descrição |
---|---|---|---|---|---|
Número de registros corrompidos permitidos | Número de erros permitidos | Número de erros permitidos | --max_bad_records |
maxBadRecords |
(Opcional) O número máximo de registros inválidos que o BigQuery pode ignorar ao executar o job. Se o número de registros inválidos exceder esse valor, um erro "invalid" será retornado no resultado do job. O valor padrão é 0, o que exige que todos os registros sejam válidos. |
Valores desconhecidos | Ignorar valores desconhecidos | Ignorar valores desconhecidos | --ignore_unknown_values |
ignoreUnknownValues |
(Opcional) Indica se o BigQuery permitirá 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 registros inválidos e, se houver muitos registros inválidos, um erro "invalid" será retornado no resultado do job. O valor padrão é "false". A propriedade sourceFormat determina o que o BigQuery trata como outro valor. CSV: colunas à direita. JSON: valores nomeados que não correspondem a nenhum nome de coluna. |