이 페이지는 Cloud Translation API를 통해 번역되었습니다.

쿼리 예약

이 페이지에서는 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 권한이 있어야 합니다.

참고: Google Cloud 콘솔이나 bq 명령줄 도구를 사용하여 쿼리를 예약하는 경우 bigquery.transfers.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_date`	이 매개변수는 `YYYYMMDD` 형식의 날짜로 대체됩니다.
`run_time`	이 매개변수는 다음 속성을 지원합니다. `offset` 시간(h), 분(m), 초(s)의 순서로 표시되는 타임스탬프입니다. 일(d)은 지원되지 않습니다. 소수가 허용됩니다(예: `1.5h`). `time_format` 형식이 지정된 문자열. 가장 일반적인 형식 지정 매개변수는 년(%Y), 월(%m), 일(%d)입니다. 파티션을 나눈 테이블에서는 YYYYMMDD가 필수 서픽스입니다. 이는 '%Y%m%d'와 같습니다. datetime 요소 형식 지정에 대해 자세히 알아보세요.

run_time

이 매개변수는 다음 속성을 지원합니다.

offset
시간(h), 분(m), 초(s)의 순서로 표시되는 타임스탬프입니다.
일(d)은 지원되지 않습니다.
소수가 허용됩니다(예: 1.5h).

time_format
형식이 지정된 문자열. 가장 일반적인 형식 지정 매개변수는 년(%Y), 월(%m), 일(%d)입니다.
파티션을 나눈 테이블에서는 YYYYMMDD가 필수 서픽스입니다. 이는 '%Y%m%d'와 같습니다.

datetime 요소 형식 지정에 대해 자세히 알아보세요.

사용법 참고사항:

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 페이지를 엽니다.

BigQuery로 이동
원하는 쿼리를 실행합니다. 결과에 만족하면 예약을 클릭합니다.
새로 예약된 쿼리 창에 예약된 쿼리 옵션이 열립니다.
새로 예약된 쿼리 창에서 다음을 수행합니다.
- 예약된 쿼리 이름에 이름(예: My scheduled query)을 입력합니다. 예약된 쿼리 이름은 나중에 쿼리를 수정해야 하는 경우에 식별할 수 있는 모든 값일 수 있습니다.
- 선택사항: 기본적으로 쿼리는 매일 실행되도록 예약됩니다. 반복 드롭다운 메뉴에서 옵션을 선택하여 기본 일정을 변경할 수 있습니다.
  - 커스텀 빈도를 지정하려면 커스텀을 선택한 다음 커스텀 일정 필드에 크론과 유사한 시간 지정을 입력합니다(예: every mon 23:30 또는 every 6 hours). 커스텀 간격을 포함한 유효한 일정에 대한 자세한 내용은 리소스: TransferConfig의 schedule 필드를 참조하세요.
    
    참고: 예약된 쿼리 사이의 최소 기간은 5분입니다.
  - 시작 시간을 변경하려면 설정 시간에 시작 옵션을 선택하고 원하는 시작 날짜와 시간을 입력합니다.
    
    참고: 지정된 시작 시간이 일정의 시간보다 늦으면 첫 번째 쿼리 실행은 해당 주기의 다음 번 반복이 됩니다. 예를 들어 2022-06-05 23:50에서 daily 00:00 일정 및 2022-06-06 10:00 시작 시간에 생성된 쿼리는 2022-06-07 00:00까지 실행되지 않습니다.
  - 종료 시간을 지정하려면 종료 시간 예약 옵션을 선택하고 원하는 종료 날짜와 시간을 입력합니다.
  - 나중에 필요할 때 실행할 수 있도록 예약 없이 쿼리를 저장하려면 반복 메뉴에서 주문형을 선택합니다.
GoogleSQL SELECT 쿼리의 경우 쿼리 결과의 대상 테이블 설정 옵션을 선택하고 대상 데이터 세트에 대한 다음 정보를 제공합니다.
- 데이터 세트 이름에서 적절한 대상 데이터 세트를 선택합니다.
- 테이블 이름에서 대상 테이블의 이름을 입력합니다.
- 대상 테이블 쓰기 환경설정에서 테이블에 추가를 선택하여 데이터를 테이블에 추가하거나 테이블 덮어쓰기를 선택하여 대상 테이블을 덮어씁니다.
위치 유형을 선택합니다.
- 쿼리 결과에 대상 테이블을 사용 설정한 경우 자동 위치 선택을 선택하여 대상 테이블이 있는 위치를 자동으로 선택할 수 있습니다.
- 그렇지 않으면 쿼리되는 데이터가 있는 위치를 선택합니다.
고급 옵션:
- 선택사항: CMEK: 고객 관리 암호화 키를 사용하는 경우 고급 옵션에서 고객 관리 키를 선택할 수 있습니다. 선택할 수 있는 CMEK 목록이 표시됩니다. 고객 관리 암호화 키(CMEK)가 BigQuery Data Transfer Service에서 작동하는 방식에 대한 자세한 내용은 예약된 쿼리로 암호화 키 지정을 참조하세요.
- 서비스 계정으로 인증: Google Cloud 프로젝트에 연결된 서비스 계정이 한 개 이상이면 사용자 인증 정보를 사용하는 대신 서비스 계정을 예약된 쿼리와 연결할 수 있습니다. 예약된 쿼리 사용자 인증 정보에서 메뉴를 클릭하여 사용 가능한 서비스 계정 목록을 표시합니다. 제휴 ID로 로그인한 경우 서비스 계정이 필요합니다.
추가 구성:
- 선택사항: 전송 실행 실패에 대한 이메일 알림을 허용하려면 이메일 알림 전송을 선택합니다.
- 선택사항: Pub/Sub 주제에 Pub/Sub 주제 이름(예: projects/myproject/topics/mytopic)을 입력합니다.
저장을 클릭합니다.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query
public class CreateScheduledQuery {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQuery(projectId, transferConfig);
  }

  public static void createScheduledQuery(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println("\nScheduled query created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query was not created." + ex.toString());
    }
  }
}

Python

BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

서비스 계정을 사용하여 예약된 쿼리 설정

자바

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query with service account
public class CreateScheduledQueryWithServiceAccount {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String serviceAccount = "MY_SERVICE_ACCOUNT";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQueryWithServiceAccount(projectId, transferConfig, serviceAccount);
  }

  public static void createScheduledQueryWithServiceAccount(
      String projectId, TransferConfig transferConfig, String serviceAccount) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .setServiceAccountName(serviceAccount)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with service account created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with service account was not created." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

예약된 쿼리 상태 보기

콘솔

예약된 쿼리의 상태를 보려면 탐색창에서 예약된 쿼리를 클릭합니다. 예약된 쿼리의 업데이트된 상태를 확인하려면 페이지를 새로 고칩니다. 예약된 쿼리를 클릭하면 자세한 내용을 확인할 수 있습니다.

예약된 쿼리 나열

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

project_id = "my-project"
parent = transfer_client.common_project_path(project_id)

configs = transfer_client.list_transfer_configs(parent=parent)
print("Got the following configs:")
for config in configs:
    print(f"\tID: {config.name}, Schedule: {config.schedule}")

예약된 쿼리 업데이트

콘솔

예약된 쿼리를 업데이트하려면 다음 단계를 따르세요.

탐색창에서 예약된 쿼리를 클릭합니다.
예약된 쿼리 목록에서 변경하려는 쿼리 이름을 클릭합니다.
예약된 쿼리 세부정보 페이지가 열리면 수정을 클릭합니다.
선택사항: 쿼리 수정 창에서 쿼리 텍스트를 변경합니다.
쿼리 예약을 클릭한 다음 예약된 쿼리 업데이트를 선택합니다.
선택사항: 쿼리의 다른 예약 옵션을 변경합니다.
업데이트를 클릭합니다.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
new_display_name = "My Transfer Config"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.display_name = new_display_name

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["display_name"]),
    }
)

print(f"Updated config: '{transfer_config.name}'")
print(f"New display name: '{transfer_config.display_name}'")

소유권 제한이 있는 예약된 쿼리 업데이트

소유하지 않은 예약된 쿼리를 업데이트하려고 하면 다음과 같은 오류 메시지와 함께 업데이트가 실패할 수 있습니다.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

이전 날짜에 수동 실행 설정

나중에 쿼리를 실행하도록 예약하는 것 외에도 직접 실행을 수동으로 트리거할 수도 있습니다. 쿼리가 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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

예약된 쿼리 삭제

콘솔

콘솔을 통해 예약된 쿼리를 삭제하려면 다음 안내를 따르세요.

탐색창에서 예약된 쿼리를 클릭합니다.
예약된 쿼리 목록에서 삭제할 예약된 쿼리의 이름을 클릭합니다.
예약된 쿼리 세부정보 페이지가 열리면 삭제를 클릭합니다.

자바

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
try:
    transfer_client.delete_transfer_config(name=transfer_config_name)
except google.api_core.exceptions.NotFound:
    print("Transfer config not found.")
else:
    print(f"Deleted transfer config: {transfer_config_name}")

할당량

사용자가 쿼리를 직접 실행하는 것처럼 예약된 쿼리가 작성자의 사용자 인증 정보 및 프로젝트를 사용하여 실행됩니다. 예약된 쿼리는 항상 일괄 쿼리 작업으로 실행됩니다.

예약된 쿼리가 BigQuery Data Transfer Service 기능을 사용하더라도 전송되지 않으며 로드 작업 할당량에 적용되지 않습니다. 예약된 쿼리에는 수동 쿼리와 동일한 BigQuery 할당량 및 한도가 적용됩니다.

가격 책정

예약된 쿼리에는 수동 BigQuery 쿼리와 동일한 가격이 책정됩니다.

지원되는 리전

다음 위치에서는 예약된 쿼리가 지원되지 않습니다.

리전

다음 표에는 BigQuery를 사용할 수 있는 아메리카 내 리전이 나와 있습니다.

리전 설명	리전 이름	세부정보
오하이오 주 콜럼부스	`us-east5`
댈러스	`us-south1`	낮은 CO₂
아이오와	`us-central1`	낮은 CO₂
라스베이거스	`us-west4`
로스앤젤레스	`us-west2`
몬트리올	`northamerica-northeast1`	낮은 CO₂
북버지니아	`us-east4`
오리건	`us-west1`	낮은 CO₂
솔트레이크시티	`us-west3`
상파울루	`southamerica-east1`	낮은 CO₂
산티아고	`southamerica-west1`	낮은 CO₂
사우스캐롤라이나	`us-east1`
토론토	`northamerica-northeast2`	낮은 CO₂

다음 표에는 BigQuery를 사용할 수 있는 아시아 태평양의 리전이 나와 있습니다.

리전 설명	리전 이름	세부정보
델리	`asia-south2`
홍콩	`asia-east2`
자카르타	`asia-southeast2`
멜버른	`australia-southeast2`
뭄바이	`asia-south1`
오사카	`asia-northeast2`
서울	`asia-northeast3`
싱가포르	`asia-southeast1`
시드니	`australia-southeast1`
타이완	`asia-east1`
도쿄	`asia-northeast1`

다음 표에는 BigQuery를 사용할 수 있는 유럽 내 리전이 나와 있습니다.

리전 설명	리전 이름	세부정보
벨기에	`europe-west1`	낮은 CO₂
베를린	`europe-west10`	낮은 CO₂
핀란드	`europe-north1`	낮은 CO₂
프랑크푸르트	`europe-west3`	낮은 CO₂
런던	`europe-west2`	낮은 CO₂
마드리드	`europe-southwest1`	낮은 CO₂
밀라노	`europe-west8`
네덜란드	`europe-west4`	낮은 CO₂
파리	`europe-west9`	낮은 CO₂
토리노	`europe-west12`
바르샤바	`europe-central2`
취리히	`europe-west6`	낮은 CO₂

다음 표에는 BigQuery를 사용할 수 있는 중동 내 리전이 나와 있습니다.

리전 설명	리전 이름	세부정보
담맘	`me-central2`
도하	`me-central1`
텔아비브	`me-west1`

다음 표에는 BigQuery를 사용할 수 있는 아프리카 내 리전이 나와 있습니다.

리전 설명	리전 이름	세부정보
요하네스버그	`africa-south1`

멀티 리전

다음 표에는 BigQuery를 사용할 수 있는 멀티 리전이 나와 있습니다.

멀티 리전 설명	멀티 리전 이름
유럽 연합 회원국의 데이터 센터¹	`EU`
미국의 데이터 센터²	`US`

¹ EU 멀티 리전에 있는 데이터는 europe-west1(벨기에) 또는 europe-west4(네덜란드) 중 한 곳에만 저장됩니다. 데이터가 저장 및 처리되는 정확한 위치는 BigQuery에 의해 자동으로 결정됩니다.

² US 멀티 리전에 있는 데이터는 us-central1(아이오와), us-west1(오리건), us-central2(오클라호마) 중 한 곳에만 저장됩니다. 데이터가 저장 및 처리되는 정확한 위치는 BigQuery에 의해 자동으로 결정됩니다.

다음 단계

서비스 계정을 사용하고 @run_date 및 @run_time 매개변수를 포함하는 예약된 쿼리의 예시는 예약된 쿼리로 테이블 스냅샷 만들기를 참조하세요.