BigQuery용 JDBC 드라이버 사용

BigQuery용 Java 데이터베이스 연결 (JDBC) 드라이버는 Java 애플리케이션을 BigQuery에 연결하여 원하는 도구 및 인프라로 BigQuery 기능을 사용할 수 있도록 지원합니다. 이 드라이버는 BigQuery용으로 특별히 설계되었으며 다른 제품 또는 서비스에는 사용할 수 없습니다. 이 드라이버를 사용하는 데 추가 라이선스가 필요하지 않습니다.

시작하기 전에

JDBC 드라이버와 java.sql 패키지를 숙지해야 합니다.
시스템이 Java 런타임 환경 (JRE) 8.0 이상으로 구성되어 있는지 확인합니다.

드라이버 구성

BigQuery용 JDBC 드라이버를 구성하려면 드라이버를 설치하고 BigQuery에 인증하고 연결을 설정해야 합니다.

드라이버 설치

다음 JDBC 패키지 중 하나를 다운로드합니다.
- Uber JAR 모든 종속 항목이 포함된 단일 JAR 파일입니다.
- 종속 항목이 있는 씬 JAR 모든 종속 항목이 포함된 씬 JAR 파일이 포함된 ZIP 파일입니다.
- 음영 처리된 Uber JAR 모든 종속 항목이 포함되고 추가로 셰이딩된 단일 JAR 파일입니다.
Java 컴파일러와 런타임이 필요한 JDBC 클래스를 찾을 수 있도록 다운로드한 JAR 파일을 클래스 경로에 추가합니다.

BigQuery에 인증

BigQuery용 JDBC 드라이버는 다음과 같은 여러 인증 옵션을 제공합니다.

서비스 계정 사용
Google 사용자 계정 사용
사전 생성된 액세스 및 갱신 토큰 사용
애플리케이션 기본 사용자 인증 정보 사용
외부 메서드 사용

서비스 계정을 사용하여 인증

BigQuery용 JDBC 드라이버와 연결을 설정할 때는 다음을 실행하세요.

OAuthType 연결 속성을 0로 설정합니다.
ProjectId 연결 속성을 BigQuery 프로젝트의 이름으로 설정합니다.
다음 중 한 가지 방법을 사용합니다.
- 서비스 계정 이메일과 키를 사용하는 경우 OAuthServiceAcctEmail 연결 속성을 Google 서비스 계정 이메일 주소로 설정하고 OAuthPvtKey 연결 속성을 서비스 계정 키 JSON 객체로 설정합니다. OAuthPvtKey의 경우 키의 JSON 객체 또는 키 파일의 전체 경로를 사용할 수 있습니다.
- 서비스 계정 키 파일을 사용하는 경우 OAuthPvtKeyPath 연결 속성을 서비스 계정 키 파일의 전체 경로로 설정합니다.

다음 두 예에서는 서비스 계정 인증을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthServiceAcctEmail=bq-jdbc-sa@mytestproject.iam.gserviceaccount.com;
OAuthPvtKey=my-sa-key

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthPvtKeyPath=path/to/file/secret.json;

Google 사용자 계정으로 인증

BigQuery용 JDBC 드라이버와 연결을 설정할 때는 다음을 실행하세요.

OAuthType 연결 속성을 1로 설정합니다.
ProjectId 연결 속성을 BigQuery 프로젝트의 이름으로 설정합니다.
OAuthClientId 연결 속성을 클라이언트 ID로 설정하고 OAuthClientSecret 연결 속성을 클라이언트 보안 비밀번호로 설정합니다.

자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기 및 OAuth 클라이언트 관리를 참고하세요.

다음 예에서는 Google 사용자 계정 인증을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=1;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;

사전 생성된 액세스 또는 갱신 토큰으로 인증

BigQuery용 JDBC 드라이버와 연결을 설정할 때는 다음을 실행하세요.

OAuthType 연결 속성을 2로 설정합니다.
ProjectId 연결 속성을 BigQuery 프로젝트의 이름으로 설정합니다.
다음 중 한 가지 방법을 사용합니다.
- 사전 생성된 액세스 토큰을 사용하는 경우 OAuthAccessToken 연결 속성을 액세스 토큰으로 설정합니다.
- 사전 생성된 새로고침 토큰을 사용하는 경우 OAuthRefreshToken 연결 속성을 새로고침 토큰으로 설정하고, OAuthClientId 연결 속성을 클라이언트 ID로 설정하고, OAuthClientSecret 연결 속성을 클라이언트 보안 비밀번호로 설정합니다.

자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.

다음 예에서는 사전 생성된 액세스 토큰 인증을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthAccessToken=ya29.a0AfH6SMCiH1L-x_yZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_;

다음 예에서는 사전 생성된 갱신 토큰 인증을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;
OAuthRefreshToken=1/fFAGRNJru1FTz70BzhT3Zg;

애플리케이션 기본 사용자 인증 정보로 인증

애플리케이션 기본 사용자 인증 정보 (ADC)는 인증 라이브러리에서 애플리케이션 환경을 기준으로 사용자 인증 정보를 자동으로 찾는 데 사용되는 전략입니다.

BigQuery용 JDBC 드라이버와 연결을 설정할 때는 다음을 실행하세요.

OAuthType 연결 속성을 3로 설정합니다.
ProjectId 연결 속성을 BigQuery 프로젝트의 이름으로 설정합니다.

자세한 내용은 애플리케이션 기본 사용자 인증 정보 설정을 참조하세요.

다음 예에서는 ADC 인증을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=3;

외부 메서드로 인증

직원 ID 제휴 또는 워크로드 아이덴티티 제휴와 같은 외부 방법으로 인증할 수 있습니다.

BigQuery용 JDBC 드라이버와 연결을 설정할 때는 다음을 실행하세요.

OAuthType 연결 속성을 4로 설정합니다.
ProjectId 연결 속성을 BigQuery 프로젝트의 이름으로 설정합니다.
다음 중 한 가지 방법을 사용합니다.
- OAuthPvtKey 연결 속성 또는 OAuthPvtKeyPath 연결 속성을 구성 파일의 전체 경로로 설정합니다. OAuthPvtKey의 경우 키의 JSON 객체 또는 키 파일의 전체 경로를 사용할 수 있습니다.
- OAuthPvtKey 연결 속성을 원시 외부 계정 구성 객체로 설정합니다.
- 연결 속성 섹션에 설명된 다음 BYOID 연결 속성을 설정합니다.
  - BYOID_AudienceUri
  - BYOID_CredentialSource
  - BYOID_PoolUserProject
  - BYOID_SA_Impersonation_Uri
  - BYOID_SubjectTokenType
  - BYOID_TokenUri

다음 예에서는 외부 인증 방법을 사용합니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKeyPath=path/to/file/secret.json;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKey=External_account_configuration_object;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
BYOID_AudienceUri=//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider;
BYOID_SubjectTokenType=urn:ietf:params:oauth:tokentype:id_token;
BYOID_CredentialSource={\"file\":\"/path/to/file\"};
BYOID_SA_Impersonation_Uri=my-sa;
BYOID_TokenUri=https://sts.googleapis.com/v1/token;"

다음은 구성 파일의 예시입니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/my_pool_name/providers/my_provider_name",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "/path/to/workforce/tokrn.txt"
  },
  "workforce_pool_user_project": "my_project",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

연결 설정

BigQuery용 JDBC 드라이버와 연결하려면 다음을 실행하세요.

Maven POM/Gradle 빌드 파일에 google-cloud-bigquery-jdbc 종속 항목을 추가합니다.

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>0.0.1</version>
    <scope>system</scope>
    <systemPath>path/to/file/google-jdbc-jar-with-dependencies.jar</systemPath>
</dependency>

Gradle 프로젝트를 사용하는 경우 빌드 파일에도 다음을 추가합니다.

dependencies {
// ... other dependencies
implementation files('path/to/file/google-jdbc-jar-with-dependencies.jar')
}

JDBC 드라이버의 연결 문자열을 식별합니다. 이 문자열은 Java 애플리케이션과 특정 데이터베이스 간의 연결을 설정하는 데 필요한 모든 필수 정보를 캡처합니다. BigQuery 연결 문자열의 JDBC 드라이버는 다음 형식을 따릅니다.
```
jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;PROPERTIES
```
다음을 바꿉니다.
- HOST: 서버의 DNS 또는 IP 주소입니다.
- PORT: TCP 포트 번호입니다.
- PROJECT_ID: BigQuery 프로젝트의 ID입니다.
- AUTH_TYPE: 사용한 인증 유형을 지정하는 숫자입니다. 다음 필드 중 하나는 사용해야 합니다.
  - 0: Google 서비스 계정 인증
  - 1: Google 사용자 계정 인증
  - 2: 사전 생성된 갱신 토큰 또는 액세스 토큰 인증
  - 3: 애플리케이션 기본 사용자 인증 정보 인증
  - 4: 직원 ID 제휴 또는 워크로드 아이덴티티 제휴와 같은 외부 인증 방법
- PROPERTIES: JDBC 드라이버의 추가 연결 속성입니다. 속성은 property_1=value_1; property_2=value_2;... 형식으로 나열해야 합니다. 속성 이름은 대소문자를 구분하지 않습니다. 연결 속성의 전체 목록은 연결 속성을 참고하세요.

DriverManager 또는 DataSource 클래스로 드라이버에 연결합니다.

DriverManager 클래스에 연결합니다.

import java.sql.Connection;
import java.sql.DriverManager;

private static Connection getJdbcConnectionDM(){
  Connection connection = DriverManager.getConnection(CONNECTION_STRING);
  return connection;
}

CONNECTION_STRING를 이전 단계의 연결 문자열로 바꿉니다.

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;
}

CONNECTION_STRING를 이전 단계의 연결 문자열로 바꿉니다.

DataSource 클래스에는 연결 문자열에 모든 속성을 포함하는 대신 연결 속성을 설정하는 데 사용할 수 있는 setter 메서드도 있습니다. 다음은 그 예시입니다.

private static Connection getConnection() throws SQLException {
  DataSource ds = new DataSource();
  ds.setURL(CONNECTION_STRING);
  ds.setAuthType(3);  // Application Default Credentials
  ds.setProjectId("MyTestProject");
  ds.setEnableHighThroughputAPI(true);
  ds.setLogLevel("6");
  ds.setUseQueryCache(false);
  return ds.getConnection();
}

운전자 기능 살펴보기

이제 BigQuery용 JDBC 드라이버에 연결되었으므로 기능을 살펴볼 수 있습니다.

SQL 커넥터

SQL 커넥터를 사용하면 BigQuery로 SQL 쿼리를 실행할 수 있습니다. QueryDialect 연결 속성을 사용하여 사용할 SQL 다이얼렉트를 지정합니다.

데이터 유형 매핑

BigQuery용 JDBC 드라이버는 다음 데이터 유형 매핑을 지원합니다.

BigQuery 유형	SQL 유형	Java 유형
`ARRAY`	`ARRAY`	`Array`
`BIGNUMERIC`	`NUMERIC`	`BigDecimal`
`BOOL`	`BOOLEAN`	`Boolean`
`BYTES`	`VARBINARY`	`byte[]`
`DATE`	`DATE`	`Date`
`DATETIME`	`OTHER`	`String`
`FLOAT64`	`DOUBLE`	`Double`
`GEOGRAPHY`	`OTHER`	`String`
`INT64`	`BIGINT`	`Long`
`INTERVAL`	`OTHER`	`String`
`JSON`	`OTHER`	`String`
`NUMERIC`	`NUMERIC`	`BigDecimal`
`STRING`	`NVARCHAR`	`String`
`STRUCT`	`STRUCT`	`Struct`
`TIME`	`TIME`	`Time`
`TIMESTAMP`	`TIMESTAMP`	`Timestamp`

중첩되고 반복되는 레코드

BigQuery용 JDBC 드라이버는 중첩 및 반복 레코드를 지원하며, 드라이버는 기본 유형을 구조체 객체 또는 JSON 객체의 문자열 표현으로 반환합니다.

다음은 구조체 데이터의 기본 레코드를 쿼리하는 예입니다.

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

결과는 다음과 같습니다.

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

다음은 구조체 객체의 하위 구성요소를 쿼리하는 예입니다.

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());
    }

다음은 반복 데이터의 표준 배열을 쿼리하는 예시입니다.

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

다음은 반복 데이터의 구조체 배열을 쿼리하는 예입니다.

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

대규모 결과 집합

BigQuery용 JDBC 드라이버를 사용할 때 큰 결과 세트를 가져오려면 다음 단계를 따르세요.

QueryDialect 연결 속성이 SQL로 설정된 경우 LargeResultDataset 및 LargeResultTable 연결 속성을 사용하여 결과를 저장할 데이터 세트와 테이블을 지정합니다.
QueryDialect 연결 속성이 BIG_QUERY로 설정된 경우 AllowLargeResults 연결 속성을 TRUE로 설정하고 LargeResultDataset 및 LargeResultTable 연결 속성을 사용하여 결과를 저장할 데이터 세트와 테이블을 지정합니다.

두 경우 모두 LargeResultsDatasetExpirationTime 연결 속성을 사용하여 대상 데이터 세트의 전체 기간을 지정할 수 있습니다.

LargeResultDataset 및 LargeResultTable 연결 속성의 값을 지정하지 않으면 BigQuery용 JDBC 드라이버가 _google_jdbc라는 숨겨진 데이터 세트와 그 안에 임시 테이블을 만듭니다. 이러한 리소스는 24시간 후에 자동으로 삭제됩니다.

모든 BigQuery 할당량 및 한도는 계속 적용됩니다.

위치 매개변수

위치 매개변수는 쿼리 실행 중에 제공될 값을 나타내는 SQL 문 내의 자리표시자입니다. BigQuery용 JDBC 드라이버는 물음표 기호 (?)를 사용하여 위치 매개변수를 지원합니다. 다음은 위치 매개변수를 사용하는 쿼리의 예입니다.

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

쿼리 `SELECT`회

BigQuery용 JDBC 드라이버를 사용하여 BigQuery API 또는 BigQuery Storage Read API를 통해 SELECT 쿼리를 실행할 수 있습니다.

BigQuery API를 사용하는 경우 JobCreationMode 연결 속성을 설정하여 작업을 만들지 않고 쿼리를 실행할지 여부를 지정합니다.

Storage Read API를 사용하는 경우 EnableHighThroughputAPI 연결 속성을 사용하여 API를 사용 설정하고 다음 조건을 충족하는지 확인합니다.

스키마에서 INTERVAL 유형을 사용하지 않습니다.
총 행 수가 HighThroughputMinTableSize 연결 속성 값보다 적습니다.
행 대 페이지 크기 비율이 HighThroughputActivationRatio 연결 속성 값보다 작습니다.

일괄 삽입

BigQuery용 JDBC 드라이버를 사용하여 대량 삽입 작업을 실행하려면 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();

로깅

BigQuery용 JDBC 드라이버는 Java Util Logging을 통해 드라이버에서 로깅 작업을 지원합니다. 로깅은 성능에 영향을 줄 수 있으므로 문제를 포착할 때만 사용 설정하고 완료한 후에는 사용 중지하세요.

로깅을 구성하려면 다음 단계를 따르세요.

다음 표에 따라 LogLevel 속성을 설정합니다.

`LogLevel` 값	`LogLevel`	설명
`0`	`OFF`	메시지가 로깅되지 않습니다.
`1`	`SEVERE`	애플리케이션 기능에 영향을 미치는 심각한 장애 또는 오류
`2`	`WARNING`	주의가 필요할 수 있는 잠재적인 문제 또는 상황입니다.
`3`	`INFO`	일반 이벤트 및 진행 상황에 관한 정보 메시지입니다.
`4`	`CONFIG`	정적 구성 정보에 관한 메시지입니다.
`5`	`FINE`	일반 추적 메시지입니다.
`6`	`FINER`	자세한 추적 메시지
`7`	`FINEST`	매우 상세한 추적 메시지로, 광범위한 디버깅에 유용합니다.
`8`	`ALL`	모든 메시지가 로깅됩니다.

로그 파일을 저장할 폴더의 전체 경로로 LogPath 속성을 설정합니다.

또는 BIGQUERY_JDBC_LOG_LEVEL 및 BIGQUERY_JDBC_LOG_PATH 환경 변수를 사용하여 로깅을 구성할 수 있습니다.

연결 속성

JDBC 드라이버에서 연결 속성은 데이터베이스에 연결할 때 연결 문자열에 포함하거나 setter 메서드를 통해 전달할 수 있는 구성 매개변수입니다. 다음 연결 속성은 BigQuery용 JDBC 드라이버에서 지원됩니다.

AdditionalProjects

이 연결 속성을 사용하면 쿼리 및 메타데이터 작업이 연결 문자열에 정의된 기본 프로젝트 외에도 지정된 프로젝트 내의 데이터 세트에 액세스할 수 있습니다.

기본값: 해당 사항 없음
데이터 유형: 문자열 (쉼표로 구분된 프로젝트 ID 문자열)
필수: 아니요

AllowLargeResults

이 연결 속성은 QueryDialect 연결 속성이 BIG_QUERY로 설정된 경우 드라이버가 128MB보다 큰 쿼리 결과를 처리하는지 여부를 지정합니다. QueryDialect 연결 속성이 SQL로 설정되면 AllowLargeResults 연결 속성이 기본적으로 TRUE로 설정됩니다. 자세한 내용은 대규모 결과 집합을 참고하세요.

기본값: TRUE
데이터 유형: 불리언
필수: 아니요

BYOID_AudienceUri

이 연결 속성은 외부 계정 구성 파일의 잠재고객 속성을 지정합니다. audience 속성에는 워크로드 아이덴티티 풀 또는 직원 풀의 리소스 이름과 해당 풀의 공급자 식별자가 포함됩니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: OAuthType=4인 경우에만

BYOID_CredentialSource

이 연결 속성은 토큰 검색 정보와 환경 정보를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: OAuthType=4인 경우에만

BYOID_PoolUserProject

이 연결 속성은 직원 풀이 사용될 때 사용자 프로젝트를 설정합니다. 프로젝트에 serviceusage.services.use IAM 권한이 있어야 합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: OAuthType=4를 사용하고 직원 풀을 사용하는 경우에만

BYOID_SA_Impersonation_Uri

이 연결 속성은 워크로드 아이덴티티 풀이 사용되고 API가 UberMint와 통합되지 않은 경우 서비스 계정 가장의 URL을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: OAuthType=4이고 서비스 계정 명의 도용과 함께 워크로드 아이덴티티 풀을 사용하는 경우에만

BYOID_SubjectTokenType

이 연결 속성은 토큰 교환 사양에 따라 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
기본값: urn:ietf:params:oauth:tokentype:id_token
데이터 유형: 문자열
필수: OAuthType=4인 경우에만

BYOID_TokenUri

이 연결 속성은 STS 토큰 교환 엔드포인트를 설정합니다.

기본값: https://sts.googleapis.com/v1/token
데이터 유형: 문자열
필수: 아니요

ConnectionPoolSize

이 연결 속성은 연결 풀링이 사용 설정된 경우 연결 풀 크기를 설정합니다.

기본값: 10
데이터 유형: Long
필수: 아니요

DefaultDataset

이 연결 속성은 데이터 세트를 명시적으로 지정하지 않고 쿼리를 실행할 때 사용되는 데이터 세트를 지정합니다. DATASET_ID 또는 PROJECT_ID.DATASET_ID 형식을 사용할 수 있습니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

EnableHighThroughputAPI

이 연결 속성은 Storage Read API를 사용할 수 있는지 여부를 결정합니다. Storage Read API를 사용하려면 HighThroughputActivationRatio 및 HighThroughputMinTableSize 연결 속성도 충족해야 합니다.

기본값: FALSE
데이터 유형: 불리언
필수: 아니요

EnableSession

이 연결 속성은 연결이 세션을 시작하는지 여부를 결정합니다. 사용하면 세션 ID가 모든 후속 쿼리에 전달됩니다.

기본값: FALSE
데이터 유형: 불리언
필수: 아니요

EnableWriteAPI

이 연결 속성은 Storage Write API를 사용할 수 있는지 여부를 결정합니다. 일괄 삽입을 사용 설정하려면 TRUE로 설정해야 합니다.

기본값: FALSE
데이터 유형: 불리언
필수: 아니요

EndpointOverrides

이 연결 속성은 쉼표로 구분된 문자열에 맞춤 엔드포인트를 설정합니다.

기본값:
- BIGQUERY=https://bigquery.googleapis.com
- READ_API=https://bigquerystorage.googleapis.com
- OAUTH2=https://oauth2.googleapis.com
- STS=https://sts.googleapis.com
데이터 유형: 문자열
필수: 아니요

FilterTablesOnDefaultDataset

이 연결 속성은 DatabaseMetaData.getTables() 및 DatabaseMetaData.getColumns() 메서드에서 반환되는 메타데이터의 범위를 제어합니다. 속성이 사용 중지되면 필터링이 발생하지 않습니다. 필터링을 사용 설정하려면 DefaultDataset 연결 속성도 설정해야 합니다.

기본값: FALSE
데이터 유형: 불리언
필수: 아니요

HighThroughputActivationRatio

이 연결 속성은 쿼리 응답의 페이지 수에 대한 기준점을 설정합니다. 이 수를 초과하고 EnableHighThroughputAPI 및 HighThroughputMinTableSize 조건이 충족되면 드라이버는 스토리지 읽기 API를 사용하기 시작합니다.

기본값: 2
데이터 유형: 정수
필수: 아니요

HighThroughputMinTableSize

이 연결 속성은 쿼리 응답의 행 수에 대한 기준점을 설정합니다. 이 수를 초과하고 EnableHighThroughputAPI 및 HighThroughputActivationRatio 조건이 충족되면 드라이버는 스토리지 읽기 API를 사용하기 시작합니다.

기본값: 100
데이터 유형: 정수
필수: 아니요

JobCreationMode

이 연결 속성은 작업을 만들지 않고 쿼리를 실행할지 여부를 결정합니다. 1 값은 모든 쿼리에 대해 작업이 생성됨을 의미하고 2 값은 작업 없이 쿼리를 실행할 수 있음을 의미합니다.

기본값: 2
데이터 유형: 정수
필수: 아니요

JobTimeout

이 연결 속성은 서버에서 작업이 취소된 후의 작업 제한 시간 (초)을 설정합니다.

기본값: 0
데이터 유형: Long
필수: 아니요

KMSKeyName

이 연결 속성은 데이터를 암호화하는 KMS 키 이름을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

Labels

이 연결 속성은 쿼리 작업을 정리하고 그룹화하기 위해 쿼리와 연결된 라벨을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: Map<String, String>
필수: 아니요

LargeResultDataset

이 연결 속성은 쿼리 결과의 대상 데이터 세트를 설정합니다. 자세한 내용은 대규모 결과 집합을 참고하세요.

기본값: _google_jdbc(QueryDialect=BIG_QUERY 또는 QueryDialect=SQL 및 LargeResultTable 연결 속성이 설정된 경우에만)
데이터 유형: 문자열
필수: 아니요

LargeResultsDatasetExpirationTime

이 연결 속성은 데이터 세트의 모든 테이블의 수명을 밀리초 단위로 지정합니다. 데이터 세트에 이미 기본 만료 시간이 설정되어 있으면 이 속성은 무시됩니다.

기본값: 3600000
데이터 유형: Long
필수: 아니요

LargeResultTable

이 연결 속성은 쿼리 결과의 대상 테이블을 설정합니다. 자세한 내용은 대규모 결과 집합을 참고하세요.

기본값: temp_table...(QueryDialect=BIG_QUERY 또는 QueryDialect=SQL 및 LargeResultTable 연결 속성이 설정된 경우에만)
데이터 유형: 문자열
필수: 아니요

ListenerPoolSize

이 연결 속성은 연결 풀링이 사용 설정된 경우 리스너 풀 크기를 설정합니다.

기본값: 10
데이터 유형: Long
필수: 아니요

Location

이 연결 속성은 데이터 세트가 생성되거나 쿼리되는 위치를 지정합니다. 이 값을 설정하지 않으면 BigQuery에서 위치를 자동으로 결정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

LogLevel

이 연결 속성은 데이터베이스 상호작용 중에 로깅되는 세부정보 수준을 제어합니다. 수준 설명은 로깅을 참고하세요.

기본값: 0
데이터 유형: 정수
필수: 아니요

LogPath

이 연결 속성은 로그 파일이 기록되는 디렉터리를 설정합니다. 자세한 내용은 로깅을 참고하세요.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

MaximumBytesBilled

이 연결 속성은 청구되는 바이트 수를 제한합니다. 청구되는 바이트가 이 한도를 초과하는 쿼리는 실패하고 요금은 청구되지 않습니다.

기본값: 0
데이터 유형: Long
필수: 아니요

MaxResults

이 연결 속성은 페이지당 최대 결과 수를 설정합니다.

기본값: 10000
데이터 유형: Long
필수: 아니요

MetaDataFetchThreadCount

이 연결 속성은 데이터베이스 메타데이터 메서드에 사용되는 스레드 수를 구성합니다.

기본값: 32
데이터 유형: 정수
필수: 아니요

OAuthAccessToken

이 연결 속성은 사전 생성된 액세스 토큰 인증에 사용되는 액세스 토큰을 지정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=2

OAuthClientId

이 연결 속성은 사전 생성된 갱신 토큰 인증 및 사용자 계정 인증의 클라이언트 ID를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=1 또는 AUTH_TYPE=2

OAuthClientSecret

이 연결 속성은 사전 생성된 갱신 토큰 인증 및 사용자 계정 인증의 클라이언트 보안 비밀번호를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=1 또는 AUTH_TYPE=2

OAuthP12Password

이 연결 속성은 PKCS12 키 파일의 비밀번호를 설정합니다.

기본값: notasecret
데이터 유형: 문자열
필수: 아니요

OAuthPvtKey

이 연결 속성은 서비스 계정 인증을 사용할 때 서비스 계정 키를 설정합니다. 이 값은 원시 JSON 키 파일 객체이거나 JSON 키 파일의 경로일 수 있습니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=0 및 OAuthPvtKeyPath 값이 설정되지 않은 경우

OAuthPvtKeyPath

이 연결 속성은 서비스 계정 인증을 사용할 때 서비스 계정 키의 경로를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=0 및 OAuthPvtKey, OAuthServiceAcctEmail 값이 설정되지 않은 경우

OAuthRefreshToken

이 연결 속성은 미리 생성된 갱신 토큰 인증의 갱신 토큰을 설정합니다. OAuth 2.0 갱신 토큰은 현재 토큰이 만료될 때 사용자가 재인증하지 않아도 애플리케이션이 새 액세스 토큰을 획득할 수 있도록 하는 특수한 유형의 토큰입니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=2

OAuthServiceAcctEmail

이 연결 속성은 서비스 계정 인증을 사용할 때 서비스 계정 이메일을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: AUTH_TYPE=0 및 OAuthPvtKeyPath 값이 설정되지 않은 경우

OAuthType

이 연결 속성은 인증 유형을 지정합니다. 값은 다음 중 하나여야 합니다.

0: Google 서비스 계정 인증
1: Google 사용자 계정 인증
2: 사전 생성된 갱신 토큰 또는 액세스 토큰 인증
3: 애플리케이션 기본 사용자 인증 정보 인증
4: 직원 ID 제휴 또는 워크로드 아이덴티티 제휴와 같은 외부 인증 방법
기본값: -1
데이터 유형: 정수
필수: 예

PartnerToken

이 연결 속성은 Google Cloud 파트너가 드라이버 사용량을 추적하는 데 사용됩니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

PrivateServiceConnectUris

이 연결 속성은 EndpointOverrides 속성과 동일합니다. 대신 EndpointOverrides 속성을 사용하세요.

ProjectId

이 연결 속성은 드라이버의 기본 프로젝트 ID를 설정합니다. 이 프로젝트는 쿼리를 실행하는 데 사용되며 리소스 사용량에 따라 요금이 청구됩니다. 설정되지 않은 경우 드라이버가 프로젝트 ID를 추론합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요, 적극 권장

ProxyHost

이 연결 속성은 JDBC 연결이 라우팅되는 프록시 서버의 호스트 이름 또는 IP 주소를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

ProxyPort

이 연결 속성은 프록시 서버가 연결을 수신 대기하는 포트 번호를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

ProxyPwd

이 연결 속성은 인증이 필요한 프록시 서버를 통해 연결할 때 필요한 비밀번호를 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

ProxyUid

이 연결 속성은 인증이 필요한 프록시 서버를 통해 연결할 때 필요한 사용자 이름을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

QueryDialect

이 연결 속성은 쿼리 실행을 위한 SQL 언어를 설정합니다. GoogleSQL에는 SQL (권장)를 사용하고 기존 SQL에는 BIG_QUERY를 사용합니다.

기본값: SQL
데이터 유형: 문자열
필수: 아니요

QueryProperties

이 연결 속성은 쿼리 동작 수정을 구성합니다.

다음은 연결 문자열에 설정된 예시입니다.

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
QueryProperties=dataset_project_id=TestProjectID,time_zone=America/New_York;

다음은 DataSource 클래스에 설정된 예입니다.

Map<String, String> queryProperties = new HashMap<>();
queryProperties.put("dataset_project_id", "TestProjectID");
queryProperties.put("time_zone", "America/New_York");
DataSource dataSource = new DataSource();
dataSource.setQueryProperties(queryProperties);

자세한 내용은 ConnectionProperty를 참고하세요.

기본값: 해당 사항 없음
데이터 유형: Map<String, String>
필수: 아니요

RequestGoogleDriveScope

이 연결 속성은 Google Drive에 대한 액세스를 요청하는 데 사용됩니다. 사용 설정하면 읽기 전용 Drive 범위가 연결에 추가됩니다. 이 속성을 사용 설정하려면 값을 1로 설정하세요.

기본값: 0
데이터 유형: 정수
필수: 아니요

RetryInitialDelay

이 연결 속성은 첫 번째 재시도 전 지연 시간 (초)을 설정합니다.

기본값: 0
데이터 유형: Long
필수: 아니요

RetryMaxDelay

이 연결 속성은 재시도 지연의 최대 한도 (초)를 설정합니다.

기본값: 0
데이터 유형: Long
필수: 아니요

ServiceAccountImpersonationChain

이 연결 속성은 가장 체인에 있는 서비스 계정 이메일을 쉼표로 구분된 목록으로 지정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

ServiceAccountImpersonationEmail

이 연결 속성은 가장할 서비스 계정 이메일을 설정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

ServiceAccountImpersonationScopes

이 연결 속성은 가장된 계정과 함께 사용할 OAuth2 범위의 쉼표로 구분된 목록을 지정합니다.

기본값: https://www.googleapis.com/auth/bigquery
데이터 유형: 문자열
필수: 아니요

ServiceAccountImpersonationTokenLifetime

이 연결 속성은 가장된 계정 토큰 수명 (초)을 설정합니다.

기본값: 3600
데이터 유형: 정수
필수: 아니요

SSLTrustStore

이 연결 속성은 신뢰할 수 있는 인증 기관 (CA) 인증서가 포함된 Java 트러스트 저장소의 전체 경로를 지정합니다. 드라이버는 이 트러스트 저장소를 사용하여 SSL/TLS 핸드셰이크 중에 서버의 ID를 검증합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 아니요

SSLTrustStorePwd

이 연결 속성은 SSLTrustStore 속성에 지정된 Java TrustStore의 비밀번호를 지정합니다.

기본값: 해당 사항 없음
데이터 유형: 문자열
필수: 비밀번호로 보호된 Java TrustStore를 사용하는 경우에만

SWA_ActivationRowCount

이 연결 속성은 executeBatch insert 행의 기준 개수를 설정하며, 이 기준을 초과하면 커넥터가 Storage Write API로 전환됩니다.

기본값: 3
데이터 유형: 정수
필수: 아니요

SWA_AppendRowCount

이 연결 속성은 쓰기 스트림의 크기를 설정합니다.

기본값: 1000
데이터 유형: 정수
필수: 아니요

Timeout

이 연결 속성은 커넥터가 제한 시간 초과 전에 실패한 API 호출을 재시도하는 시간(초)을 설정합니다.

기본값: 0
데이터 유형: Long
필수: 아니요

UniverseDomain

이 연결 속성은 조직의 Google Cloud 리소스와 연결된 최상위 도메인인 유니버스 도메인을 설정합니다.

기본값: googleapis.com
데이터 유형: 문자열
필수: 아니요

UnsupportedHTAPIFallback

이 연결 속성은 커넥터가 REST API로 대체되는지(TRUE로 설정된 경우) 또는 오류를 반환하는지 (FALSE로 설정된 경우)를 결정합니다.

기본값: TRUE
데이터 유형: 불리언
필수: 아니요

UseQueryCache

이 연결 속성은 쿼리 캐싱을 사용 설정합니다.

기본값: TRUE
데이터 유형: 불리언
필수: 아니요

BigQuery용 JDBC 드라이버 사용

시작하기 전에

드라이버 구성

드라이버 설치

BigQuery에 인증

서비스 계정을 사용하여 인증

Google 사용자 계정으로 인증

사전 생성된 액세스 또는 갱신 토큰으로 인증

애플리케이션 기본 사용자 인증 정보로 인증

외부 메서드로 인증

연결 설정

운전자 기능 살펴보기

SQL 커넥터

데이터 유형 매핑

중첩되고 반복되는 레코드

대규모 결과 집합

위치 매개변수

쿼리 SELECT회

일괄 삽입

로깅

연결 속성

쿼리 `SELECT`회