Usa el controlador JDBC para BigQuery

El controlador de conectividad de bases de datos de Java (JDBC) para BigQuery conecta tus aplicaciones de Java a BigQuery, lo que te permite usar las funciones de BigQuery con la infraestructura y las herramientas que prefieras. Para conectar aplicaciones que no son de Java a BigQuery, usa el controlador de conectividad abierta de bases de datos (ODBC) de Simba para BigQuery.

Limitaciones

El controlador JDBC para BigQuery está sujeto a las siguientes limitaciones:

Antes de comenzar

  1. Asegúrate de conocer los controladores JDBC, Apache Maven y el paquete java.sql.
  2. Verifica que tu sistema esté configurado con Java Runtime Environment (JRE) 8.0 o una versión posterior. Para obtener información sobre cómo verificar la versión de JRE, consulta Cómo verificar el entorno de JRE.

  3. Autentícate en BigQuery y toma nota de la siguiente información, que se usará más adelante cuando establezcas una conexión con el controlador JDBC para BigQuery. Solo debes anotar la información que corresponde al método de autenticación que usas.

    Método de autenticación Información de autenticación Ejemplo Propiedad de conexión (para configurar más adelante)
    Cuenta de servicio estándar Correo electrónico de la cuenta de servicio bq-jdbc-sa@mytestproject.iam.gserviceaccount.com OAuthServiceAcctEmail
    Clave de la cuenta de servicio (objeto JSON) my-sa-key OAuthPvtKey
    Archivo de claves de la cuenta de servicio Archivo de claves de la cuenta de servicio (ruta de acceso completa) path/to/file/secret.json OAuthPvtKeyPath
    Cuenta de usuario de Google ID de cliente 123-abc.apps.googleusercontent.com OAuthClientId
    Secreto del cliente _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Token de acceso generado previamente Token de acceso ya29.a0AfH6SMCiH1L-x_yZ OAuthAccessToken
    Token de actualización generado previamente Token de actualización 1/fFAGRNJru1FTz70BzhT3Zg OAuthRefreshToken
    ID de cliente 123-abc.apps.googleusercontent.com OAuthClientId
    Secreto del cliente _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Credencial predeterminada de la aplicación Ninguno N/A N/A
    Archivo de configuración Archivo de configuración (objeto JSON o ruta de acceso completa) path/to/file/secret.json OAuthPvtKey
    Objeto de configuración de la cuenta externa Objeto de configuración de la cuenta external_account_configuration_object OAuthPvtKey
    Otro Propiedad de público del archivo de configuración de la cuenta externa //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider BYOID_AudienceUri
    Archivo de información del entorno y recuperación de tokens {\"file\":\"/path/to/file\"} BYOID_CredentialSource
    Proyecto del usuario (solo si se usa un grupo de personal) my_project BYOID_PoolUserProject
    URI para la suplantación de identidad de la cuenta de servicio (solo si se usa un grupo de personal) my-sa BYOID_SA_Impersonation_Uri
    Token del servicio de tokens de seguridad basado en la especificación de intercambio de tokens urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    Extremo de intercambio de tokens del servicio de tokens de seguridad https://sts.googleapis.com/v1/token BYOID_TokenUri

Cómo configurar tu entorno de desarrollo

Para configurar tu entorno de desarrollo con el controlador de JDBC para BigQuery, haz lo siguiente:

  1. Descarga uno de los siguientes paquetes de JDBC:

  2. Agrega el archivo JAR descargado a tu ruta de clase para que el compilador y el tiempo de ejecución de Java puedan ubicar las clases JDBC necesarias. Para obtener información sobre cómo agregar un archivo a tu classpath, consulta Cómo configurar el classpath.

  3. Agrega la siguiente dependencia a tu archivo de compilación:

    <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. Si usas un proyecto de Gradle, agrega lo siguiente a tu archivo de compilación:

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

Establece la conexión

Para establecer una conexión entre tu aplicación Java y BigQuery con el controlador JDBC para BigQuery, haz lo siguiente:

  1. Identifica tu cadena de conexión para el controlador JDBC de BigQuery. Esta cadena captura toda la información necesaria para establecer una conexión entre tu aplicación Java y BigQuery. La cadena de conexión tiene el siguiente formato:

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

    Reemplaza lo siguiente:

    • HOST: Es la dirección IP o de DNS del servidor.
    • PORT: Es el número de puerto TCP.
    • PROJECT_ID: Es el ID de tu proyecto de BigQuery.
    • AUTH_TYPE: Es un número que especifica el tipo de autenticación que usaste. Uno de los siguientes:
      • 0: Para la autenticación de la cuenta de servicio (estándar y archivo de claves)
      • 1: Para la autenticación de la cuenta de usuario de Google
      • 2: Para la autenticación con tokens de acceso o actualización generados previamente
      • 3: Para la autenticación con credenciales predeterminadas de la aplicación
      • 4: Para otros métodos de autenticación
    • AUTH_PROPS: La información de autenticación que anotaste cuando te autenticaste en BigQuery, que se muestra en el formato property_1=value_1; property_2=value_2;..., por ejemplo, OAuthPvtKeyPath=path/to/file/secret.json, si te autenticaste con un archivo de clave de cuenta de servicio.
    • OTHER_PROPS (opcional): Propiedades de conexión adicionales para el controlador JDBC, que se indican en el formato property_1=value_1; property_2=value_2;.... Para obtener una lista completa de las propiedades de conexión, consulta Propiedades de conexión.

  2. Conecta tu aplicación Java al controlador JDBC para BigQuery con la clase DriverManager o DataSource.

    • Conéctate con la clase DriverManager:

      import java.sql.Connection;
import java.sql.DriverManager;

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

      Reemplaza CONNECTION_STRING por la cadena de conexión del paso anterior.

    • Conéctate con la clase 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;
}

      Reemplaza CONNECTION_STRING por la cadena de conexión del paso anterior.

      La clase DataSource también tiene métodos setter que puedes usar para establecer propiedades de conexión, en lugar de incluirlas en la cadena de conexión. A continuación, se muestra un ejemplo:

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

Propiedades de la conexión

Las propiedades de conexión del controlador JDBC son parámetros de configuración que se incluyen en la cadena de conexión o se pasan a través de métodos setter cuando se establece una conexión con una base de datos. El controlador JDBC para BigQuery admite las siguientes propiedades de conexión.

Propiedad de conexión Descripción Valor predeterminado Tipo de datos Obligatorio
AdditionalProjects Son los proyectos a los que el controlador puede acceder para realizar consultas y operaciones de metadatos, además del proyecto principal establecido por la propiedad ProjectId. N/A Cadena separada por comas No
AllowLargeResults Determina si el controlador procesa los resultados de la consulta que son mayores a 128 MB cuando la propiedad QueryDialect se establece en BIG_QUERY. Si la propiedad QueryDialect se establece en SQL, el controlador siempre procesa los resultados de consultas grandes. TRUE Booleano No
BYOID_AudienceUri Es la propiedad del público en un archivo de configuración de una cuenta externa. La propiedad audience puede contener el nombre del recurso del grupo de identidades para cargas de trabajo o del grupo de personal, así como el identificador del proveedor en ese grupo. N/A String Solo cuando OAuthType=4
BYOID_CredentialSource Es la información del entorno y la recuperación del token. N/A String Solo cuando OAuthType=4
BYOID_PoolUserProject Es el proyecto del usuario cuando se usa un grupo de personal para la autenticación. N/A String Solo cuando OAuthType=4 y se usa el grupo de trabajadores
BYOID_SA_Impersonation_Uri Es el URI de la suplantación de identidad de la cuenta de servicio cuando se usa un grupo de personal para la autenticación. N/A String Solo cuando OAuthType=4 y se usa el grupo de trabajadores
BYOID_SubjectTokenType Es el token del servicio de tokens de seguridad basado en la especificación de intercambio de tokens. Una de las siguientes opciones:
  • 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 Solo cuando OAuthType=4
BYOID_TokenUri Es el extremo de intercambio de tokens del servicio de tokens de seguridad. https://sts.googleapis.com/v1/token String No
ConnectionPoolSize Es el tamaño del grupo de conexiones si la agrupación de conexiones está habilitada. 10 Largo No
DefaultDataset Es el conjunto de datos que se usa cuando no se especifica uno en una consulta. N/A String No
EnableHighThroughputAPI Determina si se puede usar la API de Storage Read. Las propiedades HighThroughputActivationRatio y HighThroughputMinTableSize también deben establecerse en TRUE para usar la API de Storage Read. FALSE Booleano No
EnableSession Determina si la conexión inicia una sesión. Si se configura como TRUE, el ID de sesión se pasa a todas las consultas posteriores. FALSE Booleano No
EnableWriteAPI Determina si se puede usar la API de Storage Write. Debe establecerse en TRUE para habilitar las inserciones masivas. FALSE Booleano No
EndpointOverrides Extremos personalizados para anular lo siguiente:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
 N/A Cadena separada por comas No
FilterTablesOnDefaultDataset Determina el alcance de los metadatos que devuelven los métodos DatabaseMetaData.getTables() y DatabaseMetaData.getColumns(). Cuando se establece en FALSE, no se aplica ningún filtro. La propiedad DefaultDataset también debe establecerse para habilitar el filtrado. FALSE Booleano No
HighThroughputActivationRatio Es el umbral para la cantidad de páginas en una respuesta de búsqueda. Cuando se supera este número y se cumplen las condiciones de EnableHighThroughputAPI y HighThroughputMinTableSize, el controlador comienza a usar la API de Storage Read. 2 Número entero No
HighThroughputMinTableSize Es el umbral para la cantidad de filas en una respuesta de consulta. Cuando se supera este número y se cumplen las condiciones de EnableHighThroughputAPI y HighThroughputActivationRatio, el controlador comienza a usar la API de Storage Read. 100 Número entero No
JobCreationMode Determina si las consultas se ejecutan con trabajos o sin ellos. Un valor 1 significa que se crean trabajos para cada búsqueda, y un valor 2 significa que las búsquedas se pueden ejecutar sin trabajos. 2 Número entero No
JobTimeout Es el tiempo de espera del trabajo (en segundos) después del cual se cancela el trabajo en el servidor. 0 Largo No
KMSKeyName Es el nombre de la clave de KMS para encriptar datos. N/A String No
Labels Son las etiquetas asociadas a la búsqueda para organizar y agrupar los trabajos de búsqueda. N/A Map<String, String> No
LargeResultDataset Es el conjunto de datos de destino para los resultados de consultas grandes, solo cuando se establece la propiedad LargeResultTable. Cuando estableces esta propiedad, las escrituras de datos omiten la caché de resultados y activan la facturación para cada consulta, incluso si los resultados son pequeños. _google_jdbc String No
LargeResultsDatasetExpirationTime Es el ciclo de vida de todas las tablas en un conjunto de datos de resultados grande, en milisegundos. Esta propiedad se ignora si el conjunto de datos ya tiene establecida una hora de vencimiento predeterminada. 3600000 Largo No
LargeResultTable Tabla de destino para los resultados de consultas grandes, solo cuando se establece la propiedad LargeResultDataset. Cuando estableces esta propiedad, las escrituras de datos omiten la caché de resultados y activan la facturación para cada consulta, incluso si los resultados son pequeños. temp_table... String No
ListenerPoolSize Es el tamaño del grupo de listeners si la agrupación de conexiones está habilitada. 10 Largo No
Location La ubicación en la que se crean o consultan los conjuntos de datos. BigQuery determina automáticamente la ubicación si no se configura esta propiedad. N/A String No
LogLevel Es el nivel de detalle que registra el paquete java.util.logging durante las interacciones con la base de datos. El registro puede afectar el rendimiento, por lo que solo debes habilitarlo de forma temporal para capturar un problema. Una de las siguientes opciones:
  • 0: el nivel de OFF
  • 1: el nivel de SEVERE
  • 2: El nivel de WARNING
  • 3: el nivel de INFO
  • 4: el nivel de CONFIG
  • 5: el nivel de FINE
  • 6: el nivel de FINER
  • 7: el nivel de FINEST
  • 8: el nivel de ALL
 0 Número entero No
LogPath Es el directorio en el que se escriben los archivos de registro. N/A String No
MaximumBytesBilled Es el límite de bytes facturados. Las consultas con bytes facturados superiores a este número fallan sin generar cargos. 0 Largo No
MaxResults Es la cantidad máxima de resultados por página. 10000 Largo No
MetaDataFetchThreadCount Cantidad de subprocesos que se usan para los métodos de metadatos de la base de datos. 32 Número entero No
OAuthAccessToken Es el token de acceso que se usa para la autenticación con tokens de acceso generados previamente. N/A String Solo cuando OAUTH_TYPE=2
OAuthClientId Es el ID de cliente para la autenticación con tokens de actualización generados previamente y la autenticación de cuentas de usuario. N/A String Solo cuando OAUTH_TYPE=1 o OAUTH_TYPE=2
OAuthClientSecret Es el secreto del cliente para la autenticación con tokens de actualización pregenerados y la autenticación de cuentas de usuario. N/A String Solo cuando OAUTH_TYPE=1 o OAUTH_TYPE=2
OAuthP12Password Contraseña del archivo de clave PKCS12. notasecret String No
OAuthPvtKey Es la clave de la cuenta de servicio cuando se usa la autenticación de cuenta de servicio. Este valor puede ser un objeto de archivo de claves JSON sin procesar o una ruta de acceso al archivo de claves JSON. N/A String Solo cuando no se establecen OAUTH_TYPE=0 ni el valor de OAuthPvtKeyPath
OAuthPvtKeyPath Es la ruta a la clave de la cuenta de servicio cuando se usa la autenticación de cuenta de servicio. N/A String Solo cuando no se establecen OAUTH_TYPE=0 ni los valores de OAuthPvtKey y OAuthServiceAcctEmail
OAuthRefreshToken Es el token de actualización para la autenticación con tokens de actualización generados previamente. N/A String Solo cuando OAUTH_TYPE=2
OAuthServiceAcctEmail Es el correo electrónico de la cuenta de servicio cuando se usa la autenticación de cuenta de servicio. N/A String Solo cuando no se establecen OAUTH_TYPE=0 ni el valor de OAuthPvtKeyPath
OAuthType Es el tipo de autenticación. Una de las siguientes opciones:
  • 0: Autenticación de la cuenta de servicio
  • 1: Autenticación de la cuenta de usuario
  • 2: Autenticación con token de acceso o actualización generado previamente
  • 3: Autenticación con credenciales predeterminadas de la aplicación
  • 4: Otros métodos de autenticación
 -1 Número entero Sí
PartnerToken Es un token que usan los socios de Google Cloud para hacer un seguimiento del uso del controlador. N/A String No
ProjectId Es el ID del proyecto predeterminado para el controlador. Este proyecto se usa para ejecutar consultas y se factura por el uso de recursos. Si no se configura, el controlador infiere un ID del proyecto. N/A String No, pero se recomienda
ProxyHost Nombre de host o dirección IP de un servidor proxy a través del cual se enruta la conexión JDBC. N/A String No
ProxyPort Número de puerto en el que el servidor proxy escucha las conexiones. N/A String No
ProxyPwd Contraseña para la autenticación cuando se conecta a través de un servidor proxy que la requiere. N/A String No
ProxyUid Nombre de usuario para la autenticación cuando se conecta a través de un servidor proxy que lo requiere. N/A String No
QueryDialect Es el dialecto de SQL para la ejecución de consultas. Usa SQL para GoogleSQL (muy recomendado) y BIG_QUERY para SQL heredado. SQL String No
QueryProperties Propiedades de conexión de REST que personalizan el comportamiento de las consultas. N/A Map<String, String> No
RequestGoogleDriveScope Agrega el alcance de Drive de solo lectura a la conexión cuando se establece en 1. 0 Número entero No
RetryInitialDelay Establece la demora (en segundos) antes del primer reintento. 0 Largo No
RetryMaxDelay Establece el límite máximo (en segundos) para la demora del reintento. 0 Largo No
ServiceAccountImpersonationChain Es una lista separada por comas de las direcciones de correo electrónico de las cuentas de servicio en la cadena de suplantación. N/A String No
ServiceAccountImpersonationEmail Es la dirección de correo electrónico de la cuenta de servicio que se suplantará. N/A String No
ServiceAccountImpersonationScopes Lista separada por comas de los permisos de OAuth2 que se usarán con la cuenta suplantada. https://www.googleapis.com/auth/bigquery String No
ServiceAccountImpersonationTokenLifetime Es la vida útil del token de la cuenta suplantada (en segundos). 3600 Número entero No
SSLTrustStore Ruta de acceso completa al almacén de confianza de Java que contiene certificados de autoridad certificadora (CA) de confianza. El controlador utiliza este almacén de confianza para validar la identidad del servidor durante el protocolo de enlace SSL/TLS. N/A String No
SSLTrustStorePwd Contraseña del almacén de confianza de Java especificado en la propiedad SSLTrustStore. N/A String Solo si el almacén de confianza de Java está protegido con contraseña
SWA_ActivationRowCount Es el umbral de filas de executeBatch insert que, cuando se supera, hace que el conector cambie a la API de Storage Write. 3 Número entero No
SWA_AppendRowCount Es el tamaño del flujo de escritura. 1000 Número entero No
Timeout Es la cantidad de tiempo, en segundos, que el conector vuelve a intentar una llamada a la API fallida antes de que se agote el tiempo de espera. 0 Largo No
UniverseDomain Es el dominio de nivel superior asociado a los recursos de tu organización. Google Cloud googleapis.com String No
UnsupportedHTAPIFallback Determina si el conector recurre a la API de REST (cuando se establece en TRUE) o muestra un error (cuando se establece en FALSE). TRUE Booleano No
UseQueryCache Habilita el almacenamiento en caché de consultas. TRUE Booleano No

Ejecuta consultas con el controlador

Ahora que tu aplicación Java está conectada a BigQuery a través del controlador JDBC, puedes ejecutar consultas en tu entorno de desarrollo a través del proceso JDBC estándar. Se aplican todos los límites y cuotas de BigQuery.

Asignación de tipos de datos

Cuando ejecutas consultas a través del controlador JDBC para BigQuery, se produce la siguiente asignación de tipos de datos:

Tipo de GoogleSQL Tipo de 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

Ejemplos

En las siguientes secciones, se proporcionan ejemplos que usan las funciones de BigQuery a través del controlador JDBC para BigQuery.

Parámetros posicionales

En el siguiente ejemplo, se ejecuta una consulta con un parámetro posicional:

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

Registros anidados y repetidos

En el siguiente ejemplo, se consulta el registro base de los datos 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());

El controlador devuelve el registro base como un objeto struct o una representación de cadena de un objeto JSON. El resultado es similar al siguiente:

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

En el siguiente ejemplo, se consultan los subcomponentes de un 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());
    }

En el siguiente ejemplo, se consulta un array estándar de datos repetidos y, luego, se verifica el 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]);
}

En el siguiente ejemplo, se consulta un array Struct de datos repetidos y, luego, se verifica el 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]);
}

Inserción masiva

En el siguiente ejemplo, se realiza una operación de inserción masiva con el 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();

Precios

Puedes descargar el controlador JDBC para BigQuery sin costo y no necesitas licencias adicionales para usar los controladores. Sin embargo, cuando usas el controlador, se aplican los precios estándar de BigQuery.

¿Qué sigue?