Use o controlador JDBC para o BigQuery

O controlador Java Database Connectivity (JDBC) para o BigQuery associa a sua aplicação Java ao BigQuery, o que lhe permite usar as funcionalidades do BigQuery com as ferramentas e a infraestrutura da sua preferência. Este controlador foi concebido especificamente para o BigQuery e não pode ser usado com outros produtos ou serviços. Não precisa de licenças adicionais para usar este controlador.

Antes de começar

Certifique-se de que está familiarizado com os controladores JDBC e o pacote java.sql.
Verifique se o seu sistema está configurado com o Java Runtime Environment (JRE) 8.0 ou posterior.

Configure o controlador

Para configurar o controlador JDBC para o BigQuery, tem de instalar o controlador, autenticar-se no BigQuery e estabelecer uma ligação.

Instale o controlador

Transfira um dos seguintes pacotes JDBC:
- Uber JAR. Um único ficheiro JAR com todas as dependências incluídas.
- JAR simples com dependências. Um ficheiro ZIP que inclui um ficheiro JAR simples com todas as dependências.
- JAR Uber sombreado. Um único ficheiro JAR com todas as dependências incluídas e, adicionalmente, sombreadas.
Adicione o ficheiro JAR transferido ao seu classpath para que o compilador Java e o tempo de execução possam localizar as classes JDBC necessárias.

Autentique-se no BigQuery

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

Usar uma conta de serviço
Usar uma conta de utilizador Google
Usar uma chave de acesso e um símbolo de atualização pré-gerados
Usar Credenciais padrão da aplicação
Usar um método externo

Autentique com uma conta de serviço

Quando estabelece uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Defina a OAuthType propriedade de associação como 0.
Defina a propriedade de ligação ProjectId para o nome do seu projeto do BigQuery.
Realize um dos seguintes passos:
- Se estiver a usar um email e uma chave de conta de serviço, defina a propriedade de ligação OAuthServiceAcctEmail para o endereço de email da sua conta de serviço Google e defina a propriedade de ligação OAuthPvtKey para o objeto JSON da chave de conta de serviço. Para OAuthPvtKey, pode usar o objeto JSON da chave ou o caminho completo do ficheiro de chave.
- Se estiver a usar um ficheiro de chave de conta de serviço, defina a propriedade de ligação OAuthPvtKeyPath para o caminho completo do ficheiro de chave da conta de serviço.

Os dois exemplos seguintes usam a autenticação da 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;

Autentique com uma conta de utilizador Google

Quando estabelece uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Defina a OAuthType propriedade de associação como 1.
Defina a propriedade de ligação ProjectId para o nome do seu projeto do BigQuery.
Defina a propriedade de ligação OAuthClientId para o seu ID de cliente e defina a propriedade de ligação OAuthClientSecret para o seu segredo do cliente.

Para mais informações, consulte os artigos Utilizar o OAuth 2.0 para aceder às APIs Google e Gerir clientes OAuth.

O exemplo seguinte usa a autenticação da conta de utilizador Google:

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

Autentique com uma chave de acesso ou de atualização pré-gerada

Quando estabelece uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Defina a OAuthType propriedade de associação como 2.
Defina a propriedade de ligação ProjectId para o nome do seu projeto do BigQuery.
Realize um dos seguintes passos:
- Se estiver a usar um token de acesso pré-gerado, defina a propriedade de ligação OAuthAccessToken para o seu token de acesso.
- Se estiver a usar um token de atualização pré-gerado, defina a propriedade OAuthRefreshToken connection para o seu token de atualização, defina a propriedade OAuthClientId connection para o seu ID de cliente e defina a propriedade OAuthClientSecret connection para o seu segredo do cliente.

Para mais informações, consulte o artigo Utilizar o OAuth 2.0 para aceder às APIs Google.

O exemplo seguinte 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 seguinte usa a autenticação de tokens de atualização pré-gerados:

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;

Autentique-se com as Credenciais padrão da aplicação

As credenciais padrão da aplicação (ADC) são uma estratégia usada pelas bibliotecas de autenticação para encontrar automaticamente credenciais com base no ambiente da aplicação.

Quando estabelece uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Defina a OAuthType propriedade de associação como 3.
Defina a propriedade de ligação ProjectId para o nome do seu projeto do BigQuery.

Para mais informações, consulte o artigo Configure as Credenciais padrão da aplicação.

O exemplo seguinte usa a autenticação ADC:

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

Efetue a autenticação com um método externo

Pode autenticar com métodos externos, como a federação de identidades da força de trabalho ou a federação de identidades da carga de trabalho.

Quando estabelece uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Defina a OAuthType propriedade de associação como 4.
Defina a propriedade de ligação ProjectId para o nome do seu projeto do BigQuery.
Realize um dos seguintes passos:
- Defina a propriedade de ligação OAuthPvtKey ou a propriedade de ligação OAuthPvtKeyPath para o caminho completo do ficheiro de configuração. Para OAuthPvtKey, pode usar o objeto JSON da chave ou o caminho completo do ficheiro de chave.
- Defina a propriedade de ligação OAuthPvtKey para o objeto de configuração da conta externa não processada.
- Defina as seguintes BYOID propriedades da ligação, que são descritas na secção propriedades da ligação:
  - BYOID_AudienceUri
  - BYOID_CredentialSource
  - BYOID_PoolUserProject
  - BYOID_SA_Impersonation_Uri
  - BYOID_SubjectTokenType
  - BYOID_TokenUri

Os exemplos seguintes 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;"

Segue-se um exemplo de um ficheiro 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"
}

Estabeleça uma ligação

Para estabelecer uma ligação com o controlador JDBC para o BigQuery, faça o seguinte:

Adicione a dependência google-cloud-bigquery-jdbc ao ficheiro de compilação 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 estiver a usar um projeto do Gradle, adicione também o seguinte ao ficheiro de compilação:

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

Identifique a string de ligação para o controlador JDBC. Esta string capta todas as informações essenciais necessárias para estabelecer uma ligação entre a sua aplicação Java e uma base de dados específica. O controlador JDBC para a string de ligação do BigQuery tem o seguinte formato:
```
jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;PROPERTIES
```
Substitua o seguinte:
- 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 que usou. Uma das seguintes opções:
  - 0: autenticação da conta de serviço Google
  - 1: autenticação da conta de utilizador Google
  - 2: autenticação de chave de acesso ou de atualização pré-gerada
  - 3: autenticação de credenciais padrão da aplicação
  - 4: Métodos de autenticação externos, como a federação de identidades da força de trabalho ou a federação de identidades da carga de trabalho
- PROPERTIES: propriedades de ligação adicionais para o controlador JDBC. As propriedades têm de ser indicadas no formato property_1=value_1; property_2=value_2;.... Os nomes das propriedades não são sensíveis a maiúsculas e minúsculas. Para ver uma lista completa das propriedades de associação, consulte o artigo Propriedades de associação.

Estabeleça ligação ao controlador com a classe DriverManager ou DataSource.

Associar à turma 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 ligação do passo anterior.

Associar à turma 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 ligação do passo anterior.

A classe DataSource também tem métodos setter, que pode usar para definir propriedades de ligação, em vez de incluir todas as propriedades na string de ligação. Segue-se um 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();
}

Explore as funcionalidades do condutor

Agora que tem ligação ao controlador JDBC para o BigQuery, pode explorar as respetivas funcionalidades.

Conetor SQL

O conetor SQL permite-lhe executar consultas SQL com o BigQuery. Use a propriedade de ligação QueryDialect para especificar o dialeto SQL que quer usar.

Mapeamento de tipos de dados

O controlador JDBC para o BigQuery suporta os seguintes mapeamentos de tipos 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`

Registos aninhados e repetidos

O controlador JDBC para o BigQuery suporta registos aninhados e repetidos, em que o controlador devolve o tipo base como um objeto struct ou uma representação de string de um objeto JSON.

Segue-se um exemplo de consulta do registo base de dados de estrutura:

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"
      }
    ]
  }
}

Segue-se 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());
    }

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

Segue-se um exemplo de consulta de uma matriz 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]);
}

Conjunto de resultados grande

Para obter grandes conjuntos de resultados quando usa o controlador JDBC para o BigQuery, faça o seguinte:

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

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

Se não especificar valores para as propriedades de ligação LargeResultDataset e LargeResultTable, o controlador JDBC para o BigQuery cria um conjunto de dados oculto denominado _google_jdbc e uma tabela temporária no mesmo. Estes recursos são eliminados automaticamente após 24 horas.

Todas as quotas e limites do BigQuery continuam a aplicar-se.

Parâmetros posicionais

Os parâmetros posicionais são marcadores de posição numa declaração SQL que representam valores a fornecer durante a execução da consulta. O controlador JDBC para o BigQuery suporta parâmetros posicionais com o símbolo de ponto de interrogação (?). Segue-se um exemplo de uma 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

Pode usar o controlador JDBC para o BigQuery para executar SELECT consultas através da API BigQuery ou da API BigQuery Storage Read.

Se usar a API BigQuery, defina a propriedade JobCreationModeconnection para especificar se a consulta é executada com ou sem a criação de uma tarefa.

Se usar a API Storage Read, use a propriedade de ligação para ativar a API e verificar se as seguintes condições são cumpridas:EnableHighThroughputAPI

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

Inserção em massa

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

Segue-se um exemplo de uma operação de escrita:

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();

Registo

O controlador JDBC para o BigQuery suporta ações de registo no controlador através do registo de utilidades Java. O registo pode afetar o desempenho, por isso, só o ative para capturar um problema e desative-o quando terminar.

Para configurar o registo, faça o seguinte:

Defina a propriedade LogLevel de acordo com a seguinte tabela:

Valor de `LogLevel`	`LogLevel`	Descrição
`0`	`OFF`	Não são registadas mensagens.
`1`	`SEVERE`	Falhas ou erros graves que afetam a funcionalidade da aplicação.
`2`	`WARNING`	Potenciais problemas ou situações que podem exigir atenção.
`3`	`INFO`	Mensagens informativas sobre eventos normais e progresso.
`4`	`CONFIG`	Mensagens relativas a informações de configuração estáticas.
`5`	`FINE`	Mensagens de rastreio gerais.
`6`	`FINER`	Mensagens de rastreio detalhadas.
`7`	`FINEST`	Mensagens de rastreio altamente detalhadas, úteis para depuração extensiva.
`8`	`ALL`	Todas as mensagens são registadas.

Defina a propriedade LogPath para o caminho completo da pasta onde quer guardar o ficheiro de registo.

Em alternativa, pode configurar o registo com as variáveis de ambiente BIGQUERY_JDBC_LOG_LEVEL e BIGQUERY_JDBC_LOG_PATH.

Propriedades de associação

Num controlador JDBC, as propriedades de ligação são parâmetros de configuração que pode incluir na string de ligação ou transmitir através dos métodos setter quando estabelece uma ligação a uma base de dados. As seguintes propriedades de ligação são suportadas pelo controlador JDBC para o BigQuery.

AdditionalProjects

Esta propriedade de ligação permite que as consultas e as operações de metadados acedam a conjuntos de dados em projetos especificados, além do projeto principal definido na string de ligação.

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

AllowLargeResults

Esta propriedade de ligação especifica se o controlador processa resultados de consultas superiores a 128 MB quando a propriedade de ligação QueryDialect está definida como BIG_QUERY. Se a propriedade de associação QueryDialect estiver definida como SQL, a propriedade de associação AllowLargeResults é definida como TRUE por predefinição. Para mais informações, consulte o artigo Conjunto de resultados grande.

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

BYOID_AudienceUri

Esta propriedade de associação especifica a propriedade de público-alvo num ficheiro de configuração de uma conta externa. A propriedade audience contém o nome do recurso do Workload Identity Pool ou do Workforce Pool e o identificador do fornecedor nesse pool.

Valor predefinido: N/A
Tipo de dados: string
Obrigatório: apenas quando OAuthType=4

BYOID_CredentialSource

Esta propriedade de ligação define as informações de obtenção de tokens e as informações ambientais.

Valor predefinido: N/A
Tipo de dados: string
Obrigatório: apenas quando OAuthType=4

BYOID_PoolUserProject

Esta propriedade de ligação define o projeto do utilizador quando o conjunto de trabalhadores está a ser usado. O projeto tem de ter a autorização serviceusage.services.use do IAM.

Valor predefinido: N/A
Tipo de dados: string
Obrigatório: apenas quando OAuthType=4 e usar o grupo de trabalhadores

BYOID_SA_Impersonation_Uri

Esta propriedade de ligação define o URL para a representação da conta de serviço quando estão a ser usados conjuntos de identidades de carga de trabalho e as APIs não foram integradas com o UberMint.

Valor predefinido: N/A
Tipo de dados: string
Obrigatório: apenas quando OAuthType=4 e usar o Workload Identity Pool com a simulação da conta de serviço

BYOID_SubjectTokenType

Esta propriedade de associação define o token STS com base na especificação de troca de tokens. O valor tem de ser um dos seguintes:

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 predefinido: urn:ietf:params:oauth:tokentype:id_token
Tipo de dados: string
Obrigatório: apenas quando OAuthType=4

BYOID_TokenUri

Esta propriedade de associação define o ponto final de troca de tokens do STS.

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

ConnectionPoolSize

Esta propriedade de ligação define o tamanho do conjunto de ligações se o agrupamento de ligações estiver ativado.

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

DefaultDataset

Esta propriedade de ligação especifica o conjunto de dados usado quando executa uma consulta sem especificar explicitamente um conjunto de dados. Pode usar o formato DATASET_ID ou o formato PROJECT_ID.DATASET_ID.

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

EnableHighThroughputAPI

Esta propriedade de ligação determina se a API Storage Read pode ser usada. As propriedades de ligação HighThroughputActivationRatio e HighThroughputMinTableSize também têm de ser satisfeitas para usar a API Storage Read.

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

EnableSession

Esta propriedade de ligação determina se a ligação inicia uma sessão. Quando usado, o ID da sessão é transmitido a todas as consultas subsequentes.

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

EnableWriteAPI

Esta propriedade de associação determina se é possível usar a API Storage Write. Tem de estar definido como TRUE para ativar as inserções em massa.

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

EndpointOverrides

Esta propriedade de ligação define pontos finais personalizados numa string separada por vírgulas.

Valores predefinidos:
- 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

Esta propriedade de associação controla o âmbito dos metadados devolvidos pelos métodos DatabaseMetaData.getTables() e DatabaseMetaData.getColumns(). Quando a propriedade está desativada, não ocorre qualquer filtragem. A propriedade de associação DefaultDataset também tem de ser definida para ativar a filtragem.

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

HighThroughputActivationRatio

Esta propriedade de ligação define um limite para o número de páginas numa resposta de consulta. Quando este número é excedido e as condições EnableHighThroughputAPI e HighThroughputMinTableSize são cumpridas, o condutor começa a usar a API Storage Read.

Valor predefinido: 2
Tipo de dados: número inteiro
Obrigatório: não

HighThroughputMinTableSize

Esta propriedade de ligação define um limite para o número de linhas numa resposta de consulta. Quando este número é excedido e as condições EnableHighThroughputAPI e HighThroughputActivationRatio são cumpridas, o condutor começa a usar a API Storage Read.

Valor predefinido: 100
Tipo de dados: número inteiro
Obrigatório: não

JobCreationMode

Esta propriedade de ligação determina se as consultas são executadas sem criar tarefas. Um valor 1 significa que são criadas tarefas para cada consulta e um valor 2 significa que as consultas podem ser executadas sem tarefas.

Valor predefinido: 2
Tipo de dados: número inteiro
Obrigatório: não

JobTimeout

Esta propriedade de ligação define o limite de tempo da tarefa (em segundos) após o qual a tarefa é cancelada no servidor.

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

KMSKeyName

Esta propriedade de ligação define o nome da chave do KMS para encriptar dados.

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

Labels

Esta propriedade de ligação define etiquetas associadas à consulta para organizar e agrupar tarefas de consulta.

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

LargeResultDataset

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

Valor predefinido: _google_jdbc, apenas quando QueryDialect=BIG_QUERY ou quando QueryDialect=SQL e a propriedade de associação LargeResultTable está definida
Tipo de dados: string
Obrigatório: não

LargeResultsDatasetExpirationTime

Esta propriedade de ligação especifica a duração total de todas as tabelas num conjunto de dados, em milissegundos. Esta propriedade é ignorada se o conjunto de dados já tiver um tempo de expiração predefinido definido.

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

LargeResultTable

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

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

ListenerPoolSize

Esta propriedade de ligação define o tamanho do conjunto de ouvintes se o agrupamento de ligações estiver ativado.

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

Location

Esta propriedade de ligação especifica a localização onde os conjuntos de dados são criados ou consultados. O BigQuery determina automaticamente a localização se este valor não estiver definido.

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

LogLevel

Esta propriedade de ligação controla o nível de detalhe registado durante as interações com a base de dados. Para ver as descrições de nível, consulte a secção Registo.

Valor predefinido: 0
Tipo de dados: número inteiro
Obrigatório: não

LogPath

Esta propriedade de ligação define o diretório onde os ficheiros de registo são escritos. Para mais detalhes, consulte a secção Registo.

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

MaximumBytesBilled

Esta propriedade de ligação limita o número de bytes faturados. As consultas com bytes faturados superiores a este limite falham sem incorrer numa cobrança.

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

MaxResults

Esta propriedade de ligação define o número máximo de resultados por página.

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

MetaDataFetchThreadCount

Esta propriedade de ligação configura o número de threads usados para métodos de metadados da base de dados.

Valor predefinido: 32
Tipo de dados: número inteiro
Obrigatório: não

OAuthAccessToken

Esta propriedade de ligação especifica o token de acesso usado para a autenticação de tokens de acesso pré-gerados.

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

OAuthClientId

Esta propriedade de ligação define o ID de cliente para a autenticação de tokens de atualização pré-gerados e a autenticação de contas de utilizador.

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

OAuthClientSecret

Esta propriedade de ligação define o segredo do cliente para a autenticação do token de atualização pré-gerado e a autenticação da conta de utilizador.

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

OAuthP12Password

Esta propriedade de ligação define a palavra-passe para o ficheiro de chave PKCS12.

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

OAuthPvtKey

Esta propriedade de ligação define a chave da conta de serviço quando usa a autenticação da conta de serviço. Este valor pode ser um objeto de ficheiro de chave JSON não processado ou um caminho para o ficheiro de chave JSON.

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

OAuthPvtKeyPath

Esta propriedade de ligação define o caminho para a chave da conta de serviço quando usa a autenticação da conta de serviço.

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

OAuthRefreshToken

Esta propriedade de ligação define o token de atualização para a autenticação do token de atualização pré-gerado. Um símbolo de atualização do OAuth 2.0 é um tipo especial de símbolo que permite a uma aplicação obter um novo símbolo de acesso quando o atual expira, sem exigir que o utilizador volte a autenticar.

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

OAuthServiceAcctEmail

Esta propriedade de ligação define o email da conta de serviço quando usa a autenticação da conta de serviço.

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

OAuthType

Esta propriedade de ligação especifica o tipo de autenticação. O valor tem de ser um dos seguintes:

0: autenticação da conta de serviço Google
1: autenticação da conta de utilizador Google
2: autenticação de chave de acesso ou de atualização pré-gerada
3: autenticação de credenciais padrão da aplicação
4: métodos de autenticação externos, como a federação de identidades da força de trabalho ou a federação de identidades da carga de trabalho
Valor predefinido: -1
Tipo de dados: número inteiro
Obrigatório: sim

PartnerToken

Esta propriedade de associação é usada pelos parceiros para acompanhar a utilização do controlador. Google Cloud

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

PrivateServiceConnectUris

Esta propriedade de associação é idêntica à propriedade do EndpointOverrides. Em alternativa, use a propriedade EndpointOverrides.

ProjectId

Esta propriedade de ligação define o ID do projeto predefinido para o controlador. Este projeto é usado para executar consultas e é faturado pela utilização de recursos. Se não estiver definido, o controlador infere um ID do projeto.

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

ProxyHost

Esta propriedade de ligação define o nome do anfitrião ou o endereço IP de um servidor proxy através do qual a ligação JDBC é encaminhada.

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

ProxyPort

Esta propriedade de ligação define o número de porta no qual o servidor proxy está a ouvir ligações.

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

ProxyPwd

Esta propriedade de ligação define a palavra-passe necessária para a autenticação quando se liga através de um servidor proxy que a requer.

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

ProxyUid

Esta propriedade de ligação define o nome de utilizador necessário para a autenticação quando se estabelece ligação através de um servidor proxy que o exige.

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

QueryDialect

Esta propriedade de ligação define o dialeto de SQL para a execução de consultas. Use SQL para o GoogleSQL (altamente recomendado) e BIG_QUERY para o SQL antigo.

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

QueryProperties

Esta propriedade de associação configura as modificações do comportamento das consultas.

Segue-se um exemplo definido na string de ligação:

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

Segue-se um exemplo definido na turma 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 a secção ConnectionProperty.

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

RequestGoogleDriveScope

Esta propriedade de ligação é usada para pedir acesso ao Google Drive. Quando ativado, o âmbito do Drive de leitura é adicionado à ligação. Para ativar esta propriedade, defina o valor como 1.

Valor predefinido: 0
Tipo de dados: número inteiro
Obrigatório: não

RetryInitialDelay

Esta propriedade de ligação define o atraso (em segundos) antes da primeira repetição.

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

RetryMaxDelay

Esta propriedade de ligação define o limite máximo (em segundos) para o atraso de nova tentativa.

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

ServiceAccountImpersonationChain

Esta propriedade de ligação especifica uma lista de emails de contas de serviço separados por vírgulas na cadeia de roubo de identidade.

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

ServiceAccountImpersonationEmail

Esta propriedade de ligação define o email da conta de serviço a ser representado.

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

ServiceAccountImpersonationScopes

Esta propriedade de ligação especifica uma lista separada por vírgulas de âmbitos do OAuth2 a usar com a conta roubada.

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

ServiceAccountImpersonationTokenLifetime

Esta propriedade de ligação define o tempo de vida do token da conta roubada (em segundos).

Valor predefinido: 3600
Tipo de dados: número inteiro
Obrigatório: não

SSLTrustStore

Esta propriedade de ligação especifica o caminho completo para o Java TrustStore que contém certificados de autoridade de certificação (AC) fidedignos. O controlador usa este repositório fidedigno para validar a identidade do servidor durante o handshake SSL/TLS.

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

SSLTrustStorePwd

Esta propriedade de ligação especifica a palavra-passe para o Java TrustStore especificado na propriedade SSLTrustStore.

Valor predefinido: N/A
Tipo de dados: string
Obrigatório: apenas se usar um TrustStore Java protegido por palavra-passe

SWA_ActivationRowCount

Esta propriedade de ligação define um número limite de executeBatch insertlinhas que, quando excedido, faz com que o conector mude para a API Storage Write.

Valor predefinido: 3
Tipo de dados: número inteiro
Obrigatório: não

SWA_AppendRowCount

Esta propriedade de ligação define o tamanho da stream de gravação.

Valor predefinido: 1000
Tipo de dados: número inteiro
Obrigatório: não

Timeout

Esta propriedade de ligação define o tempo, em segundos, que o conector repete uma chamada API com falha antes de atingir o limite de tempo.

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

UniverseDomain

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

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

UnsupportedHTAPIFallback

Esta propriedade de ligação determina se o conetor recorre à API REST (quando definida como TRUE) ou devolve um erro (quando definida como FALSE).

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

UseQueryCache

Esta propriedade de ligação ativa o armazenamento em cache de consultas.

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

Use o controlador JDBC para o BigQuery

Antes de começar

Configure o controlador

Instale o controlador

Autentique-se no BigQuery

Autentique com uma conta de serviço

Autentique com uma conta de utilizador Google

Autentique com uma chave de acesso ou de atualização pré-gerada

Autentique-se com as Credenciais padrão da aplicação

Efetue a autenticação com um método externo

Estabeleça uma ligação

Explore as funcionalidades do condutor

Conetor SQL

Mapeamento de tipos de dados

Registos aninhados e repetidos

Conjunto de resultados grande

Parâmetros posicionais

SELECT consultas

Inserção em massa

Registo

Propriedades de associação

`SELECT` consultas