AlloyDB에서 OpenSearch 데이터에 액세스

AlloyDB의 외부 검색 통합을 사용하여 OpenSearch에 저장된 데이터에 액세스하고 검색할 수 있습니다. 이 통합을 사용하면 데이터를 이동하거나 복사하지 않고도 OpenSearch 색인을 AlloyDB의 관계형 테이블과 조인할 수 있습니다.

시작하기 전에

시작하기 전에 다음 작업을 완료했는지 확인하세요.

Secret Manager에 OpenSearch 사용자 인증 정보 저장

AlloyDB는 Secret Manager에서 OpenSearch 사용자 인증 정보를 저장하고 읽습니다. Secret Manager 사용 방법에 대한 자세한 내용은 Secret Manager를 사용하여 보안 비밀 만들기 및 액세스를 참고하세요.

AlloyDB 서비스 계정에 Secret Manager에서 보안 비밀을 읽을 수 있는 Secret Manager 보안 비밀 접근자 (roles/secretmanager.secretAccessor) 역할이 있는지 확인합니다. 자세한 내용은 Secret Manager를 사용하여 보안 비밀 만들기 및 액세스를 참고하세요.

external_search_fdw 확장 프로그램 사용 설정 및 구성

OpenSearch와의 통합을 시작하려면 외부 데이터 서버를 통해 OpenSearch 클러스터에 대한 액세스를 구성하세요.

  1. external_search_fdw 확장 프로그램을 사용 설정합니다.

    CREATE EXTENSION external_search_fdw;

  2. OpenSearch 클러스터의 서버를 만듭니다.

    CREATE SERVER OPENSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (
  server 'OPENSEARCH_SERVER_HOST_PORT',
  search_provider 'opensearch',
  auth_mode 'secret_manager',
  auth_method 'Basic',
  secret_path 'SECRET_PATH'
);

    다음 변수를 바꿉니다.

    • OPENSEARCH_SERVER_NAME: 외부 데이터 서버의 이름입니다. 예를 들면 opensearch입니다.

    • OPENSEARCH_SERVER_HOST_PORT: OpenSearch 클러스터의 공개 URL(엔드포인트)입니다.

    • SECRET_PATH: OpenSearch 인증 사용자 인증 정보의 Secret Manager 경로입니다. 예를 들면 projects/123456789012/secrets/opensearch-credentials/versions/1입니다. 123456789012는 Google Cloud 프로젝트 ID를 나타냅니다.

  3. OpenSearch 서버의 PostgreSQL 사용자 매핑을 정의합니다. PostgreSQL FDW가 작동하려면 이 사용자 매핑이 필요합니다. AlloyDB는 REST 승인 헤더를 사용하여 인증합니다.

    CREATE USER MAPPING FOR CURRENT_USER
SERVER OPENSEARCH_SERVER_NAME;

  4. OpenSearch 색인의 스키마를 PostgreSQL 외부 테이블에 매핑합니다.

    CREATE FOREIGN TABLE OPENSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    OPENSEARCH_FIELDS)
       SERVER OPENSEARCH_SERVER_NAME
       OPTIONS(
            remote_table_name 'OPENSEARCH_INDEX_NAME'
       );

    다음 새 변수를 바꿉니다.

    • OPENSEARCH_FD_TABLE: OpenSearch 테이블을 나타내는 외부 데이터 테이블의 이름입니다. 예를 들면 my-fd-opensearch-table입니다.

    • OPENSEARCH_FIELDS: 각 항목이 opensearch_field_name PG_DATA_TYPE 형식을 사용하는 쉼표로 구분된 목록입니다. 지원되는 OpenSearch 데이터 유형과 해당 PostgreSQL 유형의 목록은 지원되는 데이터 유형을 참고하세요.

    • OPENSEARCH_INDEX_NAME: OpenSearch 색인의 이름입니다. 예를 들면 my-opensearch-index입니다.

지원되는 데이터 유형

AlloyDB는 다음 OpenSearch 데이터 유형을 지원합니다.

데이터 유형 AlloyDB 유형
alias alias이 참조하는 필드의 PostgreSQL 유형
binary bytea
boolean BOOLEAN

byte,

short

SMALLINT
date TIMESTAMPTZ

double,

scaled_float

DOUBLE PRECISION

float,

half_float

REAL
integer INTEGER
long BIGINT

object,

flattened

jsonb

text,

keyword,

constant_keyword

wildcard

TEXT
unsigned_long NUMERIC

OpenSearch 데이터 쿼리

AlloyDB는 SQL 쿼리를 가져와 OpenSearch REST API 쿼리로 변환합니다.

OpenSearch 데이터를 쿼리하는 방법은 다음과 같습니다.

  • 표준 SQL 쿼리
  • Query DSL
  • 하이브리드 검색

표준 SQL 쿼리

검색 표현식에 Lucene 구문과 함께 표준 SQL을 사용할 수 있습니다.

SELECT id, body
FROM OPENSEARCH_FD_TABLE
WHERE FILTER
ORDER BY metadata <@> 'QUERY';

다음 변수를 바꿉니다.

  • OPENSEARCH_FD_TABLE: OpenSearch 테이블을 나타내는 외부 데이터 테이블의 이름입니다. 예를 들면 my-fd-opensearch-table입니다.

  • (선택사항) FILTER: OpenSearch 쿼리에 적용할 필터입니다. 예를 들면 a = 10 AND b < 105입니다.

  • QUERY: OpenSearch에 전송할 쿼리입니다. 예를 들면 body:database입니다.

Query DSL

고급 사용 사례의 경우 OpenSearch JSON 스타일 쿼리 DSL을 사용하세요.

SELECT id, title
FROM OPENSEARCH_FD_TABLE
ORDER BY metadata <@> $${
  "query": {
    "bool": {
      "must": { "match": { "title": "opensearch" } },
      "filter": { "term": { "category": "software" } }
    }
  },
  "sort": [
    { "price": { "order": "desc" } }
  ]
}$$
LIMIT 1;

OPENSEARCH_FD_TABLE을 OpenSearch 테이블을 나타내는 외부 데이터 테이블의 이름으로 바꿉니다. 예를 들면 my-fd-opensearch-table입니다.

OpenSearch 데이터에 대해 하이브리드 검색을 실행하려면 OpenSearch 토큰 검색 결과를 AlloyDB 벡터 검색 결과와 결합하세요.

SELECT *
FROM ai.hybrid_search(
  ARRAY[
    '{"limit": LIMIT,
      "weight": WEIGHT,
      "table_name": OPENSEARCH_FD_TABLE,
      "key_column": "id",
      "query_text_input": "QUERY"}'::jsonb
  ])
ORDER BY score DESC;

다음 변수를 바꿉니다.

  • LIMIT: 반환할 결과 수입니다. 예를 들면 10입니다.

  • WEIGHT: 전체 상호 순위 융합 (RRF)에 대한 이 검색 항목의 기여도입니다. 예를 들면 0.5입니다.

  • OPENSEARCH_FD_TABLE: OpenSearch 테이블을 나타내는 외부 데이터 테이블의 이름입니다. 예를 들면 my-fd-opensearch-table입니다.

  • QUERY: OpenSearch에 전송할 쿼리입니다. 예를 들어 "opensearch_field_name:\"cloud databases\""은 opensearch_field_name 필드에서 '클라우드 데이터베이스'라는 문구를 검색합니다.

푸시다운 예

쿼리를 더 효율적으로 만들기 위해 AlloyDB는 OpenSearch에 이루어진 API 호출에 쿼리의 다음 측면을 직접 푸시하려고 시도합니다.

  • 필드 SELECT개
  • 필터 WHERE개
  • ORDER BY 정렬
  • LIMIT

AlloyDB에서 푸시 다운할 수 있는 측면과 푸시 다운할 수 없는 측면을 보여주는 쿼리 예시는 다음 표를 참고하세요.

쿼리 유형 쿼리 예시 아래로 푸시된 쿼리 요소
필터링되지 않은 쿼리 
SELECT id, body
FROM opensearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • 필드 SELECT개
  • ORDER BY ... DESC 정렬
  • LIMIT
정확한 텍스트 일치 
SELECT id, body
FROM opensearch_table
WHERE body = 'foo'
LIMIT 10;
  • 필드 SELECT개
  • 필터 WHERE개
  • LIMIT
단일 필드 표현식 
SELECT id, body
FROM opensearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • 필드 SELECT개
  • 필터 WHERE개
상수 표현식 
SELECT id, body
FROM opensearch_table
WHERE id > (1+1)
LIMIT 10;
  • 필드 SELECT개
  • 필터 WHERE개
  • LIMIT
함수가 포함된 표현식 
SELECT id, body
FROM opensearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • 필드 SELECT개
다중 필드 표현식 
SELECT id, body
FROM opensearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • 필드 SELECT개
점수 필터링 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM opensearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • 필드 SELECT개
  • ORDER BY ... DESC 정렬
LIKE 및 유사한 연산자 
SELECT id, body
FROM opensearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • 필드 SELECT개
  • 필터 WHERE id > 10개
원시 쿼리 
SELECT id, body
FROM opensearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • 필드 SELECT개
  • ORDER BY ... DESC 정렬

문제 해결

OpenSearch 클러스터를 쿼리할 때 인증 또는 연결 문제가 발생하면 다음의 일반적인 원인을 확인하세요.

  • HTTP 401 또는 403 인증 오류: Secret Manager의 OpenSearch 보안 비밀에 username:password로 형식이 지정된 문자열이 포함되어 있고 AlloyDB 서비스 계정에 Secret Manager 보안 비밀 접근자 (roles/secretmanager.secretAccessor) 역할이 있는지 확인합니다.
  • 연결 시간 초과: 기본 AlloyDB 인스턴스에서 아웃바운드 공개 IP 연결이 사용 설정되어 있고 OpenSearch 방화벽에서 지정된 포트의 인바운드 연결이 허용되는지 확인합니다.

제한사항

AlloyDB를 OpenSearch에 연결하기 전에 다음 제한사항을 숙지하세요.

  • OpenSearch 통합은 PostgreSQL 메이저 버전 17 이상에서만 사용할 수 있습니다.

  • AlloyDB는 OpenSearch 데이터를 읽지만 쓰지는 않습니다.

  • AlloyDB는 데이터베이스 데이터를 OpenSearch에 자동으로 색인하지 않습니다. OpenSearch 색인을 채우고 AlloyDB의 데이터와 OpenSearch의 색인 데이터 간의 일관성을 유지하는 것은 사용자의 책임입니다.

  • AlloyDB는 OpenSearch와 스키마를 자동으로 동기화하지 않습니다. OpenSearch 색인 스키마가 변경되면 해당 PostgreSQL 외부 테이블의 스키마를 수동으로 업데이트해야 합니다.

  • geo_point와 같은 특수 OpenSearch 유형은 지원되지 않습니다. 지원되는 데이터 유형의 전체 목록은 지원되는 데이터 유형을 참고하세요.

  • OpenSearch 클러스터에 구성된 기본 인증 (사용자 이름 및 비밀번호)을 사용해야 합니다.

다음 단계