Usar o driver ODBC para BigQuery

O driver Open Database Connectivity (ODBC) para BigQuery conecta seus aplicativos ao BigQuery. Assim, você pode usar recursos do BigQuery com as ferramentas e a infraestrutura de sua preferência.

Antes de começar

  1. Confira se você conhece os drivers Open Database Connectivity (ODBC) e o gerenciador de drivers.

  2. Confira os requisitos do sistema:

    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 mais recente
    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.

  3. Identifique o tipo de conexão do driver ODBC para o BigQuery. O driver é compatível com os seguintes métodos de autenticação:

    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 KeyFilePath
    Federação de identidade de colaboradores ou federação de identidade da carga 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 ou outros tipos de STS BYOID_SubjectTokenType
    Endpoint de troca de token do STS URL do endpoint STS personalizado BYOID_TokenUrl
    Application Default Credentials N/A N/A N/A

Instalar e configurar o driver ODBC

Nesta seção, descrevemos como instalar e configurar o driver ODBC para sistemas operacionais Windows e não Windows.

Windows

No Windows, instale a arquitetura de driver que corresponde à arquitetura do seu aplicativo. Por exemplo, use o driver de 64 bits para aplicativos de 64 bits e o driver de 32 bits para aplicativos de 32 bits. Um sistema Windows de 64 bits é compatível com aplicativos de 32 e 64 bits.

Criar um nome de fonte de dados

Para criar um nome de fonte de dados no Windows:

  1. No menu Iniciar, acesse Fontes de dados ODBC e selecione a versão com a mesma arquitetura de bits do seu aplicativo cliente para garantir a conexão adequada com o BigQuery.
  2. No Administrador de fontes de dados ODBC, clique na guia Drivers.
  3. Localize o driver ODBC para BigQuery na lista alfabética de drivers ODBC instalados.
  4. Escolha uma das seguintes opções:
    • Para criar um DSN para o usuário atual, clique na guia DSN do usuário.
    • Para criar um DSN para todos os usuários, clique na guia DSN do sistema. Os DSNs do sistema são recomendados porque alguns aplicativos carregam dados usando contas de usuário diferentes e podem não detectar DSNs do usuário criados em outra conta.
  5. Clique em Adicionar.
  6. Na caixa de diálogo Criar nova fonte de dados, selecione Driver ODBC para BigQuery e clique em Concluir.
  7. A caixa de diálogo Configuração de DSN do driver ODBC para BigQuery é aberta.
  8. No campo Nome da fonte de dados, digite um nome para o DSN.
  9. Consulte a seção Propriedades da conexão para entender quais valores preencher.

Não Windows

As distribuições Linux de 64 bits são compatíveis com aplicativos de 32 e 64 bits. Verifique se a arquitetura do driver ODBC corresponde ao aplicativo que você pretende usar. Por exemplo, use o driver de 64 bits para aplicativos de 64 bits e o driver de 32 bits para aplicativos de 32 bits. É possível instalar as duas arquiteturas de driver simultaneamente em um único sistema.

Para instalar o conector usando o pacote de arquivo tar ou zip:

  1. Crie o diretório em que você quer instalar o conector, se ele ainda não existir.
  2. Extraia o arquivo ZIP principal para um local temporário conveniente.
  3. Acesse a pasta do arquivo tar ou zip extraído e, se quiser, copie todos os arquivos e pastas para o diretório de instalação.
  4. Depois da extração, o caminho do objeto compartilhado do driver ODBC para BigQuery é [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Atualize os arquivos .ini para refletir o caminho correto do conector.
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

Estabelecer uma conexão

Para estabelecer uma conexão usando o driver ODBC para BigQuery, use uma string de conexão ou um DSN.

Formato da string de conexão

Driver=ODBC Driver for BigQuery;ProjectId=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. Escolha uma das opções a seguir:
    • 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 de colaboradores
  • AUTH_PROPS: as informações de autenticação que você anotou ao se autenticar no BigQuery.
  • OTHER_PROPS (opcional): propriedades de conexão adicionais para o driver ODBC.

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 o 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 ProjectId. N/A String separada por vírgulas Não
AllowHtapiForLargeResults Determina se o motorista pode usar a API Read. 0 Booleano Não
AllowLargeResults Especifica se o driver ODBC deve processar resultados de consultas maiores que 128 MB ao usar o SQL legado (QueryDialect=BIG_QUERY). 0 Booleano Não
BYOID_AudienceUrl O público-alvo contém o nome do recurso do pool de identidades 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 isso quando for um pool de colaboradores e não um pool 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 Oauth2.0. Valores esperados:
  • 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
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
FilterTablesOnDefaultDataset Determina o escopo dos metadados que os métodos de metadados de tabela/coluna retornam. Quando é FALSE, nada é filtrado. Também é necessário definir a propriedade DefaultDataset para ativar a filtragem. FALSE Booleano 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
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 Número inteiro Não
KeyFilePath O caminho para a chave da conta de serviço ao usar a autenticação da conta de serviço. N/A String Somente quando OAuthMechanism=0
KMSKeyName Permite especificar o nome da chave do KMS a ser usada ao criptografar e descriptografar dados. N/A String Não
LargeResultsDataSetId Permite especificar o conjunto de dados de destino para armazenar resultados de consultas grandes. N/A String Não
LargeResultsDatasetExpirationTime Permite especificar o ciclo de vida de todas as tabelas no conjunto de dados de resultados grandes, em milissegundos. 3600000 Longo Não
Location Permite especificar o local em que o driver cria ou consulta conjuntos de dados. N/A String Não
LogLevel Limita o nível de detalhes que o driver registra durante as interações. Escolha uma das opções a seguir:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Número inteiro Não
LogPath Permite especificar o diretório em que o driver grava arquivos de registro. N/A String Não
LogFileCount Permite definir o número máximo de arquivos de registro a serem mantidos. 0 Número inteiro Não
LogFileSize Permite definir o tamanho máximo de cada arquivo de registro em bytes. 0 Longo Não
MaxResults Permite especificar o número de resultados por página no resultado da API BigQuery. 10000 Longo Não
MaxThreads Define o número máximo de linhas de execução que o conector 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 conector para conectores não Windows (Linux/macOS), especifique-a no arquivo googlebigqueryodbc.ini. 8 Número 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 Credential
  • 4: autenticação da federação de identidade da carga de trabalho ou de colaboradores
 N/A Número inteiro Sim
ProjectId O ID do projeto padrão para o motorista. O driver usa esse projeto para executar consultas e o fatura pelo uso de recursos. N/A String Sim
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
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
QueryDialect Especifica qual dialeto de consulta usar. Use SQL para o GoogleSQL (altamente recomendado) e BIG_QUERY para o SQL legado. SQL String Não
QueryProperties Configura propriedades que podem modificar o comportamento da consulta. N/A Map<String, String> Não
UniverseDomain Especifica o domínio do universo da sua organização. googleapis.com String Não
UseQueryCache Permite ativar o recurso de cache de consultas no BigQuery. true Booleano Não

Executar consultas com o driver

Esta seção fornece informações sobre o mapeamento de tipos de dados e exemplos de execução de consultas com o driver ODBC.

Mapeamento de tipo de dados

Quando você executa consultas usando o driver ODBC para BigQuery, ocorre o seguinte mapeamento de tipos de dados (com base nos tipos SQL ODBC padrão):

Tipo do GoogleSQL Tipo SQL ODBC
INT64SQL_BIGINT
BOOLSQL_BIT
DATESQL_TYPE_DATE
FLOAT64SQL_DOUBLE
TIMESQL_TYPE_TIME
TIMESTAMPSQL_TYPE_TIMESTAMP
DATETIMESQL_TYPE_TIMESTAMP
BYTESSQL_VARBINARY
STRINGSQL_VARCHAR
ARRAYSQL_VARCHAR
STRUCTSQL_VARCHAR
INTERVALSQL_VARCHAR
JSONSQL_VARCHAR
GEOGRAPHYSQL_VARCHAR
RANGESQL_VARCHAR
NUMERICSQL_NUMERIC
BIGNUMERICSQL_NUMERIC

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 com 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

A consulta pelo driver ODBC para BigQuery está sujeita aos preços padrão de análise do BigQuery.