이 문서에서는 BigQuery 구독, 워크플로, 관련 속성을 간략하게 설명합니다.
BigQuery 구독은 메시지가 수신될 때 기존 BigQuery 테이블에 메시지를 기록하는 내보내기 구독 유형입니다. 별도의 구독자 클라이언트를 구성할 필요가 없습니다. Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API를 사용하여 BigQuery 구독을 생성, 업데이트, 나열, 분리, 삭제합니다.
BigQuery 구독 유형이 없으면 메시지를 읽고 BigQuery 테이블에 작성하는 구독자(예: Dataflow)와 풀 또는 푸시 구독이 필요합니다. 메시지를 BigQuery 테이블에 저장하기 전에 추가 처리가 필요하지 않은 경우 Dataflow 작업을 실행하는 오버헤드가 필요하지 않습니다. 대신 BigQuery 구독을 사용할 수 있습니다.
그러나 데이터를 BigQuery 테이블에 저장하기 전에 일부 데이터 변환이 필요한 Pub/Sub 시스템에는 여전히 Dataflow 파이프라인이 권장됩니다. Dataflow를 사용하여 변환을 통해 Pub/Sub에서 BigQuery로 데이터를 스트리밍하는 방법은 Pub/Sub에서 BigQuery로 스트리밍을 참조하세요.
Dataflow의 Pub/Sub subscription to BigQuery 템플릿은 기본적으로 단 한 번 전송을 적용합니다. 이는 일반적으로 Dataflow 파이프라인 내 중복 삭제 메커니즘을 통해 수행됩니다. 하지만 BigQuery 구독에서는 최소 1회 이상 전송만 지원합니다. 사용 사례에 정확한 중복 삭제가 중요한 경우 BigQuery의 다운스트림 프로세스를 통해 잠재적인 중복을 처리하는 것이 좋습니다.
시작하기 전에
이 문서를 읽기 전 다음 내용을 숙지해야 합니다.
Pub/Sub 작동 방법과 여러 가지 Pub/Sub 용어
Pub/Sub가 지원하는 다양한 종류의 구독과 BigQuery 구독을 사용해야 하는 이유
BigQuery의 작동 방식과 BigQuery 테이블을 구성 및 관리하는 방법
BigQuery 구독 워크플로
다음은 BigQuery 구독과 BigQuery 간의 워크플로를 보여주는 이미지입니다.
![BigQuery 구독의 메시지 흐름](https://cloud.google.com/static/pubsub/images/subscriber_bigquery.png?authuser=2&hl=ko)
다음은 그림 1을 참조하는 워크플로에 대한 간략한 설명입니다.
- Pub/Sub는 BigQuery Storage Write API를 사용하여 BigQuery 테이블로 데이터를 전송합니다.
- 메시지가 일괄적으로 BigQuery 테이블에 전송됩니다.
- 쓰기 작업이 성공적으로 완료되면 API가 OK 응답을 반환합니다.
- 쓰기 작업에 오류가 발생하면 Pub/Sub 메시지 자체가 부정적으로 확인됩니다. 그러면 메시지가 다시 전송됩니다. 메시지가 충분히 실패하고 구독에 데드 레터 주제가 구성된 경우 메시지는 데드 레터 주제로 이동합니다.
BigQuery 구독의 속성
BigQuery 구독에 대해 구성하는 속성에 따라 Pub/Sub가 메시지를 기록하는 BigQuery 테이블과 이 테이블의 스키마 유형이 결정됩니다.
자세한 내용은 BigQuery 속성을 참조하세요.
스키마 호환성
Pub/Sub와 BigQuery는 서로 다른 방법을 사용해서 스키마를 정의합니다. Pub/Sub 스키마는 Apache Avro 또는 프로토콜 버퍼 형식으로 정의되고 BigQuery 스키마는 다양한 형식을 사용하여 정의됩니다. 다음은 Pub/Sub 주제와 BigQuery 테이블 간의 스키마 호환성에 대한 중요한 정보입니다.
부적절한 형식의 필드가 포함된 메시지는 BigQuery에 기록되지 않습니다.
BigQuery 스키마에서
INT
,SMALLINT
,INTEGER
,BIGINT
,TINYINT
,BYTEINT
는INTEGER
의 별칭이고,DECIMAL
은NUMERIC
의 별칭이고,BIGDECIMAL
은BIGNUMERIC
의 별칭입니다.주제 스키마의 유형이
string
이고 BigQuery 테이블의 유형이JSON
,TIMESTAMP
,DATETIME
,DATE
,TIME
,NUMERIC
또는BIGNUMERIC
인 경우 Pub/Sub 메시지의 필드에 대한 모든 값은 BigQuery 데이터 유형에 지정된 형식을 준수해야 합니다.다음 표에 지정된 대로 일부 Avro 논리 유형이 지원됩니다. 나열되지 않은 논리 유형은 Avro 사양에 설명된 대로 주석이 추가된 동등한 Avro 유형과만 일치합니다.
다음은 BigQuery 데이터 유형에 대해 서로 다른 스키마 형식의 매핑 모음입니다.
Avro 유형
Avro 유형 | BigQuery 데이터 유형 |
null |
Any NULLABLE |
boolean |
BOOLEAN |
int |
INTEGER , NUMERIC 또는
BIGNUMERIC |
long |
INTEGER , NUMERIC 또는
BIGNUMERIC |
float |
FLOAT64 , NUMERIC 또는
BIGNUMERIC |
double |
FLOAT64 , NUMERIC 또는
BIGNUMERIC |
bytes |
BYTES , NUMERIC 또는
BIGNUMERIC |
string |
STRING , JSON ,
TIMESTAMP , DATETIME ,
DATE , TIME ,
NUMERIC 또는 BIGNUMERIC |
record |
RECORD/STRUCT |
array /Type |
REPEATED Type |
값 유형이 ValueType 인 map
|
REPEATED STRUCT <key STRING, value
ValueType> |
union : 두 가지 유형(하나는 null , 다른 하나는 Type ) |
NULLABLE Type |
기타 union |
매핑할 수 없음 |
fixed |
BYTES , NUMERIC 또는
BIGNUMERIC |
enum |
INTEGER |
Avro 논리 유형
Avro 논리 유형 | BigQuery 데이터 유형 |
timestamp-micros |
TIMESTAMP |
date |
DATE |
time-micros |
TIME |
duration |
INTERVAL |
decimal |
NUMERIC 또는 BIGNUMERIC |
프로토콜 버퍼 유형
프로토콜 버퍼 유형 | BigQuery 데이터 유형 |
double |
FLOAT64 , NUMERIC 또는
BIGNUMERIC |
float |
FLOAT64 , NUMERIC 또는
BIGNUMERIC |
int32 |
INTEGER , NUMERIC ,
BIGNUMERIC 또는 DATE |
int64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME 또는 TIMESTAMP |
uint32 |
INTEGER , NUMERIC ,
BIGNUMERIC 또는 DATE |
uint64 |
NUMERIC 또는 BIGNUMERIC |
sint32 |
INTEGER , NUMERIC 또는
BIGNUMERIC |
sint64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME 또는 TIMESTAMP |
fixed32 |
INTEGER , NUMERIC ,
BIGNUMERIC 또는 DATE |
fixed64 |
NUMERIC 또는 BIGNUMERIC |
sfixed32 |
INTEGER , NUMERIC ,
BIGNUMERIC 또는 DATE |
sfixed64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME 또는 TIMESTAMP |
bool |
BOOLEAN |
string |
STRING , JSON ,
TIMESTAMP , DATETIME ,
DATE , TIME ,
NUMERIC 또는 BIGNUMERIC |
bytes |
BYTES , NUMERIC 또는
BIGNUMERIC |
enum |
INTEGER |
message |
RECORD/STRUCT |
oneof |
매핑할 수 없음 |
map<KeyType, ValueType> |
REPEATED RECORD<key KeyType, value
ValueType> |
enum |
INTEGER |
repeated/array of Type |
REPEATED Type |
날짜 및 시간 정수 표현
정수를 날짜 또는 시간 유형 중 하나로 매핑할 때 숫자는 올바른 값을 나타내야 합니다. 다음과 같이 이를 나타내는 정수로 BigQuery 데이터 유형을 매핑합니다.
BigQuery 데이터 유형 | 정수 표현 |
DATE |
유닉스 시간(1970년 1월 1일) 이후의 일수 |
DATETIME |
CivilTimeEncoder를 사용하여 상용시로 표현한 날짜 및 시간(마이크로초) |
TIME |
CivilTimeEncoder를 사용하여 상용시로 표현한 시간(마이크로초) |
TIMESTAMP |
유닉스 시간(1970년 1월 1일 00:00:00 UTC) 이후의 마이크로초 수 |
BigQuery 변경 데이터 캡처
BigQuery 구독은 구독 속성에서 use_topic_schema
또는 use_table_schema
가 true
로 설정된 경우에 변경 데이터 캡처(CDC) 업데이트를 지원합니다. use_topic_schema
에서 이 기능을 사용하려면 다음 필드를 사용하여 주제 스키마를 설정합니다.
_CHANGE_TYPE
(필수):UPSERT
또는DELETE
로 설정된string
필드BigQuery 테이블에 기록된 Pub/Sub 메시지에
_CHANGE_TYPE
이UPSERT
로 설정되어 있는 경우 BigQuery는 동일한 키가 있으면 동일한 키로 행을 업데이트하거나 없으면 새 행을 삽입합니다.BigQuery 테이블에 기록된 Pub/Sub 메시지에
_CHANGE_TYPE
이DELETE
로 설정되어 있으면 BigQuery는 동일한 키가 있으면 동일한 키가 있는 테이블의 행을 삭제합니다.
use_table_schema
에서 이 기능을 사용하려면 JSON 메시지에 이전 필드를 포함합니다.
Pub/Sub 서비스 계정 권한
BigQuery 구독을 만들려면 Pub/Sub 서비스 계정에 특정 BigQuery 테이블에 쓰기 권한과 테이블 메타데이터 읽기 권한이 있어야 합니다. 자세한 내용은 Pub/Sub 서비스 계정에 BigQuery 역할 할당을 참조하세요.
메시지 처리 실패
Pub/Sub 메시지를 BigQuery에 쓸 수 없으면 메시지를 확인할 수 없습니다. 이러한 전달할 수 없는 메시지를 전달하려면 BigQuery 구독에서 데드 레터 주제를 구성합니다. 데드 레터 주제로 전달된 Pub/Sub 메시지에는 Pub/Sub 메시지를 BigQuery에 쓸 수 없는 이유가 있는 CloudPubSubDeadLetterSourceDeliveryErrorMessage
속성이 포함됩니다.
Pub/Sub가 BigQuery에 메시지를 쓸 수 없으면 Pub/Sub는 push 백오프 동작과 비슷한 방식으로 메시지 전송을 중단합니다. 하지만 구독에 데드 레터 주제가 연결되어 있는 경우 Pub/Sub는 스키마 호환성 오류로 인한 메시지 오류가 발생할 때 전송을 중단하지 않습니다.
할당량 및 한도
리전별 BigQuery 구독자 처리량에 할당량 제한이 있습니다. 자세한 내용은 Pub/Sub 할당량 및 한도를 참조하세요.
BigQuery 구독은 BigQuery Storage Write API를 사용하여 데이터를 씁니다. Storage Write API의 할당량 및 한도에 대한 자세한 내용은 BigQuery Storage Write API 요청을 참조하세요. BigQuery 구독은 Storage Write API의 처리량 할당량만 사용합니다. 이 인스턴스에서는 다른 Storage Write API 할당량 고려사항을 무시해도 됩니다.
가격 책정
BigQuery 구독의 가격 책정은 Pub/Sub 가격 책정 페이지를 참조하세요.
다음 단계
BigQuery 구독과 같은 구독 만들기
BigQuery 구독 문제 해결하기
BigQuery에 대해 알아보기
BigQuery 구독을 포함한 Pub/Sub의 가격 책정 검토하기
gcloud
CLI 명령어로 구독을 만들거나 수정하기REST API로 구독을 만들거나 수정하기