Usar o driver JDBC para BigQuery

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

Limitações

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

Antes de começar

  1. Confira 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 posterior. Para informações sobre como verificar sua versão do JRE, consulte Verificar o ambiente JRE.

  3. Autentique-se no BigQuery e anote as seguintes informações, que serão usadas mais tarde ao estabelecer uma conexão com o driver JDBC 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 E-mail da conta de serviço bq-jdbc-sa@mytestproject.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 do Workforce) my-sa BYOID_SA_Impersonation_Uri
    Token do Security Token Service com base na especificação de troca de token urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    Endpoint de troca de token do Security Token Service https://sts.googleapis.com/v1/token BYOID_TokenUri

Configurar seu ambiente de desenvolvimento

Para configurar seu ambiente de desenvolvimento com o driver JDBC para o BigQuery, faça o seguinte:

  1. Faça o download de um dos seguintes pacotes JDBC:

  2. 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. Para informações sobre como adicionar um arquivo ao classpath, consulte Como definir o classpath.

  3. Adicione a seguinte dependência ao seu arquivo de build:

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

  4. Se você estiver usando um projeto do Gradle, adicione o seguinte ao arquivo de build:

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

Estabelecer uma conexão

Para estabelecer uma conexão entre seu 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 seu 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 seu projeto do BigQuery.
    • AUTH_TYPE: um número que especifica o tipo de autenticação usado. Uma das seguintes opções:
      • 0: para autenticação de conta de serviço (padrão e arquivo de chave)
      • 1: para autenticação de contas de usuário do Google
      • 2: para autenticação de token de acesso ou atualização pré-gerado
      • 3: para autenticação de Application Default Credentials
      • 4: para outros métodos de autenticação
    • AUTH_PROPS: as informações de autenticação que você anotou ao fazer a autenticação no BigQuery, listadas no formato property_1=value_1; property_2=value_2;.... Por exemplo, OAuthPvtKeyPath=path/to/file/secret.json, se você fez 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 à 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 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.

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
AllowLargeResults Determina se o driver processa resultados de consultas maiores que 128 MB quando a propriedade QueryDialect está definida como BIG_QUERY. Se a propriedade QueryDialect estiver definida como SQL, o driver sempre processará resultados de consultas grandes. TRUE Booleano Não
BYOID_AudienceUri A propriedade de público-alvo em um arquivo de configuração de conta externa. A propriedade "audiência" pode conter o nome do recurso do pool de identidades da carga de trabalho ou do pool da força de trabalho, bem como o identificador do provedor nesse pool. N/A String Somente quando OAuthType=4
BYOID_CredentialSource A recuperação de token e as informações ambientais. N/A String Somente quando OAuthType=4
BYOID_PoolUserProject O projeto do usuário quando um pool de força de trabalho é usado para autenticação. N/A String Somente quando OAuthType=4 e usando o pool de força de trabalho
BYOID_SA_Impersonation_Uri O URI para a identidade temporária de conta de serviço quando um pool de força de trabalho está sendo usado para autenticação. N/A String Somente quando OAuthType=4 e usando o pool de força de trabalho
BYOID_SubjectTokenType O token do Security Token Service com base na especificação de troca de token. Uma das seguintes opções:
  • 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
 urn:ietf:params:oauth:tokentype:id_token String Somente quando OAuthType=4
BYOID_TokenUri O endpoint de troca de token do Security Token Service. https://sts.googleapis.com/v1/token String Não
ConnectionPoolSize O tamanho do pool de conexões, se o agrupamento de conexões estiver ativado. 10 Longo Não
DefaultDataset O conjunto de dados usado quando não é especificado um em uma consulta. N/A String Não
EnableHighThroughputAPI Determina se a API Storage Read pode ser usada. As propriedades HighThroughputActivationRatio e HighThroughputMinTableSize também precisam ser definidas como TRUE para usar a API Storage Read. FALSE Booleano Não
EnableSession Determina se a conexão inicia uma sessão. Se definido como TRUE, o ID da sessão será transmitido para todas as consultas subsequentes. FALSE Booleano Não
EnableWriteAPI Determina se a API Storage Write pode ser usada. Ele precisa ser definido como TRUE para ativar as inserções em massa. FALSE Booleano Não
EndpointOverrides Endpoints personalizados para substituir o seguinte:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
 N/A String separada por vírgulas Não
FilterTablesOnDefaultDataset Determina o escopo dos metadados retornados pelos métodos DatabaseMetaData.getTables() e DatabaseMetaData.getColumns(). Quando definido como FALSE, não há filtragem. A propriedade DefaultDataset também precisa ser definida para ativar a filtragem. FALSE Booleano Não
HighThroughputActivationRatio O 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. 2 Número inteiro Não
HighThroughputMinTableSize O 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. 100 Número inteiro Não
JobCreationMode Determina se as consultas são executadas com ou sem 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. 2 Número inteiro Não
JobTimeout O tempo limite do job (em segundos) após o qual o job é cancelado no servidor. 0 Longo Não
KMSKeyName O nome da chave do KMS para criptografar dados. N/A String Não
Labels Rótulos associados à consulta para organizar e agrupar jobs de consulta. N/A Map<String, String> Não
LargeResultDataset O conjunto de dados de destino para resultados de consultas extensas, somente quando a propriedade LargeResultTable está definida. Quando você define essa propriedade, as gravações de dados ignoram o cache de resultados e acionam o faturamento de cada consulta, mesmo que os resultados sejam pequenos. _google_jdbc String Não
LargeResultsDatasetExpirationTime O ciclo de vida de todas as tabelas em um grande conjunto de dados de resultados, em milissegundos. Essa propriedade será ignorada se o conjunto de dados já tiver um prazo de validade padrão definido. 3600000 Longo Não
LargeResultTable A tabela de destino para resultados de consultas grandes, somente quando a propriedade LargeResultDataset está definida. Quando você define essa propriedade, as gravações de dados ignoram o cache de resultados e acionam o faturamento de cada consulta, mesmo que os resultados sejam pequenos. temp_table... String Não
ListenerPoolSize O tamanho do pool de listeners, se o agrupamento de conexões estiver ativado. 10 Longo Não
Location O local em que os conjuntos de dados são criados ou consultados. O BigQuery determina automaticamente o local se essa propriedade não estiver definida. N/A String Não
LogLevel O nível de detalhe registrado pelo pacote java.util.logging durante as interações com o banco de dados. O registro em log pode afetar o desempenho. Portanto, ative-o temporariamente para capturar um problema. Uma das seguintes opções:
  • 0: o nível OFF
  • 1: o nível SEVERE
  • 2: o nível WARNING
  • 3: o nível INFO
  • 4: o nível CONFIG
  • 5: o nível FINE
  • 6: o nível FINER
  • 7: o nível FINEST
  • 8: o nível ALL
 0 Número inteiro Não
LogPath O diretório em que os arquivos de registro são gravados. N/A String Não
MaximumBytesBilled O limite de bytes faturados. Consultas com bytes faturados maiores que esse número falham sem gerar cobranças. 0 Longo Não
MaxResults O número máximo de resultados por página. 10000 Longo Não
MetaDataFetchThreadCount O número de linhas de execução usadas para métodos de metadados do banco de dados. 32 Número inteiro Não
OAuthAccessToken O token de acesso usado para autenticação de token de acesso pré-gerado. N/A String Somente quando OAUTH_TYPE=2
OAuthClientId O ID do cliente para autenticação de token de atualização pré-gerado e autenticação de conta de usuário. N/A String Somente quando OAUTH_TYPE=1 ou OAUTH_TYPE=2
OAuthClientSecret A chave secreta do cliente para autenticação de token de atualização pré-gerado e autenticação de conta de usuário. N/A String Somente quando OAUTH_TYPE=1 ou OAUTH_TYPE=2
OAuthP12Password A senha do arquivo de chave PKCS12. notasecret String Não
OAuthPvtKey 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. N/A String Somente quando OAUTH_TYPE=0 e o valor de OAuthPvtKeyPath não estão definidos
OAuthPvtKeyPath 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 OAUTH_TYPE=0 e os valores OAuthPvtKey e OAuthServiceAcctEmail não estão definidos
OAuthRefreshToken O token de atualização para autenticação de token de atualização pré-gerado. N/A String Somente quando OAUTH_TYPE=2
OAuthServiceAcctEmail O e-mail da conta de serviço ao usar a autenticação da conta de serviço. N/A String Somente quando OAUTH_TYPE=0 e o valor de OAuthPvtKeyPath não estão definidos
OAuthType O tipo de autenticação. Uma das seguintes opções:
  • 0: autenticação da conta de serviço
  • 1: autenticação da conta de usuário
  • 2: autenticação de token de atualização ou token de acesso pré-gerado
  • 3: autenticação de Application Default Credential
  • 4: outros métodos de autenticação
 -1 Número inteiro Sim
PartnerToken Um token usado por parceiros Google Cloud para rastrear o uso do driver. N/A String Não
ProjectId O ID do projeto padrão para o driver. Esse projeto é usado para executar consultas e é cobrado pelo uso de recursos. Se não estiver definido, o driver vai inferir um ID do projeto. N/A String Não, mas é altamente recomendável
ProxyHost O nome do host ou o endereço IP de um servidor proxy por onde a conexão JDBC é encaminhada. N/A String Não
ProxyPort O número da porta em que o servidor proxy está aguardando conexões. N/A String Não
ProxyPwd A senha para autenticação ao se conectar por um servidor proxy que a exige. N/A String Não
ProxyUid O nome de usuário para autenticação ao se conectar por um servidor proxy que exige isso. N/A String Não
QueryDialect O dialeto SQL para execução de consultas. Use SQL para o GoogleSQL (altamente recomendado) e BIG_QUERY para o SQL legado. SQL String Não
QueryProperties Propriedades de conexão REST que personalizam o comportamento da consulta. N/A Map<String, String> Não
RequestGoogleDriveScope Adiciona o escopo somente leitura do Drive à conexão quando definido como 1. 0 Número inteiro Não
RetryInitialDelay Define o atraso (em segundos) antes da primeira tentativa. 0 Longo Não
RetryMaxDelay Define o limite máximo (em segundos) para o atraso da nova tentativa. 0 Longo Não
ServiceAccountImpersonationChain Uma lista separada por vírgulas de e-mails de conta de serviço na cadeia de representação. N/A String Não
ServiceAccountImpersonationEmail O e-mail da conta de serviço a ser personificada. N/A String Não
ServiceAccountImpersonationScopes Uma lista separada por vírgulas de escopos do OAuth2 a serem usados com a conta representada. https://www.googleapis.com/auth/bigquery String Não
ServiceAccountImpersonationTokenLifetime A vida útil do token da conta representada (em segundos). 3600 Número inteiro Não
SSLTrustStore O caminho completo para o Java TrustStore que contém certificados confiáveis da autoridade certificadora (CA). O driver usa esse truststore para validar a identidade do servidor durante o handshake SSL/TLS. N/A String Não
SSLTrustStorePwd A senha do TrustStore Java especificado na propriedade SSLTrustStore. N/A String Somente se o TrustStore do Java for protegido por senha
SWA_ActivationRowCount O limite de executeBatch insert linhas que, quando excedido, faz com que o conector mude para a API Storage Write. 3 Número inteiro Não
SWA_AppendRowCount O tamanho do fluxo de gravação. 1000 Número inteiro Não
Timeout O período, em segundos, em que o conector tenta novamente uma chamada de API com falha antes de atingir o tempo limite. 0 Longo Não
UniverseDomain O domínio de nível superior associado aos recursos Google Cloud da sua organização. googleapis.com String Não
UnsupportedHTAPIFallback Determina se o conector volta para a API REST (quando definido como TRUE) ou retorna um erro (quando definido como FALSE). TRUE Booleano Não
UseQueryCache Ativa o armazenamento em cache de consultas. TRUE Booleano Não

Executar consultas com o driver

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

Mapeamento de tipo de dados

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

Tipo do GoogleSQL Tipo Java
ARRAY Array
BIGNUMERIC BigDecimal
BOOL Boolean
BYTES byte[]
DATE Date
DATETIME String
FLOAT64 Double
GEOGRAPHY String
INT64 Long
INTERVAL String
JSON String
NUMERIC BigDecimal
STRING String
STRUCT Struct
TIME Time
TIMESTAMP Timestamp

Exemplos

As seções a seguir fornecem 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 dos 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 de 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 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 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 realiza 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();

Preços

Você pode fazer o download do driver JDBC para BigQuery sem custo financeiro e não precisa de licenças adicionais para usar os drivers. No entanto, ao usar o driver, são aplicados os preços padrão do BigQuery.

A seguir