BigLake 테이블에서 Cloud Storage 데이터 쿼리

이 문서에서는 Cloud Storage BigLake 테이블에 저장된 데이터를 쿼리하는 방법을 설명합니다.

시작하기 전에

Cloud Storage BigLake 테이블이 있는지 확인합니다.

필요한 역할

Cloud Storage BigLake 테이블을 쿼리하려면 다음 역할이 있는지 확인합니다.

BigQuery 데이터 뷰어(roles/bigquery.dataViewer)
BigQuery 사용자(roles/bigquery.user)

권한에 따라 이러한 역할을 직접 부여하거나 관리자에게 부여를 요청할 수 있습니다. 역할 부여에 대한 자세한 내용은 리소스에 대해 부여할 수 있는 역할 보기를 참조하세요.

Cloud Storage BigLake 테이블을 쿼리하는 데 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

bigquery.jobs.create
bigquery.readsessions.create(BigQuery Storage Read API로 데이터를 읽는 경우에만 필요)
bigquery.tables.get
bigquery.tables.getData

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

BigLake 테이블 쿼리

Cloud Storage BigLake 테이블을 만든 후에는 표준 BigQuery 테이블과 마찬가지로 GoogleSQL 구문을 사용하여 쿼리할 수 있습니다. 예를 들면 SELECT field1, field2 FROM mydataset.my_cloud_storage_table;입니다.

외부 데이터 처리 도구를 사용하여 BigLake 테이블 쿼리

BigQuery 커넥터를 다른 데이터 처리 도구와 함께 사용하여 Cloud Storage의 BigLake 테이블에 액세스할 수 있습니다. 자세한 내용은 커넥터를 참조하세요.

Apache Spark

다음 예시에서는 Dataproc을 사용되지만 Spark BigQuery 커넥터를 사용하는 Spark 배포도 작동합니다.

이 예시에서는 클러스터를 만들 때 초기화 작업으로 Spark-BigQuery 커넥터를 제공합니다. 이 작업을 통해 Zeppelin 노트북을 사용하고 데이터 분석가 사용자 여정을 수행할 수 있습니다.

Spark-BigQuery 커넥터 버전은 GitHub GoogleCloudDataproc/spark-bigquery-connector 저장소에 나열되어 있습니다.

Spark-BigQuery 커넥터에 대해 초기화 작업을 사용하여 단일 노드 클러스터를 만듭니다.

gcloud dataproc clusters create biglake-demo-cluster \
    --optional-components=ZEPPELIN \
    --region=REGION \
    --enable-component-gateway \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata spark-bigquery-connector-url= gs://spark-lib/bigquery/spark-bigquery-with-dependencies_SCALA_VERSION-CONNECTOR_VERSION.jar

Apache Hive

다음 예시에서는 Dataproc을 사용하지만 Hive-BigQuery 커넥터를 사용하는 모든 Hive 배포에서도 작동합니다.

이 예시에서는 클러스터를 만들 때 초기화 작업으로 Hive-BigQuery 커넥터를 제공합니다.

Hive-BigQuery 커넥터 버전은 GitHub GoogleCloudDataproc/hive-bigquery-connector 저장소에 나열되어 있습니다.

Hive-BigQuery 커넥터에 대해 초기화 작업을 사용하여 단일 노드 클러스터를 만듭니다.

gcloud dataproc clusters create biglake-hive-demo-cluster \
    --region=REGION \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata hive-bigquery-connector-url=gs://goog-dataproc-artifacts-REGION/hive-bigquery/hive-bigquery-connector-CONNECTOR_VERSION.jar

Hive-BigQuery 커넥터에 대한 자세한 내용은 Hive-BigQuery 커넥터 사용을 참조하세요.

Dataflow

Dataflow에서 BigLake 테이블을 읽으려면 DIRECT_READ 모드의 Dataflow 커넥터를 사용하여 BigQuery Storage API를 사용합니다. 쿼리 문자열에서 읽기도 지원됩니다. Apache Beam 문서의 BigQuery I/O를 참조하세요.

임시 BigLake 테이블 쿼리

임시 테이블을 사용하여 외부 데이터 소스를 쿼리하면 외부 데이터를 대상으로 하는 일회성 임시 쿼리 또는 ETL(추출, 변환, 로드) 프로세스에 유용합니다.

영구 테이블을 만들지 않고 외부 데이터 소스를 쿼리하려면 임시 테이블에 대한 테이블 정의를 제공한 후 명령어 또는 호출에서 해당 테이블 정의를 사용하여 임시 테이블을 쿼리합니다. 다음과 같은 방법으로 테이블 정의를 제공할 수 있습니다.

테이블 정의 파일
인라인 스키마 정의
JSON 스키마 파일

테이블 정의 파일이나 제공된 스키마는 임시 외부 테이블을 만드는 데 사용되며, 임시 외부 테이블을 대상으로 쿼리가 실행됩니다.

임시 외부 테이블을 사용하는 경우, BigQuery 데이터 세트 중 하나에 테이블을 만들지 마세요. 테이블이 데이터 세트에 영구적으로 저장되지 않으므로, 다른 사용자와 테이블을 공유할 수 없습니다.

bq 명령줄 도구, API, 클라이언트 라이브러리를 사용하여 외부 데이터 소스에 연결된 임시 테이블을 만들고 쿼리할 수 있습니다.

bq

bq query 명령어를 --external_table_definition 플래그와 함께 사용합니다.

(선택사항) --location 플래그를 지정하고 값을 사용자 위치로 설정합니다.

테이블 정의 파일을 사용하여 외부 데이터 소스에 연결된 임시 테이블을 쿼리하려면 다음 명령어를 입력합니다.

bq --location=LOCATION query \
--external_table_definition=TABLE::DEFINITION_FILE \
'QUERY'

다음을 바꿉니다.

LOCATION: 위치의 이름. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정하면 됩니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
TABLE: 만들려는 임시 테이블의 이름
DEFINITION_FILE: 로컬 머신에 있는 테이블 정의 파일의 경로
QUERY: 임시 테이블에 제출하는 쿼리

예를 들어 다음 명령어는 sales_def라는 테이블 정의 파일을 사용하여 sales라는 임시 파일을 만들고 쿼리합니다.

bq query \
--external_table_definition=sales::sales_def@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

인라인 스키마 정의를 사용하여 외부 데이터 소스에 연결된 임시 테이블을 쿼리하려면 다음 명령어를 입력합니다.

bq --location=LOCATION query \
--external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'query'

다음을 바꿉니다.

LOCATION: 위치의 이름. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정하면 됩니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
TABLE: 만들려는 임시 테이블의 이름
SCHEMA: field:data_type,field:data_type 형식의 인라인 스키마 정의
SOURCE_FORMAT: 외부 데이터 소스의 형식(예: CSV)
BUCKET_PATH: 테이블의 데이터가 포함된 Cloud Storage 버킷 경로(gs://bucket_name/[folder_name/]file_pattern 형식)

file_pattern에 별표(*) 와일드 카드 문자 하나를 지정하여 버킷에서 여러 개의 파일을 선택할 수 있습니다. 예를 들면 gs://mybucket/file00*.parquet입니다. 자세한 내용은 Cloud Storage URI의 와일드 카드 지원을 참조하세요.

여러 경로를 제공하여 uris 옵션에 대해 여러 버킷을 지정할 수 있습니다.

다음 예시에서는 유효한 uris 값을 보여줍니다.
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
여러 파일을 대상으로 하는 uris 값을 지정하는 경우 해당하는 모든 파일은 호환되는 스키마를 공유해야 합니다.

BigQuery에서 Cloud Storage URI를 사용하는 방법에 대한 자세한 내용은 Cloud Storage 리소스 경로를 참조하세요.
PROJECT_ID: 연결이 포함된 프로젝트
REGION: 연결이 포함된 리전(예: us)
CONNECTION_ID: 연결의 이름(예: myconnection)
QUERY: 임시 테이블에 제출하는 쿼리

예를 들어 다음 명령어는 스키마 정의 Region:STRING,Quarter:STRING,Total_sales:INTEGER를 사용하여 Cloud Storage에 저장되는 CSV 파일에 연결된 sales라는 임시 테이블을 만들고 쿼리합니다.

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

JSON 스키마 파일을 사용하여 외부 데이터 소스에 연결된 임시 테이블을 쿼리하려면 다음 명령어를 입력합니다.

bq --location=LOCATION query \
--external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'QUERY'

다음을 바꿉니다.

LOCATION: 위치의 이름. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정하면 됩니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
SCHEMA_FILE: 로컬 머신의 JSON 파일 경로
SOURCE_FORMAT: 외부 데이터 소스의 형식(예: CSV)
BUCKET_PATH: 테이블의 데이터가 포함된 Cloud Storage 버킷 경로(gs://bucket_name/[folder_name/]file_pattern 형식)

file_pattern에 별표(*) 와일드 카드 문자 하나를 지정하여 버킷에서 여러 개의 파일을 선택할 수 있습니다. 예를 들면 gs://mybucket/file00*.parquet입니다. 자세한 내용은 Cloud Storage URI의 와일드 카드 지원을 참조하세요.

여러 경로를 제공하여 uris 옵션에 대해 여러 버킷을 지정할 수 있습니다.

다음 예시에서는 유효한 uris 값을 보여줍니다.
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
여러 파일을 대상으로 하는 uris 값을 지정하는 경우 해당하는 모든 파일은 호환되는 스키마를 공유해야 합니다.

BigQuery에서 Cloud Storage URI를 사용하는 방법에 대한 자세한 내용은 Cloud Storage 리소스 경로를 참조하세요.
PROJECT_ID: 연결이 포함된 프로젝트
REGION: 연결이 포함된 리전(예: us)
CONNECTION_ID: 연결의 이름(예: myconnection)
QUERY: 임시 테이블에 제출하는 쿼리

예를 들어 다음 명령어는 /tmp/sales_schema.json 스키마 파일을 사용하여 Cloud Storage에 저장되는 CSV 파일에 연결된 sales라는 임시 테이블을 만들고 쿼리합니다.

  bq query \
  --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv@us.myconnection \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

API를 사용하여 쿼리를 실행하려면 다음 단계를 수행합니다.

Job 객체를 만듭니다.
Job 객체의 configuration 섹션을 JobConfiguration 객체로 채웁니다.
JobConfiguration 객체의 query 섹션을 JobConfigurationQuery 객체로 채웁니다.
JobConfigurationQuery 객체의 tableDefinitions 섹션을 ExternalDataConfiguration 객체로 채웁니다. connectionId 필드에서 Cloud Storage에 연결하는 데 사용할 연결을 지정합니다.
jobs.insert 메서드를 호출하여 쿼리를 비동기식으로 실행하거나 jobs.query 메서드를 호출하여 쿼리를 동기식으로 실행해 Job 객체를 전달합니다.

다음 단계

BigQuery에서 SQL 사용 알아보기
BigLake 테이블 알아보기
BigQuery 할당량 알아보기