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) 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. 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 identidad temporal como 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

Instala y configura el controlador JDBC

Puedes instalar y configurar el controlador JDBC para BigQuery descargando directamente el archivo uber-JAR o usando Maven.

Configuración de descarga directa

Para configurar el controlador JDBC a través de la descarga directa, haz lo siguiente:

  1. Descarga la versión 1.1.0 del controlador.
  2. Copia el archivo descargado en la ubicación que especifica tu software.

Para obtener información sobre los cambios en las funciones y las actualizaciones del flujo de trabajo, consulta el registro de cambios.

Configuración de Maven

El controlador JDBC para BigQuery está disponible en Maven Central.

Para configurar tu entorno de desarrollo con el controlador JDBC, agrega el controlador como una dependencia a tu proyecto:

Maven

Agrega la siguiente dependencia a tu archivo pom.xml:

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

Maven con uber-JAR

Agrega la siguiente dependencia a tu archivo pom.xml:

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

Gradle

Agrega lo siguiente a tu archivo build.gradle:

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

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 a 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 recuperación del token y la información del entorno. 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 identidad temporal como 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
EnableGcpLogExporter Determina si el controlador exporta automáticamente los registros a Cloud Logging (si no se usa ninguna instancia personalizada o global de OpenTelemetry). Para obtener más información, consulta OpenTelemetry. FALSE Booleano No
EnableGcpTraceExporter Determina si el controlador exporta automáticamente los registros a Cloud Trace (si no se usa ninguna instancia personalizada o global de OpenTelemetry). Para obtener más información, consulta OpenTelemetry. FALSE Booleano 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
EnableProjectDiscovery Determina si los métodos de metadatos de la base de datos detectan conjuntos de datos en todos los proyectos Google Cloud accesibles. Cuando se establece en FALSE, el descubrimiento se restringe al ProjectId predeterminado. 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 (gRPC). 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 configurarse para habilitar el filtrado. FALSE Booleano No
GcpTelemetryCredentials Son las credenciales que se usan para autenticar los exportadores de telemetría. Acepta una ruta de acceso a una clave JSON de cuenta de servicio o la cadena JSON sin procesar. Si no se configura, se usan las credenciales de conexión predeterminadas. Para obtener más información, consulta OpenTelemetry. N/A String No
GcpTelemetryProjectId Es el ID del proyecto Google Cloud de destino para la telemetría. El valor predeterminado es el ProjectId principal. Para obtener más información, consulta OpenTelemetry. N/A String 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. 10000 Número entero No
JobCreationMode Determina si las consultas se ejecutan con o sin trabajos. 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 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 de 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 establecido un tiempo de vencimiento predeterminado. 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 controlador. Para obtener más información, consulta Logging. 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 token de actualización generado previamente y la autenticación de la cuenta 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 el 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 duración 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 autoridades certificadoras (AC) de confianza. El controlador utiliza este almacén de certificados de confianza para validar la identidad del servidor durante el protocolo de enlace SSL/TLS. N/A String No
SSLTrustStoreProvider Proveedor de Java Cryptography Extension (JCE) que se usa para la propiedad SSLTrustStore. N/A String No
SSLTrustStorePwd La 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
SSLTrustStoreType El formato del archivo de almacén de confianza especificado en la propiedad SSLTrustStore (como JKS, PKCS12 o ROTKS). N/A String No
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 (gRPC). 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 devuelve un error (cuando se establece en FALSE). TRUE Booleano No
UseGlobalOpenTelemetry Determina si el controlador usa GlobalOpenTelemetry.get() para la instrumentación. Para obtener más información, consulta OpenTelemetry. FALSE 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 todas las cuotas y los límites 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();

Logging

Para solucionar problemas con el controlador JDBC para BigQuery, puedes habilitar el registro configurando propiedades de conexión o variables de entorno. El registro puede afectar el rendimiento y ocupar espacio en el disco, por lo que solo debe habilitarse de forma temporal para capturar un problema.

Niveles de registro

La propiedad LogLevel determina el nivel de detalle que registra el paquete java.util.logging:

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

Recomendamos el nivel 6 para la solución general de problemas. Los niveles 7 y 8 se limitan a las operaciones de ResultSet y generan un gran volumen de registros.

Habilita el registro en la cadena de conexión

Para habilitar el registro en el string de conexión, agrega las propiedades de conexión LogLevel y LogPath, por ejemplo:

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

Habilita el registro con variables de entorno

Si tu herramienta de desarrollo no permite editar cadenas de conexión, también puedes establecer el nivel y la ruta de acceso del registro con las siguientes variables de entorno antes de ejecutar tu aplicación:

  • BIGQUERY_JDBC_LOG_LEVEL: Es el nivel de registro (de 0 a 8).
  • BIGQUERY_JDBC_LOG_PATH: Es el directorio de los archivos de registro.

Por ejemplo, en un entorno de Linux o macOS, ejecuta el siguiente comando:

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

OpenTelemetry

El controlador JDBC para BigQuery admite OpenTelemetry (OTel) para proporcionar registros y seguimiento distribuidos, lo que te permite supervisar el rendimiento de tus interacciones con la base de datos y solucionar problemas de manera eficaz.

Operaciones rastreadas

Cuando OpenTelemetry está habilitado, el controlador genera intervalos para las siguientes operaciones:

  • Ejecución de la consulta: Se generan intervalos para BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) y BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
  • Operaciones de metadatos: Se generan tramos para métodos DatabaseMetaData específicos (getCatalogs(), getSchemas(), getTables(), getColumns()).
  • Paginación: Las recuperaciones asíncronas de páginas adicionales de resultados (cuando se usa la ruta de la API de REST) se rastrean y se vinculan causalmente al intervalo de ejecución de la consulta original con los vínculos de intervalo de OpenTelemetry. Se crea un intervalo llamado BigQueryStatement.pagination para estas operaciones.
  • Propagación del contexto: El controlador JDBC propaga el contexto activo al SDK de google-cloud-bigquery subyacente. Como resultado, los intervalos generados por el SDK (como las llamadas RPC de HTTP) aparecen automáticamente como secundarios de los intervalos de JDBC, lo que proporciona una jerarquía de seguimiento completa de extremo a extremo.

Modos de configuración

Puedes configurar OpenTelemetry en el controlador JDBC con uno de los siguientes modos, según la arquitectura y los requisitos de tu aplicación.

Telemetría administrada por la aplicación

Si tu aplicación ya usa OpenTelemetry, puedes insertar tu instancia de OpenTelemetry en el controlador JDBC para asegurarte de que la telemetría del controlador se correlacione con la telemetría de tu aplicación.

Para ello, usa la API de BigQueryDataSource:

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

Compatibilidad global con OpenTelemetry

Si inicializaste OpenTelemetry de forma global en tu aplicación (por ejemplo, con el agente de Java de OpenTelemetry o llamando a la función GlobalOpenTelemetry.set()), puedes configurar el controlador para que use esta instancia global.

Para habilitar la instancia global, establece la propiedad de conexión UseGlobalOpenTelemetry en TRUE.

Telemetría Google Cloud sin configuración

Si ejecutas en Google Cloud y deseas una configuración rápida, puedes habilitar la exportación automática de registros y seguimientos a la observabilidad de Google Cloud (Trace y Logging).

Para habilitar esta exportación, establece las siguientes propiedades de conexión en tu URL de JDBC:

  • EnableGcpTraceExporter=true
  • EnableGcpLogExporter=true

A continuación, se muestra un ejemplo de URL de conexión:

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

Propiedades de conexión de OpenTelemetry

Se admiten las siguientes propiedades de conexión para OpenTelemetry. Para obtener descripciones detalladas y valores predeterminados, consulta Propiedades de conexión.

  • EnableGcpLogExporter
  • EnableGcpTraceExporter
  • GcpTelemetryCredentials
  • GcpTelemetryProjectId
  • UseGlobalOpenTelemetry

Consideraciones importantes

Cuando implementes la integración de OpenTelemetry, ten en cuenta las siguientes consideraciones sobre el comportamiento de registro, la autenticación y los precios.

Interacción con LogLevel

La propiedad de conexión LogLevel existente actúa como un guardián principal para el registro.

  • Si se establece LogLevel=0 (APAGADO), no se generan registros. Por lo tanto, no se exportan registros con OpenTelemetry ni a Logging, incluso si EnableGcpLogExporter=true.
  • Para habilitar el registro de OTel, asegúrate de que LogLevel esté configurado en un valor mayor que 0 (por ejemplo, 5 para registros detallados).

Autenticación para la telemetría

La exportación de telemetría (tanto el registro como el seguimiento) con laGoogle Cloud automática de respaldo admite las credenciales predeterminadas de la aplicación (ADC) y las credenciales explícitas de la cuenta de servicio proporcionadas con GcpTelemetryCredentials.

Cuando se proporcionan GcpTelemetryProjectId o GcpTelemetryCredentials, tanto los registros como los seguimientos se envían al mismo proyecto de destino especificado con las mismas credenciales configuradas.

APIs y permisos de IAM obligatorios

Para escribir correctamente datos de telemetría en la observabilidad de Google Cloud , realiza la siguiente configuración en tu proyecto de Google Cloud destino:

  1. Habilita las APIs:
    • Habilita la API de Cloud Trace (cloudtrace.googleapis.com).
    • Habilita la API de Cloud Logging (logging.googleapis.com).
  2. Otorga roles de IAM:
    • Para exportar seguimientos: Otorga a la entidad o a la cuenta de servicio el rol de agente de Trace (roles/cloudtrace.agent).
    • Para exportar registros: Otorga a la principal o a la cuenta de servicio el rol de escritor de registros (roles/logging.logWriter).

Precios y facturación

Cuando se usa la telemetría de configuración cero Google Cloud (EnableGcpTraceExporter=true o EnableGcpLogExporter=true), los datos de telemetría se envían a Trace y Logging. Estos servicios pueden generar cargos según el volumen de datos transferidos. Para obtener más información, consulta Google Cloud Observability.

Métricas

Esta integración no admite las métricas de OpenTelemetry.

Sombreado de dependencias

Para evitar conflictos de classpath con tu aplicación, el controlador sombrea las dependencias del SDK y el exportador de OpenTelemetry. La API de OpenTelemetry permanece sin sombrear para permitir la interoperabilidad con el SDK proporcionado por tu aplicación.

Correlación de registros y seguimientos

Cuando OpenTelemetry está habilitado, el controlador correlaciona automáticamente los registros con los seguimientos:

  • db.connection_id: Se adjunta como un atributo de intervalo a todos los intervalos de JDBC.
  • jdbc.connection_id: Se usa como clave de equipaje y se adjunta como etiqueta a todas las entradas de registro que emite el controlador a Logging.
  • ID de seguimiento y ID de intervalo: Los registros generados dentro del alcance de la ejecución de una consulta incluyen automáticamente los elementos trace_id y span_id activos.

Precios

Puedes descargar el controlador JDBC para BigQuery sin costo. Sin embargo, cuando usas el controlador, se aplican los precios estándar de BigQuery.

¿Qué sigue?