데이터 세트는 BigQuery 테이블에 대한 액세스를 구성하고 제어하는 데 사용되는 최상위 컨테이너입니다.
Datastream을 사용하여 BigQuery 대상의 데이터 세트를 구성할 때 다음 옵션 중 하나를 선택할 수 있습니다.
각 스키마를 위한 데이터 세트: 데이터 세트는 지정된 BigQuery 위치에서 소스의 스키마 이름을 기반으로 Datastream에 의해 선택되거나 자동으로 생성됩니다. 따라서 소스의 각 스키마에는 BigQuery의 해당 데이터 세트가 있습니다.
예를 들어 MySQL 소스가 있고 이 소스에 mydb 데이터베이스가 있고 데이터베이스 내에 employees 테이블이 있으면 Datastream이 BigQuery에서 mydb 데이터 세트 및 employees 테이블을 만듭니다.
이 옵션을 선택하면 Datastream이 스트림이 포함된 프로젝트에 데이터 세트를 만듭니다. 스트림과 동일한 리전에서 데이터 세트를 만들 필요는 없지만 비용 및 성능 최적화를 위해 스트림의 모든 리소스와 데이터 세트를 동일한 리전에 유지하는 것이 좋습니다.
모든 스키마를 위한 단일 데이터 세트: 스트림의 BigQuery 데이터 세트를 선택합니다. Datastream이 모든 데이터를 이 데이터 세트로 스트리밍합니다. Datastream은 선택한 데이터 세트에 대해 모든 테이블을 <schema>_<table>로 만듭니다.
예를 들어 MySQL 소스가 있고 이 소스에 mydb 데이터베이스가 있고 데이터베이스 내에 employees 테이블이 있으면 Datastream이 선택한 데이터 세트에서 mydb_employees 테이블을 만듭니다.
쓰기 모드 구성
BigQuery에 데이터를 쓰는 방법을 정의할 때는 두 가지 모드를 사용할 수 있습니다.
병합: 기본 쓰기 모드입니다. 선택하면 BigQuery에 소스 데이터베이스에 데이터가 저장된 방식이 반영됩니다. 즉, Datastream은 데이터의 모든 변경사항을 BigQuery에 쓰고 BigQuery는 변경사항을 기존 데이터와 통합하여 소스 테이블의 복제본인 최종 테이블을 만듭니다. 병합 모드에서는 변경 이벤트의 이전 기록이 보관되지 않습니다. 예를 들어 행을 삽입한 후 업데이트하면 BigQuery는 업데이트된 데이터만 유지합니다. 그런 다음 소스 테이블에서 행을 삭제하면 BigQuery에서 해당 행의 레코드를 더 이상 보관하지 않습니다.
추가 전용: 추가 전용 쓰기 모드를 통해 BigQuery에 데이터를 변경 내역으로 추가할 수 있습니다 (INSERT, UPDATE-INSERT, UPDATE-DELETE, DELETE 이벤트). 데이터의 이전 상태를 유지해야 하는 경우 이 모드를 사용합니다.
추가 전용 쓰기 모드를 더 잘 이해하려면 다음 시나리오를 고려하세요.
초기 백필: 초기 백필 후에는 모든 이벤트가 동일한 타임스탬프, 범용 고유 식별자(UUID), 변경 시퀀스 넘버가 있는 INSERT 유형 이벤트로 BigQuery에 기록됩니다.
기본 키 업데이트: 기본 키가 변경되면 두 개의 행이 BigQuery에 기록됩니다.
원래 기본 키가 있는 UPDATE-DELETE 행
새 기본 키가 있는 UPDATE-INSERT 행
행 업데이트: 행을 업데이트하면 단일 UPDATE-INSERT 행이 BigQuery에 기록됩니다.
행 삭제: 행을 삭제하면 단일 DELETE 행이 BigQuery에 기록됩니다.
데이터 비활성 한도 지정
BigQuery는 구성된 데이터 비활성 한도에 따라 지속적으로 또는 쿼리 실행 시 백그라운드에서 소스 수정사항을 적용합니다. Datastream이 BigQuery에서 새 테이블을 만들 때 스트림의 현재 데이터 비활성 한도 값에 따라 테이블의 max_staleness 옵션이 설정됩니다.
max_staleness 옵션과 함께 BigQuery 테이블을 사용하는 방법에 대한 자세한 내용은 테이블 비활성을 참조하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Configure a BigQuery destination\n\nThis page describes how to configure Datastream so that you can write\ndata to BigQuery datasets.\n\nRequired permissions\n--------------------\n\nDatastream uses the BigQuery built-in support for change data\ncapture (CDC) updates. Datastream updates the BigQuery tables\nby processing and applying streamed changes using the BigQuery Storage Write API.\n\nThe permissions required for using the API and ingesting data to\nBigQuery are granted to the\n[Datastream Service Agent](/iam/docs/roles-permissions/datastream#datastream.serviceAgent)\nrole.\n\nConfigure BigQuery as a destination\n-----------------------------------\n\nTo configure Datastream for streaming to BigQuery, perform the\nfollowing steps:\n\n1. Make sure that the BigQuery API is enabled in your Google Cloud project.\n2. If you want to use the **Single dataset for all schemas** option, [create a dataset in BigQuery](/bigquery/docs/datasets#create-dataset).\n3. [Configure the destination dataset for your stream](#configure-datasets).\n4. [Configure write mode](#configure-write-mode).\n5. [Specify the maximum data staleness limit](#specify-staleness) for your stream.\n\n### Configure the destination datasets\n\nDatasets are top-level containers that are used to organize and control access\nto your BigQuery tables.\n\nWhen you configure datasets for the BigQuery destination using\nDatastream, you can select one of the following options:\n\n- **Dataset for each schema** : The dataset is selected or automatically created by Datastream in the [BigQuery location](/bigquery/docs/locations) specified, based on the schema name of the source. As a result, each schema in the source has a corresponding dataset in BigQuery.\n For example, if you have a MySQL source, and this source has a `mydb`\n database and an `employees` table within the database, then\n Datastream creates the `mydb` dataset and `employees` table in\n BigQuery.\n\n If you select this option, then Datastream creates datasets in the project that contains the stream. Although you don't need to create the datasets in the same region as your stream, we recommend to keep all resources for the stream, as well as datasets, in the same region for cost and performance optimization.\n | **Note:** The **Dataset for each schema** option isn't supported for Salesforce sources ([Preview](/products#product-launch-stages)).\n- **Single dataset for all schemas** : You select a BigQuery\n dataset for the stream. Datastream streams all data into this\n dataset. For the dataset that you select, Datastream creates all\n tables as `\u003cschema\u003e_\u003ctable\u003e`.\n\n For example, if you have a MySQL source, and this source has a `mydb`\n database and an `employees` table within the database, then\n Datastream creates the `mydb_employees` table in the dataset that\n you select.\n | **Note:** If your source is Salesforce ([Preview](/products#product-launch-stages)), Datastream uses the customer domain as the dataset name.\n\n### Configure write mode\n\nThere are two modes you can use to define how you want your data written to\nBigQuery:\n\n- **Merge**: This is the default write mode. When selected, BigQuery reflects the way your data is stored in the source database. This means that Datastream writes all changes to your data to BigQuery, and BigQuery then consolidates the changes with existing data, thus creating final tables that are replicas of the source tables. With merge mode, no historical record of the change events is kept. For example, if you insert and then update a row, BigQuery only keeps the updated data. If you then delete the row from the source table, BigQuery no longer keeps any record of that row.\n\n | **Note:** Merge mode is only applicable for tables with primary keys. Tables without primary keys are append-only.\n- **Append-only** : The append-only write mode lets you add data to BigQuery as a stream of changes (`INSERT`, `UPDATE-INSERT`, `UPDATE-DELETE` and `DELETE` events). Use this mode when you need to retain the historical state of your data.\n To get a better understanding of the append-only write mode, consider the following scenarios:\n\n - *Initial backfill* : after the initial backfill, all events are written to BigQuery as `INSERT` type events, with the same timestamp, universally unique identifier (UUID), and change sequence number.\n - *Primary key update* : when a primary key changes, two rows are written to BigQuery:\n - An `UPDATE-DELETE` row with the original primary key\n - An `UPDATE-INSERT` row with the new primary key\n - *Row update* : when you update a row, a single `UPDATE-INSERT` row is written to BigQuery\n - *Row deletion* : when you delete a row, a single `DELETE` row is written to BigQuery\n\n### Specify data staleness limit\n\nBigQuery applies source modifications in the background on an ongoing basis, or at query run time, according to the configured data staleness limit. When Datastream creates a new table in BigQuery, the table's `max_staleness` option is set according to the current data staleness limit value for the stream.\n\nFor more information about using BigQuery tables with the `max_staleness` option, see [Table staleness](/bigquery/docs/change-data-capture#manage_table_staleness)."]]
