Storage Write API를 사용한 데이터 스트리밍
이 문서에서는 BigQuery Storage Write API를 사용하여 BigQuery로 데이터를 스트리밍하는 방법을 설명합니다.
스트리밍 시나리오에서는 데이터가 연속적으로 도착하므로 지연 시간을 최소화하면서 읽기에 사용할 수 있습니다. 스트리밍 워크로드에 BigQuery Storage Write API를 사용할 때는 필요한 사항을 고려하세요.
- 애플리케이션에 1회 이상 실행되는 시맨틱스만 필요한 경우 기본 스트림을 사용합니다.
- 1회만 실행되는 시맨틱스가 필요한 경우 커밋 유형으로 스트림을 한 개 이상 만들고 스트림 오프셋을 사용하여 정확히 1회 쓰기를 보장합니다.
커밋 유형에서는 서버가 쓰기 요청을 확인하는 즉시 스트림에 작성된 데이터를 쿼리에 사용할 수 있습니다. 기본 스트림도 커밋 유형을 사용하지만 정확히 1회 보장을 제공하지 않습니다.
1회 이상 실행되는 시맨틱스에 기본 스트림 사용
애플리케이션이 대상 테이블에 중복된 레코드가 나타날 가능성을 허용하는 경우 스트리밍 시나리오에 기본 스트림을 사용하는 것이 좋습니다.
다음 코드는 기본 스트림에 데이터를 쓰는 방법을 보여줍니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
다중화 사용
기본 스트림에 대해서만 스트림 작성자 수준에서 다중화를 사용 설정합니다. Java에서 다중화를 사용 설정하려면 StreamWriter
또는 JsonStreamWriter
객체를 구성할 때 setEnableConnectionPool
메서드를 호출합니다.
// One possible way for constructing StreamWriter StreamWriter.newBuilder(streamName) .setWriterSchema(protoSchema) .setEnableConnectionPool(true) .build(); // One possible way for constructing JsonStreamWriter JsonStreamWriter.newBuilder(tableName, bigqueryClient) .setEnableConnectionPool(true) .build();
Go에서 다중화를 사용 설정하려면 연결 공유(다중화)를 참조하세요.
1회만 실행되는 시맨틱에 커밋 유형 사용
1회만 실행되는 쓰기 시맨틱스가 필요하면 커밋 유형으로 쓰기 스트림을 만듭니다. 커밋 유형에서는 클라이언트가 백엔드로부터 확인을 수신하는 즉시 쿼리에 레코드를 사용할 수 있습니다.
커밋 유형은 레코드 오프셋을 사용하여 스트림 내에서 정확히 한 번만 전달을 제공합니다. 애플리케이션은 레코드 오프셋을 사용하여 각 AppendRows
호출에서 다음 추가 오프셋을 지정합니다. 쓰기 작업은 오프셋 값이 다음 추가 오프셋과 일치할 때만 수행됩니다. 자세한 내용은 스트림 오프셋 관리를 통해 1회만 실행되는 시맨틱스 구현을 참조하세요.
오프셋을 제공하지 않으면 스트림의 현재 끝에 레코드가 추가됩니다. 이 경우 추가 요청으로 오류가 반환될 때 이를 다시 시도하면 레코드가 스트림에서 두 번 이상 표시되는 결과가 발생합니다.
커밋 유형을 사용하려면 다음 단계를 수행합니다.
자바
CreateWriteStream
을 호출하여 커밋 유형으로 스트림을 하나 이상 만듭니다.- 각 스트림에 대해 루프에서
AppendRows
를 호출하여 레코드 배치를 씁니다. - 스트림마다
FinalizeWriteStream
을 호출하여 스트림을 해제합니다. 이 메서드를 호출한 다음에는 스트림에 추가 행을 기록할 수 없습니다. 이 단계는 커밋 유형에서 선택사항이지만 활성 스트림의 한도를 초과하지 않도록 도와줍니다. 자세한 내용은 스트림 생성 속도 제한을 참조하세요.
Node.js
createWriteStreamFullResponse
을 호출하여 커밋 유형으로 스트림을 하나 이상 만듭니다.- 각 스트림에 대해 루프에서
appendRows
를 호출하여 레코드 배치를 씁니다. - 스트림마다
finalize
을 호출하여 스트림을 해제합니다. 이 메서드를 호출한 다음에는 스트림에 추가 행을 기록할 수 없습니다. 이 단계는 커밋 유형에서 선택사항이지만 활성 스트림의 한도를 초과하지 않도록 도와줍니다. 자세한 내용은 스트림 생성 속도 제한을 참조하세요.
스트리밍은 명시적으로 삭제할 수 없습니다. 스트림은 시스템 정의 TTL(수명)을 따릅니다.
- 스트림에 트래픽이 없으면 커밋된 스트림의 TTL이 3일입니다.
- 스트림에 트래픽이 없으면 기본적으로 버퍼링된 스트림의 TTL은 7일입니다.
다음은 커밋 유형을 사용하는 방법을 보여주는 코드입니다.
자바
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
BigQuery용 클라이언트 라이브러리 설치 및 사용 방법은 BigQuery 클라이언트 라이브러리를 참조하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.