BigQuery 데이터를 AlloyDB에 동기화

이 페이지에서는 BigQuery의 테이블을 PostgreSQL용 AlloyDB 인스턴스에 동기화하는 방법을 보여줍니다.

BigQuery의 분석 데이터를 AlloyDB에 동기화하면 데이터 레이크에 대한 지연 시간이 짧은 트랜잭션 액세스의 이점을 누릴 수 있는 운영 시스템을 구축할 수 있습니다. 데이터를 제자리에서 쿼리하는 외부 데이터 래퍼 (FDW)와 달리 동기화 테이블은 최대 성능을 위해 데이터를 AlloyDB 스토리지로 이동합니다.

AlloyDB는 BigQuery 데이터를 인스턴스로 이동하는 다음과 같은 방법을 제공합니다.

  • 일회성 동기화: 쓰기 가능하고 독립적인 BigQuery 테이블 사본을 만듭니다.

  • 주기적 동기화 (미러링): 6시간마다 또는 매일과 같이 일정에 따라 자동으로 새로고침되는 읽기 전용 로컬 테이블을 만듭니다.

성능 및 운영 고려사항

BigQuery 동기화 테이블을 사용하는 경우 다음 사항을 고려하세요.

  • 리소스 사용량: 데이터 이동은 CPU와 메모리를 사용합니다. 매우 큰 테이블의 경우 기본 트랜잭션 워크로드에 영향을 미치지 않도록 사용량이 많지 않은 시간대에 동기화를 예약하는 것이 좋습니다.
  • 데이터 공개 상태: 바꾸기 작업 중에 기존 대상 테이블이 미리 삭제되고 다시 생성됩니다. 가져오기 중에 쿼리는 처음에는 빈 테이블을 확인하고, 일괄 트랜잭션이 커밋되면 새로 가져온 데이터가 점진적으로 표시됩니다.

시작하기 전에

  1. alloydb_sync 확장 프로그램은 bigquery_fdw를 사용하여 BigQuery에 연결하므로 bigquery_fdw가 BigQuery 데이터 유형 및 열 매핑을 처리하는 방법을 숙지하세요.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. AlloyDB를 만들고 여기에 연결하는 데 필요한 Cloud API를 사용 설정합니다.

    API 사용 설정

  5. 프로젝트 확인 단계에서 다음을 클릭하여 변경할 프로젝트의 이름을 확인합니다.

  6. API 사용 설정 단계에서 사용 설정을 클릭하여 다음을 사용 설정합니다.

    • AlloyDB API
    • Compute Engine API
    • Cloud Resource Manager API
    • Service Networking API
    • BigQuery Storage API

    AlloyDB와 동일한 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Service Networking API가 필요합니다.

    다른 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Compute Engine API와 Cloud Resource Manager API가 필요합니다.

  7. 데이터를 동기화할 기존 BigQuery 테이블이 있는지 확인합니다. 자세한 내용은 BigQuery 테이블 만들기 및 사용을 참고하세요.

필요한 역할

AlloyDB 클러스터 서비스 계정에 BigQuery 데이터 세트 액세스 권한을 부여하려면 다음 권한이 필요합니다.

  • BigQuery 데이터 뷰어(roles/bigquery.dataViewer) 또는 bigquery.tables.get 및 bigquery.tables.getData 권한아 있는 커스텀 역할. 서비스 계정에 부여되면 이 역할은 테이블 또는 뷰에서 데이터와 메타데이터를 읽을 수 있는 권한을 제공합니다.
  • BigQuery 읽기 세션 사용자(roles/bigquery.readSessionUser) 또는 bigquery.readsessions.create 및 bigquery.readsessions.getData 권한이 있는 커스텀 역할. 읽기 세션을 만들고 사용할 수 있는 기능을 제공합니다.
  • BigQuery 작업 사용자(roles/bigquery.jobUser) 또는 bigquery.jobs.create 권한이 있는 커스텀 역할. 쿼리 작업을 비롯한 작업을 만들고 실행할 수 있는 기능을 제공합니다.

확장 프로그램 구성

BigQuery에서 테이블을 동기화하기 전에 필요한 확장 프로그램을 사용 설정하고 BigQuery에 대한 연결을 구성합니다. Google Cloud 콘솔을 사용하는 경우 AlloyDB에서 이러한 단계를 자동으로 실행합니다.

  1. 확장 프로그램을 만듭니다.

    1. 인스턴스에 psql 클라이언트 연결의 안내에 따라 psql 클라이언트를 사용하여 AlloyDB 인스턴스에 연결합니다.

    2. 다음 명령어를 실행합니다.

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;

  2. AlloyDB가 BigQuery로 인증되도록 하려면 사용자 매핑을 만드세요.

    CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;

    다음을 바꿉니다.

    • USER: BigQuery 테이블에 액세스하는 데이터베이스 사용자 이름 또는 IAM 사용자입니다.
    • BIGQUERY_SERVER_NAME: BigQuery 서버의 고유 식별자입니다. 지정된 데이터베이스에서 한 번 정의합니다. BIGQUERY_SERVER_NAME을 서버 이름으로 바꿀 수 있습니다.

일회성 내보내기를 위해 BigQuery 테이블 동기화

Google Cloud 콘솔을 사용하거나 psql을 사용하여 일회성 내보내기를 위해 BigQuery 테이블을 동기화할 수 있습니다.

Google Cloud 콘솔 사용

Google Cloud 콘솔을 사용하여 BigQuery 테이블을 AlloyDB에 동기화하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.

    BigQuery 페이지로 이동

  2. 왼쪽 창에서 탐색기를 클릭합니다.

    왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다.

  3. 탐색기 창에서 프로젝트를 펼치고 데이터 세트를 클릭한 다음 데이터 세트를 클릭합니다.

  4. 개요 > 테이블을 클릭한 다음 테이블을 선택합니다.

  5. 세부정보 창에서 업로드 내보내기 / 동기화 > AlloyDB (한 번 내보내기 또는 동기화)를 클릭합니다.

  6. 타겟 클러스터 선택에서 다음 옵션 중 하나를 선택합니다.

    • 기존 클러스터 사용을 선택하여 BigQuery 테이블을 기존 AlloyDB 클러스터로 내보냅니다. 그런 후 다음 작업을 수행합니다.

      1. 기본 AlloyDB 클러스터를 선택합니다.

      2. 대상 AlloyDB 데이터베이스를 선택합니다.

      3. 대상 AlloyDB 테이블의 스키마를 선택합니다.

      4. 대상 AlloyDB 테이블의 이름을 지정합니다.

      5. 동기화 빈도에서 한 번만을 선택하여 BigQuery 테이블의 사본을 만듭니다.

      6. 내보내기 설정을 클릭합니다.

      동기화 설정이 완료되면 제공된 SQL 문을 사용하여 가져오기 작업을 추적하고 가져온 테이블을 쿼리할 수 있습니다. 쿼리를 클릭하여 AlloyDB Studio의 가져온 테이블로 이동합니다.

    • 새 클러스터 만들기를 선택하여 BigQuery 테이블을 새 AlloyDB 클러스터로 내보냅니다. 그런 후 다음 작업을 수행합니다.

      1. 내보내기 설정을 클릭합니다.

      2. AlloyDB로 리디렉션 대화상자에서 리디렉션을 선택합니다.

      3. 클러스터 유형(무료 체험판 클러스터 또는 프로비저닝된 클러스터)을 선택합니다.

      4. 계속을 클릭합니다.

      5. 동기화 구성에서 기본 postgres 대상 AlloyDB 데이터베이스와 대상 AlloyDB 테이블의 기본 public 스키마를 선택하고 대상 AlloyDB 테이블의 이름을 지정합니다.

        동기화 빈도에서 한 번만을 선택하여 BigQuery 테이블의 사본을 만듭니다.

      6. 계속을 클릭합니다.

      7. 클러스터를 구성하세요. 각 필드에 대한 자세한 내용은 새 클러스터 및 기본 인스턴스 만들기를 참고하세요.

      8. 클러스터 만들기를 클릭합니다.

      동기화 설정이 완료되면 AlloyDB 스튜디오로 이동하여 가져온 테이블을 쿼리합니다.

psql을 사용하여 BigQuery 테이블을 일회성으로 동기화

BigQuery 데이터의 수정 가능한 사본을 만들려면 psql을 사용하여 alloydb_sync.import_bq_table 함수를 실행합니다.

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

다음을 바꿉니다.

  • PROJECT_ID: BigQuery 데이터 세트가 있는 프로젝트의 ID입니다.
  • DATASET_ID: 테이블의 BigQuery 데이터 세트 이름 이름이 4부분으로 구성된 Iceberg 테이블의 경우 Catalog.Namespace입니다.
  • TABLE_ID: BigQuery 테이블 또는 뷰의 이름입니다.
  • ALLOYDB_DESTINATION_TABLE_NAME: AlloyDB 데이터베이스에서 데이터를 생성하고 가져올 로컬 테이블의 이름입니다. 스키마 이름(예: public.local_sales)을 포함할 수 있습니다.
  • ON_EXISTS: 대상 테이블이 이미 있는 경우 사용할 전략입니다.
  • PRIMARY_KEY_COLUMN: 기본 키로 사용할 열 이름의 선택적 목록입니다.

예

다음 예시에서는 BigQuery 데이터 세트의 transactions라는 테이블을 public.local_sales라는 새 AlloyDB 테이블로 동기화하는 방법을 보여줍니다.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);
on_exists 매개변수

on_exists 매개변수는 AlloyDB에 대상 테이블이 이미 있는 경우 함수가 동기화를 처리하는 방식을 결정합니다.

  • error: 기본 옵션입니다. 대상 테이블이 이미 있는 경우 동기화를 중지합니다.
  • skip: 대상 테이블이 이미 있으면 동기화를 건너뜁니다.
  • replace: 기존 로컬 테이블을 BigQuery의 최신 데이터로 대체합니다.
기본 키 지원

선택사항인 primary_key 매개변수를 텍스트 배열로 제공하면 AlloyDB에서 지정된 열을 기본 키로 사용하여 테이블을 만듭니다.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

정기적으로 내보낼 BigQuery 테이블 동기화

Google Cloud 콘솔을 사용하거나 psql을 사용하여 주기적으로 내보낼 BigQuery 테이블을 동기화할 수 있습니다.

Google Cloud 콘솔 사용

Google Cloud 콘솔을 사용하여 BigQuery 테이블을 AlloyDB에 동기화하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.

    BigQuery 페이지로 이동

  2. 왼쪽 창에서 탐색기를 클릭합니다.

    강조 표시된 탐색기 창 버튼

    왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다.

  3. 탐색기 창에서 프로젝트를 펼치고 데이터 세트를 클릭한 다음 데이터 세트를 클릭합니다.

  4. 개요 > 테이블을 클릭한 다음 테이블을 선택합니다.

  5. 세부정보 창에서 업로드 내보내기 / 동기화 > AlloyDB (한 번 내보내기 또는 동기화)를 클릭합니다.

  6. 타겟 클러스터 선택에서 다음 옵션 중 하나를 선택합니다.

    • 기존 클러스터 사용을 선택하여 BigQuery 테이블을 기존 AlloyDB 클러스터로 내보냅니다. 그런 후 다음 작업을 수행합니다.

      1. 기본 AlloyDB 클러스터를 선택합니다.

      2. 대상 AlloyDB 데이터베이스를 선택합니다.

      3. 대상 AlloyDB 테이블의 스키마를 선택합니다.

      4. 대상 AlloyDB 테이블의 이름을 지정합니다.

      5. 동기화 빈도에서 BigQuery 테이블의 주기적 동기화를 만들 기간을 선택합니다(예: 매시간, 6시간마다).

      6. 내보내기 설정을 클릭합니다.

      동기화 설정이 완료되면 제공된 SQL 문을 사용하여 가져오기 작업을 추적하고 가져온 테이블을 쿼리할 수 있습니다. 쿼리를 클릭하여 AlloyDB Studio의 가져온 테이블로 이동합니다.

    • 새 클러스터 만들기를 선택하여 BigQuery 테이블을 새 AlloyDB 클러스터로 내보냅니다. 그런 후 다음 작업을 수행합니다.

      1. 내보내기 설정을 클릭합니다.

      2. AlloyDB로 리디렉션 대화상자에서 리디렉션을 선택합니다.

      3. 클러스터 유형(무료 체험판 클러스터 또는 프로비저닝된 클러스터)을 선택합니다.

      4. 계속을 클릭합니다.

      5. 동기화 구성에서 기본 postgres 대상 AlloyDB 데이터베이스와 대상 AlloyDB 테이블의 기본 public 스키마를 선택하고 대상 AlloyDB 테이블의 이름을 지정합니다.

        동기화 빈도에서 한 번만을 선택하여 BigQuery 테이블의 사본을 만듭니다.

      6. 계속을 클릭합니다.

      7. 클러스터를 구성하세요. 각 필드에 대한 자세한 내용은 새 클러스터 및 기본 인스턴스 만들기를 참고하세요.

      8. 클러스터 만들기를 클릭합니다.

      동기화 설정이 완료되면 AlloyDB 스튜디오로 이동하여 가져온 테이블을 쿼리합니다.

주기적 동기화 만들기

BigQuery 데이터와 동기화된 읽기 전용 테이블을 유지하려면 psql을 사용하여 alloydb_sync.create_bq_sync_table 함수를 실행하세요.

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

다음을 바꿉니다.

  • PROJECT_ID.DATASET_ID.TABLE_ID: 마침표로 구분된 프로젝트 ID, 데이터 세트 ID, 테이블 ID를 포함한 BigQuery 테이블 또는 뷰의 정규화된 이름입니다. 이름이 4부분으로 구성된 Iceberg 테이블의 경우 DATASET_ID이 Catalog.Namespace로 표시됩니다. 예를 들면 my-gcp-project.sales_data.transactions입니다.
  • ALLOYDB_DESTINATION_TABLE_NAME: 데이터를 생성하고 동기화할 AlloyDB 데이터베이스의 로컬 테이블 이름입니다.
  • REFRESH_INTERVAL: AlloyDB가 BigQuery의 데이터를 주기적으로 새로고침하는 간격입니다(예: 12 hours).
  • ON_EXISTS: 대상 테이블이 이미 있는 경우 사용할 전략입니다.
  • PRIMARY_KEY_COLUMN: 기본 키로 사용할 열 이름의 선택적 목록입니다.

예

다음 예에서는 12시간마다 새로고침되는 고객 프로필 미러를 만드는 방법을 보여줍니다.

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

작업 모니터링 및 관리

동기화를 시작한 후 진행 상황을 모니터링하고 작업을 관리할 수 있습니다.

작업 상태 확인

대규모 동기화에는 시간이 걸릴 수 있습니다. job_status 뷰를 쿼리하여 처리된 레코드와 예상 완료 시간 등 진행 상황을 모니터링할 수 있습니다.

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

예를 들어 작업을 취소하려면 다음 명령어를 실행합니다.

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

동기화 작업 중지 및 삭제

BigQuery 테이블의 미러링을 중지하고 로컬 테이블을 삭제하려면 alloydb_sync.delete_bq_sync_table 함수를 사용하세요.

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

데이터 유형 매핑

alloydb_sync 확장 프로그램을 사용하여 BigQuery에서 AlloyDB로 데이터를 동기화하거나 가져올 때 AlloyDB는 BigQuery 데이터 유형을 대상 테이블의 해당 PostgreSQL 데이터 유형에 매핑합니다.

소스 BigQuery 테이블 열이 지원되는 다음 데이터 유형을 사용하는지 확인합니다.

다음 표에는 BigQuery와 AlloyDB 간의 데이터 유형 매핑이 나와 있습니다.

BigQuery 테이블 데이터 유형 권장되는 PostgreSQL 외부 테이블 데이터 유형

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

자세한 내용은 PostGIS_Geography를 참고하세요.

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N는 벡터의 차원입니다. 세션에서 bigquery_fdw.enable_vector_downcasting 플래그를 설정해야 합니다. AlloyDB의 VECTOR 유형은 float4 유형을 사용하므로 이 변환에서 정밀도가 손실될 수 있습니다.

자세한 내용은 pgvector 확장 프로그램을 참고하세요.

제한사항

BigQuery에서 테이블을 동기화할 때는 다음 제한사항이 적용됩니다.

  • 이 기능은 PostgreSQL 버전 18에서만 지원됩니다.
  • alloydb_sync 확장 프로그램을 DROP하는 경우 확장 프로그램을 다시 만들기 전에 인스턴스를 다시 시작해야 합니다.
  • 동기화는 트랜잭션 내에서 실행됩니다. 가져오기 작업이 중단되거나 실패하면 시스템에서 가져온 데이터를 롤백합니다.
  • 두 사용자가 동일한 대상 테이블로 동시에 동기화 작업을 시작하면 테이블이 서로 덮어쓰여질 수 있습니다.
  • 새로 등록된 동기화 테이블의 초기 백그라운드 가져오기 중에 중단이 발생하면 다음 예약된 새로고침 간격까지 테이블이 불완전한 상태로 유지됩니다. 이 문제를 해결하려면 alloydb_sync.delete_bq_sync_table() 함수를 사용하여 동기화 테이블을 삭제하고 다시 만드세요.
  • ARRAY, BYTES, VECTOR, GEOGRAPHY과 같은 복잡한 BigQuery 유형은 동기화에 지원되지 않습니다. 전체 목록은 지원되는 BigQuery 데이터 유형 및 열 매핑을 참고하세요.
  • 복제된 테이블을 수동으로 삭제하지 마세요. alloydb_sync.delete_bq_sync_table() API 함수를 사용하여 테이블을 안전하게 삭제하고 새로고침합니다.
  • alloydb_sync 확장 프로그램을 사용하는 데이터베이스를 삭제하려면 DROP DATABASE ... WITH (FORCE)을 사용해야 합니다.
  • 가져오기가 실행되는 동안 Postgres 데이터베이스가 비정상 종료되면 메타데이터가 RUNNING 상태로 멈춰 향후 가져오기가 차단될 수 있습니다. UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING';를 수동으로 실행하여 차단을 해제해야 합니다.

가격 책정

BigQuery에서 AlloyDB로 데이터를 동기화하면 BigQuery 스트리밍 읽기 (Storage Read API) 가격 책정에 따라 요금이 청구됩니다.

데이터를 내보낸 후 AlloyDB에 데이터를 저장하는 데는 요금이 청구됩니다. 자세한 내용은 PostgreSQL용 AlloyDB 가격 책정을 참고하세요.

다음 단계