Referência da ferramenta de linha de comando bq

Este documento descreve a sintaxe, comandos, sinalizações e argumentos da bq, a ferramenta de linha de comando do BigQuery. Ela é destinada a usuários que já estão familiarizados com o BigQuery, mas querem saber como usar um determinado comando da ferramenta de linha de comando bq. Para informações gerais sobre como usar a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.

Sinopse

A ferramenta de linha de comando bq usa o seguinte formato:

bq COMMAND [FLAGS] [ARGUMENTS]

Algumas sinalizações podem ser usadas com vários comandos da ferramenta de linha de comando bq; : essas sinalizações são descritas na seção Sinalizações globais.

Outras sinalizações são específicas de comandos; só podem ser usadas com um comando específico da ferramenta de linha de comando bq. As sinalizações específicas de comando são descritas nas seções de comando.

Sinalizações booleanas

Algumas sinalizações da ferramenta de linha de comando bq são booleanastrue; defina o valor da sinalização como false ou . A ferramenta de linha de comando bq aceita os seguintes formatos para definir sinalizações booleanas.

Valor	Formato	Exemplo
true	--FLAGNAME=true	--debug_mode=true
true	--FLAGNAME	--debug_mode
false	--FLAGNAME=false	--debug_mode=false
false	--noFLAGNAME	--nodebug_mode

Este documento usa o formato --FLAGNAME=VALUE para sinalizações booleanas.

Todas as sinalizações booleanas são opcionais. Se uma sinalização booleana não estiver presente, o BigQuery usará o valor padrão da sinalização.

Como especificar valores para sinalizações

Quando você especifica um valor para uma sinalização, o sinal de igual (=) é opcional. No exemplo abaixo, as seguintes consultas são equivalentes:

bq ls --format prettyjson myDataset
bq ls --format=prettyjson myDataset

Neste documento, usamos o sinal de igual para maior clareza.

Ajuda on-line

A documentação está disponível na ferramenta de linha de comando bq da seguinte maneira:

Descrição	Formato do comando de ajuda	Exemplo
Lista de todos os comandos com exemplos	bq help	bq help
Descrição das sinalizações globais	bq --help	bq --help
Descrição de um comando específico	bq help COMMAND	bq help mk

Especificação de recursos

O formato para especificar um recurso depende do contexto. Em alguns casos, o separador entre o projeto e o conjunto de dados é dois pontos (:) e, em alguns casos, um ponto (.). A tabela a seguir descreve como especificar uma tabela do BigQuery em contextos diferentes.

Contexto	Formato	Exemplo
Ferramenta de linha de comando bq	PROJECT:DATASET.TABLE	myProject:myDataset.myTable
Consulta do GoogleSQL	PROJECT.DATASET.TABLE	myProject.myDataset.myTable
Consulta do SQL legado	PROJECT:DATASET.TABLE	myProject:myDataset.myTable

Se você não especificar um projeto, o BigQuery usará o projeto atual. Por exemplo, se o projeto atual for myProject, o BigQuery interpretará myDataset.myTable como myProject:myDataset.myTable (ou myProject.myDataset.myTable).

Alguns identificadores de recurso precisam ser citados com acentos graves (`). Se o identificador de recurso começar com uma letra ou um caractere de sublinhado e contiver apenas caracteres que sejam letras, números e sublinhados, não será necessário citá-lo. No entanto, se o identificador de recurso contiver outros tipos de caracteres ou palavras-chave reservadas, você precisará cercar o identificador (ou a parte do identificador com os caracteres especiais ou palavras-chave reservadas) com acentos graves. Para mais informações, consulte Identificadores.

Sinalizações globais

Use as sinalizações a seguir com qualquer comando bq, quando aplicável:

--api=ENDPOINT

Especifica o endpoint da API a ser chamada. O valor padrão é https://www.googleapis.com.

--api_version=VERSION

Especifica a versão da API a ser usada. O padrão é v2.

--apilog=FILE

Registra todas as solicitações e respostas de API no arquivo especificado por FILE. Os valores possíveis são:

• o caminho para um arquivo - registra para o arquivo especificado
• stdout: grava na saída padrão
• stderr: registra para erro padrão
• false: as solicitações e as respostas da API não são registradas (padrão)

--bigqueryrc=PATH

Especifica o caminho para o arquivo de configuração da ferramenta de linha de comando bq. Se você não especificar a sinalização --bigqueryrc, o comando usará a variável de ambiente BIGQUERYRC. Se a variável de ambiente não estiver configurada, $HOME/.bigqueryrc será usado. Se esse arquivo não existir, será usado ~/.bigqueryrc. Para mais informações, consulte Como configurar valores padrão para sinalizações de linha de comando.

--ca_certificates_file=PATH

Especifica a localização do arquivo do Certificate Authority Service (CA, na sigla em inglês).

--dataset_id=DATASET_ID

Especifica o conjunto de dados padrão a ser usado com o comando. Essa sinalização é ignorada quando não aplicável. É possível especificar o argumento DATASET_ID usando o formato PROJECT:DATASET ou DATASET. Se a parte PROJECT estiver ausente, o projeto padrão será usado. É possível substituir a configuração padrão do projeto especificando a sinalização --project_id.

--debug_mode={true|false}

Se definido como true, mostra rastreamentos em exceções do Python. O valor padrão é false.

--disable_ssl_validation={true|false}

Se definido como true, ativa a validação do certificado HTTPS. O valor padrão é false.

--discovery_file=PATH

Especifica o arquivo JSON que será lido para descoberta.

--enable_gdrive={true|false}

Se definido como false, solicita um novo token OAuth sem escopo do Google Drive. O valor padrão é true; solicita um novo token OAuth com escopo do Drive.

--fingerprint_job_id={true|false}

Para usar um ID do job derivado de uma impressão digital da configuração do job, defina como true. Isso evita que o mesmo job seja executado várias vezes acidentalmente. O valor padrão é false.

--format=FORMAT

Especifica o formato da saída do comando. Use um dos seguintes valores:

• pretty: saída de tabela formatada
• sparse: saída de tabela mais simples
• prettyjson: formato JSON fácil de ler
• json: JSON compactado ao máximo
• csv: formato csv com cabeçalho

pretty, sparse e prettyjson foram desenvolvidos para ser legíveis por humanos. json e csv devem ser usados por outro programa. Se none for especificado, o comando não produzirá saída. Se a sinalização --format não estiver presente, um formato de saída apropriado será escolhido com base no comando.

--headless={true|false}

Para executar a sessão bq sem interação do usuário, defina como true. Por exemplo, debug_mode não forçará a entrada no depurador, e a frequência da impressão informativa será reduzida. O valor padrão é false.

--httplib2_debuglevel=DEBUG_LEVEL

Especifica se as informações de depuração HTTP serão exibidas. Se DEBUG_LEVEL for maior que 0, o comando registrará solicitações e respostas do servidor HTTP para stderr, além de mensagens de erro. Se DEBUG_LEVEL não for > 0, ou se a sinalização --httplib2_debuglevel não for usada, apenas mensagens de erro serão fornecidas.

Exemplo:

--httplib2_debuglevel=1

Observação: a depuração de vários níveis não é compatível com essa sinalização, então é possível definir DEBUG_LEVEL como qualquer número positivo.

--job_id=JOB_ID

Especifica um identificador de job para um novo job. Essa sinalização aplica-se apenas aos comandos que criam jobs: cp, extract, load e query. Se você não usar a sinalização --job_id, os comandos gerarão um identificador de job exclusivo. Para mais informações, consulte Como executar jobs de maneira programática.

--job_property=KEY:VALUE

Um par de chave-valor a ser incluído no campo de propriedades da configuração do job. Repita essa sinalização para especificar outras propriedades.

--location=LOCATION

Uma string correspondente ao local da sua região ou multirregião. A sinalização de local é obrigatória nos comandos bq cancel e bq show quando você usa a sinalização --jobs para mostrar informações sobre jobs. Nos comandos a seguir, ela é opcional:

• query
• cp
• load
• extract
• partition
• update
• wait
• mk ao usar as sinalizações --dataset, --reservation, --capacity_commitment ou --reservation_assignment
• ls quando você usa as sinalizações --reservation, --capacity_commitment ou --reservation_assignment

Todos os outros comandos ignoram a sinalização --location.

Observação: a sinalização --location foi introduzida na versão 2.0.29 da bq. Para verificar a versão da ferramenta de linha de comando bq, digite bq version.

--max_rows_per_request=MAX_ROWS

Um número inteiro que especifica o número máximo de linhas a serem retornadas por leitura.

--project_id=PROJECT

Especifica o projeto a ser usado para comandos.

--proxy_address=PROXY

O nome ou endereço IP do host proxy a ser usado para conexão com o Google Cloud.

--proxy_password=PASSWORD

Especifica a senha a ser usada ao autenticar com o host proxy.

--proxy_port=PORT

Especifica o número da porta a ser usado para se conectar ao host proxy.

--proxy_username=USERNAME

Especifica o nome de usuário a ser usado na autenticação com o host de proxy.

--quiet={true|false} ou -q={true|false}

Para suprimir atualizações de status enquanto os jobs estão em execução, defina como true. O valor padrão é false.

--synchronous_mode={true|false} ou -sync={true|false}

Para criar o job e retornar imediatamente, com um status de conclusão bem-sucedido como código de erro, defina como false. Se definido como true, o comando aguardará a conclusão do job antes de retornar e retornará o status de conclusão do job como o código do erro. O valor padrão é true.

--trace=token:TOKEN

Especifica um token de rastreamento a ser incluído nas solicitações da API.

--use_regional_endpoints={true|false}

Em pré-lançamento. Para se conectar a um endpoint regional, defina a sinalização --use_regional_endpoints como true e a sinalização --location como a região a que você quer se conectar. O valor padrão é false.

Sinalizações globais obsoletas

A sinalização global a seguir para especificar sinalizações da ferramenta de linha de comando bq de um arquivo está obsoleta. Para especificar sinalizações de um arquivo, use a sinalização --bigqueryrc.

--flagfile=PATH

Quando essa sinalização é especificada, as definições de sinalização do arquivo fornecido são inseridas na ferramenta de linha de comando bq. O valor padrão é ''. Para mais informações, consulte Como configurar valores padrão para sinalizações de linha de comando.

Comandos

As seções a seguir descrevem os comandos da ferramenta de linha de comando bq, além das sinalizações e argumentos específicos dos comandos.

bq add-iam-policy-binding

Use o comando bq add-iam-policy-binding para recuperar a política do Identity and Access Management (IAM) de uma tabela ou visualização e adicionar uma vinculação à política em uma etapa.

Esse comando é uma alternativa ao processo de três etapas a seguir:

1. Como usar o comando bq get-iam-policy para recuperar o arquivo de política (no formato JSON).
2. Como editar o arquivo de política.
3. Como usar o comando bq set-iam-policy para atualizar a política com uma nova vinculação.

Observação: bq add-iam-policy-binding não é compatível com conjuntos de dados. Para modificar o acesso a um conjunto de dados, consulte Conceder acesso a um conjunto de dados.

Sinopse

bq add-iam-policy-binding [FLAGS] --member=MEMBER_TYPE:MEMBER --role=ROLE
  [--table] RESOURCE

Exemplo

bq add-iam-policy-binding --member=user:[e-mail] \
  --role=roles/bigquery.dataViewer myDataset.myTable

Sinalizações e argumentos

O comando bq add-iam-policy-binding usa as seguintes sinalizações e argumentos:

--member=MEMBER_TYPE:MEMBER

Obrigatório. Use a sinalização --member para especificar a parte do membro da vinculação da política do IAM. A sinalização --member é obrigatória com a sinalização --role. Uma combinação de sinalizações --member e --role é igual a uma vinculação.

O valor MEMBER_TYPE especifica o tipo de membro na vinculação da política do IAM. Use um dos seguintes valores:

• user
• serviceAccount
• group
• domain

O valor MEMBER especifica o endereço de e-mail ou o domínio do membro na vinculação política do IAM.

--role=ROLE

Obrigatório. Especifica a parte do papel da vinculação de política do IAM. A sinalização --role é obrigatória com a sinalização --member. Uma combinação de sinalizações --member e --role é igual a uma vinculação.

--table={true|false}

Para retornar um erro se o argumento RESOURCE não for um identificador de tabela ou visualização, defina a sinalização --table como true. O valor padrão é false. Essa sinalização é compatível com a consistência de outros comandos.

RESOURCE

A tabela ou a visualização com a política que você quer adicionar.

Para mais informações, consulte a referência da política do IAM.

bq cancel

Use o comando bq cancel para cancelar jobs do BigQuery.

Sinopse

bq [--synchronous_mode=false] cancel JOB_ID

Exemplos

bq cancel bqjob_12345

bq --synchronous_mode=false cancel bqjob_12345

Sinalizações e argumentos

O comando bq cancel usa as seguintes sinalizações e argumentos:

--synchronous_mode=false

Se você não quiser aguardar a conclusão do comando bq cancel, defina a sinalização global --synchronous_mode como false. O padrão é true.

JOB_ID

O job que você quer cancelar.

Para mais informações sobre como usar o comando bq cancel, consulte Como gerenciar jobs.

bq cp

Use o comando bq cp para as seguintes tarefas:

• Crie uma cópia de uma tabela, de um clone de tabela ou de um snapshot de tabela.
• Crie um clone da tabela.
• Crie um snapshot da tabela.

Sinopse

bq cp [FLAGS] SOURCE_TABLE DESTINATION_TABLE

Exemplo

bq cp myDataset.myTable myDataset.myTableCopy

Sinalizações e argumentos

O comando bq cp usa as seguintes sinalizações e argumentos:

--append_table={true|false} ou -a={true|false}

Para anexar uma tabela a uma tabela atual, defina como true. O valor padrão é false.

Não é possível usar as configurações de sinalização --append_table=true e --clone=true ao mesmo tempo.

--clone={true|false}

Para criar um clone de tabela, defina como true. A tabela de base pode ser uma tabela padrão, um clone de tabela ou um snapshot de tabela. A tabela de destino é um clone da tabela. O padrão é false. Se --clone=true e --snapshot=true não forem especificados, a tabela de destino será o mesmo tipo da tabela de base.

Não é possível usar as configurações de sinalização --append_table=true e --clone=true ao mesmo tempo.

--destination_kms_key=KEY

Especifica um ID de recurso de chave do Cloud KMS para criptografar os dados da tabela de destino.

Exemplo:

--destination_kms_key=projects/myProject/locations/global/keyRings/myKeyRing/cryptoKeys/myKey

--expiration=SECONDS

O número de segundos até a expiração de um snapshot da tabela. Se não for incluído, a expiração do snapshot da tabela será definida como a expiração padrão do conjunto de dados que contém o novo snapshot da tabela. Use com a sinalização --snapshot.

--force={true|false} ou -f={true|false}

Para substituir a tabela de destino, se houver, sem prompt, defina como true. O valor padrão é false; se a tabela de destino existir, o comando solicitará uma confirmação antes da substituição.

--no_clobber={true|false} ou -n={true|false}

Para proibir a substituição da tabela de destino, se ela existir, defina como true. O valor padrão é false; se a tabela de destino existir, ela será substituída.

--restore={true|false}

A sinalização terá o uso suspenso. Para criar uma tabela gravável em um snapshot de tabela, use os comandos bq cp ou bq cp --clone.

--snapshot={true|false}

Para criar um snapshot da tabela especificada no argumento SOURCE_TABLE, defina como true. A tabela de base pode ser uma tabela padrão, um clone de tabela ou outro snapshot de tabela. O padrão é false. Se --clone=true e --snapshot=true não forem especificados, a tabela de destino será o mesmo tipo da tabela de base. Requer a sinalização --no_clobber.

SOURCE_TABLE

A tabela que você quer copiar.

DESTINATION_TABLE

A tabela para onde você quer copiar.

Para mais informações sobre como usar o comando cp, consulte:

• Copiar uma tabela
• Criar clones de tabelas
• Criar snapshots de tabelas
• Restaurar snapshots da tabela

bq extract

Use o comando bq extract para exportar dados da tabela ao Cloud Storage.

Sinopse

bq extract [FLAGS] RESOURCE DESTINATION

Exemplos

bq extract --compression=GZIP --destination_format=CSV --field_delimiter=tab \
    --print_header=false myDataset.myTable gs://my-bucket/myFile.csv.gzip

bq extract --destination_format=CSV --field_delimiter='|' myDataset.myTable \
  gs://myBucket/myFile.csv

Sinalizações e argumentos

O comando bq extract usa as seguintes sinalizações e argumentos:

--compression=COMPRESSION_TYPE

Especifica o tipo de compactação a ser usado para arquivos exportados. Os valores possíveis são:

• GZIP
• DEFLATE
• SNAPPY
• NONE

O valor padrão é NONE.

Para conferir informações sobre quais formatos são compatíveis com cada tipo de compactação, consulte Exportar formatos e tipos de compactação.

--destination_format=FORMAT

Especifica o formato dos dados exportados. Os valores possíveis são:

• CSV
• NEWLINE_DELIMITED_JSON
• AVRO
• PARQUET

O valor padrão é CSV.

--field_delimiter=DELIMITER

Nas exportações CSV, especifica o caractere que marca o limite entre as colunas no arquivo de saída. O separador pode ser qualquer caractere ISO-8859-1 de um byte. É possível usar \t ou tab para especificar delimitadores de tabulação.

--print_header={true|false}

Para suprimir linhas de cabeçalho de impressão para formatos que tenham cabeçalhos, defina como false. O padrão é true; linhas de cabeçalho estão incluídas.

RESOURCE

A tabela da qual você está exportando.

DESTINATION

O local de armazenamento que recebe os dados exportados.

Para mais informações sobre como usar o comando bq extract, consulte Como exportar dados da tabela.

bq get-iam-policy

Use o comando bq get-iam-policy para recuperar a política do IAM de um recurso e imprima-a no stdout. O recurso pode ser uma tabela ou uma visualização. A política está no formato JSON.

Observação: bq get-iam-policy não é compatível com conjuntos de dados. Para conferir a política do IAM de um conjunto de dados, consulte Consultar a política de acesso de um conjunto de dados.

Sinopse

bq get-iam-policy [FLAGS] RESOURCE

Exemplo

bq get-iam-policy myDataset.myTable

Sinalizações e argumentos

O comando bq get-iam-policy usa as seguintes sinalizações e argumentos:

--table={true|false} ou --t={true|false}

Para retornar um erro se RESOURCE não for um identificador de tabela ou visualização, defina a sinalização --table como true. O valor padrão é false. Essa sinalização é compatível com a consistência de outros comandos.

RESOURCE

A tabela ou visualização da política que você quer receber.

Para mais informações sobre o comando bq get-iam-policy, consulte Controlar o acesso a recursos com o IAM.

bq head

Use o comando bq head para exibir as linhas e colunas especificadas de uma tabela. Por padrão, ele exibe todas as colunas das primeiras 100 linhas.

Sinopse

bq head [FLAGS] [TABLE]

Exemplo

bq head --max_rows=10 --start_row=50 --selected_fields=field1,field3 \
  myDataset.myTable

Sinalizações e argumentos

O comando bq head usa as seguintes sinalizações e argumentos:

--job=JOB or -j=JOB

Para ler os resultados de um job de consulta, especifique essa sinalização com um ID de job válido.

--max_rows=MAX or -n=MAX

Um número inteiro que indica o número máximo de linhas a serem impressas ao mostrar dados da tabela. O valor padrão é 100.

--selected_fields=COLUMN_NAMES or -c=COLUMN_NAMES

Uma lista separada por vírgulas que indica um subconjunto de campos (incluindo campos aninhados e repetidos) para retornar ao mostrar dados da tabela. Se essa sinalização não for especificada, todas as colunas serão retornadas.

--start_row=START_ROW or -s=START_ROW

Um número inteiro que especifica a quantidade de linhas a serem ignoradas antes de mostrar os dados da tabela. O valor padrão é 0; os dados da tabela começam na primeira linha.

--table={true|false} ou -t={true|false}

Para retornar um erro se o argumento do comando não for uma tabela ou visualização, defina como true. O valor padrão é false. Essa sinalização é compatível com a consistência de outros comandos.

TABLE

A tabela cujos dados você quer recuperar.

Para mais informações sobre como usar o comando bq head, consulte Como gerenciar dados de tabela.

bq help

Use o comando bq help para exibir a documentação da ferramenta de linha de comando bq na ferramenta.

Sinopse

bq help [COMMAND]

Sinalizações e argumentos

O comando bq help usa as seguintes sinalizações e argumentos:

COMMAND

Especifica um comando específico da ferramenta de linha de comando bq para receber ajuda on-line.

bq insert

Use o comando bq insert para inserir linhas de dados delimitados por nova linha em formato JSON em uma tabela de um arquivo usando a inserção por streaming. Os tipos de dados são convertidos para corresponder aos tipos de coluna da tabela de destino. Esse comando é usado apenas para testes. Use o método de API insertAll para fazer streaming de dados para o BigQuery.

Sinopse

bq insert [FLAGS] TABLE FILE

Exemplos

bq insert --ignore_unknown_values --template_suffix=_insert myDataset.myTable /tmp/myData.json

echo '{"a":1, "b":2}' | bq insert myDataset.myTable

Sinalizações e argumentos

O comando bq insert usa as seguintes sinalizações e argumentos:

--ignore_unknown_values={true|false} ou -i={true|false}

Quando definido como true, o BigQuery ignora todos os pares de chave-valor que não correspondem ao esquema da tabela e insere a linha com os dados que correspondem ao esquema. Quando definido como false, as linhas com dados que não correspondem ao esquema da tabela não são inseridas. O padrão é false.

--skip_invalid_rows={true|false} ou -s={true|false}

Quando definido como true, o BigQuery tenta inserir qualquer linha válida, mesmo que haja linhas inválidas. Quando definido como false, o comando falhará se houver linhas inválidas. O padrão é false.

--template_suffix=SUFFIX or -x=SUFFIX

Quando especificada, trata a tabela de destino TABLE como um modelo base e insere as linhas em uma tabela de instâncias denominada {destination}{templateSuffix}. O BigQuery cria a tabela de instâncias usando o esquema do modelo base.

TABLE

A tabela em que você quer inserir dados.

FILE

O arquivo que contém os dados que você quer inserir.

Saiba mais sobre como usar o comando bq insert em Como fazer streaming de dados para o BigQuery.

bq load

Use o comando bq load para carregar dados em uma tabela.

Sinopse

bq load [FLAGS] DESTINATION_TABLE SOURCE_DATA [SCHEMA]

Exemplo

bq load myDataset.newTable gs://mybucket/info.csv ./info_schema.json

Sinalizações e argumentos

O comando bq load usa as seguintes sinalizações e argumentos:

--allow_jagged_rows={true|false}

Para permitir a falta de colunas opcionais à direita nos dados CSV, defina como true.

--preserve_ascii_control_characters={true|false}

Para permitir caracteres de controle ASCII incorporados nos dados CSV, defina como true.

--allow_quoted_newlines={true|false}

Para permitir novas linhas entre aspas em dados CSV, defina como true.

--autodetect={true|false}

Para ativar a detecção automática de esquema em dados CSV e JSON, defina como true. O padrão é false. Se --autodetect for false e nenhum esquema for especificado usando a sinalização --schema e a tabela de destino existir, o esquema da tabela de destino será usado.

--clustering_fields=COLUMNS

Uma lista separada por vírgulas de até quatro nomes de colunas que especifica os campos a serem usados para o clustering de tabelas.

--destination_kms_key=KEY

Especifica um ID de recurso de chave do Cloud KMS para criptografar os dados da tabela de destino.

--encoding=ENCODING_TYPE or -E=ENCODING_TYPE

A codificação de caracteres usada nos dados. Use um dos seguintes valores:

• ISO-8859-1 (também conhecido como Latin-1)
• UTF-8

--field_delimiter=DELIMITER or -F=DELIMITER

Especifica o caractere que marca o limite entre colunas nos dados. O delimitador pode ser qualquer caractere ISO-8859-1 de um byte. É possível usar \t ou tab para especificar os delimitadores de guia.

--ignore_unknown_values={true|false}

Quando definido como true, ignora e não carrega linhas de arquivos CSV e JSON com valores de colunas extras que não correspondem ao esquema da tabela. Da mesma forma, para arquivos Avro, Parquet e ORC, os campos no esquema de arquivo que não existem no esquema da tabela são ignorados e não são carregados.

--json_extension=JSON_TYPE

Especifica o tipo de arquivo JSON que será carregado. Aplicável apenas a arquivos JSON. Os valores possíveis são:

• GEOJSON: arquivo GeoJSON delimitado por nova linha.

Para usar essa sinalização, a sinalização --source_format precisa ser definida como NEWLINE_DELIMITED_JSON.

Para mais informações, consulte Como carregar arquivos GeoJSON delimitados por nova linha.

--max_bad_records=MAX

Um número inteiro que especifica o número máximo 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. Essa sinalização aplica-se apenas ao carregamento de dados CSV, JSON e Google Sheets.

--null_marker=STRING

Uma string personalizada opcional que representa um valor NULL nos dados CSV.

--projection_fields=PROPERTY_NAMES

Se você definir --source_format como DATASTORE_BACKUP, essa sinalização indicará quais propriedades da entidade serão carregadas de uma exportação do Datastore. Especifique os nomes das propriedades em uma lista separada por vírgulas. Nomes de propriedades diferenciam maiúsculas e minúsculas e precisam fazer referência às propriedades de nível superior. Também é possível usar essa sinalização com exportações do Firestore.

--quote=CHARACTER

Especifica um caractere de aspas ao redor dos campos nos dados CSV. O argumento CHARACTER pode ser qualquer caractere de um byte. O valor padrão é aspas duplas ("). Para especificar que não há caracteres de aspas, use uma string vazia "".

--replace={true|false}

Para apagar todos os dados e esquemas atuais quando novos dados forem carregados, defina como true. Todas as chaves do Cloud KMS também são removidas, a menos que você especifique a sinalização --destination_kms_key. O valor padrão é false.

Equivalente ao valor WRITE_TRUNCATE para JobConfigurationLoad.writeDisposition.

Observação: é possível usar a TRUNCATE TABLE instrução para remover todas as linhas de uma tabela sem excluir o esquema.

--schema={SCHEMA_FILE|SCHEMA}

Especifica o caminho para um arquivo de esquema JSON local ou uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante. Se você usar um arquivo de esquema, não atribua uma extensão a ele.

Exemplo:

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

Se nenhum esquema for especificado e --autodetect for false, e a tabela de destino existir, o esquema da tabela de destino será usado.

--schema_update_option=OPTION

Ao anexar dados a uma tabela (em um job de carregamento ou consulta) ou ao substituir uma partição de tabela, especifica como atualizar o esquema da tabela de destino. Use um dos seguintes valores:

• ALLOW_FIELD_ADDITION: permite que novos campos sejam adicionados.
• ALLOW_FIELD_RELAXATION: permite o relaxamento de campos REQUIRED para NULLABLE.

Repita essa sinalização para especificar várias opções de atualização de esquema.

--skip_leading_rows=NUMBER_OF_ROWS

Um número inteiro que especifica a quantidade de linhas a ignorar no início do arquivo de origem. O padrão é 0.

--file_set_spec_type=FILE_SET_SPEC_TYPE

Especifica como interpretar URIs de origem. Em pré-lançamento.

• FILE_SYSTEM_MATCH: expande os URIs de origem listando arquivos do armazenamento de objetos. Esse é o comportamento padrão se FileSetSpecType não estiver definido.
• NEW_LINE_DELIMITED_MANIFEST: indica que os URIs fornecidos são arquivos de manifesto delimitados por nova linha, com um URI por linha. URIs curinga não são compatíveis com os arquivos de manifesto.

Por exemplo, se você tiver um URI de origem de "gs://bucket/path/file" e file_set_spec_type for FILE_SYSTEM_MATCH, o arquivo será usado diretamente como um arquivo de dados. Se file_set_spec_type for NEW_LINE_DELIMITED_MANIFEST, cada linha no arquivo será interpretada como um URI que aponta para um arquivo de dados.

--source_format=FORMAT

O formato dos dados de origem. Use um dos seguintes valores:

• CSV
• NEWLINE_DELIMITED_JSON
• AVRO
• DATASTORE_BACKUP (use este valor para o Filestore)
• PARQUET
• ORC

--time_partitioning_expiration=SECONDS

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. Um número negativo indica que não há validade.

--time_partitioning_field=COLUMN_NAME

Especifica o campo que determina como criar uma partição baseada em tempo. Se o particionamento baseado em tempo estiver ativado sem esse valor, a tabela será particionada com base no tempo de carregamento.

--time_partitioning_type=INTERVAL

Ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Use um dos seguintes valores:

• DAY
• HOUR
• MONTH
• YEAR

O tipo de partição padrão para particionamento baseado em tempo é DAY.

--use_avro_logical_types={true|false}

Se a sinalização --source_format estiver definida como AVRO, defina-a como true para converter os tipos lógicos nos tipos correspondentes (como TIMESTAMP), em vez de apenas usar. seus tipos brutos (como INTEGER).

--decimal_target_types=DECIMAL_TYPE

Determina como converter um tipo lógico Decimal. Equivale a JobConfigurationLoad.decimalTargetTypes. Repita essa sinalização para especificar vários tipos de destino.

--parquet_enum_as_string={true|false}

Se a sinalização --source_format estiver definida como PARQUET e você quiser que o BigQuery infira tipos lógicos ENUM do Parquet como valores STRING, defina essa sinalização como true. O padrão é false.

--parquet_enable_list_inference={true|false}

Se a sinalização --source_format estiver definida como PARQUET, essa sinalização indicará se é necessário usar a inferência de esquema para os tipos lógicos LIST do Parquet.

--reference_file_schema_uri=URI

Especifica o caminho para um arquivo de referência com o esquema de tabela esperado para criar tabelas externas. Equivale a ExternalDataConfiguration.referenceFileSchemaUri. Essa sinalização está ativada para os formatos Avro, ORC e PARQUET.

DESTINATION_TABLE

A tabela em que você quer carregar dados.

SOURCE_DATA

O URI do Cloud Storage do arquivo que contém os dados que você quer carregar.

SCHEMA

O esquema da tabela de destino.

Saiba mais sobre como carregar dados do Cloud Storage usando o comando bq load em:

• Como carregar dados Avro
• Como carregar dados CSV
• Como carregar dados JSON
• Como carregar dados ORC
• Como carregar dados Parquet
• Como carregar dados de exportações do Datastore
• Como carregar dados de exportações do Firestore

Para mais informações sobre como carregar dados de uma fonte local usando o comando bq load, consulte:

• Como carregar dados de arquivos locais

bq ls

Use o comando bq ls para listar objetos em uma coleção.

Sinopse

bq ls [FLAGS] [RESOURCE]

Exemplo

bq ls myDataset

Sinalizações e argumentos

O comando bq ls usa as seguintes sinalizações e argumentos:

--all={true|false} ou -a={true|false}

Para mostrar todos os resultados, defina como true. Mostra jobs de todos os usuários ou de todos os conjuntos de dados, incluindo os ocultos. Essa sinalização não é necessária ao listar configurações ou execuções de transferência. O valor padrão é false.

--capacity_commitment={true|false}

Para listar compromissos de capacidade, defina como true e use a sinalização --location para especificar o local. Para mais informações, consulte Ver compromissos adquiridos.

Por exemplo: bq ls --capacity_commitment=true --location='us'

--datasets={true|false} ou -d={true|false}

Para listar conjuntos de dados, defina como true. O valor padrão é false.

--filter="FILTER"

Filtra os recursos listados para corresponder ao argumento FILTER.

Para conjuntos de dados, FILTER consiste em um ou mais triplos separados por espaço no formato labels.KEY:VALUE. Se mais de um triplo for fornecido, o comando retornará apenas os conjuntos de dados correspondentes a todos dos três (ou seja, o comando usa o operador lógico AND, não OR). Se você quiser especificar mais de três vezes, coloque o seguinte valor FILTER com aspas.

• Para filtrar com base nos rótulos do conjunto de dados, use as chaves e os valores aplicados aos conjuntos de dados.

  Exemplo:

  --filter "labels.department:marketing labels.team:sales"
  

Para configurações de transferência, use dataSourceIds como a chave e uma das seguintes fontes de dados como o valor:

• amazon_s3 - Transferência de dados do Amazon S3
• azure_blob_storage: transferência de dados do Armazenamento de Blobs do Azure
• dcm_dt - Transferência de dados do Campaign Manager
• google_cloud_storage - Transferência de dados do Cloud Storage
• cross_region_copy - Cópia do conjunto de dados
• dfp_dt- Transferência de dados do Google Ad Manager
• adwords - Transferência de dados do Google Ads
• google_ads – Transferência de dados do Google Ads (visualização)
• merchant_center - Transferência de dados do Google Merchant Center
• play - Transferência de dados do Google Play
• scheduled_query - Transferência de dados de consultas programadas
• doubleclick_search- Transferência de dados do Search Ads 360
• youtube_channel - Transferência de dados do canal do YouTube
• youtube_content_owner - Transferência de dados do proprietário do conteúdo do YouTube
• redshift - Migração do Amazon Redshift
• on_premises - Migração da Teradata

Exemplo:

   --filter labels.dataSourceIds:dcm_dt
   

Para execuções de transferência, usestates como a chave, e um dos seguintes estados de transferência como o valor: +SUCCEEDED +FAILED +PENDING +RUNNING +CANCELLED

 For example:
 <pre>
 --filter labels.states:FAILED
 </pre>

A sinalização de filtro não é compatível com jobs.

--jobs={true|false} ou -j={true|false}

Para listar jobs, defina como true. O valor padrão é false. Por padrão, o limite é de 100.000 resultados.

--max_creation_time=MAX_CREATION_TIME_MS

Um número inteiro que representa um carimbo de data/hora Era Unix em milissegundos. Quando especificada com --jobs, essa sinalização lista apenas os jobs criados antes do carimbo de data/hora.

--max_results=MAX_RESULTS or -n=MAX_RESULTS

Um número inteiro indicando a quantidade máxima de resultados. O valor padrão é 50, e o valor máximo é 1.000. Se você tiver mais de 1.000 jobs, use a sinalização page_token para listar todos os jobs usando paginação.

--min_creation_time=MIN_CREATION_TIME_MS

Um número inteiro que representa um carimbo de data/hora de época do Unix em milissegundos. Quando especificada com --jobs, essa sinalização lista apenas os jobs criados após o carimbo de data/hora.

--message_type=messageTypes:MESSAGE_TYPE

Para listar mensagens de registro de execução de transferência de um tipo específico, use messageTypes:MESSAGE_TYPE. Os valores possíveis são:

• INFO
• WARNING
• ERROR

--models={true|false} ou -m={true|false}

Para listar modelos do BigQuery ML, defina como true. O valor padrão é false.

--page_token=TOKEN ou -k=TOKEN

Lista itens a partir do token de página especificado.

--projects={true|false} ou -p={true|false}

Para mostrar todos os projetos, defina como true. O valor padrão é false.

--reservation={true|false}

Para listar todas as reservas de um determinado projeto e local, defina como true. O valor padrão é false. Use com as sinalizações --project_id e --location.

Exemplo:

bq ls --reservation=true --project_id=myProject --location=us

--reservation_assignment={true|false}

Para listar todas as atribuições de reserva de um determinado projeto e local, defina como true. O valor padrão é false. Use com as sinalizações --project_id e --location.

--routines={true|false}

Para listar todas as rotinas no conjunto de dados especificado, defina como true. O valor padrão é false. As rotinas incluem funções permanentes definidas pelo usuário, funções de tabela (Visualização) e procedimentos armazenados.

--row_access_policies

Quando especificada, lista todas as políticas de acesso no nível da linha em uma tabela. As políticas de acesso no nível da linha são usadas para a segurança no nível da linha. Você precisa fornecer o nome da tabela no formato dataset.table.

--run_attempt=RUN_ATTEMPT

Use com a sinalização --transfer_run. Para listar todas as tentativas de execução da execução de transferência especificada, defina como RUN_ATTEMPT_UNSPECIFIED. Para listar apenas a última tentativa de execução, defina como LATEST. O padrão é LATEST.

--transfer_config={true|false}

Para listar configurações de transferência no projeto e no local especificados, defina como true. Use com as sinalizações --transfer_location e --project_id. O valor padrão é false.

--transfer_location=LOCATION

Lista as configurações de transferência no local especificado. O local da transferência é definido quando ela é criada.

--transfer_log={true|false}

Use com a sinalização --transfer_run. Para listar mensagens de registro de transferência da execução de transferência especificada, defina como true. O valor padrão é false.

--transfer_run={true|false}

Lista as execuções de transferência para a configuração de transferência especificada.

Exemplo:

bq ls --transfer_run=true projects/myProject/locations/us/transferConfigs/12345

RESOURCE

A coleção cujos objetos você quer listar. O recurso pode ser um conjunto de dados, projeto, reserva ou configuração de transferência.

Para mais informações sobre como usar o comando bq ls, consulte:

• Como gerenciar jobs
• Como listar conjuntos de dados em um projeto
• Como criar e usar tabelas
• Como listar visualizações em um conjunto de dados
• Como trabalhar com transferências
• Como listar snapshots da tabela em um conjunto de dados

bq mk

Use o comando bq mk para criar um recurso do BigQuery.

Sinopse

bq mk TYPE_FLAG [OTHER FLAGS] [ARGS]

Sinalizações e argumentos

O comando bq mk usa uma sinalização de tipo que especifica o tipo de recurso a ser criado e outras sinalizações que dependem do tipo de recurso.

TYPE_FLAG: defina uma das seguintes sinalizações como true. Sua seleção especifica o tipo de recurso que será criado.

• --capacity_commitment: adquirir um compromisso de capacidade.

• --connection: criar uma conexão

• --dataset ou -d: criar um conjunto de dados.

• --materialized_view: criar uma visualização materializada.

• --reservation: criar uma reserva.

• --reservation_assignment: atribui uma pasta, projeto ou organização a uma reserva.

• --table ou -t: criar uma tabela.

• --transfer_config: criar uma configuração de transferência.

• --transfer_run: criar uma execução de transferência para um intervalo de tempo.

• --view: criar uma visualização.

O comando bq mk é compatível com a seguinte sinalização para todos os tipos de recursos:

--force={true|false} ou -f={true|false}

Para ignorar erros se um recurso com o mesmo nome já existir, defina como true. Se o recurso já existir, o código de saída será 0, mas definir essa sinalização como true não fará com que o comando bq mk substitua o recurso. O valor padrão é false.

O comando bq mk aceita sinalizações adicionais, dependendo do tipo de recurso que você está criando, conforme descrito nas seções a seguir.

bq mk --capacity_commitment

Para adquirir um compromisso de capacidade, defina --capacity_commitment como true e use as seguintes sinalizações:

--location=LOCATION

Especifica o local do compromisso.

--plan=PLAN_TYPE

Especifica o tipo de plano de compromisso. Precisa ser um dos valores abaixo.

• ANNUAL
• THREE_YEAR

Os clientes que usam preços fixos legados também podem usar um dos seguintes valores:

• FLEX
• MONTHLY
• ANNUAL

--renewal_plan=RENEWAL_TYPE

Especifica o tipo de plano de renovação. Obrigatório para planos de compromisso ANNUAL ou THREE_YEAR. Precisa ser um dos seguintes:

• ANNUAL
• THREE_YEAR
• NONE

Os clientes que usam preços fixos legados também podem usar um dos seguintes valores:

• FLEX
• MONTHLY
• ANNUAL

--project_id=PROJECT_ID

Especifica o projeto que administra os slots.

--slots=NUMBER_OF_SLOTS

Especifica o número de slots para compra.

--edition=EDITION

A edição associada ao compromisso de capacidade. Deve atender a uma das seguintes condições:

• ENTERPRISE
• ENTERPRISE_PLUS

Para mais informações, consulte Slots de compra.

bq mk --connection

Cria uma conexão. As sinalizações a seguir são compatíveis:

--connection_type=CONNECTION_TYPE

O tipo de conexão (por exemplo, CLOUD_SQL) para conexões do Cloud SQL.

--properties=PROPERTIES

Parâmetros específicos de conexão no formato JSON. É preciso especificar instanceId e database.type

Se você criar uma conexão do Spanner e quiser usar o Data Boost, inclua os pares "useParallelism":true e "useDataBoost":true.

--connection_credential=CONNECTION_CREDENTIAL

As credenciais da conexão no formato JSON. É preciso especificar username e password.

--project_id=PROJECT_ID

Especifica o ID do projeto ao qual a conexão pertence.

--location=LOCATION

Especifica o local em que a conexão será armazenada.

--display_name=DISPLAY_NAME

Especifica um nome opcional fácil de lembrar para a conexão.

--description=DESCRIPTION

Especifica uma descrição opcional da conexão.

--iam_role_id=ROLE_ID

Para o BigQuery Omni na AWS, especifica um papel do IAM que permite acesso ao recurso.

Use o seguinte formato: "arn:aws:iam::AWS_ACCOUNT_ID:role/POLICY_NAME", em que:

• AWS_ACCOUNT_ID é o número do ID do usuário do IAM da AWS da conexão.
• POLICY_NAME é o nome da política.

Exemplo: "arn:aws:iam::0123456789AB:policy/s3-read-role"

--tenant_id=TENANT_ID

Para o BigQuery Omni no Azure, especifica o ID do locatário do diretório do Azure que contém a conta do Azure Storage.

CONNECTION_ID

Especifica um ID de conexão opcional para a conexão. Se um ID de conexão não for fornecido, um ID exclusivo será gerado automaticamente. O ID da conexão pode conter letras, números e sublinhados.

Para mais informações, consulte Como criar conexões.

bq mk --dataset

Cria um conjunto de dados. As sinalizações a seguir são compatíveis:

--default_kms_key=KEY

Especifica o ID de recurso de chave padrão do Cloud KMS para criptografar os dados da tabela em um conjunto de dados, caso nenhuma chave explícita seja fornecida durante a criação ou consulta da tabela.

--default_partition_expiration=SECONDS

Um número inteiro que especifica o prazo de validade padrão, em segundos, para todas as partições em tabelas particionadas recém-criadas em um conjunto de dados. O prazo de validade é definido como a data UTC da partição acrescida do valor de número inteiro. Se essa propriedade for definida, o valor dela modificará a validade da tabela padrão no nível do conjunto de dados, se houver. Se você fornecer a sinalização --time_partitioning_expiration ao criar ou atualizar uma tabela particionada, a validade da partição no nível da tabela terá prioridade sobre a validade da partição padrão no nível do conjunto de dados.

--default_table_expiration=SECONDS

Um número inteiro que especifica o ciclo de vida padrão, em segundos, para tabelas recém-criadas em um conjunto de dados. O prazo de validade é definido como a hora UTC atual mais esse valor.

--description=DESCRIPTION

Especifica a descrição do conjunto de dados.

--external_source=EXTERNAL_SOURCE

Especifica a fonte de dados externa quando você cria um conjunto de dados federado.

--label=KEY:VALUE

Especifica um rótulo para o conjunto de dados. Repita essa sinalização para especificar vários rótulos.

--location=LOCATION ou --data_location=LOCATION

Especifica a localização do conjunto de dados. Prefira a sinalização --location. A sinalização --data_location é legada.

--max_time_travel_hours=HOURS

Especifica a duração em horas da janela de viagem no tempo para o conjunto de dados. O valor --max_time_travel_hours precisa ser um número inteiro expresso em múltiplos de 24 (48, 72, 96, 120, 144 e 168) entre 48 (2 dias) e 168 (7 dias). O padrão será 168 horas se essa sinalização não for especificada.

--storage_billing_model=BILLING_MODEL

Especifica o modelo de faturamento de armazenamento do conjunto de dados. Defina o valor de --storage_billing_model como PHYSICAL para usar bytes físicos ao calcular as cobranças de armazenamento ou como LOGICAL para usar bytes lógicos. O padrão é LOGICAL.

Leva 24 horas para alterar o modelo de faturamento de um conjunto de dados.

Depois de alterar o modelo de faturamento do armazenamento de um conjunto de dados, aguarde 14 dias antes de alterar o modelo de faturamento do armazenamento novamente.

Para mais informações, consulte Como criar conjuntos de dados.

bq mk --materialized_view

Cria uma visualização materializada. As sinalizações a seguir são compatíveis:

--enable_refresh={true|false}

Para desativar a atualização automática de uma visualização materializada, defina como false. O padrão ao criar uma visualização materializada é true.

--refresh_interval_ms=MILLISECONDS

Especifica o número de milissegundos para o intervalo de atualização de uma visualização materializada. Se essa sinalização não for especificada, o intervalo de atualização padrão para uma visualização materializada com atualização ativada será de 1.800.000 milissegundos, ou seja, 30 minutos.

Para mais informações, consulte Como criar e usar visualizações materializadas.

bq mk --reservation

Cria uma reserva com slots dedicados. As sinalizações a seguir são compatíveis:

--target_job_concurrency=CONCURRENCY

Especifica o número desejado de consultas executadas simultaneamente. O valor padrão é 0, o que significa que a simultaneidade é calculada automaticamente com base no tamanho da reserva. Para mais informações, consulte Usar filas de consultas.

--ignore_idle_slots={true|false}

Para restringir os jobs em execução nesta reserva a fim de usar somente slots alocados para a reserva, defina como true. O valor padrão é false; jobs nesta reserva podem usar slots inativos de outras reservas ou slots que não são alocados para nenhuma reserva. Para mais informações, consulte Slots inativos.

--location=LOCATION

Especifica a localização da reserva.

--project_id=PROJECT_ID

Especifica o projeto que é proprietário da reserva.

--slots=NUMBER_OF_SLOTS

Especifica o número de slots a serem alocados para esta reserva.

--edition=EDITION

A edição associada ao compromisso de capacidade. Deve atender a uma das seguintes condições:

• STANDARD
• ENTERPRISE
• ENTERPRISE_PLUS

--autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS

O número de slots de escalonamento automático atribuídos à reserva. Disponível apenas com a sinalização --edition.

Para mais informações, consulte Criar uma reserva com slots dedicados.

bq mk --reservation_assignment

Atribui um projeto, uma pasta ou uma organização a uma reserva. As sinalizações a seguir são compatíveis:

--assignee_id=ASSIGNEE_ID

Especifica o ID da pasta, organização ou projeto.

--assignee_type=ASSIGNEE_TYPE

Especifica o tipo de entidade a ser atribuído à reserva. Uma das seguintes opções:

• FOLDER
• ORGANIZATION
• PROJECT

--job_type=JOB_TYPE

Especifica o tipo de job a ser atribuído à reserva. Uma das seguintes opções:

• QUERY
• PIPELINE
• ML_EXTERNAL
• BACKGROUND

--location=LOCATION

Especifica a localização da reserva.

--project_id=PROJECT_ID

Especifica o projeto que é proprietário da reserva.

--reservation_id=RESERVATION_ID

Especifica o ID da reserva.

Para mais informações, consulte Trabalhar com atribuições de reserva.

bq mk --table

Cria uma tabela. As sinalizações a seguir são compatíveis:

--add_tags=TAGS

Especifica as tags que você está anexando à nova tabela, separadas por vírgulas, por exemplo, 556741164180/env:prod,myProject/department:sales. Cada tag precisa ter o nome da chave com namespace e o nome curto do valor.

--clustering_fields=COLUMNS

Uma lista separada por vírgulas de até quatro nomes de colunas que especifica os campos a serem usados para o clustering de tabelas. Se especificada com particionamento, a tabela será particionada e, em seguida, cada partição será agrupada usando as colunas fornecidas.

--description=DESCRIPTION

Especifica a descrição da tabela.

--destination_kms_key=KEY

Especifica um ID de recurso de chave do Cloud KMS para criptografar os dados da tabela de destino.

--expiration=SECONDS

Especifica a vida útil da tabela. Se você não especificar a flag --expiration, o BigQuery criará a tabela com a vida útil da tabela padrão do conjunto de dados, ou a tabela não vencerá.

--external_table_definition=STRING

Especifica uma definição de tabela para criar uma tabela externa.

Para tabelas externas do Cloud Storage e do Google Drive:

--external_table_definition={PATH_TO_FILE|DEFINITION}

O valor pode ser um caminho para um arquivo que contém uma definição de tabela (PATH_TO_FILE) ou uma definição de tabela inline (DEFINITION).

• O formato do campo DEFINITION é SCHEMA@FORMAT=URI.

• O formato do valor SCHEMA é uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE, e assim por diante. É possível omitir o valor SCHEMA se o formato de dados for autodescritivo (como Avro) ou se você estiver usando a detecção automática de esquema.

• O valor FORMAT especifica o formato de dados, que pode ser uma das seguintes opções:

  • AVRO
  • CSV
  • DATASTORE_BACKUP (use este valor para o Filestore)
  • ICEBERG
  • NEWLINE_DELIMITED_JSON
  • ORC
  • PARQUET

Se você especificar um arquivo de definição de tabela, não atribua uma extensão a ele.

Exemplo:

--external_table_definition=/tmp/tabledef

--external_table_definition=Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

Para tabelas externas do Bigtable e tabelas do BigLake baseadas na AWS e no Azure:

--external_table_definition=PATH_TO_FILE

O valor precisa ser um caminho para um arquivo que contenha uma definição de tabela.

Para tabelas do BigLake baseadas no Cloud Storage:

--external_table_definition=FORMAT=[e-mail]_NAME :

• O valor FORMAT especifica o formato de dados, que pode ser uma das seguintes opções:

  • AVRO
  • CSV
  • NEWLINE_DELIMITED_JSON
  • ICEBERG
  • ORC
  • PARQUET

• BUCKET_PATH é o caminho para um ou mais arquivos no Cloud Storage que contêm os dados da tabela do BigLake. É possível especificar BUCKET_PATH nos seguintes formatos:

  • Para um único arquivo: gs://bucket_name/[folder_name/]file_name.
  • Para vários arquivos em um único bucket: gs://bucket_name/[folder_name/]*.

  • Para vários arquivos em vários buckets: gs://mybucket1/*,gs://mybucket2/folder5/*.

    Importante: se você especificar mais de um arquivo, todos eles precisarão ter esquemas compatíveis.

    É possível usar caracteres curinga para limitar os arquivos incluídos na tabela do BigLake. Por exemplo, se o bucket contiver vários tipos de dados, pode ser que a tabela use apenas arquivos PARQUET especificando gs://bucket_name/*.parquet. Para mais informações sobre o uso de caracteres curinga, consulte Caracteres curinga de URI.

• O valor REGION especifica a região ou multirregião que contém a conexão.

• O valor CONNECTION_NAME especifica o nome da conexão do recurso de nuvem a ser usado com a tabela externa. A conexão determina qual conta de serviço é usada para ler dados a partir do Cloud Storage.

Para tabelas de objeto:

--external_table_definition=[e-mail]_NAME :

• BUCKET_PATH é o caminho para o bucket do Cloud Storage que contém os objetos representados pela tabela de objetos, no formato gs://bucket_name/[folder_name/]*.É possível especificar vários buckets fornecendo vários caminhos, por exemplo, gs://mybucket1/*,gs://mybucket2/folder5/*.

  É possível usar caracteres curinga para limitar os objetos na tabela. Por exemplo, se o bucket contiver vários tipos de dados não estruturados, você poderia criar a tabela de objetos usando apenas objetos PDF especificando gs://bucket_name/*.pdf. Para mais informações sobre o uso de caracteres curinga, consulte Caracteres curinga de URI.

• O valor REGION especifica a região ou multirregião que contém a conexão.

• O valor CONNECTION_NAME especifica o nome da conexão do recurso de nuvem a ser usado com a tabela externa. A conexão determina qual conta de serviço é usada para ler dados a partir do Cloud Storage.

--file_set_spec_type=FILE_SET_SPEC_TYPE

Especifica como interpretar URIs de origem. Em pré-lançamento.

• FILE_SYSTEM_MATCH: expande os URIs de origem listando arquivos do armazenamento de objetos. Esse é o comportamento padrão se FileSetSpecType não estiver definido.
• NEW_LINE_DELIMITED_MANIFEST: indica que os URIs fornecidos são arquivos de manifesto delimitados por nova linha, com um URI por linha. URIs curinga não são compatíveis com os arquivos de manifesto.

Por exemplo, se você tiver um URI de origem de "gs://bucket/path/file" e file_set_spec_type for FILE_SYSTEM_MATCH, o arquivo será usado diretamente como um arquivo de dados. Se file_set_spec_type for NEW_LINE_DELIMITED_MANIFEST, cada linha no arquivo será interpretada como um URI que aponta para um arquivo de dados.

--reference_file_schema_uri=URI

Especifica o caminho para um arquivo de referência com o esquema de tabela esperado para criar tabelas externas. Equivale a ExternalDataConfiguration.referenceFileSchemaUri. Essa sinalização está ativada para os formatos Avro, ORC e PARQUET.

--label=KEY:VALUE

Especifica um rótulo para a tabela. Repita essa sinalização para especificar vários rótulos.

--max_staleness=INTERVAL

Especifica se os metadados em cache são usados pelas operações na tabela e quando eles precisam ser atualizados para que a operação possa usá-los.

Aplicável a tabelas do BigLake e tabelas de objetos.

Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de inatividade de quatro horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação retornará aos metadados do Cloud Storage.

--object_metadata=STRING

Defina o valor dessa sinalização como SIMPLE ao criar uma tabela de objetos.

Obrigatório apenas ao criar uma tabela de objetos.

--range_partitioning=COLUMN_NAME,START,END,INTERVAL

Especifica opções para uma partição de intervalo de números inteiros, da seguinte maneira:

• column_name é a coluna usada para criar as partições por intervalo de números inteiros;
• start é o início do particionamento por intervalo, inclusivo;
• end é o fim do particionamento por intervalo, exclusivo;
• interval é a largura de cada intervalo dentro da partição.

Exemplo:

--range_partitioning=customer_id,0,10000,100

--require_partition_filter={true|false}

Para exigir um filtro de partição para consultas na tabela fornecida, defina como true. Essa sinalização só se aplica a tabelas particionadas. O valor padrão é false.

--schema={SCHEMA_FILE|SCHEMA}

Especifica o caminho para um arquivo de esquema JSON local ou uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante. Se você usar um arquivo de esquema, não atribua uma extensão a ele.

Exemplos:

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

--time_partitioning_expiration=SECONDS

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. Um número negativo indica que não há validade.

--time_partitioning_field=COLUMN_NAME

Especifica o campo usado para determinar como criar uma partição baseada em tempo. Se o particionamento baseado em tempo estiver ativado sem esse valor, a tabela será particionada com base no tempo de carregamento.

--time_partitioning_type=INTERVAL

Ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Use um dos seguintes valores:

• DAY
• HOUR
• MONTH
• YEAR

--use_avro_logical_types={true|false}

Se a parte FORMAT da sinalização --external_table_definition estiver definida como AVRO, essa sinalização especificará se os tipos lógicos serão convertidos nos tipos correspondentes (como TIMESTAMP) em vez de usar apenas os tipos brutos (como INTEGER).

--parquet_enable_list_inference={true|false}

Se a parte FORMAT da sinalização --external_table_definition estiver definida como PARQUET, essa sinalização especificará se é necessário usar inferência de esquema nos tipos lógicos Parquet LIST.

--parquet_enum_as_string={true|false}

Se a parte FORMAT da sinalização --external_table_definition estiver definida como PARQUET, essa sinalização especificará se tipos lógicos Parquet ENUM serão inferidos como valores STRING.

Para mais informações, consulte Como criar e usar tabelas.

bq mk --transfer_config

Cria uma configuração de transferência. As sinalizações a seguir são compatíveis:

--data_source=DATA_SOURCE

Especifica a fonte de dados. Obrigatório ao criar uma configuração de transferência. Use um dos seguintes valores:

• amazon_s3 - Transferência de dados do Amazon S3
• azure_blob_storage: transferência de dados do Armazenamento de Blobs do Azure
• dcm_dt - Transferência de dados do Campaign Manager
• google_cloud_storage - Transferência de dados do Cloud Storage
• cross_region_copy - Cópia do conjunto de dados
• dfp_dt- Transferência de dados do Google Ad Manager
• adwords - Transferência de dados do Google Ads
• google_ads – Transferência de dados do Google Ads (visualização)
• merchant_center - Transferência de dados do Google Merchant Center
• play - Transferência de dados do Google Play
• scheduled_query - Transferência de dados de consultas programadas
• doubleclick_search- Transferência de dados do Search Ads 360
• youtube_channel - Transferência de dados do canal do YouTube
• youtube_content_owner - Transferência de dados do proprietário do conteúdo do YouTube
• redshift - Migração do Amazon Redshift
• on_premises - Migração da Teradata

Observação: os valores redshift e on_premises são para migrações de dados. Antes de usar o comando bq mk --transfer_config com esses valores, consulte a documentação vinculada da lista anterior.

--display_name=DISPLAY_NAME

Especifica o nome de exibição da configuração de transferência.

--params={"PARAMETER":"VALUE"} ou -p={"PARAMETER":"VALUE"}

Especifica os parâmetros da configuração de transferência no formato JSON. Os parâmetros variam de acordo com a fonte de dados.

--refresh_window_days=DAYS

Um número inteiro que especifica a janela de atualização para uma configuração de transferência em dias. O valor padrão é 0.

--service_account_name=SERVICE_ACCOUNT

Especifica uma conta de serviço a ser usada como a credencial para a configuração de transferência.

--target_dataset=DATASET

Especifica o conjunto de dados de destino na configuração da transferência.

--table_filter=TABLES

Usado apenas com a fonte de dados google_ads. O parâmetro TABLES é uma lista separada por vírgulas de tabelas a serem incluídas na transferência. Para excluir uma tabela, use um hífen (-) antes dela. O valor padrão inclui todas as tabelas na transferência.

Para informações sobre como usar o comando bq mk com o serviço de transferência de dados do BigQuery, consulte:

• Como configurar uma transferência do Amazon S3
• Configurar uma transferência do Campaign Manager
• Configurar uma transferência do Cloud Storage
• Configurar uma transferência do Google Ad Manager
• Configurar uma transferência do Google Ads
• Como configurar uma transferência do Google Merchant Center (Beta)
• Configurar uma transferência do Google Play
• Configurar uma transferência do Search Ads 360 (Beta)
• Configurar uma transferência de canal do YouTube
• Configurar uma transferência do proprietário do conteúdo do YouTube
• Migrar dados do Amazon Redshift
• Migrar dados do Teradata

bq mk --transfer_run

Cria uma transferência de dados no horário ou intervalo de tempo especificado usando a configuração de transferência de dados especificada.

Sinopse

bq mk --transfer_run [--run_time=RUN_TIME | --start_time=START_TIME --end_time=END_TIME] CONFIG

As sinalizações a seguir são compatíveis:

--run_time=RUN_TIME

Um carimbo de data/hora que especifica o horário para programar a execução da transferência de dados.

--start_time=START_TIME

Um carimbo de data/hora que especifica o horário de início para um intervalo de execuções de transferência.

--end_time=END_TIME

Um carimbo de data/hora que especifica o horário de término para um intervalo de execuções de transferência.

O formato dos carimbos de data/hora é RFC3339 UTC "Zulu".

O argumento CONFIG especifica uma configuração de transferência de dados preexistente.

Exemplos

bq mk --transfer_run \
      --run_time=2021-01-20T17:00:00.00Z \
      projects/p/locations/l/transferConfigs/c

bq mk --transfer_run \
      --start_time=2020-12-19T16:39:57-08:00 \
      --end_time=2020-12-19T20:39:57-08:00 \
      projects/p/locations/l/transferConfigs/c

bq mk --view

Cria uma visualização. As sinalizações a seguir são compatíveis:

--description=DESCRIPTION

Especifica a descrição da visualização.

--expiration=SECONDS

Especifica a vida útil da visualização. Se SECONDS for 0, a visualização não expirará. Se você não especificar a sinalização --expiration, o BigQuery criará a visualização com o ciclo de vida padrão da tabela do conjunto de dados.

--label=KEY:VALUE

Especifica um rótulo para a visualização. Repita essa sinalização para especificar vários rótulos.

--use_legacy_sql={true|false}

Defina como false para usar uma consulta do GoogleSQL para criar uma visualização. O valor padrão é true (usa SQL legado).

--view_udf_resource=FILE

O URI do Cloud Storage ou o caminho para um arquivo de código local que é carregado e avaliado imediatamente como um recurso de função definido pelo usuário usado pela consulta SQL de uma visualização. Repita a sinalização para especificar vários arquivos.

Para mais informações, consulte Como criar visualizações.

bq mkdef

Use o comando bq mkdef para criar uma definição de tabela no formato JSON para dados armazenados no Cloud Storage ou no Google Drive.

Sinopse

bq mkdef [FLAGS] URI [ > FILE ]

Sinalizações e argumentos

O comando bq mkdef usa as seguintes sinalizações e argumentos:

--autodetect={true|false}

Especifica se quer usar a detecção automática de esquema para dados CSV e JSON. O padrão é false.

--connection_id=CONNECTION_ID

O ID de um recurso de conexão para usar na autenticação.

--hive_partitioning_mode

Especifica como determinar o esquema de particionamento quando o BigQuery lê dados. Estes são os modos compatíveis:

• AUTO: inferir automaticamente nomes e tipos de chaves de partição.
• STRINGS: inferir automaticamente nomes de chave de partição. Todos os tipos são tratados como strings.
• CUSTOM: especifica o esquema de particionamento no prefixo do URI de origem.

O valor padrão é AUTO.

--hive_partitioning_source_uri_prefix

Especifica o prefixo comum para os URIs de origem. O valor de prefixo comum é a parte do URI que precede imediatamente a codificação da chave de partição. Se você especificou CUSTOM para o modo, também precisa identificar o esquema de particionamento.

Por exemplo, considere os arquivos com a seguinte estrutura:

• gs://bucket/path_to_table/dt=2019-06-01/country=USA/id=7/file.avro
• gs://bucket/path_to_table/dt=2019-05-31/country=CA/id=3/file.avro

Se você usar os modos AUTO ou STRINGS, os seguintes valores serão aceitáveis:

• gs://bucket/path_to_table
• gs://bucket/path_to_table/

Se você usar o modo CUSTOM, os seguintes valores serão aceitáveis:

• gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:INTEGER}
• gs://bucket/path_to_table/{dt:STRING}/{country:STRING}/{id:INTEGER}
• gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:STRING}

Para mais informações sobre como usar o comando bq mkdef, consulte Como criar um arquivo de definição de tabela para uma fonte de dados externa.

--ignore_unknown_values={true|false} ou -i={true|false}

Especifica se é necessário ignorar quaisquer valores em uma linha que não estejam presentes no esquema. O padrão é false.

--metadata_cache_mode=STRING

Especifica se o cache de metadados da tabela é atualizado de forma automática ou manual.

Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

Será necessário configurar a sinalização --metadata_cache_mode se você definir a sinalização --max_staleness com o comando bq mk.

--parquet_enable_list_inference={true|false}

Se source_format estiver definido como PARQUET, essa sinalização especificará se é necessário usar a inferência de esquema para os tipos lógicos LIST do Parquet. O padrão é false.

--parquet_enum_as_string={true|false}

Se source_format estiver definido como PARQUET, essa sinalização especificará se os tipos lógicos ENUM do Parquet serão inferidos como valores STRING. O padrão é false.

--file_set_spec_type=FILE_SET_SPEC_TYPE

Especifica como interpretar URIs de origem. Em pré-lançamento.

• FILE_SYSTEM_MATCH: expande os URIs de origem listando arquivos do armazenamento de objetos. Esse é o comportamento padrão se FileSetSpecType não estiver definido.
• NEW_LINE_DELIMITED_MANIFEST: indica que os URIs fornecidos são arquivos de manifesto delimitados por nova linha, com um URI por linha. URIs curinga não são compatíveis com os arquivos de manifesto.

Por exemplo, se você tiver um URI de origem de "gs://bucket/path/file" e file_set_spec_type for FILE_SYSTEM_MATCH, o arquivo será usado diretamente como um arquivo de dados. Se file_set_spec_type for NEW_LINE_DELIMITED_MANIFEST, cada linha no arquivo será interpretada como um URI que aponta para um arquivo de dados.

--source_format=FORMAT

Especifica formato dos dados de origem. Use um dos seguintes valores:

• AVRO
• CSV
• DATASTORE_BACKUP (use este valor para o Filestore)
• GOOGLE_SHEETS
• NEWLINE_DELIMITED_JSON
• ORC
• PARQUET

O valor padrão é CSV.

--use_avro_logical_types={true|false}

Se a sinalização --source_format estiver definida como AVRO, ela especificará se é necessário converter os tipos lógicos nos tipos correspondentes (como TIMESTAMP) em vez de apenas usar os tipos brutos (como INTEGER). O padrão é false.

bq partition

Use o comando bq partition para converter um grupo de tabelas com sufixos de unidade de tempo, como tabelas que terminam em YYYYMMDD para particionamento de data, em tabelas particionadas.

Sinopse

bq partition [FLAGS] SOURCE_TABLE_BASE_NAME PARTITION_TABLE

Sinalizações e argumentos

O comando bq partition usa as seguintes sinalizações e argumentos:

--no_clobber={true|false} ou -n={true|false}

Para proibir a substituição de uma partição atual, defina como true. O valor padrão é false; se a partição existir, ela será substituída.

--time_partitioning_expiration=SECONDS

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. Um número negativo indica que não há validade.

--time_partitioning_type=INTERVAL

Especifica o tipo de partição. A tabela a seguir fornece os valores possíveis para a sinalização INTERVAL e o formato de sufixo de unidade de tempo esperado para cada um:

INTERVAL	Sufixo
HOUR	YYYYMMDDHH
DAY	YYYYMMDD
MONTH	YYYYMM
YEAR	YYYY

SOURCE_TABLE_BASE_NAME

O nome base do grupo de tabelas com sufixos de unidade de tempo.

PARTITION_TABLE

O nome da tabela particionada de destino.

Para mais informações sobre como usar o comando bq partition, consulte Como converter tabelas fragmentadas por data em tabelas particionadas por tempo de processamento.

bq query

Use o comando bq query para criar um job de consulta que execute a consulta SQL especificada.

Sinopse

bq query [FLAGS] 'QUERY'

Sinalizações e argumentos

O comando bq query usa as seguintes sinalizações e argumentos:

--allow_large_results={true|false}

Para ativar tamanhos de tabela de destino grandes para consultas SQL legadas, defina como true. O valor padrão é false.

--append_table={true|false}

Para anexar dados a uma tabela de destino, defina como true. O valor padrão é false.

--batch={true|false}

Para executar a consulta no modo em lote, defina como true. O valor padrão é false.

--clustering_fields=COLUMNS

Uma lista separada por vírgulas de até quatro nomes de colunas que especifica os campos a serem usados para armazenar em cluster a tabela de destino em uma consulta. Se especificada com particionamento, a tabela será particionada e, em seguida, cada partição será agrupada usando as colunas fornecidas.

--destination_kms_key=KEY

Especifica um ID de recurso de chave do Cloud KMS para criptografar os dados da tabela de destino.

--destination_schema={PATH_TO_FILE|SCHEMA}

O caminho para um arquivo de esquema JSON local ou uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante.

As alterações no esquema ocorrem em uma operação separada da execução da consulta. Se você gravar os resultados da consulta em uma tabela especificando a sinalização --destination_table e a consulta gerar uma exceção posteriormente, é possível que todas as alterações de esquema sejam ignoradas. Se isso ocorrer, verifique o esquema da tabela de destino e atualize-o manualmente, se necessário.

--destination_table=TABLE

Quando especificada, os resultados da consulta são salvos em TABLE. Especifique TABLE no seguinte formato: PROJECT:DATASET.TABLE Se PROJECT não for especificado, o projeto atual será considerado. Se a sinalização --destination_table não for especificada, os resultados da consulta serão salvos em uma tabela temporária.

Exemplos:

--destination_table myProject:myDataset.myTable

--destination_table myDataset.myTable

--dry_run={true|false}

Quando especificada, a consulta é validada, mas não executada.

--external_table_definition={TABLE::PATH_TO_FILE|TABLE::DEFINITION}

Especifica o nome da tabela e a definição da tabela para uma consulta de tabela externa. A definição da tabela pode ser um caminho para um arquivo de esquema JSON local ou uma definição de tabela in-line. O formato para fornecer a definição de tabela in-line é SCHEMA@SOURCE_FORMAT=CLOUD_STORAGE_URI. O formato do valor SCHEMA é uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante. Se você usa um arquivo de definição de tabela, não atribua uma extensão a ele.

Exemplo:

--external_table_definition=myTable::/tmp/tabledef

--external_table_definition=myTable::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

Repita essa sinalização para consultar várias tabelas.

--flatten_results={true|false}

Para proibir o nivelamento de campos aninhados e repetidos nos resultados de consultas SQL legadas, defina como false. O valor padrão é true.

--label=KEY:VALUE

Especifica um rótulo para o job de consulta. Repita essa sinalização para especificar vários rótulos.

--max_rows=MAX_ROWS ou -n=MAX_ROWS

Um número inteiro que especifica o número de linhas a retornar nos resultados da consulta. O valor padrão é 100.

--maximum_bytes_billed=MAX_BYTES

Um número inteiro que limita os bytes faturados pela consulta. Se a consulta ultrapassar o limite, ela falhará (sem gerar cobranças). Se essa sinalização não for especificada, os bytes faturados serão definidos como o padrão do projeto.

--max_statement_results=VALUE

Um número inteiro que especifica o número máximo de instruções de script exibidas para os resultados da consulta. O valor padrão é 100.

--min_completion_ratio=RATIO

[Experimental] Um número entre 0 e 1 que especifica a fração mínima de dados que precisa ser verificada antes que uma consulta seja retornada. Se a sinalização não for especificada, o valor de servidor padrão 1.0 será usado.

--parameter={PATH_TO_FILE|PARAMETER}

Um arquivo JSON contendo uma lista de parâmetros de consulta ou um parâmetro de consulta no formulário NAME:TYPE:VALUE. Um nome vazio gera um parâmetro de posição. Se TYPE for omitido, o tipo STRING será usado. NULL especifica um valor nulo. Repita essa sinalização para especificar vários parâmetros.

Exemplo:

--parameter=/tmp/queryParams

--parameter=Name::Oscar

--parameter=Count:INTEGER:42

--range_partitioning=COLUMN_NAME,START,END,INTERVAL

Use com a sinalização --destination_table. Especifica opções para particionamento por intervalo de números inteiros na tabela de destino. O valor é uma lista separada por vírgulas no formato column_name,start,end,interval, em que:

• column_name é a coluna usada para criar as partições por intervalo de números inteiros;
• start é o início do particionamento por intervalo, inclusivo;
• end é o fim do particionamento por intervalo, exclusivo;
• interval é a largura de cada intervalo dentro da partição.

Exemplo:

--range_partitioning=customer_id,0,10000,100

--replace={true|false}

Para substituir a tabela de destino pelos resultados da consulta, defina como true. Todos os dados e esquemas atuais são apagados. Todas as chaves do Cloud KMS também são removidas, a menos que você especifique a sinalização --destination_kms_key. O valor padrão é false.

Observação: para remover todas as linhas de uma tabela sem excluir o esquema, use a instrução TRUNCATE TABLE.

--require_cache={true|false}

Se especificada, executa a consulta apenas se os resultados puderem ser recuperados do cache.

--require_partition_filter={true|false}

Se especificada, requer um filtro de partição para consultas na tabela fornecida. Essa sinalização só pode ser usada com uma tabela particionada.

--rpc={true|false}

Para usar a API de consulta no estilo RPC, em vez do método jobs.insert da API REST, defina como true. O valor padrão é false.

--schedule="SCHEDULE"

Transforma a consulta em uma programada recorrente. É necessário definir uma frequência de execução da consulta.

Exemplos:

--schedule="every 24 hours"

--schedule="every 3 hours"

Para conferir uma descrição da sintaxe, consulte Como formatar a programação.

--schema_update_option=OPTION

Ao anexar dados a uma tabela (em um job de carregamento ou consulta) ou ao substituir uma partição de tabela, especifica como atualizar o esquema da tabela de destino. Use um dos seguintes valores:

• ALLOW_FIELD_ADDITION: permite que novos campos sejam adicionados.
• ALLOW_FIELD_RELAXATION: permite o relaxamento de campos REQUIRED para NULLABLE.

Repita essa sinalização para especificar várias opções de atualização de esquema.

--start_row=ROW_NUMBER ou -s=ROW_NUMBER

Um número inteiro que especifica a primeira linha a retornar no resultado da consulta. O valor padrão é 0.

--target_dataset=DATASET

Quando especificada com --schedule, atualiza o conjunto de dados de destino para uma consulta programada. A consulta deve ser DDL ou DML.

--time_partitioning_expiration=SECONDS

Use com a sinalização --destination_table. Trata-se de um número inteiro que especifica (em segundos) quando uma partição baseada em tempo será excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro. Caso ele seja negativo, isso indica que não há validade.

--time_partitioning_field=COLUMN_NAME

Use com a sinalização --destination_table. Especifica a coluna para o particionamento baseado em tempo. Se ele for ativado sem esse valor, a tabela será particionada com base no tempo de ingestão.

--time_partitioning_type=INTERVAL

Use com a sinalização --destination_table. Especifica o tipo de partição da tabela de destino. Use um dos seguintes valores:

• DAY
• HOUR
• MONTH
• YEAR

--udf_resource=FILE

Essa sinalização aplica-se somente a consultas SQL legadas. Especifica o URI do Cloud Storage ou o caminho para um arquivo local que contém um recurso de função definido pelo usuário a ser usado por uma consulta SQL legada. Repita a sinalização para especificar vários arquivos.

--use_cache={true|false}

Para não permitir o armazenamento dos resultados da consulta em cache, defina como false. O valor padrão é true.

--use_legacy_sql={true|false}

Para executar uma consulta do GoogleSQL, defina como false. O valor padrão é true. O comando usa o SQL legado.

--job_timeout_ms={string (Int64Value)}

Especifica o tempo máximo de execução de uma consulta em milissegundos. Se esse limite de tempo for excedido, o BigQuery tentará interromper o job.

QUERY

A consulta que você quer executar.

Para mais informações sobre como usar o comando bq query, consulte Como executar consultas interativas e em lote.

bq remove-iam-policy-binding

Use o comando bq remove-iam-policy-binding para recuperar a política do IAM de um recurso e remover uma vinculação da política em uma única etapa. O recurso pode ser uma tabela ou uma visualização.

Esse comando é uma alternativa ao processo de três etapas a seguir:

1. Como usar o comando bq get-iam-policy para recuperar o arquivo de política (no formato JSON).
2. Como editar o arquivo de política.
3. Como usar o comando bq set-iam-policy para atualizar a política sem a vinculação

Observação: bq remove-iam-policy-binding não é compatível com conjuntos de dados. Para remover o acesso a um conjunto de dados, consulte Revogar o acesso a um conjunto de dados.

Sinopse

bq remove-iam-policy-binding FLAGS --member=MEMBER_TYPE:MEMBER --role=ROLE RESOURCE

Sinalizações e argumentos

O comando bq remove-iam-policy-binding usa as seguintes sinalizações e argumentos:

--member=MEMBER_TYPE:MEMBER

Obrigatório. Use a sinalização --member para especificar a parte do membro da vinculação da política do IAM. A sinalização --member é obrigatória com a sinalização --role. Uma combinação de sinalizações --member e --role é igual a uma vinculação.

O valor MEMBER_TYPE especifica o tipo de membro na vinculação da política do IAM. Use um dos seguintes valores:

• user
• serviceAccount
• group
• domain

O valor MEMBER especifica o endereço de e-mail ou o domínio do membro na vinculação política do IAM.

--role=ROLE

Obrigatório. Especifica a parte do papel da vinculação de política do IAM. A sinalização --role é obrigatória com a sinalização --member. Uma combinação de sinalizações --member e --role é igual a uma vinculação.

--table={true|false} ou -t={true|false}

Opcional. Para remover uma vinculação da política do IAM de uma tabela ou visualização, defina como true. O valor padrão é false.

RESOURCE é a tabela ou a visualização com a vinculação de política que você quer remover.

Para mais informações, consulte a referência da política do IAM.

bq rm

Use o comando bq rm para excluir um recurso do BigQuery.

Sinopse

bq rm [FLAGS] RESOURCE

Sinalizações e argumentos

O comando bq rm usa as seguintes sinalizações e argumentos:

--capacity_commitment={false|true}

Para excluir um compromisso de capacidade, defina como true, especifique o local do compromisso que você quer remover usando a sinalização --location e substitua RESOURCE pelo Código do compromisso que você quer remover.

--dataset={true|false} ou -d={true|false}

Para excluir um conjunto de dados, defina como true. O valor padrão é false.

--force={true|false} ou -f={true|false}

Para excluir um recurso sem prompt, defina como true. O valor padrão é false.

--job={true|false} ou -j={true|false}

Para excluir um job, defina como "true". O valor padrão é falso.

--model={true|false} ou -m={true|false}

Para excluir um modelo do BigQuery ML, defina como true. O padrão é false.

--recursive={true|false} ou -r{true|false}

Para excluir um conjunto de dados e quaisquer tabelas, dados da tabela ou modelos contidos nele, defina como true. O valor padrão é false.

--reservation={true|false}

Para excluir uma reserva, defina como true. O valor padrão é false.

--reservation_assignment={true|false}

Para excluir uma atribuição de reserva, defina como true. O valor padrão é false.

--routine={true|false}

Para excluir uma rotina, defina como true. O valor padrão é false. Uma rotina pode ser uma função definida pelo usuário permanente ,função de tabela (Visualização), ou procedimento armazenado.

--table={true|false} ou -t={true|false}

Para excluir uma tabela ou visualização, defina como true. O valor padrão é false.

--transfer_config={true|false}

Para excluir uma configuração de transferência, defina como true. O valor padrão é false.

RESOURCE

O recurso que você quer remover.

Para mais informações sobre como usar o comando bq rm, consulte:

• Como gerenciar conjuntos de dados
• Como gerenciar jobs
• Como gerenciar tabelas
• Como gerenciar visualizações
• Como trabalhar com transferências
• Como excluir snapshots da tabela

bq set-iam-policy

Use o comando bq set-iam-policy para especificar ou atualizar a política do IAM de um recurso. O recurso pode ser uma tabela ou uma visualização. Depois de definir a política, a nova política é impressa em stdout. A política está no formato JSON.

O campo etag na política atualizada precisa corresponder ao valor etag da política atual. Caso contrário, a atualização falhará. Esse recurso evita atualizações simultâneas.

É possível conseguir a política atual e o valor etag de um recurso usando o comando bq get-iam-policy.

Observação: bq set-iam-policy não é compatível com conjuntos de dados. Para modificar o acesso a um conjunto de dados, consulte Conceder acesso a um conjunto de dados ou Revogar acesso a um conjunto de dados.

Sinopse

bq set-iam-policy [FLAGS] RESOURCE FILE_NAME

Sinalizações e argumentos

O comando bq set-iam-policy usa as seguintes sinalizações e argumentos.

--table={true|false} ou -t={true|false}

Opcional. Para definir a política do IAM de uma tabela ou visualização, defina como true. O valor padrão é false.

RESOURCE é a tabela ou a visualização com a política que você quer atualizar.

FILE_NAME é o nome de um arquivo que contém a política no formato JSON.

Para mais informações sobre o comando bq set-iam-policy, consulte Controlar o acesso a recursos com o IAM.

bq show

Use o comando bq show para exibir informações sobre um recurso.

Sinopse

bq show [FLAGS] [RESOURCE]

Sinalizações e argumentos

O comando bq show usa as seguintes sinalizações e argumentos:

--assignee_id=ASSIGNEE

Quando usado com a sinalização --reservation_assignment, especifica o ID de uma pasta, organização ou projeto. Use a sinalização --assignee_type para especificar o tipo de cessionário a ser exibido.

--assignee_type=TYPE

Quando usado com a sinalização --reservation_assignment, especifica o tipo de entidade a ser exibido. Use um dos seguintes valores:

• FOLDER
• ORGANIZATION
• PROJECT

--connection={true|false}

Para mostrar informações sobre uma conexão, defina como true. O valor padrão é false. Para mais informações, consulte Como visualizar um recurso de conexão.

--dataset={true|false} ou -d={true|false}

Para mostrar informações sobre um conjunto de dados, defina como true. O valor padrão é false.

--encryption_service_account={true|false}

Para mostrar a conta de serviço de criptografia de um projeto, se existir, ou criar uma se não existir, defina como true. O valor padrão é false. Use com a sinalização --project_id.

--job={true|false} ou -j={true|false}

Para mostrar informações sobre um job, defina como true. O valor padrão é false.

--job_type=JOB_TYPE

Quando usado com a sinalização --reservation_assignment, especifica o tipo de job das atribuições de reserva que você quer mostrar. Use um dos seguintes valores:

• QUERY
• PIPELINE
• ML_EXTERNAL

--model={true|false} ou -m={true|false}

Para mostrar informações sobre um modelo de ML do BigQuery, defina como true. O valor padrão é false.

--reservation={true|false}

Para mostrar informações sobre uma reserva, defina como true. O valor padrão é false.

--reservation_assignment={true|false}

Quando definido como true, o comando exibe atribuições de reserva para uma pasta, organização ou projeto especificado. O comando exibe as atribuições explícitas do recurso de destino, se houver. Caso contrário, exibirá atribuições herdadas dos recursos pai. Por exemplo, um projeto pode herdar atribuições da pasta pai. Ao usar essa sinalização, as sinalizações --job_type, --assignee_type e --assignee_id são aplicáveis. O valor padrão é false.

--routine={true|false}

Para mostrar informações sobre uma rotina, defina como true. O valor padrão é false. Uma rotina pode ser uma função definida pelo usuário permanente ,função de tabela (Visualização), ou procedimento armazenado.

--schema={true|false}

Para exibir apenas o esquema da tabela, defina como true. O valor padrão é false.

--transfer_config={true|false}

Para exibir informações sobre uma configuração de transferência, defina como true. O valor padrão é false.

--transfer_run={true|false}

Para exibir informações sobre uma execução de transferência, defina como true. O valor padrão é false.

--view={true|false}

Para exibir informações sobre uma visualização, defina como true. O valor padrão é false.

RESOURCE

O recurso cujas informações você quer mostrar.

Para mais informações sobre como usar o comando bq show, consulte:

• Como receber informações sobre conjuntos de dados
• Como criar e usar tabelas
• Como receber informações sobre visualizações
• Como trabalhar com transferências
• Como gerenciar jobs
• Como encontrar informações sobre um snapshot da tabela

bq update

Use o comando bq update para alterar um recurso.

Sinopse

bq update [FLAGS] [RESOURCE]

Sinalizações e argumentos

O comando bq update usa as seguintes sinalizações e argumentos:

--add_tags=TAGS

Disponível apenas em tabelas. Especifica as tags que você está anexando ao recurso, separadas por vírgulas, por exemplo, 556741164180/env:prod,myProject/department:sales. Cada tag precisa ter o nome da chave com namespace e o nome curto do valor.

--autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS

O número de slots de escalonamento automático atribuídos à reserva. Disponível apenas com a sinalização --reservation e se a reserva foi criada com uma edição.

--capacity_commitment={true|false}

Para atualizar um compromisso de capacidade, defina como true. Use essa sinalização com as sinalizações --merge, --plan, --renewal_plan, --split e --slots.

--clear_all_tags={true|false}

Disponível apenas em tabelas. Para limpar todas as tags de um recurso, defina como true. O valor padrão é false.

--clear_label=KEY:VALUE

Remove um rótulo do recurso. Use o formato KEY:VALUE para especificar o rótulo a ser removido. Repita essa sinalização para remover vários rótulos.

--clustering_fields=COLUMNS

Atualiza a especificação de clustering de uma tabela. O valor COLUMNS é uma lista separada por vírgulas de nomes de colunas para usar no cluster. Para remover o clustering, defina COLUMNS como "" (a string vazia). Para mais informações, consulte Como modificar a especificação de clustering.

--target_job_concurrency=CONCURRENCY

Quando usado com a sinalização --reservation, especifica o número de destino de consultas executadas ao mesmo tempo. O valor padrão é 0, o que significa que a simultaneidade é definida automaticamente com base no tamanho da reserva. Para mais informações, consulte Usar filas de consultas.

--dataset={true|false} ou -d={true|false}

Para atualizar um conjunto de dados, defina como true. O valor padrão é false.

--default_kms_key=KEY

Especifica o ID de recurso de chave padrão do Cloud KMS para criptografar dados da tabela em um conjunto de dados. A chave padrão será usada se nenhuma chave explícita for fornecida para uma criação de tabela ou uma consulta.

--default_partition_expiration=SECONDS

Um número inteiro que especifica o prazo de validade padrão, em segundos, para todas as partições em tabelas particionadas recém-criadas em um conjunto de dados. Essa sinalização não tem valor mínimo.

O prazo de validade é definido como a data UTC da partição acrescida do valor de número inteiro. Se essa propriedade for definida, ela substituirá a validade da tabela padrão no nível do conjunto de dados, se houver. Se você fornecer a sinalização --time_partitioning_expiration ao criar ou atualizar uma tabela particionada, a validade da partição no nível da tabela terá prioridade sobre a validade da partição padrão no nível do conjunto de dados. Especifique 0 para remover uma validade atual.

--default_table_expiration=SECONDS

Um número inteiro que atualiza a duração padrão, em segundos, para tabelas recém-criadas em um conjunto de dados. O prazo de validade é definido como a hora UTC atual mais esse valor. Especifique 0 para remover a validade atual.

--description=DESCRIPTION

Atualiza a descrição de um conjunto de dados, tabela, snapshot da tabela, modelo ou visualização.

--destination_reservation_id=RESERVATION_ID

Quando usado com a sinalização --reservation_assignment, move uma atribuição de reserva atual para a reserva especificada. O valor é o ID da reserva de destino. Para mais informações, consulte Mover uma atribuição para uma reserva diferente.

--display_name=DISPLAY_NAME

Atualiza o nome de exibição para uma configuração de transferência.

--etag=ETAG

Atua como um filtro. Atualiza o recurso somente se ele tiver uma ETag que corresponda à string especificada no argumento ETAG.

--expiration SECONDS

Para atualizar a expiração da tabela, do modelo, do snapshot da tabela ou da visualização, inclua essa sinalização. Substitua SECONDS pelo número de segundos entre a hora de atualização e o prazo de validade. Para remover a expiração de uma tabela, um modelo, um snapshot da tabela ou uma visualização, defina o argumento SECONDS como 0.

--external_table_definition={TABLE::PATH_TO_FILE|TABLE::DEFINITION}

Atualiza uma tabela externa com a definição de tabela especificada. A definição da tabela pode ser um caminho para um arquivo de definição de tabela JSON local ou in-line no formato SCHEMA@SOURCE_FORMAT=CLOUD_STORAGE_URI. O valor SCHEMA é uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante. Se você usa um arquivo de definição de tabela, não atribua uma extensão a ele.

Exemplo:

--external_table_definition=myTable::/tmp/tabledef

--external_table_definition=myTable::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

--ignore_idle_slots={true|false}

Use com a sinalização --reservation. Para restringir os jobs em execução na reserva especificada para usar somente os slots alocados para aquela reserva, defina como true. O valor padrão é false. Os jobs na reserva especificada podem usar slots inativos de outras reservas ou aqueles que não são alocados para nenhuma reserva. Para mais informações, consulte Slots inativos.

--max_time_travel_hours=HOURS

Especifica a duração em horas da janela de viagem no tempo para o conjunto de dados. O valor --max_time_travel_hours precisa ser um número inteiro expresso em múltiplos de 24 (48, 72, 96, 120, 144 e 168) entre 48 (2 dias) e 168 (7 dias).

--merge={true|false}

Para mesclar dois compromissos de capacidade, defina --merge como true. Defina a sinalização --capacity_commitment como true, especifique o local dos compromissos que você quer mesclar usando a sinalização --location e substitua RESOURCE pelos IDs dos dois compromissos que você quer mesclar, separados por vírgula. Para mais informações, consulte Mesclar dois compromissos.

--model={true|false} ou -m={true|false}

Para atualizar os metadados de um modelo de ML do BigQuery, defina como true. O valor padrão é false.

--params={"PARAMETER":"VALUE"} or -p={"PARAMETER":"VALUE"}

Atualiza parâmetros para uma configuração de transferência. Os parâmetros variam de acordo com a fonte de dados. Para mais informações, consulte Introdução ao serviço de transferência de dados do BigQuery.

--plan=PLAN

Quando usado com a sinalização --capacity_commitment, converte um compromisso de capacidade no plano de compromisso de maior duração especificado. Substitua PLAN por um dos seguintes:

• ANNUAL
• THREE_YEAR

--refresh_window_days=DAYS

Um número inteiro que especifica uma janela atualizada (em dias) para uma configuração de transferência.

--remove_tags=TAG_KEYS

Disponível apenas em tabelas. Especifica as tags que você está removendo do recurso, separadas por vírgulas, por exemplo, 556741164180/env,myProject/department. Cada chave de tag precisa ter o nome de chave com namespace.

--renewal_plan=PLAN

Quando usado com a sinalização --capacity_commitment, atualiza o plano de renovação para um compromisso de capacidade anual. Substitua PLAN por um dos seguintes:

• ANNUAL
• THREE_YEAR
• NONE

Os clientes que usam preços fixos legados também podem usar um dos seguintes valores:

• FLEX
• MONTHLY
• ANNUAL

--reservation={true|false}

Especifica se é necessário atualizar uma reserva. O valor padrão é false.

--reservation_assignment={true|false}

Especifica se é necessário atualizar uma atribuição de reserva. O valor padrão é false.

--schema={SCHEMA_FILE|SCHEMA}

Especifica o caminho para um arquivo de esquema JSON local ou uma lista separada por vírgulas de definições de coluna no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE e assim por diante. Se você usar um arquivo de esquema, não atribua uma extensão a ele.

Exemplo:

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

--service_account_name=SERVICE_ACCOUNT

Especifica uma conta de serviço a ser usada como a credencial de uma configuração de transferência.

--set_label=KEY:VALUE

Especifica um rótulo a ser atualizado. Para atualizar vários rótulos, repita essa sinalização.

--slots=NUMBER_OF_SLOTS

Quando usado com as sinalizações --capacity_commitment e --split, especifica o número de slots a serem divididos de um compromisso de capacidade atual em um novo compromisso. Substitua RESOURCE pelo ID do compromisso do qual você quer dividir o arquivo.

Quando usado com a sinalização --reservation, atualiza o número de slots em uma reserva.

--source=FILE

O caminho para o arquivo JSON local que contém um payload usado para atualizar um recurso. Por exemplo, é possível usar essa sinalização para especificar um arquivo JSON que contenha um recurso de conjunto de dados com uma propriedade de access atualizada. O arquivo é usado para substituir os controles de acesso do conjunto de dados. O arquivo JSON não pode incluir uma marca de ordem de byte (BOM, na sigla em inglês).

--split={true|false}

Quando definido como true e usado com a sinalização --capacity_commitment, especifica que você quer dividir um compromisso de capacidade atual. Use a sinalização --location para especificar o local do compromisso de que você quer dividir e use a sinalização --slots para especificar o número de slots que você quer dividir. Substitua RESOURCE pelo ID do compromisso do qual você quer dividir. Para mais informações, consulte Dividir um compromisso.

--storage_billing_model=BILLING_MODEL

Especifica o modelo de faturamento de armazenamento do conjunto de dados. Defina o valor de --storage_billing_model como PHYSICAL para usar bytes físicos ao calcular as cobranças de armazenamento ou como LOGICAL para usar bytes lógicos.

Leva 24 horas para alterar o modelo de faturamento de um conjunto de dados.

Depois de alterar o modelo de faturamento do armazenamento de um conjunto de dados, aguarde 14 dias antes de alterar o modelo de faturamento do armazenamento novamente.

--table={true|false} ou -t={true|false}

Especifica se é necessário atualizar uma tabela. O valor padrão é false.

--target_dataset=DATASET

Quando especificada, atualiza o conjunto de dados de destino para uma configuração de transferência.

--time_partitioning_expiration=SECONDS

Um número inteiro que atualiza (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. Um número negativo indica que não há validade.

--time_partitioning_field=COLUMN_NAME

Atualiza o campo usado para determinar como criar uma partição baseada em tempo. Se o particionamento baseado em tempo estiver ativado sem esse valor, a tabela será particionada com base no tempo de carregamento.

--time_partitioning_type=INTERVAL

Especifica o tipo de particionamento. Use um dos seguintes valores:

• DAY
• HOUR
• MONTH
• YEAR

Não é possível alterar o tipo de particionamento de uma tabela existente.

--transfer_config={true|false}

Especifica se é necessário atualizar uma configuração de transferência. O valor padrão é false.

--update_credentials={true|false}

Especifica se é necessário atualizar as credenciais de configuração de transferência. O valor padrão é false.

--use_legacy_sql={true|false}

Defina como false para atualizar a consulta SQL para uma visualização do SQL legado para o GoogleSQL. O valor padrão é true. A consulta usa SQL legado.

--view=QUERY

Quando especificada, atualiza a consulta SQL para uma exibição.

--view_udf_resource=FILE

Atualiza o URI do Cloud Storage ou o caminho para um arquivo de código local, carregado e avaliado imediatamente, como recurso de uma função definida pelo usuário na consulta SQL de uma visualização. Repita a sinalização para especificar vários arquivos.

RESOURCE

O recurso que você quer atualizar.

Para mais informações sobre como usar o comando bq update, consulte:

• Como atualizar as propriedades do conjunto de dados
• Como gerenciar tabelas
• Como atualizar visualizações
• Como atualizar rótulos
• Como trabalhar com transferências
• Como atualizar metadados de snapshot da tabela

bq version

Use o comando bq version para exibir o número da versão da ferramenta de linha de comando bq.

Sinopse

bq version

Observação: é possível conferir o número da versão de todos os componentes na instalação da Google Cloud CLI usando o comando gcloud version.

bq wait

Use o comando bq wait para aguardar um número especificado de segundos para que um job seja concluído. Se um job não for especificado, o comando aguardará a conclusão do job atual.

Sinopse

bq wait [FLAGS] [JOB] [SECONDS]

Exemplos

bq wait

bq wait --wait_for_status=RUNNING 12345 100

Sinalizações e argumentos

O comando bq wait usa as seguintes sinalizações e argumentos:

--fail_on_error={true|false}

Para retornar o sucesso se o job foi concluído durante o tempo de espera, mesmo se o job falhar, defina como false. O valor padrão é true; após o tempo de espera, o comando será encerrado com um erro se o job ainda estiver em execução ou se o job foi concluído, mas tiver falhado.

--wait_for_status=STATUS

Quando especificada, aguarda um determinado status do job antes de sair. Use um dos seguintes valores:

• PENDING
• RUNNING
• DONE

O valor padrão é DONE.

JOB

Especifica o job que será aguardado. Use o comando bq ls --jobs myProject para encontrar um identificador de job.

SECONDS

Especifica o número máximo de segundos para aguardar até que o job seja concluído. Se você digitar 0, o comando pesquisará a conclusão do job e retornará imediatamente. Se você não especificar um valor inteiro, o comando aguardará até que o job seja concluído.