Usar o driver JDBC para BigQuery

O driver Java Database Connectivity (JDBC) para BigQuery conecta seus aplicativos Java ao BigQuery, permitindo que você use os recursos do BigQuery com as ferramentas e a infraestrutura de sua preferência. Para conectar aplicativos que não são Java ao BigQuery, use o driver Open Database Connectivity (ODBC) para BigQuery.

Limitações

O driver JDBC para BigQuery está sujeito às seguintes limitações:

• O driver é específico do BigQuery e não pode ser usado com outros produtos ou serviços.
• O tipo de dados INTERVAL não é compatível com a API BigQuery Storage Read.
• Todas as limitações da linguagem de manipulação de dados (DML) se aplicam.

Antes de começar

1. Verifique se você conhece os drivers JDBC, o Apache Maven e o pacote java.sql.
2. Verifique se o sistema está configurado com o Java Runtime Environment (JRE) 8.0 ou mais recente. Para saber como verificar sua versão do JRE, consulte Como verificar o ambiente do JRE.

3. Autentique-se no BigQuery e anote as informações a seguir, que serão usadas posteriormente quando você estabelecer uma conexão com o driver JDBC para BigQuery. Você só precisa anotar as informações que correspondem 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	E-mail da conta de serviço	bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.com	OAuthServiceAcctEmail
   	Chave da conta de serviço (objeto JSON)	my-sa-key	OAuthPvtKey
   Arquivo de chave da conta de serviço	Arquivo de chave da conta de serviço (caminho completo)	path/to/file/secret.json	OAuthPvtKeyPath
   Conta de usuário do Google	ID do cliente	123-abc.apps.googleusercontent.com	OAuthClientId
   	Chave secreta do cliente	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Token de acesso pré-gerado	Token de acesso	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   Token de atualização pré-gerado	Token de atualização	1/fFAGRNJru1FTz70BzhT3Zg	OAuthRefreshToken
   	ID do cliente	123-abc.apps.googleusercontent.com	OAuthClientId
   	Chave secreta do cliente	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Application Default Credentials	Nenhum	N/A	N/A
   Arquivo de configuração	Arquivo de configuração (objeto JSON ou caminho completo)	path/to/file/secret.json	OAuthPvtKey
   Objeto de configuração de conta externa	Objeto de configuração da conta	external_account_configuration_object	OAuthPvtKey
   Outro	Propriedade de público-alvo do arquivo de configuração da conta externa	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	Recuperação de token e arquivo de informações ambientais	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	Projeto do usuário (somente se estiver usando um pool de força de trabalho)	my_project	BYOID_PoolUserProject
   	URI para identidade temporária de conta de serviço (somente se estiver usando um pool de colaboradores)	my-sa	BYOID_SA_Impersonation_Uri
   	Token do Security Token Service com base na especificação de troca de tokens	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Endpoint de troca de tokens do Security Token Service	https://sts.googleapis.com/v1/token	BYOID_TokenUri

Instalar e configurar o driver JDBC

É possível instalar e configurar o driver JDBC para o BigQuery fazendo o download direto do arquivo uber-JAR ou usando o Maven.

Configuração de download direto

Para configurar o driver JDBC por download direto, faça o seguinte:

1. Faça o download da versão 1.6.0 do driver.
2. Copie o arquivo baixado para o local especificado pelo software.

Para informações sobre mudanças de recursos e atualizações de fluxo de trabalho, consulte o registro de alterações.

Configuração do Maven

O driver JDBC para BigQuery está disponível no Maven Central.

Para configurar o ambiente de desenvolvimento com o driver JDBC, adicione o driver como uma dependência ao projeto:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
</dependency>

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.0")
}

Estabelecer uma conexão

Para estabelecer uma conexão entre o aplicativo Java e o BigQuery com o driver JDBC para BigQuery, faça o seguinte:

1. Identifique sua string de conexão para o driver JDBC do BigQuery. Essa string captura todas as informações necessárias para estabelecer uma conexão entre o aplicativo Java e o BigQuery. A string de conexão tem o seguinte formato:

   jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

   Substitua:

   • HOST: o DNS ou o endereço IP do servidor.
   • PORT: o número da porta TCP.
   • PROJECT_ID: o ID do projeto do BigQuery.
   • AUTH_TYPE: um número que especifica o tipo de autenticação que você usou. Uma das seguintes opções:
     • 0: para autenticação de conta de serviço (padrão e arquivo de chave)
     • 1: para autenticação da Conta do Google do usuário
     • 2: para autenticação de token de acesso ou atualização pré-gerado.
     • 3: para autenticação do Application Default Credentials
     • 4: para outros métodos de autenticação
   • 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, OAuthPvtKeyPath=path/to/file/secret.json, se você tiver feito a autenticação com um arquivo de chave de conta de serviço.
   • OTHER_PROPS (opcional): propriedades de conexão adicionais para o driver JDBC, 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.

2. Conecte seu aplicativo Java ao driver JDBC do BigQuery com a classe DriverManager ou DataSource.

   • Conecte-se com a classe DriverManager:

     import java.sql.Connection;
     import java.sql.DriverManager;
     
     private static Connection getJdbcConnectionDM(){
       Connection connection = DriverManager.getConnection(CONNECTION_STRING);
       return connection;
     }

     Substitua CONNECTION_STRING pela string de conexão da etapa anterior.

   • Conecte-se com a classe DataSource:

     import com.google.cloud.bigquery.jdbc.DataSource;
     import java.sql.Connection;
     import java.sql.SQLException;
     
     private static public Connection getJdbcConnectionDS() throws SQLException {
       Connection connection = null;
       DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
       dataSource.setURL(CONNECTION_STRING);
       connection = dataSource.getConnection();
       return connection;
     }

     Substitua CONNECTION_STRING pela string de conexão da etapa anterior.

     A classe DataSource também tem métodos setter que podem ser usados para definir propriedades de conexão, em vez de incluí-las na string de conexão. Confira o seguinte exemplo:

     private static Connection getConnection() throws SQLException {
       DataSource ds = new DataSource();
       ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
       ds.setAuthType(3);  // Application Default Credentials
       ds.setProjectId("MyTestProject");
       ds.setEnableHighThroughputAPI(true);
       ds.setLogLevel("6");
       ds.setUseQueryCache(false);
       return ds.getConnection();
     }

Propriedades da conexão

As propriedades de conexão do driver JDBC são parâmetros de configuração que você inclui na string de conexão ou transmite por métodos setter ao estabelecer uma conexão com um banco de dados. As seguintes propriedades de conexão são compatíveis com o driver JDBC para BigQuery.

Executar consultas com o driver

Com o aplicativo Java conectado ao BigQuery pelo driver JDBC, agora é possível executar consultas no ambiente de desenvolvimento usando o processo JDBC padrão. Todas as cotas e limites do BigQuery se aplicam.

Mapeamento de tipo de dados

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

Exemplos

As seções a seguir mostram exemplos que usam recursos do BigQuery com o driver JDBC para BigQuery.

Parâmetros posicionais

O exemplo a seguir executa uma consulta com um parâmetro posicional:

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

Registros aninhados e repetidos

O exemplo a seguir consulta o registro base de dados de Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

O driver retorna o registro base como um objeto struct ou uma representação de string de um objeto JSON. O resultado será semelhante ao seguinte:

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

O exemplo a seguir consulta os subcomponentes de um objeto Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

O exemplo a seguir consulta uma matriz padrão de dados repetidos e, em seguida, verifica o resultado:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

O exemplo a seguir consulta uma matriz Struct de dados repetidos e, em seguida, verifica o resultado:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

Inserção em massa

O exemplo a seguir executa uma operação de inserção em massa com o método executeBatch.

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

Logging

Para resolver problemas com o driver JDBC para BigQuery, ative a geração de registros definindo propriedades de conexão ou variáveis de ambiente. A geração de registros pode afetar o desempenho e ocupar espaço em disco. Por isso, ative-a apenas temporariamente para capturar um problema.

Níveis de registro

A propriedade LogLevel determina o nível de detalhe registrado pelo pacote java.util.logging:

• 0: OFF (padrão)
• 1: SEVERE
• 2: WARNING
• 3: INFO
• 4: CONFIG
• 5: FINE
• 6: FINER
• 7: FINEST
• 8: ALL

Recomendamos o nível 6 para solução de problemas gerais. Os níveis 7 e 8 são limitados a operações ResultSet e geram um grande volume de registros.

Ativar a geração de registros na string de conexão

Para ativar a geração de registros na string de conexão, adicione as propriedades de conexão LogLevel e LogPath, por exemplo:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

Ativar a geração de registros com variáveis de ambiente

Se a ferramenta para desenvolvedores não permitir edições de string de conexão, você também poderá definir o nível e o caminho do registro com as seguintes variáveis de ambiente antes de executar o aplicativo:

• BIGQUERY_JDBC_LOG_LEVEL: o nível do registro (0 a 8).
• BIGQUERY_JDBC_LOG_PATH: o diretório dos arquivos de registro.

Por exemplo, em um ambiente Linux ou macOS, execute o seguinte:

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelemetry

O driver JDBC para BigQuery é compatível com o OpenTelemetry (OTel) para fornecer rastreamento e geração de registros distribuídos, o que permite monitorar o desempenho das interações do banco de dados e resolver problemas de maneira eficaz.

Operações rastreadas

Quando o OpenTelemetry está ativado, o driver gera períodos para as seguintes operações:

• Execução de consulta: os períodos são gerados para BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) e BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
• Operações de metadados: os períodos são gerados para métodos DatabaseMetaData específicos (getCatalogs(), getSchemas(), getTables(), getColumns()).
• Paginação: as buscas assíncronas de outras páginas de resultados (ao usar o caminho da API REST) são rastreadas e vinculadas causalmente ao período de execução da consulta original usando os links de período do OpenTelemetry. Um período chamado BigQueryStatement.pagination é criado para essas operações.
• Propagação de contexto: o driver JDBC propaga o contexto ativo para o SDK do google-cloud-bigquery. Como resultado, os períodos gerados pelo SDK (como chamadas RPC HTTP) aparecem automaticamente como filhos dos períodos do JDBC, fornecendo uma hierarquia de trace completa de ponta a ponta.

Modos de configuração

É possível configurar o OpenTelemetry no driver JDBC usando um dos seguintes modos, dependendo da arquitetura e dos requisitos do aplicativo.

Telemetria gerenciada por aplicativo

Se o aplicativo já usa o OpenTelemetry, é possível injetar a instância do OpenTelemetry no driver JDBC para garantir que a telemetria do driver esteja correlacionada com a telemetria do aplicativo.

Para isso, use a API BigQueryDataSource:

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

Suporte global ao OpenTelemetry

Se você inicializou o OpenTelemetry globalmente no aplicativo (por exemplo, usando o agente Java do OpenTelemetry ou chamando a função GlobalOpenTelemetry.set()), é possível configurar o driver para usar essa instância global.

Para ativar a instância global, defina a propriedade de conexão UseGlobalOpenTelemetry como TRUE.

Telemetria Cloud de Confiance sem configuração

Se você estiver executando no Cloud de Confiance e quiser uma configuração rápida, ative a exportação automática de traces e registros para a observabilidade do Cloud de Confiance (Trace e Logging).

Para ativar essa exportação, defina as seguintes propriedades de conexão no URL JDBC:

• EnableGcpTraceExporter=true
• EnableGcpLogExporter=true

Veja a seguir um exemplo de URL de conexão:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

Propriedades da conexão do OpenTelemetry

As propriedades de conexão a seguir são compatíveis com o OpenTelemetry. Para descrições detalhadas e valores padrão, consulte Propriedades de conexão.

• EnableGcpLogExporter
• EnableGcpTraceExporter
• GcpTelemetryCredentials
• GcpTelemetryProjectId
• UseGlobalOpenTelemetry

Considerações importantes

Ao implantar a integração do OpenTelemetry, lembre-se das seguintes considerações sobre o comportamento de geração de registros, a autenticação, a configuração de proxy e os preços.

Interação com LogLevel

A propriedade de conexão LogLevel atual atua como um guardião principal para a geração de registros.

• Se LogLevel=0 (OFF) estiver definido, nenhum registro será gerado. Consequentemente, nenhum registro é exportado usando o OpenTelemetry ou para o Logging, mesmo que EnableGcpLogExporter=true.
• Para ativar a geração de registros do OTel, verifique se LogLevel está definido como um valor maior que 0 (por exemplo, 5 para registros detalhados).

Autenticação para telemetria

A exportação de telemetria (rastreamento e geração de registros) com o fallback automático Cloud de Confiance é compatível com o Application Default Credentials (ADC) e com as credenciais explícitas da conta de serviço fornecidas usando GcpTelemetryCredentials.

Quando GcpTelemetryProjectId ou GcpTelemetryCredentials são fornecidos, os registros e os traces são enviados para o mesmo projeto de destino especificado usando as mesmas credenciais configuradas.

Configuração de proxy com OpenTelemetry e geração de registros

Se o aplicativo se conectar ao BigQuery por um servidor proxy, o driver vai processar o roteamento de proxy da seguinte maneira:

• Exportação de trace (HTTP). Quando você usa o protocolo HTTP padrão para exportação de traces do OpenTelemetry (otel.exporter.otlp.protocol=http/protobuf), o driver roteia automaticamente o tráfego de exportação de traces pelo proxy configurado nas propriedades de conexão usando ProxyHost e ProxyPort.

• Exportação de registros e telemetria gRPC. O exportador de registros automático do Cloud de Confiance (EnableGcpLogExporter=true) e os exportadores do OpenTelemetry baseados em gRPC (otel.exporter.otlp.protocol=grpc) usam gRPC, que não oferece suporte à configuração de proxy por conexão. Para rotear o tráfego de exportação de registros e telemetria gRPC por um servidor proxy, defina as configurações de proxy no nível da JVM usando as seguintes propriedades do sistema:

  -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

APIs e permissões do IAM necessárias

Para gravar dados de telemetria na observabilidade do Cloud de Confiance by S3NS , faça a seguinte configuração no projeto de destino do Cloud de Confiance :

1. Ative as APIs:
   • Ative a API Cloud Trace (cloudtrace.googleapis.com).
   • Ative a API Cloud Logging (logging.googleapis.com).
2. Conceda papéis do IAM:
   • Para exportar traces: conceda ao principal ou à conta de serviço o papel de agente do Trace (roles/cloudtrace.agent).
   • Para exportar registros: conceda ao principal ou à conta de serviço o papel de Gravador de registros (roles/logging.logWriter).

Preços e faturamento

Ao usar a telemetria de configuração zero do Cloud de Confiance (EnableGcpTraceExporter=true ou EnableGcpLogExporter=true), os dados de telemetria são enviados para o Trace e o Logging. Esses serviços podem gerar cobranças com base no volume de dados ingeridos. Para mais informações, consulte Google Cloud Observability.

Métricas

Essa integração não é compatível com as métricas do OpenTelemetry.

Sombreamento de dependência

Para evitar conflitos de caminho de classe com o aplicativo, o driver oculta as dependências do SDK e do exportador do OpenTelemetry. A API OpenTelemetry permanece sem sombreamento para permitir a interoperabilidade com o SDK fornecido pelo aplicativo.

Correlação de registros e traces

Quando o OpenTelemetry está ativado, o driver correlaciona automaticamente os registros com os traces:

• db.connection_id: anexado como um atributo de período a todos os períodos do JDBC.
• jdbc.connection_id: usado como uma chave de bagagem e anexado como um rótulo a todas as entradas de registro emitidas pelo driver para o Logging.
• ID do trace e ID do período: os registros gerados no escopo de uma execução de consulta incluem automaticamente os trace_id e span_id ativos.

Preços

É possível baixar o driver JDBC para BigQuery sem custo financeiro. No entanto, ao usar o driver, os preços padrão do BigQuery são aplicados.

A seguir

• Para mais instruções de configuração, manuais de referência de propriedades de URL de conexão, exemplos de código e instruções de build local, acesse o repositório de código aberto no GitHub:
  • Guia do usuário (docs/USER_GUIDE.md)
  • Guia para desenvolvedores (DEVELOPMENT.md)
  • Investigação das APIs BigQuery Storage (docs/STORAGE_APIS.md)
• Saiba mais sobre o driver ODBC para BigQuery.
• Conheça outras ferramentas para desenvolvedores do BigQuery.