쿼리 예약
이 페이지에서는 BigQuery에서 반복 쿼리의 일정을 예약하는 방법을 설명합니다.
쿼리가 반복적으로 실행되도록 일정을 예약할 수 있습니다. 예약된 쿼리는 GoogleSQL로 작성되어야 하며 데이터 정의 언어(DDL)와 데이터 조작 언어(DML) 문을 포함할 수 있습니다. 쿼리 문자열과 대상 테이블을 매개변수화하여 쿼리 결과를 날짜와 시간별로 구성할 수 있습니다.
쿼리 일정을 만들거나 업데이트하면 쿼리의 예약된 시간이 현지 시간에서 UTC로 변환됩니다. UTC는 일광 절약 시간의 영향을 받지 않습니다.
시작하기 전에
- 예약된 쿼리는 BigQuery Data Transfer Service의 기능을 사용합니다. BigQuery Data Transfer Service 사용 설정에 필요한 모든 작업을 완료했는지 확인합니다.
- 사용자에게 이 문서의 각 작업을 수행하는 데 필요한 권한을 부여하는 Identity and Access Management(IAM) 역할을 부여합니다.
- 고객 관리 암호화 키(CMEK)를 지정하려는 경우 서비스 계정에 암호화 및 복호화 권한이 있어야하며, Cloud KMS 키 리소스 ID가 필요합니다. CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 예약된 쿼리로 암호화 키 지정을 참조하세요.
필수 권한
쿼리를 예약하려면 다음 IAM 권한이 필요합니다.
전송을 만들려면
bigquery.transfers.update
및bigquery.datasets.get
권한이 있거나bigquery.jobs.create
,bigquery.transfers.get
,bigquery.datasets.get
권한이 있어야 합니다.예약된 쿼리를 실행하려면 다음이 필요합니다.
- 대상 데이터 세트에 대한
bigquery.datasets.get
권한 bigquery.jobs.create
- 대상 데이터 세트에 대한
예약된 쿼리를 수정하거나 삭제하려면 다음 IAM 권한 중 하나가 필요합니다.
bigquery.transfers.update
bigquery.jobs.create
및 예약된 쿼리에 대한 소유권
사전 정의된 roles/bigquery.admin
IAM 역할에는 쿼리를 예약하거나 수정하는 데 필요한 권한이 포함되어 있습니다.
BigQuery에서 IAM 역할에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.
서비스 계정에서 실행하는 예약된 쿼리를 만들거나 업데이트하려면 해당 서비스 계정에 대한 액세스 권한이 있어야 합니다. 사용자에게 서비스 계정 역할을 부여하는 방법에 대한 자세한 내용은 서비스 계정 사용자 역할을 참조하세요. Google Cloud 콘솔의 예약된 쿼리 UI에서 서비스 계정을 선택하려면 다음 IAM 권한이 필요합니다.
iam.serviceAccounts.list
구성 옵션
쿼리 문자열
쿼리 문자열은 유효해야 하며 GoogleSQL로 작성되어야 합니다. 예약된 쿼리가 실행될 때마다 다음과 같은 쿼리 매개변수를 수신할 수 있습니다.
쿼리를 예약하기 전에 @run_time
매개변수와 @run_date
매개변수를 사용하여 쿼리 문자열을 수동으로 테스트하려면 bq 명령줄 도구를 사용합니다.
사용 가능한 매개변수
매개변수 | GoogleSQL 유형 | 값 |
---|---|---|
@run_time |
TIMESTAMP |
UTC 시간으로 표현됩니다. 정기적인 예약된 쿼리의 경우 run_time 은 의도한 실행 시간을 나타냅니다. 예를 들어 예약된 쿼리가 '24시간마다'로 설정된 경우 연속된 두 쿼리 사이의 run_time 차이는 정확히 24시간입니다. 단, 실제 실행 시간에는 약간 차이가 있을 수 있습니다. |
@run_date |
DATE |
논리적 달력 날짜를 나타냅니다. |
예
이 예시에서 @run_time
매개변수는 hacker_news.stories
라는 공개 데이터 세트를 쿼리하는 쿼리 문자열의 일부입니다.
SELECT @run_time AS time, title, author, text FROM `bigquery-public-data.hacker_news.stories` LIMIT 1000
대상 테이블
예약된 쿼리를 설정할 때 결과의 대상 테이블이 없으면 BigQuery가 자동으로 테이블을 만들려고 합니다.
DDL 또는 DML 쿼리를 사용하는 경우 Google Cloud 콘솔에서 처리 위치나 리전을 선택합니다. 대상 테이블을 생성하는 DDL 또는 DML 쿼리의 경우 처리 위치가 필요합니다.
대상 테이블이 있고 WRITE_APPEND
쓰기 환경설정을 사용하는 경우 BigQuery는 대상 테이블에 데이터를 추가하고 스키마를 매핑하려고 시도합니다.
BigQuery는 자동으로 필드 추가 및 재정렬을 허용하며 누락된 선택적 필드를 수용합니다. 실행 간에 테이블 스키마가 너무 많이 변경되어 BigQuery가 변경사항을 자동으로 처리할 수 없으면 예약된 쿼리가 실패합니다.
쿼리는 다른 프로젝트 및 다른 데이터 세트의 테이블을 참조할 수 있습니다. 예약된 쿼리를 구성할 때는 대상 데이터 세트를 테이블 이름에 추가할 필요 없습니다. 대상 데이터 세트는 별도로 지정합니다.
예약된 쿼리의 대상 데이터 세트와 테이블은 예약된 쿼리와 동일한 프로젝트에 있어야 합니다.
쓰기 환경설정
선택한 쓰기 환경설정에 따라 쿼리 결과가 기존 대상 테이블에 기록되는 방법이 결정됩니다.
WRITE_TRUNCATE
: 테이블이 존재하면 BigQuery가 테이블 데이터를 덮어씁니다.WRITE_APPEND
: 테이블이 존재하면 BigQuery가 데이터를 테이블에 추가합니다.
DDL 또는 DML 쿼리를 사용하는 경우 쓰기 환경설정 옵션을 사용할 수 없습니다.
대상 테이블 만들기, 잘라내기 또는 추가는 BigQuery가 쿼리를 성공적으로 완료할 수 있는 경우에만 발생합니다. 만들기, 잘라내기 또는 추가 작업은 작업 완료 시 하나의 원자적 업데이트로 발생합니다.
클러스터링
예약된 쿼리는 테이블이 DDL CREATE TABLE AS SELECT
문으로 작성된 경우에만 새 테이블에서 클러스터링을 만들 수 있습니다. 데이터 정의 언어 문 사용 페이지에서 쿼리 결과에서 클러스터링된 테이블 만들기를 참조하세요.
파티션 나누기 옵션
예약된 쿼리는 파티션을 나눈 또는 파티션을 나누지 않은 대상 테이블을 만들 수 있습니다. 파티셔닝은 Google Cloud 콘솔, bq 명령줄 도구, API 설정 메서드에서 사용 가능합니다. 파티셔닝에 DDL 또는 DML 쿼리를 사용하는 경우 대상 테이블 파티셔닝 필드를 비워 둡니다.
BigQuery에서는 다음 유형의 테이블 파티셔닝을 사용할 수 있습니다.
- 정수 범위로 파티셔닝: 특정
INTEGER
열의 값 범위를 기준으로 파티션을 나눈 테이블입니다. - 시간 단위 열로 파티셔닝:
TIMESTAMP
,DATE
또는DATETIME
열을 기준으로 파티션을 나눈 테이블입니다. - 수집 시간으로 파티셔닝: 수집 시간으로 파티션을 나눈 테이블입니다. BigQuery는 BigQuery가 데이터를 수집하는 시간을 기준으로 파티션에 자동으로 행을 할당합니다.
Google Cloud 콘솔에서 예약된 쿼리를 사용하여 파티션을 나눈 테이블을 만들려면 다음 옵션을 사용합니다.
정수 범위로 파티셔닝을 사용하려면 대상 테이블 파티셔닝 필드를 비워 둡니다.
시간 단위 열로 파티셔닝을 사용하려면 예약된 쿼리를 설정할 때 대상 테이블 파티셔닝 필드에 열 이름을 지정합니다.
수집 시간으로 파티셔닝을 사용하려면 대상 테이블 파티셔닝 필드를 비워 두고 대상 테이블의 이름에 날짜 파티셔닝을 표시합니다. 예를 들면
mytable${run_date}
입니다. 자세한 내용은 매개변수 템플릿 구문을 참조하세요.
사용 가능한 매개변수
예약된 쿼리를 설정할 때 런타임 매개변수를 사용하여 대상 테이블의 파티션을 나누는 방법을 지정할 수 있습니다.
매개변수 | 템플릿 유형 | 값 |
---|---|---|
run_time |
형식이 지정된 타임스탬프 | 일정에 따라 UTC 시간으로 표시됩니다. 정기적인 예약된 쿼리의 경우 run_time 은 의도한 실행 시간을 나타냅니다. 예를 들어 예약된 쿼리가 '24시간마다'로 설정된 경우 연속된 두 쿼리 사이의 run_time 차이는 정확히 24시간입니다. 단, 실제 실행 시간에는 약간 차이가 있을 수 있습니다.TransferRun.runTime 을 참조하세요. |
run_date |
날짜 문자열 | %Y-%m-%d 형식(예: 2018-01-01 )의 run_time 매개변수 날짜입니다. 이 형식은 수집 시간으로 파티션을 나눈 테이블에서 사용할 수 있습니다. |
템플릿 시스템
예약된 쿼리는 템플릿 구문을 사용하여 대상 테이블 이름에서 런타임 매개변수를 지원합니다.
매개변수 템플릿 구문
템플릿 문법은 기본 문자열 템플릿과 시간 오프셋을 지원합니다. 매개변수는 다음 형식으로 참조됩니다.
{run_date}
{run_time[+\-offset]|"time_format"}
매개변수 | 목적 |
---|---|
run_date |
이 매개변수는 YYYYMMDD 형식의 날짜로 대체됩니다. |
run_time |
이 매개변수는 다음 속성을 지원합니다.
|
- run_time, offset, time 형식 사이에 공백이 없어야 합니다.
- 문자열에 리터럴 중괄호를 포함하려면
'\{' and '\}'
로 이스케이프 처리합니다. "YYYY|MM|DD"
와 같은 time_format에 리터럴 따옴표 또는 세로 막대를 포함하려면 형식 문자열에서'\"'
또는'\|'
로 이스케이프 처리합니다.
매개변수 템플릿 예시
다음 예는 다양한 시간 형식을 사용하여 대상 테이블 이름을 지정하고 실행 시간을 오프셋하는 방법을 보여줍니다.run_time(UTC) | 템플릿 매개변수 | 출력 대상 테이블 이름 |
---|---|---|
2018-02-15 00:00:00 | mytable |
mytable |
2018-02-15 00:00:00 | mytable_{run_time|"%Y%m%d"} |
mytable_20180215 |
2018-02-15 00:00:00 | mytable_{run_time+25h|"%Y%m%d"} |
mytable_20180216 |
2018-02-15 00:00:00 | mytable_{run_time-1h|"%Y%m%d"} |
mytable_20180214 |
2018-02-15 00:00:00 | mytable_{run_time+1.5h|"%Y%m%d%H"}
또는 mytable_{run_time+90m|"%Y%m%d%H"} |
mytable_2018021501 |
2018-02-15 00:00:00 | {run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"} |
20180215_mytable_000137 |
서비스 계정 사용
예약된 쿼리를 서비스 계정으로 인증하도록 설정할 수 있습니다. 서비스 계정은 Google Cloud 프로젝트와 연결된 Google 계정입니다. 서비스 계정은 최종 사용자의 사용자 인증 정보 대신 고유 서비스 사용자 인증 정보를 사용하여 예약된 쿼리 또는 일괄 처리 파이프라인과 같은 작업을 실행할 수 있습니다.
서비스 계정으로 인증하는 방법에 관한 자세한 내용은 인증 소개를 참조하세요.
서비스 계정을 사용하여 예약된 쿼리를 설정할 수 있습니다. 제휴 ID로 로그인한 경우 서비스 계정이 전송을 만드는 데 필요합니다. Google 계정으로 로그인한 경우 전송에 사용되는 서비스 계정은 선택사항입니다.
bq 명령줄 도구 또는 Google Cloud 콘솔을 사용하여 기존 예약된 쿼리를 서비스 계정의 사용자 인증 정보로 업데이트할 수 있습니다. 자세한 내용은 예약된 쿼리 사용자 인증 정보 업데이트를 참조하세요.
예약된 쿼리로 암호화 키 지정
고객 관리 암호화 키(CMEK)를 지정하여 전송 실행의 데이터를 암호화할 수 있습니다. CMEK를 사용하여 예약된 쿼리로부터의 전송을 지원할 수 있습니다.전송에 CMEK를 지정하면 BigQuery Data Transfer Service는 CMEK를 수집된 데이터의 모든 중간 디스크 캐시에 적용하여 전체 데이터 전송 워크플로가 CMEK를 준수하도록 합니다.
원래 CMEK를 사용해 생성되지 않은 전송의 경우 기존 전송을 업데이트하여 CMEK를 추가할 수 없습니다. 예를 들어 원래 기본적으로 암호화된 대상 테이블을 지금 CMEK로 암호화되도록 변경할 수 없습니다. 반대로 CMEK로 암호화된 대상 테이블을 다른 유형의 암호화가 적용되도록 변경할 수도 없습니다.
전송 구성이 원래 CMEK 암호화를 사용하여 생성된 경우 전송에 대해 CMEK를 업데이트할 수 있습니다. 전송 구성에 대해 CMEK를 업데이트하면 BigQuery Data Transfer Service는 전송의 다음 실행 시 CMEK를 대상 테이블에 전파하는데, 여기서 BigQuery Data Transfer Service는 전송 실행 중 오래된 CMEK를 새 CMEK로 대체합니다. 자세한 내용은 전송 업데이트를 참조하세요.
프로젝트 기본 키를 사용할 수도 있습니다. 전송에 프로젝트 기본 키를 지정하면 BigQuery Data Transfer Service는 프로젝트 기본 키를 새 전송 구성의 기본 키로 사용합니다.
예약된 쿼리 설정
예약 구문에 대한 설명은 일정 형식 지정을 참조하세요.
예약 구문에 대한 자세한 내용은 리소스: TransferConfig
를 참조하세요.
콘솔
Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.
원하는 쿼리를 실행합니다. 결과에 만족하면 예약을 클릭합니다.
새로 예약된 쿼리 창에 예약된 쿼리 옵션이 열립니다.
새로 예약된 쿼리 창에서 다음을 수행합니다.
- 예약된 쿼리 이름에 이름(예:
My scheduled query
)을 입력합니다. 예약된 쿼리 이름은 나중에 쿼리를 수정해야 하는 경우에 식별할 수 있는 모든 값일 수 있습니다. 선택사항: 기본적으로 쿼리는 매일 실행되도록 예약됩니다. 반복 드롭다운 메뉴에서 옵션을 선택하여 기본 일정을 변경할 수 있습니다.
커스텀 빈도를 지정하려면 커스텀을 선택한 다음 커스텀 일정 필드에 크론과 유사한 시간 지정을 입력합니다(예:
every mon 23:30
또는every 6 hours
). 커스텀 간격을 포함한 유효한 일정에 대한 자세한 내용은 리소스:TransferConfig
의schedule
필드를 참조하세요.시작 시간을 변경하려면 설정 시간에 시작 옵션을 선택하고 원하는 시작 날짜와 시간을 입력합니다.
종료 시간을 지정하려면 종료 시간 예약 옵션을 선택하고 원하는 종료 날짜와 시간을 입력합니다.
나중에 필요할 때 실행할 수 있도록 예약 없이 쿼리를 저장하려면 반복 메뉴에서 주문형을 선택합니다.
- 예약된 쿼리 이름에 이름(예:
GoogleSQL
SELECT
쿼리의 경우 쿼리 결과의 대상 테이블 설정 옵션을 선택하고 대상 데이터 세트에 대한 다음 정보를 제공합니다.- 데이터 세트 이름에서 적절한 대상 데이터 세트를 선택합니다.
- 테이블 이름에서 대상 테이블의 이름을 입력합니다.
대상 테이블 쓰기 환경설정에서 테이블에 추가를 선택하여 데이터를 테이블에 추가하거나 테이블 덮어쓰기를 선택하여 대상 테이블을 덮어씁니다.
위치 유형을 선택합니다.
쿼리 결과에 대상 테이블을 사용 설정한 경우 자동 위치 선택을 선택하여 대상 테이블이 있는 위치를 자동으로 선택할 수 있습니다.
그렇지 않으면 쿼리되는 데이터가 있는 위치를 선택합니다.
고급 옵션:
선택사항: CMEK: 고객 관리 암호화 키를 사용하는 경우 고급 옵션에서 고객 관리 키를 선택할 수 있습니다. 선택할 수 있는 CMEK 목록이 표시됩니다. 고객 관리 암호화 키(CMEK)가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 예약된 쿼리로 암호화 키 지정을 참조하세요.
서비스 계정으로 인증: Google Cloud 프로젝트에 연결된 서비스 계정이 한 개 이상이면 사용자 인증 정보를 사용하는 대신 서비스 계정을 예약된 쿼리와 연결할 수 있습니다. 예약된 쿼리 사용자 인증 정보에서 메뉴를 클릭하여 사용 가능한 서비스 계정 목록을 표시합니다. 제휴 ID로 로그인하는 경우 서비스 계정이 필요합니다.
추가 구성:
저장을 클릭합니다.
bq
옵션 1: bq query
명령어를 사용합니다.
예약된 쿼리를 만들려면 destination_table
(또는 target_dataset
), --schedule
, --display_name
옵션을 bq query
명령어에 추가합니다.
bq query \ --display_name=name \ --destination_table=table \ --schedule=interval
다음을 바꿉니다.
name
. 예약된 쿼리의 표시 이름입니다. 표시 이름은 나중에 쿼리를 수정해야 하는 경우에 식별할 수 있는 모든 값일 수 있습니다.table
. 쿼리 결과의 대상 테이블입니다.--target_dataset
는 DDL 및 DML 쿼리와 함께 사용될 경우 쿼리 결과에서 대상 데이터 세트 이름을 지정하는 또 다른 방법입니다.--destination_table
또는--target_dataset
을 사용합니다. 둘 다 사용할 수 없습니다.
interval
.bq query
와 함께 사용될 경우 쿼리를 예약된 반복 쿼리로 만듭니다. 쿼리 실행 빈도에 대한 일정이 필요합니다. 커스텀 간격을 포함한 유효한 일정에 대한 자세한 내용은 리소스:TransferConfig
의schedule
필드를 참조하세요. 예를 들면 다음과 같습니다.--schedule='every 24 hours'
--schedule='every 3 hours'
--schedule='every monday 09:00'
--schedule='1st sunday of sep,oct,nov 00:00'
선택적 플래그:
--project_id
는 프로젝트 ID입니다.--project_id
를 지정하지 않으면 기본 프로젝트가 사용됩니다.--replace
는 대상 테이블을 잘라내며 예약된 쿼리가 실행될 때마다 새 결과를 작성합니다.--append_table
은 대상 테이블에 결과를 추가합니다.DDL 및 DML 쿼리의 경우
--location
플래그를 지정하여 처리할 특정 리전을 지정할 수도 있습니다.--location
을 지정하지 않으면 가장 가까운 Google Cloud 위치가 사용됩니다.
예를 들어 다음 명령어는 SELECT 1 from mydataset.test
라는 단순한 쿼리를 사용하여 My Scheduled Query
라는 예약된 쿼리를 만듭니다.
대상 테이블은 데이터 세트 mydataset
의 mytable
입니다. 예약된 쿼리는 기본 프로젝트에 생성됩니다.
bq query \
--use_legacy_sql=false \
--destination_table=mydataset.mytable \
--display_name='My Scheduled Query' \
--schedule='every 24 hours' \
--replace=true \
'SELECT
1
FROM
mydataset.test'
옵션 2: bq mk
명령어를 사용합니다.
예약된 쿼리는 일종의 전송입니다. 쿼리를 예약하려면 bq 명령줄 도구를 사용하여 전송 구성을 만들면 됩니다.
예약하려는 쿼리는 StandardSQL 언어로 되어 있어야 합니다.
bq mk
명령어를 입력하고 다음 필수 플래그를 제공합니다.
--transfer_config
--data_source
--target_dataset
(DDL 및 DML 쿼리의 경우 선택사항)--display_name
--params
선택적 플래그:
--project_id
는 프로젝트 ID입니다.--project_id
를 지정하지 않으면 기본 프로젝트가 사용됩니다.--schedule
은 쿼리 실행 빈도입니다.--schedule
을 지정하지 않으면 기본값은 만든 시간을 기준으로 '24시간마다'입니다.DDL 및 DML 쿼리의 경우
--location
플래그를 지정하여 처리할 특정 리전을 지정할 수도 있습니다.--location
을 지정하지 않으면 가장 가까운 Google Cloud 위치가 사용됩니다.--service_account_name
은 개별 사용자 계정 대신 서비스 계정으로 예약된 쿼리를 인증할 때 사용됩니다.--destination_kms_key
: 이 전송에 고객 관리 암호화 키(CMEK)를 사용하는 경우 키의 키 리소스 ID를 지정합니다. CMEK가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 예약된 쿼리로 암호화 키 지정을 참조하세요.
bq mk \ --transfer_config \ --target_dataset=dataset \ --display_name=name \ --params='parameters' \ --data_source=data_source
다음을 바꿉니다.
dataset
. 전송 구성의 대상 데이터 세트입니다.- 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.
name
. 전송 구성의 표시 이름입니다. 표시 이름은 나중에 쿼리를 수정해야 하는 경우에 식별할 수 있는 모든 값일 수 있습니다.parameters
. JSON 형식으로 생성된 전송 구성의 매개변수가 있습니다. 예를 들면--params='{"param":"param_value"}'
입니다.- 예약된 쿼리의 경우
query
매개변수를 지정해야 합니다. destination_table_name_template
매개변수는 대상 테이블의 이름입니다.- 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.
write_disposition
매개변수의 경우WRITE_TRUNCATE
를 선택하여 대상 테이블을 자르거나(덮어쓰거나)WRITE_APPEND
를 선택하여 대상 테이블에 쿼리 결과를 추가할 수 있습니다.- 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.
- 예약된 쿼리의 경우
data_source
. 데이터 소스:scheduled_query
.- 선택사항:
--service_account_name
플래그는 개별 사용자 계정 대신 서비스 계정으로 인증하기 위한 플래그입니다. - 선택사항:
--destination_kms_key
는 Cloud KMS 키의 키 리소스 ID를 지정합니다(예:projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name
).
예를 들어 다음 명령어는 SELECT 1
from mydataset.test
라는 단순한 쿼리를 사용하여 My Scheduled Query
라는 예약된 쿼리 전송 구성을 만듭니다. 대상 테이블 mytable
은 매 쓰기 시 잘리며 대상 데이터 세트는 mydataset
입니다. 예약된 쿼리는 기본 프로젝트에 생성되고, 서비스 계정으로 인증됩니다.
bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}' \
--data_source=scheduled_query \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
명령어를 처음 실행할 때 다음과 같은 메시지를 받게 됩니다.
[URL omitted] Please copy and paste the above URL into your web browser and
follow the instructions to retrieve an authentication code.
메시지 안내를 따라 명령줄에 인증 코드를 붙여넣습니다.
API
projects.locations.transferConfigs.create
메서드를 사용하고 TransferConfig
리소스의 인스턴스를 지정합니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
서비스 계정을 사용하여 예약된 쿼리 설정
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
예약된 쿼리 상태 보기
콘솔
예약된 쿼리의 상태를 보려면 탐색창에서 예약된 쿼리를 클릭합니다. 예약된 쿼리의 업데이트된 상태를 확인하려면 페이지를 새로 고칩니다. 예약된 쿼리를 클릭하면 자세한 내용을 확인할 수 있습니다.
bq
예약된 쿼리는 일종의 전송입니다. 예약된 쿼리의 세부정보를 표시하려면 먼저 bq 명령줄 도구를 사용하여 전송 구성을 나열하면 됩니다.
bq ls
명령어를 입력하고 전송 플래그 --transfer_config
를 지정합니다. 다음 플래그도 필요합니다.
--transfer_location
예를 들면 다음과 같습니다.
bq ls \
--transfer_config \
--transfer_location=us
예약된 단일 쿼리의 세부정보를 표시하려면 bq show
명령어를 입력하고 예약된 쿼리/전송 구성의 transfer_path
를 지정합니다.
예를 들면 다음과 같습니다.
bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38
API
projects.locations.transferConfigs.list
메서드를 사용하고 TransferConfig
리소스의 인스턴스를 지정합니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
예약된 쿼리 업데이트
콘솔
예약된 쿼리를 업데이트하려면 다음 단계를 따르세요.
- 탐색창에서 예약된 쿼리를 클릭합니다.
- 예약된 쿼리 목록에서 변경하려는 쿼리 이름을 클릭합니다.
- 예약된 쿼리 세부정보 페이지가 열리면 수정을 클릭합니다.
- 선택사항: 쿼리 수정 창에서 쿼리 텍스트를 변경합니다.
- 쿼리 예약을 클릭한 다음 예약된 쿼리 업데이트를 선택합니다.
- 선택사항: 쿼리의 다른 예약 옵션을 변경합니다.
- 업데이트를 클릭합니다.
bq
예약된 쿼리는 일종의 전송입니다. 예약된 쿼리를 업데이트하려면 bq 명령줄 도구를 사용하여 전송 구성을 만들면 됩니다.
필요한 --transfer_config
플래그와 함께 bq update
명령어를 입력합니다.
선택적 플래그:
--project_id
는 프로젝트 ID입니다.--project_id
를 지정하지 않으면 기본 프로젝트가 사용됩니다.--schedule
은 쿼리 실행 빈도입니다.--schedule
을 지정하지 않으면 기본값은 만든 시간을 기준으로 '24시간마다'입니다.--service_account_name
은--update_credentials
도 설정된 경우에만 적용됩니다. 자세한 내용은 예약된 쿼리 사용자 인증 정보 업데이트를 참조하세요.--target_dataset
(DDL 및 DML 쿼리의 경우 선택사항)는 DDL 및 DML 쿼리와 함께 사용될 경우 쿼리 결과에서 대상 데이터 세트 이름을 지정하는 또 다른 방법입니다.--display_name
은 예약된 쿼리의 이름입니다.--params
는 JSON 형식으로 생성된 전송 구성의 매개변수입니다. 예: --params='{"param":"param_value"}'--destination_kms_key
는 이 전송에 고객 관리 암호화 키(CMEK)를 사용하는 경우 Cloud KMS 키의 키 리소스 ID를 지정합니다. 고객 관리 암호화 키(CMEK)가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 예약된 쿼리로 암호화 키 지정을 참조하세요.
bq update \ --target_dataset=dataset \ --display_name=name \ --params='parameters' --transfer_config \ RESOURCE_NAME
다음을 바꿉니다.
dataset
. 전송 구성의 대상 데이터 세트입니다. 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.name
. 전송 구성의 표시 이름입니다. 표시 이름은 나중에 쿼리를 수정해야 하는 경우에 식별할 수 있는 모든 값일 수 있습니다.parameters
. JSON 형식으로 생성된 전송 구성의 매개변수가 있습니다. 예를 들면--params='{"param":"param_value"}'
입니다.- 예약된 쿼리의 경우
query
매개변수를 지정해야 합니다. destination_table_name_template
매개변수는 대상 테이블의 이름입니다. 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.write_disposition
매개변수의 경우WRITE_TRUNCATE
를 선택하여 대상 테이블을 자르거나(덮어쓰거나)WRITE_APPEND
를 선택하여 대상 테이블에 쿼리 결과를 추가할 수 있습니다. 이 매개변수는 DDL 및 DML 쿼리의 선택사항입니다. 다른 모든 쿼리에 필수입니다.
- 예약된 쿼리의 경우
- 선택사항:
--destination_kms_key
는 Cloud KMS 키의 키 리소스 ID를 지정합니다(예:projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name
). RESOURCE_NAME
: 전송 리소스 이름입니다(전송 구성이라고도 함). 전송 리소스 이름을 모르면bq ls --transfer_config --transfer_location=location
으로 리소스 이름을 찾습니다.
예를 들어 다음 명령어는 SELECT 1
from mydataset.test
라는 단순한 쿼리를 사용하여 My Scheduled Query
라는 예약된 쿼리 전송 구성을 업데이트합니다. 대상 테이블 mytable
은 매 쓰기 시 잘리며 대상 데이터 세트는 mydataset
입니다.
bq update \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}'
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
API
projects.transferConfigs.patch
메서드를 사용하고 transferConfig.name
매개변수를 사용하여 전송의 리소스 이름을 제공합니다. 전송 리소스 이름을 모르면 bq ls --transfer_config --transfer_location=location
명령어를 사용하여 모든 전송을 나열하거나 projects.locations.transferConfigs.list
메서드를 호출하고 parent
매개변수를 사용하여 프로젝트 ID를 제공합니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
소유권 제한사항이 있는 예약된 쿼리 업데이트
소유하지 않은 예약된 쿼리를 업데이트하려고 하면 업데이트가 실패하고 다음 오류 메시지가 표시될 수 있습니다.
Cannot modify restricted parameters without taking ownership of the transfer configuration.
예약된 쿼리의 소유자는 예약된 쿼리와 연결된 사용자 또는 예약된 쿼리와 연결된 서비스 계정에 액세스할 수 있는 사용자입니다. 연결된 사용자는 예약된 쿼리의 구성 세부정보에서 확인할 수 있습니다. 소유권을 갖도록 예약된 쿼리를 업데이트하는 방법에 대한 자세한 내용은 예약된 쿼리 사용자 인증 정보 업데이트를 참조하세요. 사용자에게 서비스 계정에 대한 액세스 권한을 부여하려면 서비스 계정 사용자 역할이 있어야 합니다.
예약된 쿼리의 소유자는 아니지만 쿼리에서 언급한 모든 리소스에 액세스할 수 있는 모든 사용자가 쿼리를 업데이트할 수 있습니다. 이 시나리오는 1~2분 내에 쿼리 유효성을 검사할 수 있는 경우에만 지원됩니다. 그렇지 않으면 앞에서 언급한 것과 동일한 오류 메시지가 표시됩니다. 쿼리가 너무 복잡하면 예약된 쿼리 사용자 인증 정보를 업데이트하여 예약된 쿼리의 직접 소유권을 갖거나 서비스 계정을 사용할 수 있습니다.
예약된 쿼리의 사용자 인증 정보 업데이트
기존 쿼리를 예약할 경우 쿼리에서 사용자 인증 정보를 업데이트해야 할 수 있습니다. 새로 예약된 쿼리에서는 사용자 인증 정보가 자동으로 최신 상태로 업데이트됩니다.
사용자 인증 정보 업데이트가 필요할 수 있는 일부 다른 상황은 다음과 같습니다.
- 예약된 쿼리에서 Google Drive 데이터를 쿼리하려고 합니다.
쿼리를 예약하려고 하면 INVALID_USER 오류가 발생합니다.
Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID
쿼리를 업데이트하려고 하면 다음과 같은 제한된 파라미터 오류가 발생합니다.
Cannot modify restricted parameters without taking ownership of the transfer configuration.
콘솔
예약된 쿼리에서 기존 사용자 인증 정보를 새로 고치려면 다음 안내를 따르세요.
더보기 버튼을 클릭하고 사용자 인증 정보 업데이트를 선택합니다.
변경사항이 적용되는 데 10~20분 정도 걸립니다. 브라우저의 캐시를 지워야 할 수도 있습니다.
bq
예약된 쿼리는 일종의 전송입니다. 예약된 쿼리의 사용자 인증 정보를 업데이트하려면 bq 명령줄 도구를 사용하여 전송 구성을 업데이트하면 됩니다.
bq update
명령어를 입력하고 전송 플래그 --transfer_config
를 지정합니다. 다음 플래그도 필요합니다.
--update_credentials
선택적 플래그:
--service_account_name
은 개별 사용자 계정 대신 서비스 계정으로 예약된 쿼리를 인증할 때 사용됩니다.
예를 들어 다음 명령어는 서비스 계정으로 인증하도록 예약된 쿼리 전송 구성을 업데이트합니다.
bq update \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이전 날짜에 수동 실행 설정
나중에 쿼리를 실행하도록 예약하는 것 외에도 직접 실행을 수동으로 트리거할 수도 있습니다. 쿼리가 run_date
매개변수를 사용하고 이전 실행 중에 문제가 발생한 경우 즉시 실행을 트리거해야 합니다.
예를 들어 매일 09:00에 소스 테이블에서 현재 날짜와 일치하는 행을 쿼리했는데 지난 3일 동안 소스 테이블에 데이터가 추가되지 않았다는 것을 알게 되었다면 지정된 기간 내 이전 데이터를 대상으로 쿼리를 실행하도록 설정할 수 있습니다. 쿼리는 예약된 쿼리에서 구성한 날짜에 해당하는 run_date
매개변수와 run_time
매개변수의 조합을 통해 실행됩니다.
예약된 쿼리를 설정한 후 이전 기간을 사용하여 쿼리를 실행하는 방법은 다음과 같습니다.
콘솔
일정을 클릭하여 예약된 쿼리를 저장하면 예약된 쿼리 버튼을 클릭하여 현재 예약된 쿼리 목록을 확인할 수 있습니다. 해당 쿼리의 일정에 대한 세부정보를 보려면 표시 이름을 클릭합니다. 페이지 오른쪽 상단에 있는 백필 예약을 클릭하여 이전 기간을 지정합니다.
선택한 런타임이 모두 선택한 범위 내에 있으며 처음 날짜는 포함되지만 마지막 날짜는 제외됩니다.
예시 1
예약된 쿼리가 every day 09:00
(태평양 표준시)에 실행되도록 설정됩니다. 1월 1일, 1월 2일, 1월 3일의 데이터가 누락되었습니다. 다음과 같은 이전 기간을 선택합니다.
Start Time = 1/1/19
End Time = 1/4/19
쿼리가 다음 시간에 해당하는 run_date
및 run_time
매개변수를 사용하여 실행됩니다.
- 태평양 표준시 기준 19/1/1 09:00
- 태평양 표준시 기준 19/1/2 09:00
- 태평양 표준시 기준 19/1/3 09:00
예시 2
예약된 쿼리가 every day 23:00
(태평양 표준시)에 실행되도록 설정됩니다. 1월 1일, 1월 2일, 1월 3일의 데이터가 누락되었습니다. 다음과 같은 이전 기간을 선택합니다(태평양 표준시 23:00에서는 UTC의 날짜가 다르므로 다음 날짜가 선택됨).
Start Time = 1/2/19
End Time = 1/5/19
쿼리가 다음 시간에 해당하는 run_date
및 run_time
매개변수를 사용하여 실행됩니다.
- UTC 기준 19/1/2 06:00 또는 태평양 표준시 기준 2019/1/1 23:00
- UTC 기준 19/1/3 06:00 또는 태평양 표준시 기준 2019/1/2 23:00
- UTC 기준 19/1/4 06:00 또는 태평양 표준시 기준 2019/1/3 23:00
수동 실행을 설정한 후 페이지를 새로고침하면 실행 목록에 표시됩니다.
bq
이전 기간에 대한 쿼리를 수동으로 실행하려면 다음 안내를 따르세요.
bq mk
명령어를 입력하고 전송 실행 플래그 --transfer_run
를 지정합니다. 다음 플래그도 필요합니다.
--start_time
--end_time
bq mk \ --transfer_run \ --start_time='start_time' \ --end_time='end_time' \ resource_name
다음을 바꿉니다.
start_time
및end_time
. Z로 끝나거나 유효한 시간대 오프셋이 포함된 타임스탬프입니다. 예를 들면 다음과 같습니다.- 2017-08-19T12:11:35.00Z
- 2017-05-25T00:00:00+00:00
resource_name
. 예약된 쿼리(또는 전송)의 리소스 이름입니다. 리소스 이름을 전송 구성이라고도 합니다.
예를 들어 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
명령어는 예약된 쿼리 리소스(또는 전송 구성)에 대한 백필을 예약합니다.
bq mk \
--transfer_run \
--start_time 2017-05-25T00:00:00Z \
--end_time 2017-05-25T00:00:00Z \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
자세한 내용은 bq mk --transfer_run
를 참조하세요.
API
projects.locations.transferConfigs.scheduleRun 메서드를 사용하고 TransferConfig 리소스의 경로를 지정합니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
예약된 쿼리 삭제
콘솔
콘솔을 통해 예약된 쿼리를 삭제하려면 다음 안내를 따르세요.
탐색창에서 예약된 쿼리를 클릭합니다.
예약된 쿼리 목록에서 삭제할 예약된 쿼리의 이름을 클릭합니다.
예약된 쿼리 세부정보 페이지가 열리면 삭제를 클릭합니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
할당량
사용자가 쿼리를 직접 실행하는 것처럼 예약된 쿼리가 작성자의 사용자 인증 정보 및 프로젝트를 사용하여 실행됩니다. 예약된 쿼리는 항상 일괄 쿼리 작업으로 실행됩니다.
예약된 쿼리가 BigQuery Data Transfer Service 기능을 사용하더라도 전송되지 않으며 로드 작업 할당량에 적용되지 않습니다. 예약된 쿼리에는 수동 쿼리와 동일한 BigQuery 할당량 및 한도가 적용됩니다.
가격 책정
예약된 쿼리에는 수동 BigQuery 쿼리와 동일한 가격이 책정됩니다.
지원되는 리전
다음 위치에서는 예약된 쿼리가 지원되지 않습니다.
리전
다음 표에는 BigQuery를 사용할 수 있는 아메리카 내 리전이 나와 있습니다.리전 설명 | 리전 이름 | 세부정보 |
---|---|---|
오하이오 주 콜럼부스 | us-east5 |
|
댈러스 | us-south1 |
낮은 CO2 |
아이오와 | us-central1 |
낮은 CO2 |
라스베이거스 | us-west4 |
|
로스앤젤레스 | us-west2 |
|
몬트리올 | northamerica-northeast1 |
낮은 CO2 |
북버지니아 | us-east4 |
|
오리건 | us-west1 |
낮은 CO2 |
솔트레이크시티 | us-west3 |
|
상파울루 | southamerica-east1 |
낮은 CO2 |
산티아고 | southamerica-west1 |
낮은 CO2 |
사우스캐롤라이나 | us-east1 |
|
토론토 | northamerica-northeast2 |
낮은 CO2 |
리전 설명 | 리전 이름 | 세부정보 |
---|---|---|
델리 | asia-south2 |
|
홍콩 | asia-east2 |
|
자카르타 | asia-southeast2 |
|
멜버른 | australia-southeast2 |
|
뭄바이 | asia-south1 |
|
오사카 | asia-northeast2 |
|
서울 | asia-northeast3 |
|
싱가포르 | asia-southeast1 |
|
시드니 | australia-southeast1 |
|
타이완 | asia-east1 |
|
도쿄 | asia-northeast1 |
리전 설명 | 리전 이름 | 세부정보 |
---|---|---|
벨기에 | europe-west1 |
낮은 CO2 |
베를린 | europe-west10 |
낮은 CO2 |
핀란드 | europe-north1 |
낮은 CO2 |
프랑크푸르트 | europe-west3 |
낮은 CO2 |
런던 | europe-west2 |
낮은 CO2 |
마드리드 | europe-southwest1 |
낮은 CO2 |
밀라노 | europe-west8 |
|
네덜란드 | europe-west4 |
낮은 CO2 |
파리 | europe-west9 |
낮은 CO2 |
토리노 | europe-west12 |
|
바르샤바 | europe-central2 |
|
취리히 | europe-west6 |
낮은 CO2 |
리전 설명 | 리전 이름 | 세부정보 |
---|---|---|
Dammam | me-central2 |
|
도하 | me-central1 |
|
텔아비브 | me-west1 |
리전 설명 | 리전 이름 | 세부정보 |
---|---|---|
요하네스버그 | africa-south1 |
멀티 리전
다음 표에는 BigQuery를 사용할 수 있는 멀티 리전이 나와 있습니다.멀티 리전 설명 | 멀티 리전 이름 |
---|---|
유럽 연합 회원국의 데이터 센터1 | EU |
미국의 데이터 센터2 | US |
1 EU
멀티 리전에 있는 데이터는 europe-west1
(벨기에) 또는 europe-west4
(네덜란드) 중 한 곳에만 저장됩니다.
데이터가 저장 및 처리되는 정확한 위치는 BigQuery에 의해 자동으로 결정됩니다.
2 US
멀티 리전에 있는 데이터는 us-central1
(아이오와), us-west1
(오리건), us-central2
(오클라호마) 중 한 곳에만 저장됩니다. 데이터가 저장 및 처리되는 정확한 위치는 BigQuery에 의해 자동으로 결정됩니다.
다음 단계
- 서비스 계정을 사용하고
@run_date
및@run_time
매개변수를 포함하는 예약된 쿼리의 예시는 예약된 쿼리로 테이블 스냅샷 만들기를 참조하세요.