Como carregar dados ORC a partir do Cloud Storage
Nesta página, apresentamos uma visão geral sobre como carregar dados ORC do Cloud Storage no BigQuery.
ORC é um formato de dados de código aberto orientado por colunas que é muito usado no ecossistema Apache Hadoop.
Os dados ORC podem ser carregados pelo Cloud Storage em uma nova tabela ou partição. Também é possível anexá-los a uma tabela ou partição, além de substituir esses itens. Quando os dados são carregados no BigQuery, eles são convertidos no formato de colunas do Capacitor, o formato de armazenamento do BigQuery.
Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que a contém precisa estar na mesma região ou multirregião que o bucket do Cloud Storage.
Para informações sobre como carregar dados ORC de um arquivo local, consulte Como carregar dados no BigQuery de uma fonte de dados local.
Limitações
Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:
- Se o local do conjunto de dados estiver definido como um valor diferente da multirregião
US
, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados. - O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.
- O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.
Antes de começar
Atribua papéis do Identity and Access Management (IAM) que concedem aos usuários as permissões necessárias para executar cada tarefa neste documento e crie um conjunto de dados para armazenamento.
Permissões necessárias
Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.
Permissões para carregar dados no BigQuery
Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(inclui a permissãobigquery.jobs.create
)bigquery.user
(inclui a permissãobigquery.jobs.create
)bigquery.jobUser
(inclui a permissãobigquery.jobs.create
)
Além disso, se você tiver a permissão bigquery.datasets.create
, poderá criar e atualizar
tabelas usando um job de carregamento nos conjuntos de dados que criar.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.
Permissões para carregar dados do Cloud Storage
Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage,
peça ao administrador para conceder a você o
o papel IAM doAdministrador de armazenamento (roles/storage.admin
) no bucket.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.
crie um conjunto de dados
Crie um conjunto de dados do BigQuery para armazenamento.
Esquemas ORC
Quando você carrega arquivos ORC no BigQuery, o esquema da tabela é recuperado automaticamente pelos dados de origem autodescritivos. Quando o BigQuery recupera o esquema dos dados de origem, o último arquivo em ordem alfabética é usado.
Por exemplo, você tem os arquivos ORC a seguir no Cloud Storage:
gs://mybucket/00/ a.orc z.orc gs://mybucket/01/ b.orc
Executar esse comando na ferramenta de linha de comando bq carrega todos os arquivos (como uma
lista separada por vírgulas) e o esquema é derivado de mybucket/01/b.orc
:
bq load \ --source_format=ORC \ dataset.table \ "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
Quando o BigQuery detecta o esquema, alguns tipos de dados ORC são convertidos para os tipos de dados do BigQuery para que sejam compatíveis com a sintaxe do GoogleSQL. Todos os campos do esquema detectado são NULLABLE
. Para mais informações, veja conversões de ORC.
Quando você carrega vários arquivos ORC com esquemas diferentes, campos idênticos (com o mesmo nome e mesmo nível aninhado) especificados em mais de um esquema precisam fazer o mapeamento para o mesmo tipo de dados convertido do BigQuery em cada definição de esquema.
Para fornecer um esquema de tabela para criar tabelas externas, defina a propriedadereferenceFileSchemaUri
na API BigQuery ou o parâmetro --reference_file_schema_uri
na ferramenta de linha de comando bq
como o URL do arquivo de referência.
Por exemplo, --reference_file_schema_uri="gs://mybucket/schema.orc"
.
Compactação ORC
O BigQuery é compatível com os seguintes codecs de compactação para conteúdo de arquivos ORC:
Zlib
Snappy
LZO
LZ4
Os dados em arquivos ORC não permanecem compactados depois de serem enviados ao
BigQuery. O armazenamento de dados é relatado em bytes lógicos ou
físicos, dependendo do
modelo de faturamento do armazenamento do conjunto de dados.
Para ver informações sobre o uso do armazenamento, consulte a
visualização INFORMATION_SCHEMA.TABLE_STORAGE
.
Como carregar dados ORC em uma nova tabela
Para carregar dados ORC em uma nova tabela:
- Use o console do Google Cloud
- use o comando
bq load
da ferramenta de linha de comando bq; - Chame o método da API
jobs.insert
e configure um jobload
. - use as bibliotecas de cliente.
Para carregar dados ORC do Cloud Storage em uma nova tabela do BigQuery, siga as instruções a seguir:
Console
No Console do Google Cloud, acesse a página BigQuery.
- No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
- Na seção Informações do conjunto de dados, clique em Criar tabela.
- No painel Criar tabela, especifique os seguintes detalhes:
- Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de.
Em seguida, faça o seguinte:
- Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
- Em Formato de arquivo, selecione ORC.
- Na seção Destino, especifique os seguintes campos:
- Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
- No campo Tabela, insira o nome da tabela que você quer criar.
- Verifique se o campo Tipo de tabela está definido como Tabela nativa.
- Na seção Esquema, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.
- Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
- Clique em Opções avançadas e faça o seguinte:
- 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.
- Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
- 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.
- Selecione Criar tabela.
SQL
Use a
instrução DDL LOAD DATA
.
O exemplo a seguir carrega um arquivo ORC na nova tabela mytable
:
No Console do Google Cloud, acesse a página BigQuery.
No editor de consultas, digite a seguinte instrução:
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'ORC', uris = ['gs://bucket/path/file.orc']);
Clique em
Executar.
Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.
bq
Use o comando bq load
, especifique ORC como o source_format
e inclua um
URI do Cloud Storage.
É possível incluir apenas um URI, uma lista de URIs separados por vírgulas ou um URI que contenha um caractere curinga.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Estas são outras sinalizações opcionais:
--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
. Não é possível alterar a especificação de particionamento em uma tabela existente.--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 for ativado sem esse valor, será criada uma tabela particionada por tempo de processamento.--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 partição reduz os custos e melhora o desempenho. Para mais informações, acesse 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 tabelas particionadas, consulte:
Para mais informações sobre tabelas em cluster, consulte:
Para mais informações sobre a criptografia de tabelas, consulte:
Para carregar dados ORC no BigQuery, insira o comando a seguir:
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source
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 é
ORC
. - 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.
Exemplos:
O comando a seguir carrega dados de gs://mybucket/mydata.orc
em uma tabela chamada mytable
em mydataset
.
bq load \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
O comando a seguir carrega dados de gs://mybucket/mydata.orc
em uma nova
tabela particionada por tempo de processamento chamada mytable
em mydataset
.
bq load \
--source_format=ORC \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.orc
O comando a seguir carrega dados de gs://mybucket/mydata.orc
em uma tabela particionada chamada mytable
em mydataset
. A tabela é particionada na coluna mytimestamp
.
bq load \
--source_format=ORC \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.orc
O comando a seguir 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.
bq load \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata*.orc
O comando a seguir 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.
bq load --autodetect \
--source_format=ORC \
mydataset.mytable \
"gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
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 "*".Especifique o formato de dados ORC definindo a propriedade
sourceFormat
comoORC
.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
mostra que o job foi concluído com sucesso.- Se a propriedade
status.errorResult
estiver presente, a solicitação falhou e esse objeto incluirá informações que descrevem o que deu errado. 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 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 BigQuery em C#.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Go
Antes de testar esta amostra, 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 em Go.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Java
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 em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
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 em PHP.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
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 em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Ruby
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 em Ruby.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Anexar ou substituir uma tabela com dados ORC
Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.
No console do Google Cloud, use a opção Preferência de gravação para especificar qual ação será executada 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 | flag da ferramenta bq | Propriedade da API BigQuery | Descrição |
---|---|---|---|
Gravar apenas se a tabela estiver vazia | Incompatível | 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 a segurança no nível da linha, além de remover 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:
- Use o console do Google Cloud
- use o comando
bq load
da ferramenta de linha de comando bq; - Chame o método da API
jobs.insert
e configure um jobload
. - Como usar bibliotecas de cliente
Para anexar ou substituir uma tabela com dados ORC:
Console
No Console do Google Cloud, acesse a página BigQuery.
- No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
- Na seção Informações do conjunto de dados, clique em Criar tabela.
- No painel Criar tabela, especifique os seguintes detalhes:
- Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de.
Em seguida, faça o seguinte:
- Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
- Em Formato de arquivo, selecione ORC.
- Na seção Destino, especifique os seguintes campos:
- Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
- No campo Tabela, insira o nome da tabela que você quer criar.
- Verifique se o campo Tipo de tabela está definido como Tabela nativa.
- Na seção Esquema, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.
- Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster. Não é possível anexar ou substituir uma tabela para convertê-la em uma particionada ou em cluster. O console do Cloud não é compatível com anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
- Clique em Opções avançadas e faça o seguinte:
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
- 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.
- Selecione Criar tabela.
SQL
Use a
instrução DDL LOAD DATA
.
O exemplo a seguir anexa um arquivo ORC à tabela mytable
:
No Console do Google Cloud, acesse a página BigQuery.
No editor de consultas, digite a seguinte instrução:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'ORC', uris = ['gs://bucket/path/file.orc']);
Clique em
Executar.
Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.
bq
Digite o comando bq load
com 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. Forneça a sinalização --source_format
e
defina-a como ORC
. Como os esquemas ORC são recuperados automaticamente
dos dados de origem autodescritivos, não é necessário fornecer uma definição
de esquema.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Estas são outras sinalizações opcionais:
--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
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 é
ORC
. - 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.
Exemplos:
O comando a seguir carrega dados de gs://mybucket/mydata.orc
e substitui uma tabela chamada mytable
em mydataset
.
bq load \
--replace \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
O comando a seguir carrega dados de gs://mybucket/mydata.orc
e anexa dados a uma tabela chamada mytable
em mydataset
.
bq load \
--noreplace \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
Para informações sobre como anexar e substituir tabelas particionadas usando a ferramenta de linha de comando bq, consulte: Como anexar e substituir dados de tabelas particionadas.
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
comoORC
.Especifique a preferência de gravação definindo a propriedade
configuration.load.writeDisposition
comoWRITE_TRUNCATE
ouWRITE_APPEND
.
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 BigQuery em C#.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Go
Antes de testar esta amostra, 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 em Go.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Java
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 em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
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 em PHP.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
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 em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Para substituir as linhas em uma tabela existente, defina a propriedade LoadJobConfig.write_disposition como WRITE_TRUNCATE.Ruby
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 em Ruby.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Carregar dados ORC particionados do Hive
O BigQuery é compatível com o carregamento de dados ORC particionados do Hive armazenados no Cloud Storage e preenche as colunas de particionamento do Hive como colunas na tabela gerenciada de destino do BigQuery. Para mais informações, consulte Como carregar dados particionados externamente do Cloud Storage.
Conversões de ORC
O BigQuery converte tipos de dados ORC nos seguintes tipos de dados:
Tipos primitivos
Tipo de dados BigQuery | Notas | |
---|---|---|
boolean | BOOLEAN | |
byte | INTEGER | |
short | INTEGER | |
int | INTEGER | |
long | INTEGER | |
float | FLOAT | |
double | FLOAT | |
string | STRING | somente UTF-8 |
varchar | STRING | somente UTF-8 |
char | STRING | somente UTF-8 |
binary | BYTES | |
date | DATE | Uma tentativa de converter qualquer valor nos dados ORC que seja inferior a -719162 dias ou superior a 2932896 dias retorna um erro invalid date
value . Se isso afetar você, entre em contato com o suporte para que os valores não compatíveis sejam convertidos para o valor mínimo do BigQuery de 0001-01-01 ou para o valor máximo de 9999-12-31 , conforme apropriado. |
timestamp | CARIMBO DE DATA/HORA |
ORC é compatível com a precisão de nanossegundos, mas o BigQuery converte valores de sub-microssegundos para microssegundos durante a leitura dos dados. Uma tentativa de converter qualquer valor nos dados ORC que seja inferior a -719162 dias ou superior a 2932896 dias retorna um erro |
decimal | NUMERIC, BIGNUMERIC ou STRING | Consulte Tipo decimal. |
Tipo decimal
Os tipos lógicos Decimal
podem ser convertidos em tipos NUMERIC
, BIGNUMERIC
ou STRING
. O tipo convertido depende
dos parâmetros de precisão e escalonamento do tipo lógico decimal
e dos
tipos decimais de destino especificados. Especifique o tipo decimal de destino da seguinte forma:
- Para um job de carregamento usando a
API
jobs.insert
, use o campoJobConfigurationLoad.decimalTargetTypes
. - Para um job de carregamento usando o
comando
bq load
na ferramenta de linha de comando bq, use a sinalização--decimal_target_types
. - Para uma consulta em uma tabela com fontes externas,
use o campo
ExternalDataConfiguration.decimalTargetTypes
. - Para uma tabela externa permanente criada com DDL,
use a opção
decimal_target_types
.
Tipos complexos
Tipo de dados BigQuery | Notas | |
---|---|---|
struct | RECORD |
|
map<K,V> | RECORD | Um campo map<K,V> é convertido em um RECORD repetido que contém dois campos: uma chave do mesmo tipo de dados que K e um valor do mesmo tipo de dados que V. Os dois campos são ANULÁVEIS. |
list | campos repetidos | Listas aninhadas e listas de mapas não são aceitas. |
union | RECORD |
|
Nomes de coluna
O nome da coluna pode conter letras (a-z, A-Z), números (0-9) ou sublinhados (_) e precisa começar com uma letra ou sublinhado. Se você usa nomes de coluna flexíveis, o BigQuery aceita iniciar um nome de coluna com um número. Tenha cuidado ao iniciar colunas com um número, já que o uso de nomes de colunas flexíveis com a API BigQuery Storage Read ou a API BigQuery Storage Write requer tratamento especial. Para mais informações sobre o suporte a nomes de colunas flexíveis, consulte nomes de colunas flexíveis.
Os nomes das colunas podem ter no máximo 300 caracteres. Os nomes de colunas não podem usar nenhum dos seguintes prefixos:
_TABLE_
_FILE_
_PARTITION
_ROW_TIMESTAMP
__ROOT__
_COLIDENTIFIER
Não é permitido haver nomes de coluna duplicados, mesmo com diferença de maiúsculas e minúsculas. Por exemplo, uma
coluna chamada Column1
é considerada idêntica a uma coluna chamada column1
. Para
saber mais sobre regras de nomenclatura de coluna, consulte Nomes
de coluna na
referência do GoogleSQL.
Se um nome de tabela (por exemplo, test
) é igual a um de seus nomes de coluna
(por exemplo, test
), a expressão SELECT
interpreta a coluna test
como
um STRUCT
, que contém todas as outras colunas da tabela. Para evitar essa colisão, use
um dos seguintes métodos:
Evite usar o mesmo nome para uma tabela e suas colunas.
Atribua um alias diferente à tabela. Por exemplo, a consulta a seguir atribui um alias de tabela
t
à tabelaproject1.dataset.test
:SELECT test FROM project1.dataset.test AS t;
Inclua o nome da tabela ao fazer referência a uma coluna. Exemplo:
SELECT test.test FROM project1.dataset.test;
Nomes de colunas flexíveis
Agora você tem mais flexibilidade para nomear as colunas, incluindo mais acesso a caracteres em outros idiomas além de inglês, bem como outros símbolos.
Os nomes de colunas flexíveis são compatíveis com os seguintes caracteres:
- Qualquer letra em qualquer idioma, conforme representado pela expressão regular Unicode
\p{L}
. - Qualquer caractere numérico em qualquer idioma, conforme representado pela expressão
regular Unicode
\p{N}
. - Qualquer caractere de pontuação do conector, incluindo sublinhados, conforme representado
pela expressão regular Unicode
\p{Pc}
. - Hífen ou traço, conforme representado pela expressão regular Unicode
\p{Pd}
. - Qualquer marca destinada a acompanhar outro caractere, conforme representado pela expressão regular Unicode
\p{M}
. Por exemplo, acentos, trema ou caixas de delimitação. - Estes caracteres especiais:
- Um "e" comercial (
&
), conforme representado pela expressão regular Unicode\u0026
. - Um sinal de porcentagem (
%
), conforme representado pela expressão regular Unicode\u0025
. - Um sinal de igual (
=
), conforme representado pela expressão regular Unicode\u003D
. - Um sinal de adição (
+
), conforme representado pela expressão regular Unicode\u002B
. - Dois-pontos (
:
), conforme representado pela expressão regular Unicode\u003A
. - Um apóstrofo (
'
), conforme representado pela expressão regular Unicode\u0027
. - Um sinal de menor que (
<
), conforme representado pela expressão regular Unicode\u003C
. - Um sinal de maior que (
>
), conforme representado pela expressão regular Unicode\u003E
. - Um sinal numérico (
#
), conforme representado pela expressão regular Unicode\u0023
. - Uma linha vertical (
|
), conforme representado pela expressão regular Unicode\u007c
. - Espaço em branco.
- Um "e" comercial (
Os nomes de colunas flexíveis não são compatíveis com os seguintes caracteres especiais:
- Um ponto de exclamação (
!
), conforme representado pela expressão regular Unicode\u0021
. - Aspas (
"
), conforme representadas pela expressão regular Unicode\u0022
. - Um cifrão (
$
), conforme representado pela expressão regular Unicode\u0024
. - Um parêntese esquerdo (
(
), conforme representado pela expressão regular Unicode\u0028
. - Um parêntese direito (
)
), conforme representado pela expressão regular Unicode\u0029
. - Um asterisco (
*
), conforme representado pela expressão regular Unicode\u002A
. - Uma vírgula (
,
), conforme representado pela expressão regular Unicode\u002C
. - Um ponto (
.
), conforme representado pela expressão regular Unicode\u002E
. - Uma barra (
/
), conforme representada pela expressão regular Unicode\u002F
. - Ponto e vírgula (
;
), conforme representado pela expressão regular Unicode\u003B
. - Um ponto de interrogação (
?
), conforme representado pela expressão regular Unicode\u003F
. - Um sinal de arroba (
@
), conforme representado pela expressão regular Unicode\u0040
. - Um colchete esquerdo (
[
), conforme representado pela expressão regular Unicode\u005B
. - Uma barra invertida (
\
), conforme representado pela expressão regular Unicode\u005C
. - Um colchete direito (
]
), conforme representado pela expressão regular Unicode\u005D
. - Um acento circunflexo (
^
), conforme representado pela expressão regular Unicode\u005E
. - Um acento grave (
`
), conforme representado pela expressão regular Unicode\u0060
. - Uma chave à esquerda (
{
), conforme representado pela expressão regular Unicode\u007B
. - Uma chave à direita (
}
), conforme representado pela expressão regular Unicode\u007D
. - Um til (
~
) conforme representado pela expressão regular Unicode\u007E
.
Para acessar outras diretrizes, consulte Nomes de colunas.
Os caracteres da coluna expandida são compatíveis com a API BigQuery Storage Read
e a API BigQuery Storage Write. Para usar a lista expandida de caracteres Unicode
com a API BigQuery Storage Read, é necessário definir uma flag. É possível usar o
atributo displayName
para recuperar o nome da coluna. O exemplo a seguir mostra
como definir uma flag com o cliente Python:
from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()
#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options
Para usar a lista expandida de caracteres Unicode com a API BigQuery Storage Write,
forneça o esquema com a notação column_name
, a menos que você esteja usando
o objeto gravador JsonStreamWriter
. O exemplo a seguir mostra como fornecer
o esquema:
syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";
message FlexibleSchema {
optional string item_name_column = 1
[(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
optional string item_description_column = 2
[(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}
Neste exemplo, item_name_column
e item_description_column
são
nomes de marcadores que precisam estar em conformidade
com a convenção de nomenclatura do
buffer de protocolo. Observe que as anotações column_name
sempre têm precedência sobre
nomes de marcadores.
- Por padrão, o carregamento de dados do Parquet não é compatível com nomes de colunas flexíveis. Para se inscrever nesse pré-lançamento, preencha o formulário de inscrição. Depois de se registrar na visualização, todos os nomes de coluna inválidos (por exemplo, ordenação de nomes de colunas) retornam um erro. Para projetos não registrados, a solicitação de carregamento substitui os caracteres inválidos por sublinhados em vez de retornar um erro.
- Por padrão, o carregamento de dados CSV usando detecção automática de esquema não é compatível com nomes de colunas flexíveis. Para se inscrever nesse pré-lançamento, preencha o formulário de inscrição. Depois de se registrar na visualização, todos os nomes de coluna inválidos (por exemplo, ordenação de nomes de colunas) retornam um erro. Para projetos não registrados, a solicitação de carregamento substitui os caracteres inválidos por sublinhados em vez de retornar um erro.
Limitações
Nomes de colunas flexíveis não são compatíveis com tabelas externas.
NULL
valores
Para jobs de carregamento, o BigQuery ignora elementos NULL
para o tipo composto list
, porque senão eles seriam traduzidos como elementos NULL
ARRAY
, que não podem permanecer em uma tabela (consulte Tipos de dados para mais detalhes).
Para mais informações sobre os tipos de dados ORC, consulte a Especificação do Apache ORC™ v1.