BigQuery 구독

BigQuery 구독은 수신되는 메시지를 기존 BigQuery 테이블에 기록합니다. 구독자 클라이언트는 개별적으로 구성할 필요가 없습니다. Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API를 사용하여 BigQuery 구독을 생성, 업데이트, 나열, 분리, 삭제합니다.

종종 Dataflow를 사용하여 BigQuery에 기록하는 단순 데이터 수집 파이프라인의 대안으로 BigQuery 구독은 다음과 같은 이점이 있습니다.

  • 간단한 배포. 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API에서 단일 워크플로를 통해 BigQuery 구독을 설정할 수 있습니다.

  • 낮은 비용 제공. Dataflow 작업을 포함하는 비슷한 Pub/Sub 파이프라인의 추가 비용 및 지연 시간을 없애 줍니다. 이러한 비용 최적화는 스토리지 이전 추가 처리가 필요하지 않은 메시징 시스템에 유용합니다.

  • 모니터링을 최소화합니다. BigQuery 구독은 멀티 테넌트 Pub/Sub 서비스의 일부이며 사용자가 개별 모니터링 작업을 실행할 필요가 없습니다.

시작하기 전에

이 문서를 읽기 전 다음 내용을 숙지해야 합니다.

  • Pub/Sub 작동 방법과 여러 가지 Pub/Sub 용어

  • Pub/Sub가 지원하는 다양한 종류의 구독과 BigQuery 구독을 사용해야 하는 이유

  • BigQuery의 작동 방식과 BigQuery 테이블을 구성 및 관리하는 방법

Pub/Sub 및 BigQuery에 대한 기본 지식 외에도 BigQuery 구독을 만들기 전에 다음 기본 요건을 충족해야 합니다.

  • BigQuery 테이블이 있습니다. 또는 BigQuery 구독을 만들 때 테이블을 만들 수 있습니다. 자세한 내용은 BigQuery 구독을 참조하세요.

  • Pub/Sub 주제의 스키마와 BigQuery 테이블 간의 호환성. 호환되지 않는 BigQuery 테이블을 추가하면 호환성 관련 오류 메시지가 표시됩니다. 자세한 내용은 다음 섹션을 참조하세요.

BigQuery 구독의 속성

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

구독 전송 유형을 BigQuery에 쓰기로 선택하면 다음과 같은 추가 속성을 지정할 수 있습니다.

  • 주제 스키마 사용. 이 옵션을 사용하면 Pub/Sub가 구독이 연결된 Pub/Sub 주제의 스키마를 사용할 수 있습니다. 또한 Pub/Sub가 BigQuery 테이블에서 해당 열에 메시지의 필드를 기록합니다. 이 옵션을 사용할 때는 다음 추가 요구사항을 확인해야 합니다.

    • 주제 스키마 및 BigQuery 스키마의 필드가 이름이 동일하고 유형이 서로 호환되어야 합니다.

    • 주제 스키마에서 선택적인 필드는 BigQuery 스키마에서도 선택적이어야 합니다.

    • 주제 스키마의 필수 필드는 BigQuery 스키마에서 필수일 필요가 없습니다.

    • 주제 스키마에 없는 BigQuery 필드가 있으면 이러한 BigQuery 필드가 NULLABLE 모드에 있어야 합니다.

    • 주제 스키마에 BigQuery 스키마에 없는 추가 필드가 있고 이러한 필드를 생략할 수 있으면 알 수 없는 필드 삭제 옵션을 선택합니다.

    주제 스키마 사용 옵션을 선택하지 않는 경우에는 BigQuery 테이블에 BYTES, STRING 또는 JSON 유형의 data라는 열이 있는지 확인해야 합니다. Pub/Sub는 이 BigQuery 열에 메시지를 기록합니다.

매개변수
subscription_name

STRING

구독 이름입니다.
message_id

STRING

메시지 ID
publish_time

TIMESTAMP

메시지를 게시하는 시간입니다.
data

BYTES, STRING 또는 JSON

메시지 본문입니다.

data 필드는 주제 스키마 사용을 선택하지 않는 모든 대상 BigQuery 테이블에 필요합니다. 필드가 JSON 유형이면 메시지 본문은 유효한 JSON이어야 합니다.
attributes

STRING 또는 JSON

모든 메시지 속성을 포함하는 JSON 객체입니다. 또한 순서 키(있는 경우)를 포함하여 Pub/Sub 메시지에 속하는 추가 필드를 포함합니다.
  • 알 수 없는 필드 삭제. 이 옵션은 주제 스키마 사용 옵션과 함께 사용됩니다. 이 옵션을 사용하면 Pub/Sub가 주제 스키마에 있지만 BigQuery 스키마에 없는 필드를 삭제할 수 있습니다. 알 수 없는 필드 삭제를 설정하지 않으면 추가 필드가 있는 메시지가 BigQuery에 기록되지 않고 구독 백로그에 남게 됩니다. 구독이 결국 오류 상태가 됩니다.

모든 유형의 구독에 공통되는 속성 목록을 보고 BigQuery 구독을 만들려면 구독 만들기 및 사용을 참조하세요.

스키마 호환성

Pub/Sub와 BigQuery는 서로 다른 방법을 사용해서 스키마를 정의합니다. Pub/Sub 스키마는 Apache Avro 또는 프로토콜 버퍼 형식으로 정의되고 BigQuery 스키마는 ZetaSQL 형식으로 정의됩니다. 다음은 Pub/Sub 주제와 BigQuery 테이블 간의 스키마 호환성에 대한 중요한 정보입니다.

  • 부적절한 형식의 필드가 포함된 메시지는 BigQuery에 기록되지 않습니다.

  • BigQuery 스키마에서 INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT는 INT64의 별칭입니다. DECIMAL은 NUMERIC의 별칭이고 BIGDECIMAL은 BIGNUMERIC의 별칭입니다.

  • 주제 스키마의 유형이 string이고 BigQuery 테이블의 유형이 JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC 또는 BIGNUMERIC인 경우 Pub/Sub 메시지의 필드에 대한 모든 값은 BigQuery 데이터 유형에 지정된 형식을 준수해야 합니다.

  • 다음 표에 지정된 대로 일부 Avro 논리 유형이 지원됩니다. 나열되지 않은 논리 유형은 Avro 사양에 설명된 대로 주석이 추가된 동등한 Avro 유형과만 일치합니다.

다음은 서로 다른 스키마 형식의 매핑 모음입니다.

Avro - ZetaSQL

Avro 유형 ZetaSQL 유형
null Any NULLABLE
boolean BOOLEAN
int INT64, NUMERIC 또는 BIGNUMERIC
long INT64, 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 INT64

Protobuf - ZetaSQL

프로토콜 버퍼 유형 ZetaSQL 유형
double FLOAT64, NUMERIC 또는 BIGNUMERIC
float FLOAT64, NUMERIC 또는 BIGNUMERIC
int32 INT64, NUMERIC 또는 BIGNUMERIC
int64 INT64, NUMERIC 또는 BIGNUMERIC
uint32 INT64, NUMERIC 또는 BIGNUMERIC
uint64 NUMERIC 또는 BIGNUMERIC
sint32 INT64, NUMERIC 또는 BIGNUMERIC
sint64 INT64, NUMERIC 또는 BIGNUMERIC
fixed32 INT64, NUMERIC 또는 BIGNUMERIC
fixed64 NUMERIC 또는 BIGNUMERIC
sfixed32 INT64, NUMERIC 또는 BIGNUMERIC
sfixed64 INT64, NUMERIC 또는 BIGNUMERIC
bool BOOLEAN
string STRING, JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC, 또는 BIGNUMERIC
bytes BYTES, NUMERIC 또는 BIGNUMERIC
enum INT64
message RECORD/STRUCT
oneof 매핑할 수 없음
map<KeyType, ValueType> REPEATED RECORD<key KeyType, value ValueType>
enum INT64
repeated/array of Type REPEATED Type

Avro 논리 - ZetaSQL

Avro 논리 유형 ZetaSQL 유형
timestamp-micros TIMESTAMP
date DATE
time-micros TIME

Pub/Sub 서비스 계정 권한

BigQuery 구독을 만들려면 Pub/Sub 서비스 계정에 특정 BigQuery 테이블에 쓰기 권한과 테이블 메타데이터 읽기 권한이 있어야 합니다. 자세한 내용은 Pub/Sub 서비스 계정에 BigQuery 역할 할당을 참조하세요.

메시지 처리 실패

Pub/Sub 메시지를 BigQuery에 쓸 수 없으면 메시지를 확인할 수 없습니다. 이러한 전달할 수 없는 메시지를 전달하려면 BigQuery 구독에서 데드 레터 주제를 구성합니다.

할당량

리전별 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 가격 책정 페이지를 참조하세요.

다음 단계