O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o driver ODBC para BigQuery

O driver Open Database Connectivity (ODBC) para BigQuery conecta seus aplicativos não Java ao BigQuery, permitindo que você use recursos do BigQuery com suas ferramentas e infraestrutura preferidas. Para conectar aplicativos Java ao BigQuery, use o driver JDBC para BigQuery.

O driver ODBC para BigQuery está disponível sob a licença Apache 2.0.

Antes de começar

Familiarize-se com os drivers ODBC e os gerenciadores de drivers.

Verifique se o sistema operacional atende aos seguintes requisitos:

Sistema operacional	Arquiteturas compatíveis	Versão mínima e dependências
Windows	32 bits (x86), 64 bits (x64)	Versão: Windows 10, Windows Server 2016 ou posterior Dependência: Microsoft Visual C++ Redistribuível para Visual Studio 2019 ou 2022
macOS	64 bits (x86_64), ARM64 (Apple Silicon)	Versão: macOS 12 (Monterey) ou mais recente Dependência: um gerenciador de drivers ODBC (por exemplo, unixODBC). Adicione o diretório de instalação ao seu `DYLD_LIBRARY_PATH`.
Linux	64 bits (x86_64)	Versão: qualquer distribuição com glibc 2.27 ou mais recente (por exemplo, Ubuntu 20.04 LTS+, Debian 11+) Dependência: um gerenciador de drivers ODBC (por exemplo, unixODBC). Adicione o diretório de instalação ao seu `LD_LIBRARY_PATH`.

Autentique-se no BigQuery e anote as seguintes informações, que serão usadas mais tarde quando você estabelecer uma conexão com o driver ODBC para BigQuery. Você só precisa anotar as informações correspondentes ao método de autenticação que você usa.

Método de autenticação	Informações de autenticação	Exemplo	Propriedade de conexão (para definir mais tarde)
Conta de serviço padrão	Chave da conta de serviço (objeto JSON)	`my-sa-key.json`	`KeyFilePath`
Identidade temporária de conta de serviço	Endereço de e-mail da conta de serviço de destino	`service-account@project.iam.gserviceaccount.com`	`ServiceAccountImpersonationEmail, KeyFilePath`
Federação de identidade da carga de trabalho ou da força de trabalho	Propriedade de público-alvo do arquivo de configuração da conta externa	`//iam.googleapis.com/locations/global/...`	`BYOID_AudienceUrl`
	Recuperação de token e arquivo de informações ambientais	`{"file":"/path/to/file"}`	`BYOID_CredentialSource`
	Projeto do usuário (somente para pool de força de trabalho)	`my_project`	`BYOID_PoolUserProject`
	Tipo de token STS	`id_token`	`BYOID_SubjectTokenType`
	Endpoint de troca de token do STS	`https://sts.googleapis.com/v1/token`	`BYOID_TokenUrl`
Application Default Credentials	Nenhum	N/A	N/A

Instalar e configurar o driver ODBC

É possível instalar e configurar o driver ODBC para BigQuery usando um sistema operacional Windows ou não Windows.

Windows

Instale o driver que corresponde à arquitetura do seu aplicativo:
- Faça o download do arquivo ODBCDriverforBigQuery_windows_x86.msi para aplicativos de 32 bits.
- Faça o download do arquivo ODBCDriverforBigQuery_windows_x64.msi para aplicativos de 64 bits.
Crie um nome da fonte de dados (DSN) fazendo o seguinte:
1. No menu Iniciar do Windows, acesse Fontes de dados ODBC e selecione a versão com a mesma arquitetura (32 ou 64 bits) do seu aplicativo cliente.
2. Na página Administrador de fonte de dados ODBC, clique na guia Drivers.
3. Na lista de drivers ODBC instalados, localize Driver ODBC para BigQuery.
4. Selecione a guia DSN do sistema para criar um DSN para todos os usuários ou a guia DSN do usuário para criar um DSN para o usuário atual. Os DSNs do sistema são geralmente recomendados porque alguns aplicativos carregam dados usando contas de usuário diferentes e podem não detectar outros DSNs de usuário.
5. Clique em Adicionar.
6. Na caixa de diálogo Criar nova fonte de dados, selecione Driver ODBC para BigQuery e clique em Concluir. A caixa de diálogo Configuração de DSN do driver ODBC para BigQuery é aberta.
7. No campo Nome da fonte de dados, insira um nome para o DSN.
8. Adicione propriedades de conexão. Para uma lista completa de propriedades, consulte Propriedades de conexão.

Não Windows

Instale o driver correspondente ao seu sistema operacional:
- Faça o download do arquivo ODBCDriverforBigQuery_linux_latest.zip para Linux.
- Faça o download do arquivo ODBCDriverforBigQuery_macos_latest.tar.gz para macOS.
Extraia o conteúdo do arquivo ZIP ou TAR baixado.
Mova o conteúdo do arquivo ZIP ou TAR para o diretório em que você quer instalar o driver. O caminho do objeto compartilhado do driver ODBC para BigQuery é INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so, em que INSTALL_DIR é o diretório de instalação.

Atualize os arquivos .ini para refletir o novo caminho do driver.

O exemplo a seguir atualiza os arquivos .ini em um sistema Linux:

unzip linux_odbc-driver.VERSION.zip -d linux_odbc-driver.VERSION/
cd ./linux_odbc-driver.VERSION
export INSTALL_DIR=$(pwd)
export ODBCINI=$INSTALL_DIR/odbc.ini
export ODBCINSTINI=$INSTALL_DIR/odbcinst.ini
export GOOGLEBIGQUERYODBCINI=$INSTALL_DIR/googlebigqueryodbc.ini

Substitua VERSION pela versão do driver.

Versões anteriores do driver ODBC para BigQuery

1.3.1

Estabelecer uma conexão

Para estabelecer uma conexão entre seu aplicativo e o BigQuery com o driver ODBC para BigQuery, identifique a string de conexão. Pule esta etapa se já tiver configurado as propriedades de conexão usando seu DSN.

A string de conexão tem o seguinte formato:

Driver=ODBC Driver for BigQuery;Catalog=PROJECT_ID;OAuthMechanism=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

Substitua:

PROJECT_ID: o ID do seu projeto do BigQuery.
AUTH_TYPE: um número que especifica o tipo de autenticação usado. Selecione uma destas opções:
- 0: para autenticação de conta de serviço
- 3: para autenticação de Application Default Credentials
- 4: para autenticação da federação de identidade da carga de trabalho ou da força de trabalho
AUTH_PROPS: as informações de autenticação que você anotou ao autenticar no BigQuery, listadas no formato property_1=value_1; property_2=value_2;.... Por exemplo, KeyFilePath=my-sa-key.json, se você fez a autenticação com uma conta de serviço.
OTHER_PROPS (opcional): propriedades de conexão adicionais para o driver ODBC, listadas no formato property_1=value_1; property_2=value_2;.... Para uma lista completa de propriedades de conexão, consulte Propriedades de conexão.

Propriedades da conexão

As propriedades de conexão do driver ODBC são parâmetros de configuração incluídos na string de conexão ao estabelecer uma conexão com um banco de dados. O driver ODBC para BigQuery é compatível com as seguintes propriedades de conexão.

Propriedade de conexão	Descrição	Valor padrão	Tipo de dado	Obrigatório
`AdditionalProjects`	Projetos que o driver pode acessar para consultas e operações de metadados, além do projeto principal definido pela propriedade `Catalog`.	N/A	String separada por vírgulas	Não
`AllowHtapiForLargeResults`	Determina se o driver pode usar a API BigQuery Storage Read.	`0`	Booleano	Não
`AllowLargeResults`	Determina se o driver processa resultados de consultas maiores que 128 MB quando a propriedade `SQLDialect` está definida como `0` (SQL legado). Se a propriedade `SQLDialect` estiver definida como `1` (GoogleSQL), o driver sempre processará resultados de consultas grandes.	`0`	Booleano	Não
`BYOID_AudienceUrl`	Contém o nome do recurso do pool de Identidade da carga de trabalho ou do pool de força de trabalho e o identificador do provedor nesse pool.	N/A	String	Somente quando `OAuthMechanism=4`
`BYOID_CredentialSource`	Define as informações necessárias para recuperar o token e algumas informações ambientais.	N/A	String	Somente quando `OAuthMechanism=4`
`BYOID_PoolUserProject`	Defina o projeto quando ele for um pool de força de trabalho e não um pool de Identidade da carga de trabalho.	N/A	String	Somente quando `OAuthMechanism=4` e usando um pool de funcionários
`BYOID_SubjectTokenType`	Define o tipo de token do STS com base na especificação de troca de token do OAuth 2.0. Os valores esperados incluem: `urn:ietf:params:oauth:token-type:jwt` `urn:ietf:params:oauth:token-type:id_token` `urn:ietf:params:oauth:token-type:saml2` `urn:ietf:params:aws:token-type:aws4_request`	N/A	String	Somente quando `OAuthMechanism=4`
`BYOID_TokenUrl`	Define o endpoint de troca de token do STS.	`https://sts.googleapis.com/v1/token`	String	Não
`Catalog`	O ID do projeto padrão do BigQuery para o driver. O driver usa esse projeto para executar consultas e o fatura pelo uso de recursos.	N/A	String	Sim
`DefaultDataset`	Serve como um conjunto de dados designado em um projeto que o driver referencia automaticamente quando você executa consultas sem especificar explicitamente um conjunto de dados.	N/A	String	Não
`EnableSession`	Determina se uma conexão inicia uma sessão. Quando ativada, a primeira consulta executada por essa conexão inicia uma sessão, e o driver transmite o ID da sessão para todas as consultas subsequentes.	`0`	Booleano	Não
`FilterTablesOnDefaultDataset`	Determina o escopo dos metadados que os métodos de metadados de tabela ou coluna retornam. Quando é falso (`0`), não há filtragem. Também é necessário definir a propriedade `DefaultDataset` para ativar a filtragem.	`0`	Booleano	Não
`IgnoreTransactions`	Quando ativado (`1` ou `TRUE`), o driver ignora o processamento manual de transações (`BEGIN TRANSACTION`, `COMMIT`, `ROLLBACK`) quando `SQL_ATTR_AUTOCOMMIT` é definido como `SQL_AUTOCOMMIT_OFF`. Recomendado para ferramentas de BI e clientes SQL de terceiros (como Tableau, Power BI e DBeaver) que desativam o autocommit por padrão.	`0`	Booleano	Não
`JobCreationMode`	Permite ativar o caminho de consulta de baixa latência. Escolha uma das opções a seguir: `1`: o driver cria jobs para cada consulta (`JOB_CREATION_REQUIRED`) `2`: o driver executa consultas sem jobs (`JOB_CREATION_OPTIONAL`)	`2`	Inteiro	Não
`KeyFilePath`	O caminho para o arquivo JSON da chave da conta de serviço ao usar a autenticação da conta de serviço.	N/A	String	Somente quando `OAuthMechanism=0`
`KMSKeyName`	Especifica o nome do recurso de chave do Cloud KMS a ser usado ao criptografar e descriptografar dados.	N/A	String	Não
`LargeResultsDataSetId`	Especifica o conjunto de dados de destino para armazenar resultados de consultas grandes.	N/A	String	Não
`LargeResultsTempTableExpirationTime`	Especifica a vida útil das tabelas temporárias no `LargeResultsDataSetId`, em milissegundos.	`3600000`	Longo	Não
`LogLevel`	Limita os detalhes que o motorista registra durante as interações. Para mais informações, consulte Configuração de geração de registros e de driver. Escolha uma das opções a seguir: `0`: `OFF` `1`: `ERROR` `2`: `WARNING` `3`: `INFO`	`0`	Inteiro	Não
`LogPath`	Especifica o diretório em que o driver grava arquivos de registro. Para mais informações, consulte Configuração de geração de registros e de driver.	N/A	String	Não
`LogFileCount`	Especifica o número máximo de arquivos de registro a serem mantidos.	`0`	Inteiro	Não
`LogFileSize`	Especifica o tamanho máximo de cada arquivo de registro em KB.	`0`	Longo	Não
`MaxRetries`	Configura o número máximo de tentativas de repetição executadas pelo driver com espera exponencial ao encontrar erros transitórios de API REST e gRPC do BigQuery (como limites de taxa ou HTTP 5xx) antes de retornar um erro.	`6`	Inteiro	Não
`MaxThreads`	Define o número máximo de linhas de execução que o driver pode usar para processamento simultâneo em um pool de linhas de execução. Para configurar essa propriedade como uma definição em todo o driver para ambientes que não são do Windows, especifique-a no arquivo `googlebigqueryodbc.ini`.	`8`	Inteiro	Não
`OAuthMechanism`	O tipo de autenticação. Escolha uma das opções a seguir: `0`: autenticação da conta de serviço `3`: autenticação de Application Default Credentials `4`: autenticação da federação de identidade da carga de trabalho ou da força de trabalho	N/A	Inteiro	Sim
`PrivateServiceConnectUris`	Endpoints personalizados para substituir os endpoints padrão. Exemplos: `BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/` `READ_API=bigquerystorage.us-east4.rep.googleapis.com` `OAUTH2=oauth2.us-east4.rep.googleapis.com`	N/A	String separada por vírgulas	Não
`ProxyHost`	Nome do host ou endereço IP de um servidor proxy.	N/A	String	Não
`ProxyPort`	Número da porta em que o servidor proxy está detectando.	N/A	String	Não
`ProxyPwd`	Senha para autenticação ao se conectar por um servidor proxy.	N/A	String	Não
`ProxyUid`	Nome de usuário para autenticação ao se conectar por um servidor proxy.	N/A	String	Não
`QueryProperties`	Configura propriedades que podem modificar o comportamento da consulta.	N/A	Map<String, String>	Não
`RefreshToken`	Token de atualização do OAuth armazenado para fluxos de autenticação do usuário.	N/A	String	Não
`RowsFetchedPerBlock`	Especifica o número máximo de linhas buscadas por bloco ou página de resultados do BigQuery.	`100000`	Longo	Não
`ServiceAccountImpersonationEmail`	Especifica um endereço de e-mail da conta de serviço de destino a ser personificado usando as credenciais básicas do caller. Permite fluxos de trabalho multitenant e de delegação de menor privilégio sem distribuir chaves privadas de conta de serviço adicionais.	N/A	String	Não
`SessionLocation`	Especifica a localização geográfica (região ou multirregião) em que o driver cria ou consulta conjuntos de dados e executa sessões de consulta (por exemplo, `US`, `EU` ou `us-central1`).	N/A	String	Não
`SQLDialect`	Especifica qual dialeto de consulta usar. Use `1` para o GoogleSQL (SQL padrão, altamente recomendado) e `0` para o SQL legado.	`1`	Inteiro	Não
`TrustedCerts`	Especifica o caminho completo para um arquivo de certificados de CA raiz SSL/TLS personalizado no formato PEM (por exemplo, `roots.pem` ou `cacerts.pem`). Substitui o arquivo de certificado agrupado padrão.	N/A	String	Não
`UniverseDomain`	Especifica o domínio do universo da sua organização.	`googleapis.com`	String	Não
`UseDefaultLargeResultsDataset`	Quando `AllowLargeResults=1`, determina se o driver encaminha automaticamente resultados de consultas grandes para o conjunto de dados temporário padrão (`_bqodbc_temp_tables`). Quando definido como `0`, `LargeResultsDataSetId` precisa ser especificado explicitamente.	`1`	Booleano	Não
`UseQueryCache`	Ativa o recurso de cache de consultas no BigQuery.	`true`	Booleano	Não
`UseSystemTrustStore`	Somente no Windows. Instrui o driver a carregar e validar certificados TLS na Windows Certificate Trust Store em vez de procurar um arquivo PEM local.	`0`	Booleano	Não

Mapeamento de tipo de dados

Quando você executa consultas pelo driver ODBC para BigQuery, ocorre o seguinte mapeamento de tipos de dados:

Tipo do GoogleSQL	Tipo SQL do ODBC
`INT64`	`SQL_BIGINT`
`BOOL`	`SQL_BIT`
`DATE`	`SQL_TYPE_DATE`
`FLOAT64`	`SQL_DOUBLE`
`TIME`	`SQL_TYPE_TIME`
`TIMESTAMP`	`SQL_TYPE_TIMESTAMP`
`DATETIME`	`SQL_TYPE_TIMESTAMP`
`BYTES`	`SQL_VARBINARY`
`STRING`	`SQL_VARCHAR`
`ARRAY`	`SQL_VARCHAR`
`STRUCT`	`SQL_VARCHAR`
`INTERVAL`	`SQL_VARCHAR`
`JSON`	`SQL_VARCHAR`
`GEOGRAPHY`	`SQL_VARCHAR`
`RANGE`	`SQL_VARCHAR`
`NUMERIC`	`SQL_NUMERIC`
`BIGNUMERIC`	`SQL_NUMERIC`

Configuração de geração de registros e de driver

Para configurar opções em todo o driver (como geração de registros e codificação de caracteres), faça o seguinte:

Windows

Configure as opções de registro e DSN usando a caixa de diálogo de configuração de DSN no Administrador de fonte de dados ODBC.

Não Windows

Crie ou edite um arquivo de configuração, como googlebigqueryodbc.ini, e adicione opções de driver na seção [Driver]. Confira um exemplo:
```
[Driver]
LogLevel=3
LogPath=/path/to/log/directory
LogFileCount=200
LogFileSize=1000
MaxThreads=8
WcharEncoding=UTF-16LE
```
Defina a variável de ambiente GOOGLEBIGQUERYODBCINI como o caminho deste arquivo:
```
export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini
```

Níveis de registro do driver

O driver é compatível com níveis de geração de registros de 0 a 3. Recomendamos começar com LogLevel=3 (INFO) para resolver problemas.

Nível de registro do ODBC	Descrição
0 (DESATIVADO)	Desativa toda a geração de registros.
1 (ERRO)	Registra eventos de erro.
2 (AVISO)	Registra eventos de alerta.
3 (INFO)	Registra informações gerais que descrevem o progresso do motorista.

Propriedades de configuração em todo o driver (não Windows)

As seguintes propriedades podem ser configuradas na seção [Driver] em googlebigqueryodbc.ini:

Propriedade	Descrição	Valores permitidos	Valor padrão
`WcharEncoding`	Controla explicitamente a codificação de transmissão de buffers de caracteres `SQLWCHAR` ao transmitir strings de caracteres largos entre o driver e o gerenciador de drivers ODBC (por exemplo, `WcharEncoding=UTF-16LE`). Isso resolve problemas de corrupção e truncamento de caracteres no unixODBC (normalmente UTF-16LE de 2 bytes) e no iODBC (normalmente UTF-32LE de 4 bytes).	`UTF-8`, `UTF-16LE`, `UTF-32LE`	Vazio (detecção automática com base em `sizeof(SQLWCHAR)`)
`MaxThreads`	Define o número máximo de linhas de execução que o driver pode usar para processamento simultâneo em um pool de linhas de execução.	Número inteiro positivo	`8`

Exemplos

Os exemplos a seguir demonstram como usar consultas parametrizadas e scripts com várias instruções com o driver ODBC.

Consultas parametrizadas

// 1. Prepare statement
std::string insert_stmt = "INSERT INTO MyTable VALUES (?, ?, ?)";
status = SQLPrepare(hstmt, (SQLCHAR*)insert_stmt.c_str(), SQL_NTS);

// 2. Bind parameters
std::string str_val = "example_string";
long long int_val = 12345;
double float_val = 1.2345;

// Bind string field
status = SQLBindParameter(
    hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0,
    (SQLPOINTER)str_val.c_str(), str_val.size(), NULL);

// Bind integer field
status = SQLBindParameter(
    hstmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_BIGINT, 0, 0,
    &int_val, 0, NULL);

// Bind float field
status = SQLBindParameter(
    hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DOUBLE, 0, 0,
    &float_val, 0, NULL);

// 3. Execute statement
status = SQLExecute(hstmt);

Scripts de várias instruções

// 1. Prepare and execute the multi-statement script
std::string query =
    "CREATE OR REPLACE TABLE MyTable (StringField STRING, IntegerField INTEGER); "
    "INSERT INTO MyTable VALUES ('example', 123); "
    "SELECT * FROM MyTable;";

status = SQLExecDirect(hstmt, (SQLCHAR*)query.c_str(), SQL_NTS);

// 2. Process results for each statement using SQLMoreResults
do {
    SQLSMALLINT num_cols;
    status = SQLNumResultCols(hstmt, &num_cols);

    if (num_cols > 0) {
        // This is a result-returning statement (e.g., SELECT)
        while (SQLFetch(hstmt) == SQL_SUCCESS) {
            // Process rows...
        }
    } else {
        // This is a non-result statement (e.g., CREATE, INSERT)
        SQLLEN row_count;
        SQLRowCount(hstmt, &row_count);
        // Process affected rows...
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);

Preços

Faça o download do driver ODBC para BigQuery sem custo financeiro. No entanto, ao usar o driver, os preços padrão de análise do BigQuery são aplicados.

A seguir

Saiba mais sobre o driver JDBC para BigQuery.
Conheça outras ferramentas para desenvolvedores do BigQuery.