BigQuery 用の ODBC ドライバを使用する

BigQuery 用の Open Database Connectivity（ODBC）ドライバは、アプリケーションを BigQuery に接続します。これにより、任意のツールとインフラストラクチャで BigQuery の機能を使用できます。

始める前に

  1. Open Database Connectivity（ODBC）ドライバとドライバ マネージャーについて十分に理解しておきます。

  2. 次のシステム要件に注意してください。

    OS サポートされているアーキテクチャ 最小バージョンと依存関係
    Windows 32 ビット（x86）、64 ビット（x64） バージョン: Windows 10、Windows Server 2016 以降
    依存関係: Microsoft Visual C++ 再頒布可能パッケージ（Visual Studio 2019 または 2022 用）
    macOS 64 ビット（x86_64）、ARM64（Apple シリコン） バージョン: macOS 12（Monterey）以降
    依存関係: ODBC ドライバ マネージャー（unixODBC など）。インストール ディレクトリを DYLD_LIBRARY_PATH に追加してください。
    Linux 64 ビット（x86_64） バージョン: glibc 2.27 以降を含む任意のディストリビューション（Ubuntu 20.04 LTS 以降、Debian 11 以降など）
    依存関係: ODBC ドライバ マネージャー（unixODBC など）。インストール ディレクトリを LD_LIBRARY_PATH に追加してください。

  3. BigQuery 用の ODBC ドライバの接続タイプを特定します。ドライバは、次の認証方法をサポートしています。

    認証方法 認証情報 例 接続プロパティ（後で設定）
    標準サービス アカウント サービス アカウント キー（JSON オブジェクト） my-sa-key KeyFilePath
    Workload Identity 連携または Workforce Identity 連携 外部アカウント構成ファイルのオーディエンス プロパティ //iam.googleapis.com/locations/global/... BYOID_AudienceUrl
    トークンの取得と環境情報ファイル {"file":"/path/to/file"} BYOID_CredentialSource
    ユーザー プロジェクト（Workforce プールの場合のみ） my_project BYOID_PoolUserProject
    STS トークンのタイプ id_token またはその他の STS タイプ BYOID_SubjectTokenType
    STS トークン交換エンドポイント カスタム sts エンドポイント URL BYOID_TokenUrl
    アプリケーションのデフォルト認証情報 なし なし なし

ODBC ドライバをインストールして構成する

このセクションでは、Windows オペレーティング システムと Windows 以外のオペレーティング システムに ODBC ドライバをインストールして構成する方法について説明します。

Windows

Windows では、アプリケーションのアーキテクチャと一致するドライバ アーキテクチャをインストールしてください。たとえば、64 ビット アプリケーションには 64 ビット ドライバを使用し、32 ビット アプリケーションには 32 ビット ドライバを使用します。64 ビットの Windows システムは、32 ビット アプリケーションと 64 ビット アプリケーションの両方をサポートします。

データソース名を作成する

Windows でデータソース名を作成するには:

  1. [スタート] メニューから [ODBC データソース] に移動し、クライアント アプリケーションと同じビット数のバージョンを選択して、BigQuery への接続が適切に行われるようにします。
  2. ODBC データソース アドミニストレータで、[ドライバ] タブをクリックします。
  3. インストールされている ODBC ドライバのアルファベット順のリストで、ODBC Driver for BigQuery を見つけます。
  4. 次のいずれかのオプションを選択します。
    • 現在のユーザーの DSN を作成するには、[ユーザー DSN] タブをクリックします。
    • すべてのユーザーの DSN を作成するには、[システム DSN] タブをクリックします。システム DSN は、一部のアプリケーションが異なるユーザー アカウントを使用してデータを読み込み、別のユーザー アカウントで作成されたユーザー DSN を検出しない可能性があるため、推奨されます。
  5. [追加] をクリックします。
  6. [Create New Data Source] ダイアログで、[ODBC Driver for BigQuery] を選択し、[Finish] をクリックします。
  7. [ODBC Driver for BigQuery DSN Setup] ダイアログが開きます。
  8. [データソース名] フィールドに、DSN の名前を入力します。
  9. 入力する値については、接続プロパティ セクションをご覧ください。

Windows 以外

64 ビット版 Linux ディストリビューションは、32 ビット版と 64 ビット版の両方のアプリをサポートしています。ODBC ドライバのアーキテクチャが、使用するアプリケーションと一致していることを確認します。たとえば、64 ビット アプリケーションには 64 ビット ドライバを使用し、32 ビット アプリケーションには 32 ビット ドライバを使用します。1 つのシステムに両方のドライバ アーキテクチャを同時にインストールできます。

tar または zip ファイル パッケージを使用してコネクタをインストールするには:

  1. コネクタをインストールするディレクトリが存在しない場合は、作成します。
  2. メインの ZIP ファイルを一時的な場所に解凍します。
  3. 抽出した tar ファイルまたは zip ファイルのフォルダに移動し、すべてのファイルとフォルダをインストール ディレクトリにコピーします（省略可）。
  4. 抽出後、BigQuery 用 ODBC ドライバの共有オブジェクト パスは [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so になります。.ini ファイルを更新して、コネクタの正しいパスを反映します。
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

接続を確立する

BigQuery 用の ODBC ドライバを使用して接続を確立するには、接続文字列または DSN を使用します。

接続文字列の形式

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

次のように置き換えます。

  • PROJECT_ID: BigQuery プロジェクトの ID。
  • AUTH_TYPE: 使用した認証のタイプを指定する数値。次のいずれかを選択します。
    • 0: サービス アカウント認証用
    • 3: アプリケーションのデフォルト認証情報による認証の場合
    • 4: Workload Identity 連携または Workforce Identity 連携の認証の場合
  • AUTH_PROPS: BigQuery への認証時にメモした認証情報。
  • OTHER_PROPS（省略可）: ODBC ドライバの追加の接続プロパティ。

接続プロパティ

ODBC ドライバの接続プロパティは、データベースへの接続を確立するときに接続文字列に含める構成パラメータです。BigQuery 用の ODBC ドライバは、次の接続プロパティをサポートしています。

接続プロパティ 説明 デフォルト値 データの種類 必須
AdditionalProjects ProjectId プロパティで設定されたプライマリ プロジェクトに加えて、ドライバがクエリとメタデータ オペレーションでアクセスできるプロジェクト。 なし カンマ区切りの文字列 ×
AllowHtapiForLargeResults ドライバが Read API を使用できるかどうかを判断します。 0 ブール値 ×
AllowLargeResults レガシー SQL（QueryDialect=BIG_QUERY）を使用する場合に、ODBC ドライバが 128 MB を超えるクエリ結果を処理するかどうかを指定します。 0 ブール値 ×
BYOID_AudienceUrl オーディエンスには、Workload Identity プールまたは Workforce プールのリソース名と、そのプール内のプロバイダ ID が含まれます。 なし 文字列 OAuthMechanism=4 の場合のみ
BYOID_CredentialSource トークン自体を取得するために必要な情報と、環境情報を設定します。 なし 文字列 OAuthMechanism=4 の場合のみ
BYOID_PoolUserProject Workload Identity プールではなく Workforce プールの場合に設定します。 なし 文字列 OAuthMechanism=4 を使用し、Workforce Pool を使用している場合のみ
BYOID_SubjectTokenType Oauth2.0 トークン交換仕様に基づいて STS トークンタイプを設定します。想定される値は次のとおりです。
  • 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
 なし 文字列 OAuthMechanism=4 の場合のみ
BYOID_TokenUrl STS トークン交換エンドポイントを設定します。 https://sts.googleapis.com/v1/token 文字列 ×
DefaultDataset データセットを明示的に指定せずにクエリを実行するときに、ドライバが自動的に参照するプロジェクト内の指定されたデータセットとして機能します。 なし 文字列 ×
FilterTablesOnDefaultDataset テーブル/列のメタデータ メソッドが返すメタデータのスコープを決定します。FALSE の場合、フィルタリングは行われません。フィルタリングを有効にするには、DefaultDataset プロパティも設定する必要があります。 FALSE ブール値 ×
EnableSession 接続がセッションを開始するかどうかを決定します。有効にすると、その特定の接続で実行される最初のクエリがセッションを開始し、ドライバはセッション ID を後続のすべてのクエリに渡します。 0 ブール値 ×
JobCreationMode 低レイテンシのクエリパスを有効にできます。次のいずれかを選択します。
  • 1: ドライバはすべてのクエリに対してジョブを作成します（JOB_CREATION_REQUIRED）。
  • 2: ドライバはジョブなしでクエリを実行します（JOB_CREATION_OPTIONAL）
 2 Integer ×
KeyFilePath サービス アカウント認証を使用する場合のサービス アカウント キーのパス。 なし 文字列 OAuthMechanism=0 の場合のみ
KMSKeyName データの暗号化と復号に使用する KMS 鍵の名前を指定できます。 なし 文字列 ×
LargeResultsDataSetId 大規模なクエリ結果を格納する宛先データセットを指定できます。 なし 文字列 ×
LargeResultsDatasetExpirationTime 大きな結果データセット内のすべてのテーブルの存続期間をミリ秒単位で指定できます。 3600000 長い ×
Location ドライバがデータセットを作成またはクエリするロケーションを指定できます。 なし 文字列 ×
LogLevel インタラクション中にドライバがログに記録する詳細を制限します。次のいずれかを選択します。
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Integer ×
LogPath ドライバがログファイルを書き込むディレクトリを指定できます。 なし 文字列 ×
LogFileCount 保持するログファイルの最大数を設定できます。 0 Integer ×
LogFileSize 各ログファイルの最大サイズをバイト単位で設定できます。 0 長い ×
MaxResults BigQuery API の結果でページあたりの結果数を指定できます。 10000 長い ×
MaxThreads コネクタがスレッドプールで同時処理に使用できるスレッドの最大数を定義します。このプロパティを Windows 以外の（Linux/macOS）コネクタのコネクタ全体の設定として構成するには、googlebigqueryodbc.ini ファイルで指定します。 8 Integer ×
OAuthMechanism 認証タイプ。次のいずれかを選択します。
  • 0: サービス アカウント認証
  • 3: アプリケーションのデフォルト認証情報による認証
  • 4: Workload Identity 連携または Workforce Identity 連携の認証
 なし Integer ○
ProjectId ドライバのデフォルト プロジェクト ID。ドライバはこのプロジェクトを使用してクエリを実行し、リソース使用量に対して課金します。 なし 文字列 ○
ProxyHost プロキシ サーバーのホスト名または IP アドレス。 なし 文字列 ×
ProxyPort プロキシ サーバーがリッスンしているポート番号。 なし 文字列 ×
ProxyPwd プロキシ サーバー経由で接続する際の認証に使用するパスワード。 なし 文字列 ×
ProxyUid プロキシ サーバー経由で接続する際の認証に使用するユーザー名。 なし 文字列 ×
PrivateServiceConnectUris デフォルトのエンドポイントを上書きするカスタム エンドポイント。例:
  • BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/
  • READ_API=bigquerystorage.us-east4.rep.googleapis.com
  • OAUTH2=oauth2.us-east4.rep.googleapis.com
 なし カンマ区切りの文字列 ×
QueryDialect 使用するクエリ言語を指定します。GoogleSQL（強く推奨）には SQL を使用し、レガシー SQL には BIG_QUERY を使用します。 SQL 文字列 ×
QueryProperties クエリの動作を変更できるプロパティを構成します。 なし Map<String, String> ×
UniverseDomain 組織のユニバース ドメインを指定します。 googleapis.com 文字列 ×
UseQueryCache BigQuery でクエリ キャッシュ機能を有効にできます。 true ブール値 ×

ドライバを使用してクエリを実行する

このセクションでは、データ型のマッピングと、ODBC ドライバでクエリを実行する例について説明します。

データ型マッピング

BigQuery 用の ODBC ドライバを介してクエリを実行すると、次のデータ型マッピングが行われます（標準 ODBC SQL 型に基づく）。

GoogleSQL 型 ODBC SQL 型
INT64SQL_BIGINT
BOOLSQL_BIT
DATESQL_TYPE_DATE
FLOAT64SQL_DOUBLE
TIMESQL_TYPE_TIME
TIMESTAMPSQL_TYPE_TIMESTAMP
DATETIMESQL_TYPE_TIMESTAMP
BYTESSQL_VARBINARY
STRINGSQL_VARCHAR
ARRAYSQL_VARCHAR
STRUCTSQL_VARCHAR
INTERVALSQL_VARCHAR
JSONSQL_VARCHAR
GEOGRAPHYSQL_VARCHAR
RANGESQL_VARCHAR
NUMERICSQL_NUMERIC
BIGNUMERICSQL_NUMERIC

例

次の例は、ODBC ドライバでパラメータ化クエリと複数ステートメント スクリプトを使用する方法を示しています。

パラメータ化されたクエリ

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

マルチステートメント スクリプト

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

料金

BigQuery 用の ODBC ドライバを介したクエリには、標準の BigQuery 分析料金が適用されます。