Cloud Spanner 통합 쿼리

이 페이지에서는 통합 쿼리를 사용하여 BigQuery에서 Cloud Spanner의 데이터를 쿼리하는 방법을 설명합니다.

개요

BigQuery Spanner 통합을 사용하여 BigQuery는 데이터를 복사하거나 이동하지 않고도 Spanner에 있는 데이터를 실시간으로 쿼리할 수 있습니다.

처음 1회 설정 이후 SQL EXTERNAL_QUERY 함수를 사용하여 쿼리를 작성할 수 있습니다.

권한

Spanner 데이터베이스에 대한 연결을 만들려면 연결 작업에 설명된 권한이 있어야 합니다.

Spanner 데이터베이스를 쿼리하려면 다음 권한이 있어야 합니다.

• spanner.databases.select
• spanner.instances.get
• spanner.sessions.create

병렬 읽기를 수행하려면 spanner.databases.partitionQuery 권한이 있어야 합니다.

시작하기 전에

BigQuery 연결 서비스 사용 설정

1. API 라이브러리에서 BigQuery connection API 페이지를 엽니다.
2. 드롭다운 메뉴에서 외부 데이터 소스가 포함된 프로젝트를 선택합니다.

3. 사용 설정 버튼을 클릭합니다.

   BigQuery connection API

Spanner 데이터베이스 연결 설정

BigQuery Connection API가 사용 설정되면 Spanner 데이터베이스에 대한 연결을 만듭니다.

Console

1. 연결 리소스를 만들려면 Console에서 BigQuery 페이지로 이동합니다.

   BigQuery 페이지로 이동

2. 데이터 추가 메뉴에서 외부 데이터 소스를 선택합니다.

   

3. 외부 데이터 소스 창에서 다음 정보를 입력합니다.

   • 연결 유형에 Spanner를 선택합니다.
   • 연결 ID에는 연결 리소스의 식별자를 입력합니다. 문자, 숫자, 밑줄을 사용할 수 있습니다.
   • 연결 위치에서 외부 데이터 소스 리전과 호환되는 BigQuery 위치(또는 리전)를 선택합니다.
   • 선택사항: 별칭에 사용자 친화적인 연결 이름(예: My connection resource)을 입력합니다. 사용자 친화적인 이름으로 나중에 수정해야 하는 경우 연결 리소스를 식별하는 데 도움이 되는 모든 값을 사용할 수 있습니다.
   • 선택사항: 설명에 이 연결 리소스에 대한 설명을 입력합니다.
   • 데이터베이스 이름에 Spanner 이름을 "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" 형식으로 입력합니다.
   • 선택사항: 병렬 읽기를 수행하려면 동시에 데이터 읽기를 선택합니다. 자세한 내용은 동시에 데이터 읽기를 참조하세요.

4. 연결 만들기를 클릭합니다.

bq

연결을 만들려면 --connection 플래그와 함께 bq mk 명령어를 사용합니다.

bq mk --connection \
  --connection_type=CLOUD_SPANNER \
  --properties='PROPERTIES' \
  --location=LOCATION \
  --display_name='FRIENDLY_NAME' \
  --description 'DESCRIPTION' \
  CONNECTION_ID

다음을 바꿉니다.

• PROPERTIES: 다음 필드가 있는 JSON 객체입니다.

  • "database": 연결에 사용되는 Spanner 데이터베이스입니다. "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" 형식의 문자열로 지정합니다.
  • "use_parallelism": 선택사항. true인 경우 이 연결은 병렬 읽기를 수행합니다. 기본값은 false입니다. 자세한 내용은 동시에 데이터 읽기를 참조하세요.

• LOCATION: 외부 데이터 소스 리전과 호환되는 BigQuery 위치입니다.

• FRIENDLY_NAME: 선택사항. 사용자 친화적인 연결 이름입니다.

• DESCRIPTION: 선택사항. 이 연결에 대한 설명입니다.

• CONNECTION_ID: 선택사항. 연결 리소스의 식별자입니다. 연결 ID에는 문자, 숫자, 밑줄이 포함될 수 있습니다. 연결 ID를 제공하지 않으면 BigQuery에서 자동으로 고유 ID를 생성합니다.

다음 예시에서는 my_connection_id라는 새 연결 리소스를 만듭니다.

bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

BigQuery 연결 API에서 ConnectionService 서비스 내의 CreateConnection 메서드를 호출하여 연결 리소스를 만듭니다.

Spanner에서 데이터 쿼리

BigQuery 표준 SQL 쿼리에서 통합 쿼리를 Spanner로 보내려면 EXTERNAL_QUERY 함수를 사용합니다.

데이터베이스의 지정된 언어에 따라 Google 표준 SQL 또는 PostgreSQL로 Spanner 쿼리를 작성합니다.

다음 예시에서는 orders라는 Spanner 데이터베이스에 통합 쿼리를 수행하고 결과를 mydataset.customers라는 BigQuery 테이블과 조인합니다.

SELECT c.customer_id, c.name, rq.first_order_date
FROM mydataset.customers AS c
LEFT OUTER JOIN EXTERNAL_QUERY(
  'my-project.us.example-db',
  '''SELECT customer_id, MIN(order_date) AS first_order_date
  FROM orders
  GROUP BY customer_id''') AS rq
  ON rq.customer_id = c.customer_id
GROUP BY c.customer_id, c.name, rq.first_order_date;

동시에 데이터 읽기

Spanner에서는 특정 쿼리를 더 작은 부분이나 파티션 여러 개로 나누고 파티션을 동시에 가져올 수 있습니다. 자세한 내용은 Spanner 문서의 동시에 데이터 읽기를 참조하세요.

통합 쿼리에서 병렬 읽기를 사용 설정하려면 연결 리소스를 만들 때 이 설정을 구성합니다. 이 옵션은 SQL 쿼리를 더 작은 파티션으로 나누고 각 파티션을 동시에 가져옵니다. 하지만 이 옵션은 실행 계획의 첫 번째 연산자가 분산 통합 연산자인 쿼리로 제한됩니다. 다른 쿼리는 오류를 반환합니다. Spanner 쿼리의 쿼리 실행 계획을 보려면 Cloud Spanner의 쿼리 실행 방법 이해를 참조하세요.

쿼리 실행 우선순위 관리

아래 표시된 것처럼 query_execution_priority 옵션을 지정해서 우선순위(high, medium, low)를 개별 쿼리에 할당할 수 있습니다.

SELECT *
FROM EXTERNAL_QUERY(
  'my-project.us.example-db',
  '''SELECT customer_id, MIN(order_date) AS first_order_date
  FROM orders
  GROUP BY customer_id''',
  '{"query_execution_priority":"high"}');

기본 우선순위는 medium입니다.

우선순위가 high인 쿼리는 트랜잭션 트래픽과 경합합니다. 우선순위가 low인 쿼리는 최대한 노력이 지원되며 예약된 백업과 같은 백그라운드 로드에 의해 선점될 수 있습니다.

주의: 우선순위가 low인 쿼리는 BigQuery의 제한 시간 내에 완료되지 않을 수 있는 백업 작업과 같은 쿼리 아래로 내려갈 수 있습니다.

Spanner 테이블 스키마 보기

EXTERNAL_QUERY 함수를 사용하여 information_schema 뷰를 쿼리해 데이터베이스의 모든 테이블 나열 또는 테이블 스키마 표시와 같은 데이터베이스 메타데이터에 액세스할 수 있습니다. 다음 예시에서는 MyTable 테이블의 열에 대한 정보를 반환합니다.

Google SQL 데이터베이스

SELECT *
FROM EXTERNAL_QUERY(
    'my-project.us.example-db',
    '''SELECT t.column_name, t.spanner_type, t.is_nullable
      FROM information_schema.columns AS t
      WHERE
        t.table_catalog = ''
        AND t.table_schema = ''
        AND t.table_name = 'MyTable'
      ORDER BY t.ordinal_position
    ''');

PostgreSQL 데이터베이스

SELECT * from EXTERNAL_QUERY(
  'my-project.us.postgresql.example-db',
  '''SELECT t.column_name, t.data_type, t.is_nullable
    FROM information_schema.columns AS t
    WHERE
      t.table_schema = 'public' and t.table_name='MyTable'
    ORDER BY t.ordinal_position
  ''');

자세한 내용은 Spanner 문서의 다음 정보 스키마 참조 문서를 확인하세요.

• Google 표준 SQL 정보 스키마
• PostgreSQL 정보 스키마

데이터 유형 매핑

Spanner 통합 쿼리를 실행하면 Spanner의 데이터는 BigQuery 표준 SQL 유형으로 변환됩니다.

Spanner Google 표준 SQL 유형	Spanner PostgreSQL 유형	BigQuery 유형
ARRAY	-	ARRAY
BOOL	bool	BOOL
BYTES	bytea	BYTES
DATE	date	DATE
FLOAT64	float8	FLOAT64
INT64	bigint	INT64
NUMERIC	numeric*	NUMERIC
STRING	varchar	STRING
STRUCT	-	Spanner 통합 쿼리에는 지원되지 않습니다.
TIMESTAMP	timestamptz	TIMESTAMP(나노초 잘림)

* 정밀도가 BigQuery에서 지원하는 정밀도보다 큰 PostgreSQL 숫자 값은 반올림됩니다. 값이 최댓값보다 크면 Invalid NUMERIC value 오류가 발생합니다.

외부 쿼리에 통합 쿼리에 지원되지 않는 데이터 유형이 포함되면 쿼리가 즉시 실패합니다. 지원되지 않는 데이터 유형을 지원되는 데이터 유형으로 변환할 수 있습니다.

지원되는 리전

통합 쿼리는 Spanner와 BigQuery를 모두 지원하는 위치에서만 지원됩니다.

• 지원되는 Spanner 위치 목록은 리전 구성을 참조하세요.
• 지원되는 BigQuery 위치 목록은 데이터 세트 위치를 참조하세요.

다음과 같은 두 가지 유형의 위치가 있습니다.

• 리전은 특정한 지리적 장소(예: 런던)입니다.

• 멀티 리전은 두 개 이상의 지리적 장소를 포함하는 넓은 지리적 지역(예: 미국)입니다.

다음 규칙에 따라 리전 간에 연결을 만들고 통합 쿼리를 실행할 수 있습니다.

멀티 리전

BigQuery 멀티 리전은 동일한 대규모 지역(미국, EU)의 모든 데이터 소스 리전을 쿼리할 수 있습니다. 예를 들면 다음과 같습니다.

• BigQuery US 멀티 리전은 미국 리전 내 모든 단일 리전(예: us-central1, us-east4, us-west2 등)을 쿼리할 수 있습니다.
• BigQuery EU 멀티 리전은 europe-north1, europe-west3 등 유럽 연합의 회원국 내에 있는 모든 단일 리전을 쿼리할 수 있습니다.
• 쿼리에 사용된 연결이 쿼리 위치와 동일한 위치에 있어야 합니다. 예를 들어 US 멀티 리전에서 실행되는 쿼리는 US 멀티 리전에 있는 연결을 참조해야 합니다.

쿼리 처리 위치는 멀티 리전 위치(US 또는 EU)입니다.

단일 리전

BigQuery 단일 리전은 동일한 리전의 리소스만 쿼리할 수 있습니다. 예를 들면 다음과 같습니다.

• BigQuery 단일 리전 us-east4는 us-east4의 Spanner만 쿼리할 수 있습니다.

이 예시에서 쿼리 처리 위치는 BigQuery 단일 리전입니다.

주의: 리전 간 통합 쿼리는 지원되지만 성능은 근접도에 따라 달라집니다. 예를 들어 BigQuery US 멀티 리전은 us-central1 리전과 가까우므로 이 두 리전 간의 통합 쿼리가 빠르게 실행됩니다. 그러나 같은 쿼리를 BigQuery US에서 Spanner us-east4로 실행하는 경우 성능이 훨씬 더 낮을 수 있습니다.

제한사항

Spanner 통합 쿼리에는 다음과 같은 제한사항이 적용됩니다.

• 성능 통합 쿼리는 BigQuery 스토리지만 쿼리하는 것만큼 빠르지 않을 수 있습니다. BigQuery는 소스 데이터베이스에서 외부 쿼리를 실행할 때까지 기다려야 하며 임시로 외부 데이터 소스에서 BigQuery로 데이터를 이동해야 합니다. 또한 소스 데이터베이스는 복잡한 분석 쿼리에 맞게 최적화되지 않을 수 있습니다.

• 통합 쿼리는 읽기 전용입니다. 소스 데이터베이스에서 실행되는 외부 쿼리는 읽기 전용이어야 합니다. 따라서 DML 또는 DDL 문은 지원되지 않습니다.

• 지원되지 않는 데이터 유형 외부 쿼리에 BigQuery에서 지원되지 않는 데이터 유형이 포함되면 쿼리는 즉시 실패합니다. 지원되지 않는 데이터 유형을 지원되는 다른 지원되는 데이터 유형으로 변환할 수 있습니다.

문제 해결하기

이 섹션은 통합 쿼리를 Spanner에 전송할 때 발생할 수 있는 문제를 해결하는 데 도움이 됩니다.

문제: 쿼리를 루트로 분할할 수 없습니다.

해결 방법: 연결을 동시에 구성하여 데이터를 읽을 경우 쿼리 실행 계획의 첫 번째 연산자가 분산 통합이어야 합니다. 이 오류를 해결하려면 쿼리 실행 계획을 보고 쿼리를 다시 작성합니다. 자세한 내용은 Cloud Spanner의 쿼리 실행 방법 이해를 참조하세요.

문제: 기한이 지났습니다.

해결 방법: 데이터 병렬로 읽기 옵션을 선택하여 루트 분할이 가능한 쿼리를 다시 작성합니다. 자세한 내용은 Cloud Spanner의 쿼리 실행 방법 이해를 참조하세요.