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

• El controlador es específico de BigQuery y no se puede usar con otros productos o servicios.
• El tipo de datos INTERVAL no es compatible con la API de BigQuery Storage Read.
• Se aplican todas las limitaciones del lenguaje de manipulación de datos (DML).

Antes de comenzar

1. Asegúrate de estar familiarizado con los controladores de 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 tu versión de JRE, consulta Verifica 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 necesitas 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.s3ns.iam.gserviceaccount.com	OAuthServiceAcctEmail
   	Clave de 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 recuperación de tokens y de información del entorno	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	Proyecto de 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 de 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 de JDBC a través de la descarga directa, haz lo siguiente:

1. Descarga la versión 1.6.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 de JDBC, agrega el controlador como una dependencia a tu proyecto:

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

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

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

Establece la conexión

Para establecer una conexión entre tu aplicación de 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 de 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 el DNS del servidor.
   • PORT: Es el número de puerto TCP.
   • PROJECT_ID: 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 Google del usuario
     • 2: para la autenticación de tokens de acceso o actualización generados previamente
     • 3: para la autenticación de credenciales predeterminadas de la aplicación
     • 4: para otros métodos de autenticación
   • AUTH_PROPS: Es la información de autenticación que anotaste cuando te autenticaste en BigQuery, que se indica 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 claves de cuenta de servicio.
   • OTHER_PROPS (opcional): Son propiedades de conexión adicionales para el controlador de 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 de Java al controlador de 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 set que puedes usar para establecer las 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 de JDBC son parámetros de configuración que incluyes en la cadena de conexión o pasas a través de métodos set cuando estableces una conexión con una base de datos. El controlador de JDBC para BigQuery admite las siguientes propiedades de conexión.

Ejecuta consultas con el controlador

Con tu aplicación de Java conectada a BigQuery a través del controlador JDBC, ahora 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:

Ejemplos

En las siguientes secciones, se proporcionan ejemplos en los que se 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 de 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]);
}

Bulk-insert

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 las propiedades de conexión o las variables de entorno. El registro puede afectar el rendimiento y ocupar espacio en el disco, por lo que solo debes habilitarlo 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 de problemas generales. 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 la cadena 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 para desarrolladores no permite editar la cadena de conexión, también puedes establecer el nivel y la ruta de acceso de los registros con las siguientes variables de entorno antes de ejecutar la aplicación:

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

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

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 seguimiento y registro distribuidos, lo que te permite supervisar el rendimiento de tus interacciones con la base de datos y solucionar problemas de manera eficaz.

Operaciones con seguimiento

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

• Ejecución de consultas: Se generan intervalos para BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) y BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
• Operaciones de metadatos: Se generan intervalos para métodos DatabaseMetaData específicos (getCatalogs(), getSchemas(), getTables() y 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 de forma causal 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 de JDBC propaga el contexto activo al SDK de google-cloud-bigquery subyacente. Como resultado, los intervalos que genera el SDK (como las llamadas RPC HTTP) aparecen automáticamente como elementos 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 esté correlacionada con la 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 Cloud de Confiance sin configuración

Si ejecutas en Cloud de Confiance y quieres una configuración rápida, puedes habilitar la exportación automática de seguimientos y registros a la observabilidad de Cloud de Confiance (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 la conexión de OpenTelemetry

Las siguientes propiedades de conexión son compatibles con 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 los registros, la autenticación, la configuración del proxy y los precios.

Interacción con LogLevel

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

• Si se establece LogLevel=0 (DESACTIVADO), 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 seguimiento como el registro) con el resguardo automático deCloud de Confiance 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, los registros y los seguimientos se envían al mismo proyecto de destino especificado con las mismas credenciales configuradas.

Configuración de proxy con OpenTelemetry y registro

Si tu aplicación se conecta a BigQuery a través de un servidor proxy, el controlador controla el enrutamiento del proxy de la siguiente manera:

• Exportación de seguimientos (HTTP). Cuando usas el protocolo HTTP predeterminado para la exportación de seguimientos de OpenTelemetry (otel.exporter.otlp.protocol=http/protobuf), el controlador enruta automáticamente el tráfico de exportación de seguimientos a través del proxy configurado en las propiedades de conexión con ProxyHost y ProxyPort.

• Exportación de registros y telemetría de gRPC. El exportador automático de registros de Cloud de Confiance (EnableGcpLogExporter=true) y los exportadores de OpenTelemetry basados en gRPC (otel.exporter.otlp.protocol=grpc) usan gRPC, que no admite la configuración de proxy por conexión. Para enrutar el tráfico de exportación de registros y telemetría de gRPC a través de un servidor proxy, establece la configuración de proxy a nivel de la JVM con las siguientes propiedades del sistema:

  -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

APIs y permisos de IAM obligatorios

Para escribir correctamente datos de telemetría en la observabilidad de Cloud de Confiance by S3NS , realiza la siguiente configuración en tu proyecto de Cloud de Confiance de 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 al principal o a la cuenta de servicio el rol de agente de Trace (roles/cloudtrace.agent).
   • Para exportar registros, otorga al principal o a la cuenta de servicio el rol de Escritor de registros (roles/logging.logWriter).

Precios y facturación

Cuando usas la telemetría de configuración cero de Cloud de Confiance (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 métricas de OpenTelemetry.

Ocultamiento de dependencias

Para evitar conflictos de ruta de clase con tu aplicación, el controlador oculta las dependencias del SDK y del exportador de OpenTelemetry. La API de OpenTelemetry permanece sin sombreado para permitir la interoperabilidad con el SDK que proporciona 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 una clave de equipaje y se adjunta como una etiqueta a todas las entradas de registro que el controlador emite a Logging.
• ID de seguimiento y de intervalo: Los registros generados dentro del alcance de la ejecución de una consulta incluyen automáticamente el trace_id y el 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?

• Para obtener instrucciones de configuración adicionales, manuales de referencia de propiedades de URL de conexión, muestras de código e instrucciones de compilación local, visita el repositorio de código abierto en GitHub:
  • Guía del usuario (docs/USER_GUIDE.md)
  • Guía de desarrollo (DEVELOPMENT.md)
  • Análisis detallado de las APIs de BigQuery Storage (docs/STORAGE_APIS.md)
• Obtén más información sobre el controlador ODBC para BigQuery.
• Explora otras herramientas para desarrolladores de BigQuery.