BigQuery 구독

이 문서에서는 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 구독의 메시지 흐름
그림 1. BigQuery 구독 워크플로

다음은 그림 1을 참조하는 워크플로에 대한 간략한 설명입니다.

  1. Pub/Sub는 BigQuery Storage Write API를 사용하여 BigQuery 테이블로 데이터를 전송합니다.
  2. 메시지가 일괄적으로 BigQuery 테이블에 전송됩니다.
  3. 쓰기 작업이 성공적으로 완료되면 API가 OK 응답을 반환합니다.
  4. 쓰기 작업에 오류가 발생하면 Pub/Sub 메시지 자체가 부정적으로 확인됩니다. 그러면 메시지가 다시 전송됩니다. 메시지가 충분히 실패하고 구독에 데드 레터 주제가 구성된 경우 메시지는 데드 레터 주제로 이동합니다.

BigQuery 구독의 속성

BigQuery 구독에 대해 구성하는 속성에 따라 Pub/Sub가 메시지를 기록하는 BigQuery 테이블과 이 테이블의 스키마 유형이 결정됩니다.

자세한 내용은 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는 동일한 키가 있으면 동일한 키가 있는 테이블의 행을 삭제합니다.

  • _CHANGE_SEQUENCE_NUMBER(선택사항): BigQuery 테이블에 대한 업데이트 및 삭제가 순서대로 처리되도록 설정된 int64(long) 또는 int32(int) 필드입니다. 동일한 row key의 메시지는 _CHANGE_SEQUENCE_NUMBER에 단조 증가하는 값을 포함해야 합니다. 행에 대해 처리된 가장 높은 시퀀스 넘버보다 작은 시퀀스 넘버가 있는 메시지는 BigQuery 테이블의 행에 영향을 주지 않습니다. Pub/Sub에는 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 가격 책정 페이지를 참조하세요.

다음 단계