Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Spanner Graph 알고리즘 실행

참고: us-east1 리전의 Spanner 인스턴스에서 그래프 알고리즘을 실행하는 경우 알고리즘 입력 매개변수에서 us-east1-b, us-east1-c 또는 us-east1-d 중 하나를 zone로 지정해야 합니다. 다른 모든 지역에서는 영역을 지정하지 않아도 됩니다.

이 문서에서는 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 CLAUSE로 구성됩니다.

가장 간단한 형태에서 그래프 절은 그래프를 식별하고, 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`입니다.
`zone`	`STRING`	아니요	(없음)	알고리즘 실행이 이루어지는 영역입니다. 쿼리가 수신된 리전의 영역 중 하나여야 합니다.
`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.iam.gserviceaccount.com에 스토리지 객체 관리자 (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 그래프 데이터 유형은 형식에 따라 다음과 같이 변환됩니다.

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

전체 실행이 실패하면 시스템은 이미 커밋된 변경사항을 롤백하지 않습니다. 쓰기 프로세스는 재시도할 수 없는 첫 번째 오류에서 실패합니다. 쓰기 실패가 발생하면 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를 실행하여 참여하는 Transactions에 따라 Account의 순위를 지정하고 결과를 CSV 형식으로 Cloud Storage에 'my-bucket-name/my-output.csv'로 유지합니다.

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`	`FLOAT`	예상 완료 비율입니다. 값은 `0`과 `1` 사이입니다. 여기서 `0`은 시작됨을, `1`은 완료됨을 의미합니다.
`STATUS`	`STRING`	실행의 현재 상태입니다. 가능한 값은 `PENDING`, `IN_PROGRESS`, `OK`, `CANCELLED`, `DEADLINE_EXCEEDED`, `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를 호출합니다.