Usar o driver JDBC para BigQuery

O driver Java Database Connectivity (JDBC) para BigQuery conecta seu aplicativo Java ao BigQuery, permitindo que você use recursos do BigQuery com suas ferramentas e infraestrutura preferidas. Ele foi projetado especificamente para o BigQuery e não pode ser usado com outros produtos ou serviços. Não é preciso ter licenças adicionais para usar esse driver.

Antes de começar

Confira se você conhece os drivers JDBC e o pacote java.sql.
Verifique se o sistema está configurado com o Java Runtime Environment (JRE) 8.0 ou posterior.

Configurar o driver

Para configurar o driver JDBC do BigQuery, instale o driver, faça a autenticação no BigQuery e estabeleça uma conexão.

Instalar o driver

Faça o download de um dos seguintes pacotes JDBC:
- Uber JAR. Um único arquivo JAR com todas as dependências incluídas.
- Thin JAR com dependências. Um arquivo ZIP que inclui um arquivo JAR thin com todas as dependências.
- JAR uber sombreado. Um único arquivo JAR com todas as dependências incluídas e sombreadas.
Adicione o arquivo JAR baixado ao seu caminho de classe para que o compilador e o tempo de execução do Java possam localizar as classes JDBC necessárias.

Autenticar-se no BigQuery

O driver JDBC para BigQuery oferece várias opções de autenticação:

usar uma conta de serviço
Usar uma conta de usuário do Google
Usar um token de acesso e de atualização pré-gerado
Como usar o Application Default Credentials
Usar um método externo

Autenticar com uma conta de serviço

Ao estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Defina a propriedade de conexão OAuthType como 0.
Defina a propriedade de conexão ProjectId com o nome do seu projeto do BigQuery.
Faça o seguinte:
- Se você estiver usando um e-mail e uma chave de conta de serviço, defina a propriedade de conexão OAuthServiceAcctEmail como o endereço de e-mail da sua conta de serviço do Google e a propriedade de conexão OAuthPvtKey como o objeto JSON da chave da conta de serviço. Para OAuthPvtKey, use o objeto JSON da chave ou o caminho completo do arquivo de chave.
- Se você estiver usando um arquivo de chave de conta de serviço, defina a propriedade de conexão OAuthPvtKeyPath como o caminho completo para o arquivo de chave da conta de serviço.

Os dois exemplos a seguir usam a autenticação de conta de serviço:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthServiceAcctEmail=bq-jdbc-sa@mytestproject.iam.gserviceaccount.com;
OAuthPvtKey=my-sa-key

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthPvtKeyPath=path/to/file/secret.json;

Autenticar com uma conta de usuário do Google

Ao estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Defina a propriedade de conexão OAuthType como 1.
Defina a propriedade de conexão ProjectId com o nome do seu projeto do BigQuery.
Defina a propriedade de conexão OAuthClientId como seu ID do cliente e a propriedade de conexão OAuthClientSecret como sua chave secreta do cliente.

Para mais informações, consulte Como usar o OAuth 2.0 para acessar as APIs do Google e Gerenciar clientes OAuth.

O exemplo a seguir usa a autenticação de conta de usuário do Google:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=1;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;

Fazer a autenticação com um token de acesso ou de atualização pré-gerado

Ao estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Defina a propriedade de conexão OAuthType como 2.
Defina a propriedade de conexão ProjectId com o nome do seu projeto do BigQuery.
Faça o seguinte:
- Se você estiver usando um token de acesso pré-gerado, defina a propriedade de conexão OAuthAccessToken como seu token de acesso.
- Se você estiver usando um token de atualização pré-gerado, defina a propriedade de conexão OAuthRefreshToken como seu token de atualização, a propriedade OAuthClientId como seu ID do cliente e a propriedade OAuthClientSecret como sua chave secreta do cliente.

Para mais informações, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

O exemplo a seguir usa a autenticação de token de acesso pré-gerado:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthAccessToken=ya29.a0AfH6SMCiH1L-x_yZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_;

O exemplo a seguir usa a autenticação de token de atualização pré-gerado:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;
OAuthRefreshToken=1/fFAGRNJru1FTz70BzhT3Zg;

Autenticar com o Application Default Credentials

O Application Default Credentials (ADC) é uma estratégia usada pelas bibliotecas de autenticação para encontrar credenciais automaticamente com base no ambiente do aplicativo.

Ao estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Defina a propriedade de conexão OAuthType como 3.
Defina a propriedade de conexão ProjectId com o nome do seu projeto do BigQuery.

Para mais informações, consulte Configurar o Application Default Credentials.

O exemplo a seguir usa a autenticação do ADC:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=3;

Autenticar com um método externo

É possível autenticar com métodos externos, como a federação de identidade da força de trabalho ou a federação de identidade da carga de trabalho.

Ao estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Defina a propriedade de conexão OAuthType como 4.
Defina a propriedade de conexão ProjectId com o nome do seu projeto do BigQuery.
Faça o seguinte:
- Defina a propriedade de conexão OAuthPvtKey ou OAuthPvtKeyPath como o caminho completo do arquivo de configuração. Para OAuthPvtKey, use o objeto JSON da chave ou o caminho completo do arquivo de chave.
- Defina a propriedade de conexão OAuthPvtKey como o objeto de configuração da conta externa bruta.
- Defina as seguintes propriedades de conexão BYOID, que são descritas na seção propriedades de conexão:
  - BYOID_AudienceUri
  - BYOID_CredentialSource
  - BYOID_PoolUserProject
  - BYOID_SA_Impersonation_Uri
  - BYOID_SubjectTokenType
  - BYOID_TokenUri

Os exemplos a seguir usam métodos de autenticação externos:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKeyPath=path/to/file/secret.json;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKey=External_account_configuration_object;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
BYOID_AudienceUri=//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider;
BYOID_SubjectTokenType=urn:ietf:params:oauth:tokentype:id_token;
BYOID_CredentialSource={\"file\":\"/path/to/file\"};
BYOID_SA_Impersonation_Uri=my-sa;
BYOID_TokenUri=https://sts.googleapis.com/v1/token;"

Confira a seguir um exemplo de arquivo de configuração:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/my_pool_name/providers/my_provider_name",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "/path/to/workforce/tokrn.txt"
  },
  "workforce_pool_user_project": "my_project",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

Estabelecer uma conexão

Para estabelecer uma conexão com o driver JDBC do BigQuery, faça o seguinte:

Adicione a dependência google-cloud-bigquery-jdbc ao arquivo de build do Maven POM/Gradle:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>0.0.1</version>
    <scope>system</scope>
    <systemPath>path/to/file/google-jdbc-jar-with-dependencies.jar</systemPath>
</dependency>

Se você estiver usando um projeto do Gradle, adicione o seguinte ao arquivo de build também:

dependencies {
// ... other dependencies
implementation files('path/to/file/google-jdbc-jar-with-dependencies.jar')
}

Identifique a string de conexão do driver JDBC. Essa string captura todas as informações essenciais necessárias para estabelecer uma conexão entre seu aplicativo Java e um banco de dados específico. O driver JDBC para a string de conexão do BigQuery tem o seguinte formato:
```
jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;PROPERTIES
```
Substitua:
- HOST: o DNS ou o endereço IP do servidor.
- PORT: o número da porta TCP.
- PROJECT_ID: o ID do seu projeto do BigQuery.
- AUTH_TYPE: um número que especifica o tipo de autenticação usado. Uma das seguintes opções:
  - 0: autenticação da conta de serviço do Google
  - 1: autenticação de conta de usuário do Google
  - 2: autenticação de token de atualização ou token de acesso pré-gerado
  - 3: autenticação de Application Default Credential
  - 4: métodos de autenticação externa, como federação de identidade de colaboradores ou federação de identidade da carga de trabalho
- PROPERTIES: propriedades de conexão adicionais para o driver JDBC. As propriedades precisam ser listadas no formato property_1=value_1; property_2=value_2;.... Os nomes das propriedades não diferenciam maiúsculas de minúsculas. Para uma lista completa de propriedades de conexão, consulte Propriedades de conexão.

Conecte-se ao driver com a classe DriverManager ou DataSource.

Conecte-se à 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 à 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 incluir todas as propriedades na string de conexão. Confira o seguinte exemplo:

private static Connection getConnection() throws SQLException {
  DataSource ds = new DataSource();
  ds.setURL(CONNECTION_STRING);
  ds.setAuthType(3);  // Application Default Credentials
  ds.setProjectId("MyTestProject");
  ds.setEnableHighThroughputAPI(true);
  ds.setLogLevel("6");
  ds.setUseQueryCache(false);
  return ds.getConnection();
}

Conhecer os recursos para motoristas

Agora que você está conectado ao driver JDBC do BigQuery, pode conhecer os recursos dele.

Conector SQL

Com o conector SQL, é possível executar consultas SQL com o BigQuery. Use a propriedade de conexão QueryDialect para especificar o dialeto SQL que você quer usar.

Mapeamento de tipo de dados

O driver JDBC para BigQuery é compatível com os seguintes mapeamentos de tipo de dados:

Tipo do BigQuery	Tipo de SQL	Tipo Java
`ARRAY`	`ARRAY`	`Array`
`BIGNUMERIC`	`NUMERIC`	`BigDecimal`
`BOOL`	`BOOLEAN`	`Boolean`
`BYTES`	`VARBINARY`	`byte[]`
`DATE`	`DATE`	`Date`
`DATETIME`	`OTHER`	`String`
`FLOAT64`	`DOUBLE`	`Double`
`GEOGRAPHY`	`OTHER`	`String`
`INT64`	`BIGINT`	`Long`
`INTERVAL`	`OTHER`	`String`
`JSON`	`OTHER`	`String`
`NUMERIC`	`NUMERIC`	`BigDecimal`
`STRING`	`NVARCHAR`	`String`
`STRUCT`	`STRUCT`	`Struct`
`TIME`	`TIME`	`Time`
`TIMESTAMP`	`TIMESTAMP`	`Timestamp`

Registros aninhados e repetidos

O driver JDBC para BigQuery é compatível com registros aninhados e repetidos, em que o driver retorna o tipo básico como um objeto struct ou uma representação de string de um objeto JSON.

Confira a seguir um exemplo de consulta do 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 resultado é o seguinte:

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

Confira a seguir um exemplo de consulta de 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());
    }

Confira um exemplo de consulta de uma matriz padrão de dados repetidos:

// 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]);
}

Confira um exemplo de consulta de uma matriz de struct de dados repetidos:

// 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]);
}

Grande conjunto de resultados

Para recuperar conjuntos de resultados grandes ao usar o driver JDBC para BigQuery, faça o seguinte:

Se a propriedade de conexão QueryDialect estiver definida como SQL, especifique um conjunto de dados e uma tabela para armazenar os resultados com as propriedades de conexão LargeResultDataset e LargeResultTable.
Se a propriedade de conexão do QueryDialect estiver definida como BIG_QUERY, defina a propriedade de conexão do AllowLargeResults como TRUE e especifique um conjunto de dados e uma tabela para armazenar os resultados com as propriedades de conexão LargeResultDataset e LargeResultTable.

Em ambos os casos, você pode usar a propriedade de conexão LargeResultsDatasetExpirationTime para especificar a duração do ciclo de vida do conjunto de dados de destino.

Se você não especificar valores para as propriedades de conexão LargeResultDataset e LargeResultTable, o driver JDBC para BigQuery vai criar um conjunto de dados oculto chamado _google_jdbc e uma tabela temporária nele. Esses recursos são excluídos automaticamente após 24 horas.

Todas as cotas e limites do BigQuery ainda são válidas.

Parâmetros posicionais

Os parâmetros posicionais são marcadores de posição em uma instrução SQL que representam valores a serem fornecidos durante a execução da consulta. O driver JDBC para BigQuery é compatível com parâmetros posicionais com o símbolo de ponto de interrogação (?). Veja um exemplo de consulta que usa um parâmetro posicional:

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

`SELECT` consultas

Use o driver JDBC para BigQuery e execute consultas SELECT com a API BigQuery ou a API BigQuery Storage Read.

Se você usar a API BigQuery, defina a propriedade de conexão JobCreationMode para especificar se a consulta será executada com ou sem a criação de um job.

Se você usa a API Storage Read, use a propriedade de conexão EnableHighThroughputAPI para ativar a API e verificar se as seguintes condições são atendidas:

O esquema não usa o tipo INTERVAL.
O número total de linhas é menor que o valor da propriedade de conexão HighThroughputMinTableSize.
A proporção de linhas para tamanho da página é menor que o valor da propriedade de conexão HighThroughputActivationRatio.

Inserção em massa

Para realizar operações de inserção em massa com o driver JDBC para BigQuery, use o método executeBatch.

Confira um exemplo de operação de gravação:

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

O driver JDBC para BigQuery é compatível com ações de geração de registros no driver usando o Java Util Logging. O registro em log pode afetar o desempenho. Portanto, ative-o apenas para capturar um problema e desative-o depois de terminar.

Para configurar a geração de registros, faça o seguinte:

Defina a propriedade LogLevel de acordo com a tabela a seguir:

Valor `LogLevel`	`LogLevel`	Descrição
`0`	`OFF`	Nenhuma mensagem é registrada.
`1`	`SEVERE`	Falhas ou erros graves que afetam a funcionalidade do aplicativo.
`2`	`WARNING`	Possíveis problemas ou situações que podem exigir atenção.
`3`	`INFO`	Mensagens informativas sobre eventos e progresso normais.
`4`	`CONFIG`	Mensagens sobre informações de configuração estática.
`5`	`FINE`	Mensagens gerais de rastreamento.
`6`	`FINER`	Mensagens de rastreamento detalhadas.
`7`	`FINEST`	Mensagens de rastreamento altamente detalhadas, úteis para depuração extensa.
`8`	`ALL`	Todas as mensagens são registradas.

Defina a propriedade LogPath como o caminho completo da pasta em que você quer salvar o arquivo de registro.

Como alternativa, é possível configurar o registro em log com as variáveis de ambiente BIGQUERY_JDBC_LOG_LEVEL e BIGQUERY_JDBC_LOG_PATH.

Propriedades da conexão

Em um driver JDBC, as propriedades de conexão são parâmetros de configuração que você pode incluir na string de conexão ou transmitir pelos 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.

AdditionalProjects

Essa propriedade de conexão permite que consultas e operações de metadados acessem conjuntos de dados em projetos especificados, além do projeto principal definido na string de conexão.

Valor padrão: N/A
Tipo de dados: string (string de IDs de projetos separados por vírgulas)
Obrigatório: não

AllowLargeResults

Essa propriedade de conexão especifica se o driver processa resultados de consultas maiores que 128 MB quando a propriedade de conexão QueryDialect é definida como BIG_QUERY. Se a propriedade de conexão QueryDialect estiver definida como SQL, a propriedade AllowLargeResults será definida como TRUE por padrão. Para mais informações, consulte Conjunto de resultados grande.

Valor padrão: TRUE
Tipo de dados: booleano
Obrigatório: não

BYOID_AudienceUri

Essa propriedade de conexão especifica a propriedade de público-alvo em um arquivo de configuração de conta externa. A propriedade "audiência" contém o nome do recurso para o pool de identidades da carga de trabalho ou o pool de funcionários e o identificador do provedor nesse pool.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: somente quando OAuthType=4

BYOID_CredentialSource

Essa propriedade de conexão define informações de recuperação de token e informações ambientais.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: somente quando OAuthType=4

BYOID_PoolUserProject

Essa propriedade de conexão define o projeto do usuário quando o pool de força de trabalho está sendo usado. O projeto precisa ter a permissão serviceusage.services.use do IAM.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: somente quando OAuthType=4 e usando o pool de força de trabalho

BYOID_SA_Impersonation_Uri

Essa propriedade de conexão define o URL para a representação da conta de serviço quando pools de identidades de carga de trabalho estão sendo usados e as APIs não foram integradas ao UberMint.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: somente quando OAuthType=4 e usando o pool de identidades da carga de trabalho com representação da conta de serviço

BYOID_SubjectTokenType

Essa propriedade de conexão define o token do STS com base na especificação de troca de token. O valor precisa ser um dos indicados abaixo:

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
Valor padrão: urn:ietf:params:oauth:tokentype:id_token
Tipo de dados: string
Obrigatório: somente quando OAuthType=4

BYOID_TokenUri

Essa propriedade de conexão define o endpoint de troca de token do STS.

Valor padrão: https://sts.googleapis.com/v1/token
Tipo de dados: string
Obrigatório: não

ConnectionPoolSize

Essa propriedade define o tamanho do pool de conexões se o agrupamento de conexões estiver ativado.

Valor padrão: 10
Tipo de dados: Long
Obrigatório: não

DefaultDataset

Essa propriedade de conexão especifica o conjunto de dados usado quando você executa uma consulta sem especificar explicitamente um conjunto de dados. É possível usar o formato DATASET_ID ou PROJECT_ID.DATASET_ID.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

EnableHighThroughputAPI

Essa propriedade de conexão determina se a API Storage Read pode ser usada. As propriedades de conexão HighThroughputActivationRatio e HighThroughputMinTableSize também precisam ser atendidas para usar a API Storage Read.

Valor padrão: FALSE
Tipo de dados: booleano
Obrigatório: não

EnableSession

Essa propriedade determina se a conexão inicia uma sessão. Quando usado, o ID da sessão é transmitido para todas as consultas subsequentes.

Valor padrão: FALSE
Tipo de dados: booleano
Obrigatório: não

EnableWriteAPI

Essa propriedade de conexão determina se a API Storage Write pode ser usada. Ele precisa ser definido como TRUE para ativar as inserções em massa.

Valor padrão: FALSE
Tipo de dados: booleano
Obrigatório: não

EndpointOverrides

Essa propriedade de conexão define endpoints personalizados em uma string separada por vírgulas.

Valores padrão:
- BIGQUERY=https://bigquery.googleapis.com
- READ_API=https://bigquerystorage.googleapis.com
- OAUTH2=https://oauth2.googleapis.com
- STS=https://sts.googleapis.com
Tipo de dados: string
Obrigatório: não

FilterTablesOnDefaultDataset

Essa propriedade de conexão controla o escopo dos metadados retornados pelos métodos DatabaseMetaData.getTables() e DatabaseMetaData.getColumns(). Quando a propriedade está desativada, não há filtragem. A propriedade de conexão DefaultDataset também precisa ser definida para ativar a filtragem.

Valor padrão: FALSE
Tipo de dados: booleano
Obrigatório: não

HighThroughputActivationRatio

Essa propriedade de conexão define um limite para o número de páginas em uma resposta de consulta. Quando esse número é excedido e as condições EnableHighThroughputAPI e HighThroughputMinTableSize são atendidas, o driver começa a usar a API Storage Read.

Valor padrão: 2
Tipo de dado: inteiro
Obrigatório: não

HighThroughputMinTableSize

Essa propriedade de conexão define um limite para o número de linhas em uma resposta de consulta. Quando esse número é excedido e as condições EnableHighThroughputAPI e HighThroughputActivationRatio são atendidas, o driver começa a usar a API Storage Read.

Valor padrão: 100
Tipo de dado: inteiro
Obrigatório: não

JobCreationMode

Essa propriedade de conexão determina se as consultas são executadas sem a criação de jobs. Um valor 1 significa que os jobs são criados para cada consulta, e um valor 2 significa que as consultas podem ser executadas sem jobs.

Valor padrão: 2
Tipo de dado: inteiro
Obrigatório: não

JobTimeout

Essa propriedade de conexão define o tempo limite do job (em segundos) após o qual ele é cancelado no servidor.

Valor padrão: 0
Tipo de dados: Long
Obrigatório: não

KMSKeyName

Essa propriedade de conexão define o nome da chave do KMS para criptografar dados.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

Labels

Essa propriedade de conexão define rótulos associados à consulta para organizar e agrupar jobs de consulta.

Valor padrão: N/A
Tipo de dados: Map<String, String>
Obrigatório: não

LargeResultDataset

Essa propriedade de conexão define o conjunto de dados de destino para os resultados da consulta. Para mais informações, consulte Conjunto de resultados grande.

Valor padrão: _google_jdbc, somente quando QueryDialect=BIG_QUERY ou quando QueryDialect=SQL e a propriedade de conexão LargeResultTable está definida
Tipo de dados: string
Obrigatório: não

LargeResultsDatasetExpirationTime

Essa propriedade de conexão especifica o ciclo de vida de todas as tabelas em um conjunto de dados, em milissegundos. Essa propriedade será ignorada se o conjunto de dados já tiver um tempo de validade padrão definido.

Valor padrão: 3600000
Tipo de dados: Long
Obrigatório: não

LargeResultTable

Essa propriedade de conexão define a tabela de destino para os resultados da consulta. Para mais informações, consulte Conjunto de resultados grande.

Valor padrão: temp_table..., somente quando QueryDialect=BIG_QUERY ou quando QueryDialect=SQL e a propriedade de conexão LargeResultTable está definida
Tipo de dados: string
Obrigatório: não

ListenerPoolSize

Essa propriedade de conexão define o tamanho do pool de listeners se o pooling de conexões estiver ativado.

Valor padrão: 10
Tipo de dados: Long
Obrigatório: não

Location

Essa propriedade de conexão especifica o local em que os conjuntos de dados são criados ou consultados. O BigQuery determina automaticamente a região se esse valor não for definido.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

LogLevel

Essa propriedade de conexão controla o nível de detalhes registrados durante as interações com o banco de dados. Para descrições de nível, consulte Logging.

Valor padrão: 0
Tipo de dado: inteiro
Obrigatório: não

LogPath

Essa propriedade de conexão define o diretório em que os arquivos de registro são gravados. Para mais detalhes, consulte Registro em registros.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

MaximumBytesBilled

Essa propriedade de conexão limita o número de bytes faturados. As consultas com bytes faturados maiores que esse limite falham sem gerar cobranças.

Valor padrão: 0
Tipo de dados: Long
Obrigatório: não

MaxResults

Essa propriedade de conexão define o número máximo de resultados por página.

Valor padrão: 10000
Tipo de dados: Long
Obrigatório: não

MetaDataFetchThreadCount

Essa propriedade de conexão configura o número de linhas de execução usadas para métodos de metadados do banco de dados.

Valor padrão: 32
Tipo de dado: inteiro
Obrigatório: não

OAuthAccessToken

Essa propriedade de conexão especifica o token de acesso usado para autenticação de token de acesso pré-gerado.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=2

OAuthClientId

Essa propriedade de conexão define o ID do cliente para autenticação de token de atualização pré-gerado e autenticação de conta de usuário.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=1 ou AUTH_TYPE=2

OAuthClientSecret

Essa propriedade de conexão define a chave secreta do cliente para autenticação de token de atualização pré-gerado e autenticação de conta de usuário.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=1 ou AUTH_TYPE=2

OAuthP12Password

Essa propriedade de conexão define a senha do arquivo de chave PKCS12.

Valor padrão: notasecret
Tipo de dados: string
Obrigatório: não

OAuthPvtKey

Essa propriedade de conexão define a chave da conta de serviço ao usar a autenticação da conta de serviço. Esse valor pode ser um objeto de arquivo de chave JSON bruto ou um caminho para o arquivo de chave JSON.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=0 e o valor OAuthPvtKeyPath não estão definidos

OAuthPvtKeyPath

Essa propriedade de conexão define o caminho para a chave da conta de serviço ao usar a autenticação de conta de serviço.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=0 e os valores OAuthPvtKey e OAuthServiceAcctEmail não estão definidos

OAuthRefreshToken

Essa propriedade de conexão define o token de atualização para autenticação de token de atualização pré-gerado. Um token de atualização do OAuth 2.0 é um tipo especial de token que permite que um aplicativo obtenha um novo token de acesso quando o atual expira, sem exigir que o usuário se autentique novamente.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=2

OAuthServiceAcctEmail

Essa propriedade de conexão define o e-mail da conta de serviço ao usar a autenticação de conta de serviço.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: quando AUTH_TYPE=0 e o valor OAuthPvtKeyPath não estão definidos

OAuthType

Essa propriedade de conexão especifica o tipo de autenticação. O valor precisa ser um dos indicados abaixo:

0: autenticação da conta de serviço do Google
1: autenticação de conta de usuário do Google
2: autenticação de token de atualização ou token de acesso pré-gerado
3: autenticação de Application Default Credential
4: métodos de autenticação externos, como a federação de identidade de colaboradores ou a federação de identidade da carga de trabalho
Valor padrão: -1
Tipo de dado: inteiro
Obrigatório: sim

PartnerToken

Essa propriedade de conexão é usada por parceiros do Google Cloud para rastrear o uso do driver.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

PrivateServiceConnectUris

Essa propriedade de conexão é idêntica à propriedade EndpointOverrides. Use a propriedade EndpointOverrides.

ProjectId

Essa propriedade de conexão define o ID do projeto padrão para o driver. Esse projeto é usado para executar consultas e é cobrado pelo uso de recursos. Se não for definido, o driver vai inferir um ID do projeto.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não, mas altamente recomendado

ProxyHost

Essa propriedade de conexão define o nome do host ou o endereço IP de um servidor proxy pelo qual a conexão JDBC é encaminhada.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

ProxyPort

Essa propriedade de conexão define o número da porta em que o servidor proxy está aguardando conexões.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

ProxyPwd

Essa propriedade de conexão define a senha necessária para autenticação ao se conectar por um servidor proxy que a exige.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

ProxyUid

Essa propriedade de conexão define o nome de usuário necessário para autenticação ao se conectar por um servidor proxy que exige isso.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

QueryDialect

Essa propriedade de conexão define o dialeto SQL para execução de consultas. Use SQL para o GoogleSQL (altamente recomendado) e BIG_QUERY para o SQL legado.

Valor padrão: SQL
Tipo de dados: string
Obrigatório: não

QueryProperties

Essa propriedade de conexão configura modificações no comportamento da consulta.

Confira um exemplo definido na string de conexão:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
QueryProperties=dataset_project_id=TestProjectID,time_zone=America/New_York;

Confira um exemplo definido na classe DataSource:

Map<String, String> queryProperties = new HashMap<>();
queryProperties.put("dataset_project_id", "TestProjectID");
queryProperties.put("time_zone", "America/New_York");
DataSource dataSource = new DataSource();
dataSource.setQueryProperties(queryProperties);

Para mais detalhes, consulte ConnectionProperty.

Valor padrão: N/A
Tipo de dados: Map<String, String>
Obrigatório: não

RequestGoogleDriveScope

Essa propriedade de conexão é usada para pedir acesso ao Google Drive. Quando ativado, o escopo somente leitura do Drive é adicionado à conexão. Para ativar essa propriedade, defina o valor como 1.

Valor padrão: 0
Tipo de dado: inteiro
Obrigatório: não

RetryInitialDelay

Essa propriedade de conexão define o atraso (em segundos) antes da primeira tentativa.

Valor padrão: 0
Tipo de dados: Long
Obrigatório: não

RetryMaxDelay

Essa propriedade de conexão define o limite máximo (em segundos) para o atraso da nova tentativa.

Valor padrão: 0
Tipo de dados: Long
Obrigatório: não

ServiceAccountImpersonationChain

Essa propriedade de conexão especifica uma lista separada por vírgulas de e-mails de conta de serviço na cadeia de representação.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

ServiceAccountImpersonationEmail

Essa propriedade de conexão define o e-mail da conta de serviço a ser personificada.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

ServiceAccountImpersonationScopes

Essa propriedade de conexão especifica uma lista separada por vírgulas de escopos do OAuth2 a serem usados com a conta representada.

Valor padrão: https://www.googleapis.com/auth/bigquery
Tipo de dados: string
Obrigatório: não

ServiceAccountImpersonationTokenLifetime

Essa propriedade de conexão define o tempo de vida do token da conta representada (em segundos).

Valor padrão: 3600
Tipo de dado: inteiro
Obrigatório: não

SSLTrustStore

Essa propriedade de conexão especifica o caminho completo para o Java TrustStore que contém certificados confiáveis da autoridade de certificação (CA). O driver usa esse truststore para validar a identidade do servidor durante o handshake de SSL/TLS.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: não

SSLTrustStorePwd

Essa propriedade de conexão especifica a senha do Java TrustStore especificado na propriedade SSLTrustStore.

Valor padrão: N/A
Tipo de dados: string
Obrigatório: apenas se você estiver usando um TrustStore Java protegido por senha

SWA_ActivationRowCount

Essa propriedade de conexão define um número limite de linhas executeBatch insert que, quando excedido, faz com que o conector mude para a API Storage Write.

Valor padrão: 3
Tipo de dado: inteiro
Obrigatório: não

SWA_AppendRowCount

Essa propriedade de conexão define o tamanho do fluxo de gravação.

Valor padrão: 1000
Tipo de dado: inteiro
Obrigatório: não

Timeout

Essa propriedade de conexão define o período de tempo, em segundos, em que o conector tenta novamente uma chamada de API com falha antes de atingir o tempo limite.

Valor padrão: 0
Tipo de dados: Long
Obrigatório: não

UniverseDomain

Essa propriedade de conexão define o domínio do universo, o domínio de nível superior associado aos recursos Google Cloud da sua organização.

Valor padrão: googleapis.com
Tipo de dados: string
Obrigatório: não

UnsupportedHTAPIFallback

Essa propriedade de conexão determina se o conector volta para a API REST (quando definida como TRUE) ou retorna um erro (quando definida como FALSE).

Valor padrão: TRUE
Tipo de dados: booleano
Obrigatório: não

UseQueryCache

Essa propriedade de conexão ativa o cache de consultas.

Valor padrão: TRUE
Tipo de dados: booleano
Obrigatório: não

Usar o driver JDBC para BigQuery

Antes de começar

Configurar o driver

Instalar o driver

Autenticar-se no BigQuery

Autenticar com uma conta de serviço

Autenticar com uma conta de usuário do Google

Fazer a autenticação com um token de acesso ou de atualização pré-gerado

Autenticar com o Application Default Credentials

Autenticar com um método externo

Estabelecer uma conexão

Conhecer os recursos para motoristas

Conector SQL

Mapeamento de tipo de dados

Registros aninhados e repetidos

Grande conjunto de resultados

Parâmetros posicionais

SELECT consultas

Inserção em massa

Logging

Propriedades da conexão

`SELECT` consultas