Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

BigQuery용 ODBC 드라이버 사용

BigQuery용 Open Database Connectivity (ODBC) 드라이버는 애플리케이션을 BigQuery에 연결합니다. 이를 통해 원하는 도구와 인프라로 BigQuery 기능을 사용할 수 있습니다.

시작하기 전에

Open Database Connectivity (ODBC) 드라이버와 드라이버 관리자에 익숙해야 합니다.

다음 시스템 요구사항을 참고하세요.

운영체제	지원되는 아키텍처	최소 버전 및 종속 항목
Windows	32비트 (x86), 64비트 (x64)	버전: Windows 10, Windows Server 2016 이상 종속 항목: Microsoft Visual C++ 재배포 가능 패키지(Visual Studio 2019 또는 2022용)
macOS	64비트 (x86_64), ARM64 (Apple Silicon)	버전: 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`에 추가해야 합니다.

BigQuery용 ODBC 드라이버의 연결 유형을 확인합니다. 드라이버는 다음 인증 방법을 지원합니다.

인증 방법	인증 정보	예시	연결 속성 (나중에 설정)
표준 서비스 계정	서비스 계정 키 (JSON 객체)	`my-sa-key`	`KeyFilePath`
워크로드 아이덴티티 제휴 또는 직원 ID 제휴	외부 계정 구성 파일의 잠재고객 속성	`//iam.googleapis.com/locations/global/...`	`BYOID_AudienceUrl`
	토큰 가져오기 및 환경 정보 파일	`{"file":"/path/to/file"}`	`BYOID_CredentialSource`
	사용자 프로젝트 (직원 풀만 해당)	`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비트 애플리케이션을 모두 지원합니다.

32비트 애플리케이션용 ODBCDriverforBigQuery_windows_x86.msi 다운로드
64비트 애플리케이션용 ODBCDriverforBigQuery_windows_x64.msi 다운로드

데이터 소스 이름 만들기

Windows에서 데이터 소스 이름을 만들려면 다음 단계를 따르세요.

시작 메뉴에서 ODBC 데이터 소스로 이동하여 BigQuery에 올바르게 연결되도록 클라이언트 애플리케이션과 비트 수가 동일한 버전을 선택합니다.
ODBC 데이터 소스 관리자에서 드라이버 탭을 클릭합니다.
설치된 ODBC 드라이버의 알파벳순 목록에서 BigQuery용 ODBC 드라이버를 찾습니다.
다음 옵션 중 하나를 선택합니다.
- 현재 사용자의 DSN을 만들려면 사용자 DSN 탭을 클릭합니다.
- 모든 사용자의 DSN을 만들려면 시스템 DSN 탭을 클릭합니다. 일부 애플리케이션은 다른 사용자 계정을 사용하여 데이터를 로드하며 다른 사용자 계정으로 생성된 사용자 DSN을 감지하지 못할 수 있으므로 시스템 DSN을 사용하는 것이 좋습니다.
추가를 클릭합니다.
새 데이터 소스 만들기 대화상자에서 ODBC Driver for BigQuery를 선택한 다음 완료를 클릭합니다.
BigQuery용 ODBC 드라이버 DSN 설정 대화상자가 열립니다.
데이터 소스 이름 필드에 DSN 이름을 입력합니다.
연결 속성 섹션에서 채워야 하는 값을 확인하세요.

Windows 이외

64비트 Linux 배포판은 32비트 애플리케이션과 64비트 애플리케이션을 모두 지원합니다. ODBC 드라이버의 아키텍처가 사용하려는 애플리케이션과 일치하는지 확인합니다. 예를 들어 64비트 애플리케이션에는 64비트 드라이버를 사용하고 32비트 애플리케이션에는 32비트 드라이버를 사용합니다. 단일 시스템에 두 드라이버 아키텍처를 동시에 설치할 수 있습니다.

Linux용 ODBCDriverforBigQuery_linux_latest.zip 다운로드
macOS용 ODBCDriverforBigQuery_macos_latest.tar.gz 다운로드

tar 또는 zip 파일 패키지를 사용하여 커넥터를 설치하려면 다음 단계를 따르세요.

커넥터를 설치할 디렉터리가 아직 없으면 디렉터리를 만듭니다.
편리한 임시 위치에 기본 zip 파일의 압축을 풉니다.
추출된 tar 또는 zip 파일의 폴더로 이동한 다음 (선택사항) 모든 파일과 폴더를 설치 디렉터리에 복사합니다.
추출 후 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: 워크로드 또는 직원 ID 제휴 인증
AUTH_PROPS: BigQuery에 인증할 때 기록한 인증 정보입니다.
OTHER_PROPS (선택사항): ODBC 드라이버의 추가 연결 속성입니다.

연결 속성

ODBC 드라이버 연결 속성은 데이터베이스에 연결을 설정할 때 연결 문자열에 포함하는 구성 매개변수입니다. BigQuery용 ODBC 드라이버는 다음 연결 속성을 지원합니다.

연결 속성	설명	기본값	데이터 유형	필수
`AdditionalProjects`	드라이버가 쿼리 및 메타데이터 작업을 위해 액세스할 수 있는 프로젝트입니다. `ProjectId` 속성으로 설정된 기본 프로젝트 외에 추가됩니다.	해당 사항 없음	쉼표로 구분된 문자열	아니요
`AllowHtapiForLargeResults`	드라이버가 읽기 API를 사용할 수 있는지 여부를 결정합니다.	`0`	불리언	아니요
`AllowLargeResults`	기존 SQL (`QueryDialect=BIG_QUERY`)을 사용할 때 ODBC 드라이버가 128MB보다 큰 쿼리 결과를 처리해야 하는지 여부를 지정합니다.	`0`	불리언	아니요
`BYOID_AudienceUrl`	대상에는 워크로드 아이덴티티 풀 또는 직원 풀의 리소스 이름과 해당 풀의 공급자 식별자가 포함됩니다.	해당 사항 없음	문자열	`OAuthMechanism=4`인 경우에만
`BYOID_CredentialSource`	토큰 자체를 가져오는 데 필요한 정보와 일부 환경 정보를 설정합니다.	해당 사항 없음	문자열	`OAuthMechanism=4`인 경우에만
`BYOID_PoolUserProject`	워크로드 아이덴티티 풀이 아닌 직원 풀인 경우 이를 설정합니다.	해당 사항 없음	문자열	`OAuthMechanism=4`를 사용하고 직원 풀을 사용하는 경우에만
`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`	정수	아니요
`KeyFilePath`	서비스 계정 인증을 사용하는 경우 서비스 계정 키의 경로입니다.	해당 사항 없음	문자열	`OAuthMechanism=0`인 경우에만
`KMSKeyName`	데이터를 암호화하고 복호화할 때 사용할 KMS 키의 이름을 지정할 수 있습니다.	해당 사항 없음	문자열	아니요
`LargeResultsDataSetId`	대규모 쿼리 결과를 저장할 대상 데이터 세트를 지정할 수 있습니다.	해당 사항 없음	문자열	아니요
`LargeResultsDatasetExpirationTime`	대규모 결과 데이터 세트의 모든 테이블의 수명을 밀리초 단위로 지정할 수 있습니다.	`3600000`	길이	아니요
`Location`	드라이버가 데이터 세트를 만들거나 쿼리하는 위치를 지정할 수 있습니다.	해당 사항 없음	문자열	아니요
`LogLevel`	상호작용 중에 드라이버가 로깅하는 세부정보를 제한합니다. 다음 중 하나를 선택합니다. `0`: `OFF` `1`: `ERROR` `2`: `WARNING` `3`: `INFO`	`0`	정수	아니요
`LogPath`	드라이버가 로그 파일을 쓰는 디렉터리를 지정할 수 있습니다.	해당 사항 없음	문자열	아니요
`LogFileCount`	보관할 최대 로그 파일 수를 설정할 수 있습니다.	`0`	정수	아니요
`LogFileSize`	각 로그 파일의 최대 크기를 바이트 단위로 설정할 수 있습니다.	`0`	길이	아니요
`MaxResults`	BigQuery API 결과의 페이지당 결과 수를 지정할 수 있습니다.	`10000`	길이	아니요
`MaxThreads`	커넥터가 스레드 풀에서 동시 처리에 사용할 수 있는 최대 스레드 수를 정의합니다. 이 속성을 비 Windows(Linux/macOS) 커넥터의 커넥터 전체 설정으로 구성하려면 `googlebigqueryodbc.ini` 파일에 지정합니다.	`8`	정수	아니요
`OAuthMechanism`	인증 유형입니다. 다음 중 하나를 선택합니다. `0`: 서비스 계정 인증 `3`: 애플리케이션 기본 사용자 인증 정보 인증 `4`: 워크로드 또는 직원 ID 제휴 인증	해당 사항 없음	정수	예
`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`을 사용하고 legacy SQL에는 `BIG_QUERY`을 사용합니다.	`SQL`	문자열	아니요
`QueryProperties`	쿼리 동작을 수정할 수 있는 속성을 구성합니다.	해당 사항 없음	Map<String, String>	아니요
`UniverseDomain`	조직의 유니버스 도메인을 지정합니다.	`googleapis.com`	문자열	아니요
`UseQueryCache`	BigQuery에서 쿼리 캐싱 기능을 사용 설정할 수 있습니다.	`true`	불리언	아니요

드라이버로 쿼리 실행

이 섹션에서는 데이터 유형 매핑과 ODBC 드라이버를 사용하여 쿼리를 실행하는 예를 제공합니다.

데이터 유형 매핑

BigQuery용 ODBC 드라이버를 통해 쿼리를 실행하면 다음 데이터 유형 매핑이 발생합니다 (표준 ODBC SQL 유형 기준).

GoogleSQL 유형	ODBC SQL 유형
`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`

예시

다음 예에서는 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 분석 가격 책정이 적용됩니다.