Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Spanner Graph 알고리즘 실행

이 문서에서는 Spanner Graph에서 알고리즘을 실행하는 방법을 설명합니다.

Spanner Graph 알고리즘 쿼리 구조

Spanner Graph 알고리즘 쿼리의 구조는 다음과 같습니다.

EXPORT DATA OPTIONS (export_option_list) AS
GRAPH graph_name
match_clause
call_statement algorithm_name(common_input, algorithm_specific_input)
  YIELD algorithm_specific_output
RETURN results

export_option_list: 알고리즘 쿼리 결과를 유지하는 방법을 정의하는 옵션입니다. Cloud Storage 옵션 및 Spanner 옵션을 참고하세요.
graph_name: 그래프의 이름입니다.
match_clause: 알고리즘 입력 요소를 정의하는 선택적 MATCH 문입니다.
call_statement: match_clause 변수를 생략하고 전체 그래프에서 작업하려면 CALL 문을 사용합니다. match_clause 변수가 있고 작업 테이블에서 작업하려는 경우 CALL PER() 문을 사용합니다. 자세한 내용은 GQL CALL을 참고하세요.
algorithm_name: 실행할 알고리즘의 이름입니다. 사용 가능한 알고리즘은 Spanner Graph 알고리즘을 참고하세요.
common_input: 모든 알고리즘 쿼리에 공통적인 명명된 입력 매개변수입니다. 자세한 내용은 일반 알고리즘 입력 매개변수를 참조하세요.
algorithm_specific_input: 알고리즘의 명명된 입력 매개변수입니다. 자세한 내용은 Spanner Graph 알고리즘에 정의된 입력 파라미터를 참조하세요.
algorithm_specific_output: 알고리즘 호출의 출력입니다. 자세한 내용은 Spanner Graph 알고리즘에 정의된 출력과 CALL 문의 YIELD 절을 참고하세요.
results: 쿼리 결과에서 반환할 항목을 정의합니다.

쿼리는 결과를 유지하는 방법을 정의하는 EXPORT DATA 문과 알고리즘 쿼리 결과를 생성하는 GRAPH 절로 구성됩니다.

가장 간단한 형태의 그래프 절은 그래프를 식별하고, CALL 문을 사용하여 사전 정의된 출력을 생성하는 알고리즘을 호출한 다음, RETURN 문을 사용하여 알고리즘 출력에서 반환할 항목을 지정합니다.

필요한 경우 그래프 절은 지원되는 MATCH 문을 사용하여 관심 요소를 선택할 수 있습니다. 이 경우 PER () 절을 사용하여 MATCH 문에서 반환된 모든 행을 알고리즘의 입력으로 그룹화합니다. 알고리즘은 선택된 고유한 노드 및 에지 집합으로 구성된 논리적 하위 그래프에서 작동합니다.

쿼리가 데이터를 반환하지 않습니다. export_option_list 변수는 결과가 유지되는 방식을 결정합니다.

Spanner Graph 알고리즘 쿼리에 대한 자세한 내용은 이 문서의 다음 섹션을 참조하세요.

일반 알고리즘 입력 매개변수
알고리즘 출력 처리
예시 알고리즘 쿼리 실행

일반 알고리즘 입력 파라미터

이러한 이름이 지정된 입력 매개변수를 NAME => VALUE, ... 형식으로 지정합니다.

이름	값 유형	필수	기본값	설명
`node_labels`	`ARRAY`	아니요	(없음)	`CALL`가 사용되는 경우에만 지원됩니다. 알고리즘 입력에 포함할 노드 라벨 목록입니다. 지정된 경우 일치하는 라벨이 하나 이상 있는 노드만 포함됩니다.
`edge_labels`	`ARRAY`	아니요	(없음)	`CALL`가 사용되는 경우에만 지원됩니다. 알고리즘 입력에 포함할 가장자리 라벨 목록입니다. 지정된 경우 일치하는 라벨이 하나 이상 있는 에지만 포함됩니다.
`edge_weight_property`	`STRING`	아니요	(없음)	가중치가 포함된 가장자리 속성의 이름입니다. 정의되지 않은 경우 시스템은 모든 에지에 기본 가중치 1을 할당합니다. 속성 값 유형은 숫자여야 합니다.
`machine_category`	`STRING`	아니요	기본값	알고리즘 실행에 사용할 머신 카테고리입니다. 지원되는 값은 `default`, `large`입니다.
`fallback_compute_region`	`STRING`	아니요	(없음)	홈 리전에 용량 제약이 있는 경우 알고리즘 실행이 이루어지는 대체 리전입니다. Spanner 인스턴스의 홈 리전과 동일한 관할권에 있어야 합니다 (예: 홈 리전이 `us-east1`인 경우 `us-central1`).
`max_idle_time`	`STRING`	아니요	30분	알고리즘이 완료된 후 재사용을 위해 컴퓨팅 인스턴스가 활성 상태로 유지되어야 하는 기간을 지정합니다. 형식은 일련의 10진수이며 각각 `4m`, `1.5h`, `1h45m`와 같은 단위 서픽스가 포함됩니다. 유효한 시간 단위는 `ns`, `us` (또는 `µs`), `ms`, `s`, `m`, `h`입니다.

알고리즘 출력 처리

알고리즘 쿼리 결과를 검사하려면 먼저 결과를 유지해야 합니다. export_data_option를 사용하여 결과를 유지하는 방법을 설명합니다. 결과를 Cloud Storage에 유지하거나 쿼리가 시작된 동일한 Spanner 인스턴스로 다시 저장할 수 있습니다.

Cloud Storage에 결과 유지

이 옵션을 사용하려면 Google 관리 Spanner 서비스 계정 service-PROJECT_NUMBER@gcp-sa-spanner.에 스토리지 객체 관리자 (roles/storage.objectAdmin) 역할이 부여되었는지 확인합니다.

결과를 Cloud Storage에 유지할 때 다음 EXPORT DATA 옵션이 지원됩니다. NAME=VALUE, ... 형식으로 옵션을 지정하세요.

이름	값 유형	필수	설명
`uri`	`STRING`	예	내보내기의 대상 URI입니다(`gs://bucket/path/file` 형식). 많은 양의 데이터를 내보내는 경우 `uri`에서 와일드 카드를 사용하여 데이터를 여러 파일로 내보냅니다. 예를 들면 `gs://bucket/path/file_*.csv`입니다.
`format`	`STRING`	예	내보낸 데이터의 형식입니다. 지원되는 값은 `CSV`, `PARQUET`, `AVRO`입니다.
`header`	`BOOL`	아니요	`true`이면 시스템에서 각 데이터 파일의 첫 번째 행에 열 헤더를 출력합니다. 기본값은 `false`입니다. CSV에만 적용됩니다.
`overwrite`	`BOOL`	아니요	`true`인 경우 시스템은 동일한 URI로 기존 파일을 덮어씁니다. 그렇지 않고 동일한 URI를 가진 파일이 있으면 문에서 오류를 반환합니다. 기본값은 `false`입니다.
`field_delimiter`	`STRING`	아니요	필드를 구분하는 구분 기호입니다. 기본값: `,` (쉼표) CSV에만 적용됩니다.
`compression`	`STRING`	아니요	압축 형식을 지정합니다. 압축 형식을 지정하지 않으면 파일이 압축되지 않은 상태로 유지됩니다. `CSV`의 경우 지원되는 값은 `GZIP`입니다. `PARQUET`의 경우 지원되는 값은 `SNAPPY`, `GZIP`, `ZSTD`입니다. `AVRO`의 경우 지원되는 값은 `DEFLATE`, `SNAPPY`입니다.

RETURN 절의 열 이름은 Cloud Storage 출력 파일의 열 이름을 정의합니다.

데이터를 하나 이상의 파일로 내보내기

Spanner Graph 쿼리는 uri에서 단일 와일드 카드 연산자 (*)를 지원합니다. 와일드 카드는 파일 이름 구성요소에 나타날 수 있지만 버킷 이름, 폴더 이름 또는 파일 확장자에는 나타날 수 없습니다. 와일드 카드 연산자를 사용하면 결과 집합이 큰 경우 제공된 패턴을 기반으로 분할된 파일을 여러 개 만들도록 Spanner Graph에 지시합니다. 시스템은 와일드 카드 연산자를 숫자(0에서 시작)로 대체하고 왼쪽으로 12자리까지 채웁니다. 예를 들어 URI gs://my-bucket/file-*.csv는 gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv와 같은 파일을 만듭니다.

와일드 카드 없이 uri를 사용하면 결과는 gs://my-bucket/file.csv과 같은 단일 파일입니다.

데이터 유형

데이터를 내보낼 때 Spanner Graph 데이터 유형은 형식에 따라 다음과 같이 변환됩니다.

CSV

모든 데이터 유형은 문자열 표현으로 변환됩니다.

BOOL 값은 true 또는 false로 변환됩니다.
BYTES 값은 base64로 인코딩됩니다.
TIMESTAMP 값은 YYYY-MM-DD HH:MM:SS.ffffff UTC로 형식이 지정됩니다.
NULL 값은 빈 문자열로 표시됩니다.

중첩되거나 반복되는 데이터는 CSV 형식으로 내보낼 수 없습니다.

Avro

Spanner 데이터 유형	Avro 데이터 유형
`BOOL`	`BOOLEAN`
`INT64`	`LONG`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	논리 유형이 `DECIMAL(38,9)`인 `BYTES`
`STRING`	`STRING`
`BYTES`	`BYTES`
`TIMESTAMP`	`LONG`(에포크 이후 경과 시간(마이크로초))
`NULL`	`null`

Parquet

Spanner 데이터 유형	Parquet 데이터 유형
`BOOL`	`BOOLEAN`
`INT64`	`INT64`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTE_ARRAY`
`TIMESTAMP`	`TIMESTAMP_MICROS`
`NULL`	`null`

Spanner에 결과 저장

결과를 소스 Spanner 인스턴스에 다시 유지할 때 다음 EXPORT DATA 옵션이 지원됩니다. NAME=VALUE, ... 형식으로 옵션을 지정하세요.

이름	값 유형	필수	설명
`format`	`STRING`	예	내보낸 데이터의 형식입니다. `CLOUD_SPANNER`이어야 합니다.
`table`	`STRING`	예	결과를 쓸 대상 Spanner 테이블의 이름입니다. Spanner 인스턴스의 모든 테이블이 될 수 있습니다.
`write_mode`	`STRING`	예	사용할 쓰기 모드입니다. 지원되는 값은 다음과 같습니다. `update_ignore_all`: 대상 테이블의 기존 행을 업데이트합니다. `upsert_ignore_all`: 대상 테이블에 새 행을 삽입하거나 기존 행을 업데이트합니다. 두 모드 모두에서 Spanner는 제약 조건 위반을 일으키는 레코드 (예: 업데이트 시 누락된 키, 고유 색인 위반, 외래 키 제약 조건 위반)를 건너뜁니다. 하지만 제약 조건 위반이 아닌 오류 (예: 열 유형 불일치, NOT NULL 열의 누락된 값)로 인해 쓰기가 실패합니다.

요구사항

알고리즘 결과를 Spanner에 유지하는 경우 알고리즘 쿼리가 다음을 충족해야 합니다.

대상 테이블이 있어야 합니다.
열이 일치하는 유형으로 존재해야 함: RETURN 절에 지정된 모든 열 이름이 일치하는 데이터 유형으로 대상 테이블에 이미 존재해야 합니다. 필요한 경우 별칭을 사용하여 대상 테이블 열 이름과 일치시킵니다. 예를 들면 RETURN node.id AS person_id입니다.
모든 기본 키 열 포함: RETURN 절에는 대상 테이블의 모든 기본 키 열이 포함되어야 합니다.

쓰기 시맨틱

Spanner에 결과를 유지하는 것은 비트랜잭션 작업입니다. 행 수준 원자성을 제공합니다. 즉, 시스템은 동일한 행의 모든 열을 성공적으로 쓰거나 아무 열도 쓰지 않습니다. 최소 1회 시맨틱스를 따릅니다. 즉, 행을 여러 번 쓸 수 있습니다. 실행이 진행되는 동안 대상 테이블에서 읽으면 불완전한 결과가 발생할 수 있습니다.

전체 실행이 실패하면 시스템은 이미 커밋된 변경사항을 롤백하지 않습니다. 쓰기 프로세스는 재시도할 수 없는 첫 번째 오류에서 실패합니다. 쓰기 실패가 발생하면 GRAPH_OPERATION_EXECUTION_STATUS의 ERROR_MESSAGE는 실패한 행의 기본 키와 실패의 구체적인 이유를 나타냅니다.

시스템은 MEDIUM priority를 사용하여 알고리즘 결과를 Spanner Graph에 다시 씁니다.

예시 알고리즘 쿼리 실행

이 섹션에서는 테스트 인스턴스에서 실행할 수 있는 Spanner Graph 알고리즘 쿼리 예시를 보여줍니다. Spanner Graph에서 지원하는 알고리즘의 전체 목록은 Spanner Graph 알고리즘을 참고하세요.

시작하기 전에

Spanner Graph 알고리즘 쿼리 예시를 실행하려면 먼저 다음을 완료해야 합니다.

Spanner Graph 설정 및 쿼리에 따라 Spanner Graph를 만듭니다.
필수 권한이 있는지 확인합니다.
선택사항: 출력을 Spanner에 유지하는 경우 Spanner Graph 스키마를 보강합니다.

Account 테이블에 page_rank라는 새 열을 추가합니다. Spanner는 알고리즘 결과를 이 새 열에 기록합니다. 그런 다음 page_rank에 노드 속성으로 액세스할 수 있도록 그래프 정의를 새로고침합니다.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

라벨 필터를 사용하여 전체 그래프에서 알고리즘을 실행하고 결과를 Cloud Storage에 유지

이 예시에서는 PageRank 문을 실행하여 참여한 트랜스퍼를 기준으로 계정의 순위를 지정합니다. 쿼리 결과는 my-bucket-name/my-output.csv로 CSV 형식의 Cloud Storage 버킷에 유지됩니다.

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

이 쿼리가 성공적으로 완료되면 Cloud Storage에 두 개의 열 (id 및 page_rank)이 있는 CSV 파일이 표시됩니다.

`MATCH`로 정의된 하위 그래프에서 알고리즘을 실행하고 결과를 그래프에 유지합니다.

이 예시에서는 MATCH 패턴을 사용하여 모든 Account 노드와 금액이 500 미만인 Transfer 에지만 포함하는 논리적 하위 그래프를 동적으로 일치시킵니다. 이 논리적 하위 그래프는 PageRank 알고리즘의 입력입니다. Spanner는 알고리즘 결과를 Account 테이블에 다시 유지합니다.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

쿼리가 성공적으로 완료되면 다음 쿼리를 실행합니다.

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

다음과 비슷한 결과가 표시됩니다.

id	page_rank
20	0.49
16	0.46
7	0.05

알고리즘 실행 상태 확인

그래프 알고리즘 쿼리가 성공적으로 완료되면 0개 행과 Success 상태가 반환됩니다. 입력 그래프 크기와 특정 알고리즘 구성에 따라 알고리즘 실행이 완료되는 데 다소 시간이 걸릴 수 있습니다. SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS 테이블에서 그래프 알고리즘 쿼리의 진행 상황과 실행 상태를 확인할 수 있습니다. 이 테이블은 30일 동안 정보를 보관합니다.

스키마 `GRAPH_OPERATION_EXECUTION_STATUS`개

열 이름	유형	설명
`QUERY_ID`	`STRING`	그래프 알고리즘 쿼리의 ID입니다.
`QUERY_TEXT`	`STRING`	쿼리 문 텍스트입니다.
`START_TIMESTAMP`	`TIMESTAMP`	쿼리 실행이 시작된 시간입니다.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	상태가 마지막으로 업데이트된 시간입니다.
`PROGRESS`	`FLOAT64`	예상 완료율입니다. 값은 `0`과 `1` 사이입니다. `0`은 시작됨을, `1`은 완료됨을 의미합니다.
`STATUS`	`STRING`	현재 실행 상태입니다. 가능한 값에는 `PENDING`, `IN_PROGRESS`, `OK` 또는 오류 상태 코드(예: `CANCELLED`, `DEADLINE_EXCEEDED`, `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `RESOURCE_EXHAUSTED`, `UNAVAILABLE`, `UNKNOWN`)가 포함됩니다.
`ERROR_MESSAGE`	`STRING`	쿼리 실행이 실패한 경우의 오류 메시지입니다.

다음 샘플 쿼리는 아직 완료되지 않은 그래프 쿼리를 나열합니다.

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

알고리즘 실행 취소

진행 중인 그래프 알고리즘 쿼리를 취소하려면 SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS 테이블에서 query_id를 찾은 후 해당 query_id에 대해 cancel_query를 호출합니다.