Usa el controlador ODBC para BigQuery

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: El controlador ODBC para BigQuery está disponible bajo la licencia de Apache 2.0. Para solicitar comentarios o asistencia sobre esta función, envía un correo electrónico a [e-mail].

El controlador de conectividad abierta de bases de datos (ODBC) para BigQuery conecta tus aplicaciones a BigQuery. Esto te permite usar las funciones de BigQuery con la infraestructura y las herramientas que prefieras.

Antes de comenzar

1. Asegúrate de conocer los controladores de Open Database Connectivity (ODBC) y el administrador de controladores.

2. Ten en cuenta los siguientes requisitos del sistema:

   Sistema operativo	Arquitecturas admitidas	Versión mínima y dependencias
   Windows	32 bits (x86) y 64 bits (x64)	Versión: Windows 10, Windows Server 2016 o versiones posteriores Dependencia: Microsoft Visual C++ Redistributable para Visual Studio 2019 o 2022
   macOS	64 bits (x86_64), ARM64 (Apple Silicon)	Versión: macOS 12 (Monterey) o posterior Dependencia: Un administrador de controladores ODBC (por ejemplo, unixODBC). Asegúrate de agregar el directorio de instalación a tu DYLD_LIBRARY_PATH.
   Linux	64 bits (x86_64)	Versión: Cualquier distribución con glibc 2.27 o posterior (por ejemplo, Ubuntu 20.04 LTS+, Debian 11+) Dependencia: Un administrador de controladores ODBC (por ejemplo, unixODBC). Asegúrate de agregar el directorio de instalación a tu LD_LIBRARY_PATH.

3. Identifica tu tipo de conexión para el controlador ODBC de BigQuery. El controlador admite los siguientes métodos de autenticación:

   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	Clave de la cuenta de servicio (objeto JSON)	my-sa-key	KeyFilePath
   Federación de Workload Identity o federación de identidades de personal	Propiedad de público del archivo de configuración de la cuenta externa	//iam.googleapis.com/locations/global/...	BYOID_AudienceUrl
   	Recuperación de tokens y archivo de información del entorno	{"file":"/path/to/file"}	BYOID_CredentialSource
   	Proyecto del usuario (solo para el grupo de personal)	my_project	BYOID_PoolUserProject
   	Tipo de token de STS	id_token o cualquier otro tipo de STS	BYOID_SubjectTokenType
   	Extremo de intercambio de tokens del STS	URL del extremo de STS personalizado	BYOID_TokenUrl
   Credencial predeterminada de la aplicación	N/A	N/A	N/A

Instala y configura el controlador ODBC

En esta sección, se describe cómo instalar y configurar el controlador ODBC para sistemas operativos Windows y no Windows.

Windows

En Windows, asegúrate de instalar la arquitectura del controlador que coincida con la de tu aplicación. Por ejemplo, usa el controlador de 64 bits para las aplicaciones de 64 bits y el controlador de 32 bits para las aplicaciones de 32 bits. Un sistema Windows de 64 bits admite aplicaciones de 32 y 64 bits.

• Descarga ODBCDriverforBigQuery_windows_x86.msi para aplicaciones de 32 bits
• Descarga ODBCDriverforBigQuery_windows_x64.msi para aplicaciones de 64 bits

Crea un nombre de fuente de datos

Sigue estos pasos para crear un nombre de fuente de datos en Windows:

1. En el menú Inicio, ve a Orígenes de datos ODBC y selecciona la versión que tenga la misma cantidad de bits que tu aplicación cliente para garantizar una conexión adecuada a BigQuery.
2. En el Administrador de fuentes de datos ODBC, haz clic en la pestaña Controladores.
3. Busca el controlador ODBC para BigQuery tal como aparece en la lista alfabética de controladores ODBC instalados.
4. Elige una de las siguientes opciones:
   • Para crear un DSN para el usuario actual, haz clic en la pestaña DSN del usuario.
   • Para crear un DSN para todos los usuarios, haz clic en la pestaña DSN del sistema. Se recomiendan los DSN del sistema porque algunas aplicaciones cargan datos con diferentes cuentas de usuario y es posible que no detecten los DSN del usuario creados con otra cuenta de usuario.
5. Haz clic en Agregar.
6. En el diálogo Create New Data Source, selecciona ODBC Driver for BigQuery y, luego, haz clic en Finish.
7. Se abrirá el diálogo ODBC Driver for BigQuery DSN Setup.
8. En el campo Nombre de la fuente de datos, escribe un nombre para tu DSN.
9. Consulta la sección Propiedades de conexión para comprender qué valores debes completar.

Sistemas operativos que no son de Windows

Las distribuciones de Linux de 64 bits admiten aplicaciones de 32 y 64 bits. Asegúrate de que la arquitectura del controlador ODBC coincida con la aplicación que deseas usar. Por ejemplo, usa el controlador de 64 bits para las aplicaciones de 64 bits y el controlador de 32 bits para las aplicaciones de 32 bits. Puedes instalar ambas arquitecturas de controladores de forma simultánea en un solo sistema.

• Descarga ODBCDriverforBigQuery_linux_latest.zip para Linux
• Descarga ODBCDriverforBigQuery_macos_latest.tar.gz para macOS

Para instalar el conector con el paquete de archivo tar o zip, haz lo siguiente:

1. Crea el directorio en el que deseas instalar el conector, si aún no existe.
2. Extrae el archivo ZIP principal a una ubicación temporal conveniente.
3. Navega a la carpeta del archivo tar o zip extraído y, luego, copia todos los archivos y las carpetas en el directorio de instalación (opcional).
4. Después de la extracción, la ruta de acceso al objeto compartido del controlador ODBC para BigQuery es [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Actualiza tus archivos .ini para que reflejen la ruta de acceso correcta del conector.

unzip linux_odbc-driver.VERSION.zip -d linux_odbc-driver.VERSION/
cd ./linux_odbc-driver.VERSION
export INSTALL_DIR=$(pwd)
export ODBCINI=$INSTALL_DIR/odbc.ini
export ODBCINSTINI=$INSTALL_DIR/odbcinst.ini
export GOOGLEBIGQUERYODBCINI=$INSTALL_DIR/googlebigqueryodbc.ini

Establece la conexión

Para establecer una conexión con el controlador ODBC para BigQuery, puedes usar una cadena de conexión o un DSN.

Formato de la cadena de conexión

Driver=ODBC Driver for BigQuery;ProjectId=PROJECT_ID;OAuthMechanism=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

Reemplaza lo siguiente:

• 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. Elige una de las siguientes opciones:
  • 0: Para la autenticación de la cuenta de servicio
  • 3: Para la autenticación con credenciales predeterminadas de la aplicación
  • 4: Para la autenticación de la federación de identidades de la carga de trabajo o de personal
• AUTH_PROPS: Es la información de autenticación que anotaste cuando te autenticaste en BigQuery.
• OTHER_PROPS (opcional): Son propiedades de conexión adicionales para el controlador ODBC.

Propiedades de la conexión

Las propiedades de conexión del controlador ODBC son parámetros de configuración que se incluyen en la cadena de conexión cuando estableces una conexión a una base de datos. El controlador ODBC para BigQuery admite las siguientes propiedades de conexión.

Nota: Todos los nombres de las propiedades de conexión no distinguen mayúsculas de minúsculas.

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
AllowHtapiForLargeResults	Determina si el conductor puede usar la API de Read.	0	Booleano	No
AllowLargeResults	Especifica si el controlador ODBC debe procesar los resultados de la consulta que superen los 128 MB cuando se usa SQL heredado (QueryDialect=BIG_QUERY).	0	Booleano	No
BYOID_AudienceUrl	Audience contiene el nombre del recurso del grupo de identidades para cargas de trabajo o el grupo de personal y el identificador del proveedor en ese grupo.	N/A	String	Solo cuando OAuthMechanism=4
BYOID_CredentialSource	Establece la información necesaria para recuperar el token, así como cierta información del entorno.	N/A	String	Solo cuando OAuthMechanism=4
BYOID_PoolUserProject	Se establece cuando es un grupo de personal y no un grupo de Workload Identity.	N/A	String	Solo cuando OAuthMechanism=4 y se usa un grupo de trabajadores
BYOID_SubjectTokenType	Establece el tipo de token del STS según la especificación de intercambio de tokens de OAuth 2.0. Los valores esperados incluyen los siguientes: 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	N/A	String	Solo cuando OAuthMechanism=4
BYOID_TokenUrl	Establece el extremo de intercambio de tokens del STS.	https://sts.googleapis.com/v1/token	String	No
DefaultDataset	Actúa como un conjunto de datos designado dentro de un proyecto al que el controlador hace referencia automáticamente cuando ejecutas consultas sin especificar explícitamente un conjunto de datos.	N/A	String	No
FilterTablesOnDefaultDataset	Determina el alcance de los metadatos que devuelven los métodos de metadatos de tabla o columna. Si es FALSE, no se aplica ningún filtro. También debes establecer la propiedad DefaultDataset para habilitar el filtrado.	FALSE	Booleano	No
EnableSession	Determina si una conexión inicia una sesión. Cuando está habilitada, la primera consulta que ejecuta esa conexión en particular inicia una sesión y el controlador pasa el ID de sesión a todas las consultas posteriores.	0	Booleano	No
JobCreationMode	Te permite habilitar la ruta de consulta de baja latencia. Elige una de las siguientes opciones: 1: El controlador crea trabajos para cada consulta (JOB_CREATION_REQUIRED). 2: El controlador ejecuta consultas sin trabajos (JOB_CREATION_OPTIONAL)	2	Número entero	No
KeyFilePath	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 OAuthMechanism=0
KMSKeyName	Te permite especificar el nombre de la clave de KMS que se usará cuando se encripten y desencripten los datos.	N/A	String	No
LargeResultsDataSetId	Te permite especificar el conjunto de datos de destino para almacenar los resultados de las consultas grandes.	N/A	String	No
LargeResultsDatasetExpirationTime	Te permite especificar el ciclo de vida de todas las tablas en el conjunto de datos de resultados grandes, en milisegundos.	3600000	Largo	No
Location	Te permite especificar la ubicación en la que el controlador crea o consulta conjuntos de datos.	N/A	String	No
LogLevel	Limita el detalle que registra el conductor durante las interacciones. Elige una de las siguientes opciones: 0: OFF 1: ERROR 2: WARNING 3: INFO	0	Número entero	No
LogPath	Te permite especificar el directorio en el que el controlador escribe los archivos de registro.	N/A	String	No
LogFileCount	Te permite establecer la cantidad máxima de archivos de registro que se conservarán.	0	Número entero	No
LogFileSize	Te permite establecer el tamaño máximo de cada archivo de registro en bytes.	0	Largo	No
MaxResults	Permite especificar la cantidad de resultados por página en el objeto Result de la API de BigQuery.	10000	Largo	No
MaxThreads	Define la cantidad máxima de subprocesos que el conector puede usar para el procesamiento simultáneo en un grupo de subprocesos. Para configurar esta propiedad como un parámetro de configuración para todo el conector en conectores que no son de Windows (Linux/macOS), debes especificarla en el archivo googlebigqueryodbc.ini.	8	Número entero	No
OAuthMechanism	Es el tipo de autenticación. Elige una de las siguientes opciones: 0: Autenticación de la cuenta de servicio 3: Autenticación con credenciales predeterminadas de la aplicación 4: Autenticación de federación de identidades de personal o carga de trabajo	N/A	Número entero	Sí
ProjectId	Es el ID del proyecto predeterminado para el controlador. El controlador usa este proyecto para ejecutar consultas y lo factura por el uso de recursos.	N/A	String	Sí
ProxyHost	Nombre de host o dirección IP de un servidor proxy.	N/A	String	No
ProxyPort	Número de puerto en el que escucha el servidor proxy.	N/A	String	No
ProxyPwd	Contraseña para la autenticación cuando se conecta a través de un servidor proxy.	N/A	String	No
ProxyUid	Nombre de usuario para la autenticación cuando se conecta a través de un servidor proxy.	N/A	String	No
PrivateServiceConnectUris	Son extremos personalizados para reemplazar los extremos predeterminados. Ejemplos: BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/ READ_API=bigquerystorage.us-east4.rep.googleapis.com OAUTH2=oauth2.us-east4.rep.googleapis.com	N/A	Cadena separada por comas	No
QueryDialect	Especifica qué dialecto de consulta se debe usar. Usa SQL para GoogleSQL (muy recomendado) y BIG_QUERY para SQL heredado.	SQL	String	No
QueryProperties	Configura propiedades que pueden modificar el comportamiento de la búsqueda.	N/A	Map<String, String>	No
UniverseDomain	Especifica el dominio del universo de tu organización.	googleapis.com	String	No
UseQueryCache	Te permite habilitar la función de almacenamiento en caché de consultas en BigQuery.	true	Booleano	No

Ejecuta consultas con el controlador

En esta sección, se proporciona información sobre la asignación de tipos de datos y ejemplos para ejecutar consultas con el controlador ODBC.

Asignación de tipos de datos

Cuando ejecutas consultas a través del controlador ODBC para BigQuery, se produce la siguiente asignación de tipos de datos (según los tipos de SQL de ODBC estándar):

Tipo de GoogleSQL	Tipo de SQL de ODBC
INT64	SQL_BIGINT
BOOL	SQL_BIT
DATE	SQL_TYPE_DATE
FLOAT64	SQL_DOUBLE
TIME	SQL_TYPE_TIME
TIMESTAMP	SQL_TYPE_TIMESTAMP
DATETIME	SQL_TYPE_TIMESTAMP
BYTES	SQL_VARBINARY
STRING	SQL_VARCHAR
ARRAY	SQL_VARCHAR
STRUCT	SQL_VARCHAR
INTERVAL	SQL_VARCHAR
JSON	SQL_VARCHAR
GEOGRAPHY	SQL_VARCHAR
RANGE	SQL_VARCHAR
NUMERIC	SQL_NUMERIC
BIGNUMERIC	SQL_NUMERIC

Ejemplos

En los siguientes ejemplos, se muestra cómo usar consultas con parámetros y secuencias de comandos de varias instrucciones con el controlador ODBC.

Consultas con parámetros

// 1. Prepare statement
std::string insert_stmt = "INSERT INTO MyTable VALUES (?, ?, ?)";
status = SQLPrepare(hstmt, (SQLCHAR*)insert_stmt.c_str(), SQL_NTS);

// 2. Bind parameters
std::string str_val = "example_string";
long long int_val = 12345;
double float_val = 1.2345;

// Bind string field
status = SQLBindParameter(
    hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0,
    (SQLPOINTER)str_val.c_str(), str_val.size(), NULL);

// Bind integer field
status = SQLBindParameter(
    hstmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_BIGINT, 0, 0,
    &int_val, 0, NULL);

// Bind float field
status = SQLBindParameter(
    hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DOUBLE, 0, 0,
    &float_val, 0, NULL);

// 3. Execute statement
status = SQLExecute(hstmt);

Secuencias de comandos de varias instrucciones

// 1. Prepare and execute the multi-statement script
std::string query =
    "CREATE OR REPLACE TABLE MyTable (StringField STRING, IntegerField INTEGER); "
    "INSERT INTO MyTable VALUES ('example', 123); "
    "SELECT * FROM MyTable;";

status = SQLExecDirect(hstmt, (SQLCHAR*)query.c_str(), SQL_NTS);

// 2. Process results for each statement using SQLMoreResults
do {
    SQLSMALLINT num_cols;
    status = SQLNumResultCols(hstmt, &num_cols);

    if (num_cols > 0) {
        // This is a result-returning statement (e.g., SELECT)
        while (SQLFetch(hstmt) == SQL_SUCCESS) {
            // Process rows...
        }
    } else {
        // This is a non-result statement (e.g., CREATE, INSERT)
        SQLLEN row_count;
        SQLRowCount(hstmt, &row_count);
        // Process affected rows...
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);

Precios

Las consultas a través del controlador ODBC para BigQuery están sujetas a los precios de análisis estándar de BigQuery.