OpenSearch 커넥터

OpenSearch 커넥터 (OpenSearch connector)

OpenSearch 커넥터는 Trino에서 OpenSearch 데이터에 접근할 수 있게 해줍니다. 이 문서는 OpenSearch 커넥터로 카탈로그를 설정하고 OpenSearch에 대해 SQL 쿼리를 실행하는 방법을 설명해요.

출처: 문서

본문

요구 사항 (Requirements)

OpenSearch 1.1.0 이상.
Trino 코디네이터와 워커에서 OpenSearch 노드로의 네트워크 접근.

설정 (Configuration)

OpenSearch 커넥터를 설정하려면 etc/catalog/example.properties 카탈로그 속성 파일을 만들고, 자신의 설정에 맞게 속성을 바꿔 다음 내용을 넣어주세요:

connector.name=opensearch
opensearch.host=search.example.com
opensearch.port=9200
opensearch.default-schema-name=default

다음 표는 모든 일반 설정 속성을 설명합니다:

속성 이름	설명	기본값
`opensearch.host`	OpenSearch 클러스터의 호스트 이름 목록(쉼표 구분). 필수.	—
`opensearch.port`	OpenSearch에 연결하는 데 사용할 포트.	`9200`
`opensearch.default-schema-name`	스키마 이름을 명시하지 않은 모든 테이블을 포함하는 스키마.	`default`
`opensearch.scroll-size`	각 OpenSearch scroll 요청에서 반환될 수 있는 최대 hit 수.	`1000`
`opensearch.scroll-timeout`	scroll 요청을 위해 OpenSearch가 검색 컨텍스트를 유지하는 기간.	`1m`
`opensearch.request-timeout`	모든 OpenSearch 요청의 타임아웃.	`10s`
`opensearch.connect-timeout`	모든 OpenSearch 연결 시도의 타임아웃.	`1s`
`opensearch.backoff-init-delay`	OpenSearch에 대한 단일 요청의 역압 재시도 사이 최소 기간. 너무 낮게 설정하면 이미 힘든 클러스터에 부담을 줄 수 있음.	`500ms`
`opensearch.backoff-max-delay`	단일 요청의 역압 재시도 사이 최대 기간.	`20s`
`opensearch.max-retry-time`	단일 요청의 모든 재시도에 걸친 최대 기간.	`30s`
`opensearch.node-refresh-interval`	사용 가능한 OpenSearch 노드 목록을 갱신하는 요청 사이의 기간.	`1m`
`opensearch.ignore-publish-address`	쿼리 연결에 OpenSearch API가 게시한 주소를 사용하지 않도록 설정. 일부 배포는 OpenSearch 포트를 임의의 공용 포트로 매핑하는데 이 속성을 켜면 도움이 될 수 있음.	`false`
`opensearch.projection-pushdown-enabled`	`SELECT` 쿼리 수행 시 행 컬럼의 투영 필드만 읽음.	`true`

인증 (Authentication)

OpenSearch로의 연결은 AWS 또는 비밀번호 인증을 사용할 수 있습니다.

IAM 정책으로 AWS 인증과 권한 부여를 활성화하려면 opensearch.security 옵션을 AWS로 설정해야 합니다. 또한 다음 옵션을 설정해야 합니다:

속성 이름	설명
`opensearch.aws.region`	OpenSearch 엔드포인트의 AWS 리전. 필수.
`opensearch.aws.access-key`	OpenSearch 도메인 연결에 사용할 AWS 액세스 키. 설정하지 않으면 기본 AWS 자격 증명 공급자 체인 사용.
`opensearch.aws.secret-key`	OpenSearch 도메인 연결에 사용할 AWS 시크릿 키. 설정하지 않으면 기본 AWS 자격 증명 공급자 체인 사용.
`opensearch.aws.iam-role`	OpenSearch 연결에 수임할 IAM 역할의 선택적 ARN. 설정된 IAM 사용자가 이 역할을 수임할 수 있어야 함.
`opensearch.aws.external-id`	AWS IAM 역할 수임 시 전달할 선택적 외부 ID.
`opensearch.aws.deployment-type`	AWS OpenSearch 배포 유형. `PROVISIONED`와 `SERVERLESS` 가능. 필수.

비밀번호 인증을 활성화하려면 opensearch.security 옵션을 PASSWORD로 설정해야 합니다. 또한 다음 옵션을 설정해야 합니다:

속성 이름	설명
`opensearch.auth.user`	OpenSearch 연결에 사용할 사용자 이름.
`opensearch.auth.password`	OpenSearch 연결에 사용할 비밀번호.

TLS 연결 보안 (Connection security with TLS)

커넥터는 TLS가 활성화된 OpenSearch 클러스터에 연결하기 위한 추가 보안 옵션을 제공합니다.

클러스터가 전역 신뢰 인증서를 사용하면 TLS만 활성화하면 됩니다. 인증서에 대한 사용자 정의 설정이 필요하면 커넥터가 P12(PKCS) 또는 Java Key Store(JKS) 형식의 키 스토어와 트러스트 스토어를 지원합니다.

사용 가능한 설정 값은 다음 표에 정리되어 있습니다:

속성 이름	설명
`opensearch.tls.enabled`	TLS 보안 활성화. 기본값은 `false`.
`opensearch.tls.keystore-path`	P12(PKCS) 또는 JKS 키 스토어 경로.
`opensearch.tls.truststore-path`	P12(PKCS) 또는 JKS 트러스트 스토어 경로.
`opensearch.tls.keystore-password`	`opensearch.tls.keystore-path`가 지정한 키 스토어의 비밀번호.
`opensearch.tls.truststore-password`	`opensearch.tls.truststore-path`가 지정한 트러스트 스토어의 비밀번호.
`opensearch.tls.verify-hostnames`	인증서의 호스트 이름을 검증할지 여부. 기본값은 `true`.

데이터 유형 매핑 (Type mapping)

Trino와 OpenSearch는 서로 지원하지 않는 유형이 있으므로, 커넥터는 데이터를 읽을 때 일부 유형을 매핑합니다.

OpenSearch 유형에서 Trino 유형으로의 매핑:

OpenSearch 유형	Trino 유형	비고
`BOOLEAN`	`BOOLEAN`
`DOUBLE`	`DOUBLE`
`FLOAT`	`REAL`
`BYTE`	`TINYINT`
`SHORT`	`SMALLINT`
`INTEGER`	`INTEGER`
`LONG`	`BIGINT`
`KEYWORD`	`VARCHAR`
`TEXT`	`VARCHAR`
`DATE`	`TIMESTAMP`	Date 유형 참고
`IPADDRESS`	`IP`

그 외 유형은 지원되지 않습니다.

배열 유형 (Array types)

OpenSearch의 필드는 0개 이상의 값을 포함할 수 있지만 전용 배열 유형은 없습니다. 필드가 배열을 포함한다는 것을 나타내려면 OpenSearch의 인덱스 매핑에서 _meta 섹션의 Trino 특정 구조로 주석을 달 수 있습니다.

예를 들어 다음 구조의 문서를 포함하는 OpenSearch 인덱스가 있다고 해봅시다:

{
    "array_string_field": ["trino","the","lean","machine-ohs"],
    "long_field": 314159265359,
    "id_field": "564e6982-88ee-4498-aa98-df9e3f6b6109",
    "timestamp_field": "2025-09-17T06:22:48.000Z",
    "object_field": {
        "array_int_field": [86,75,309],
        "int_field": 2
    }
}

배열 필드는 다음 명령으로 대상 인덱스 매핑의 _meta.trino 속성에 필드 속성 정의를 추가해 표현합니다. OpenSearch는 search.example.com:9200에서 접근 가능합니다:

curl --request PUT \
    --url search.example.com:9200/doc/_mapping \
    --header 'content-type: application/json' \
    --data '
{
    "_meta": {
        "trino":{
            "array_string_field":{
                "isArray":true
            },
            "object_field":{
                "array_int_field":{
                    "isArray":true
                }
            },
        }
    }
}'

같은 컬럼에 asRawJson과 isArray 플래그를 동시에 사용하는 것은 허용되지 않습니다.

Date 유형 (Date types)

OpenSearch 커넥터는 기본 date 유형만 지원합니다. 빌트인 날짜 형식을 포함한 다른 모든 OpenSearch date 형식과 사용자 정의 date 형식은 지원되지 않습니다. format 속성이 있는 날짜는 무시됩니다.

원시 JSON 변환 (Raw JSON transform)

OpenSearch의 문서는 매핑에 표현되지 않은 더 복잡한 구조를 포함할 수 있습니다. 예를 들어 단일 keyword 필드는 단일 keyword 값, 배열, 또는 어떤 중첩 수준의 다차원 keyword 배열 등 매우 다양한 내용을 가질 수 있습니다.

search.example.com:9200에서 접근 가능한 OpenSearch로 array_string_field 매핑을 설정하는 명령:

curl --request PUT \
    --url search.example.com:9200/doc/_mapping \
    --header 'content-type: application/json' \
    --data '
{
    "properties": {
        "array_string_field":{
            "type": "keyword"
        }
    }
}'

array_string_field 매핑이 있는 OpenSearch에서 다음 문서는 모두 유효합니다:

[
    {
        "array_string_field": "trino"
    },
    {
        "array_string_field": ["trino","is","the","best"]
    },
    {
        "array_string_field": ["trino",["is","the","best"]]
    },
    {
        "array_string_field": ["trino",["is",["the","best"]]]
    }
]

자세한 내용은 OpenSearch 배열 문서를 참고하세요.

또한 OpenSearch는 Trino가 지원하지 않는 k-NN vector 같은 유형을 지원합니다. 이와 같은 유형은 OpenSearch에서 이 유형을 사용하는 사용자에게 파싱 예외를 일으킬 수 있습니다. 이런 모든 시나리오를 관리하려면 OpenSearch 인덱스 매핑의 _meta 섹션에서 Trino 특정 구조로 필드에 주석을 달아 필드를 원시 JSON으로 변환할 수 있습니다. 이것은 Trino에 해당 필드와 그 아래의 모든 중첩 필드가 원시 JSON 내용을 담은 VARCHAR 필드로 캐스팅되어야 함을 알립니다. 이 필드는 대상 인덱스 매핑의 _meta.trino 속성에 필드 속성 정의를 추가하는 다음 명령으로 정의할 수 있습니다:

curl --request PUT \
    --url search.example.com:9200/doc/_mapping \
    --header 'content-type: application/json' \
    --data '
{
    "_meta": {
      "trino":{
        "array_string_field":{
            "asRawJson":true
        }
      }
    }
}'

위 설정은 Trino가 array_string_field 필드를 원시 JSON을 담은 VARCHAR로 반환하게 합니다. 이 필드는 내장 JSON 함수로 파싱할 수 있습니다.

같은 컬럼에 asRawJson과 isArray 플래그를 동시에 사용하는 것은 허용되지 않습니다.

특수 컬럼 (Special columns)

다음 숨겨진 컬럼을 사용할 수 있습니다:

컬럼	설명
`_id`	OpenSearch 문서 ID.
`_score`	OpenSearch 쿼리가 반환한 문서 점수.
`_source`	원본 문서의 소스.

SQL 지원 (SQL support)

커넥터는 OpenSearch 카탈로그의 데이터와 메타데이터에 접근하기 위한 전역 사용 가능 명령문과 읽기 연산 명령문을 제공합니다.

와일드카드 테이블 (Wildcard table)

커넥터는 간결한 와일드카드 테이블 표기법으로 여러 테이블을 조회하는 것을 지원합니다:

SELECT *
FROM example.web."page_views_*";

테이블 함수 (Table functions)

커넥터는 OpenSearch에 접근하기 위한 특정 테이블 함수를 제공합니다.

raw_query(varchar) -> table

raw_query 함수는 OpenSearch Query DSL 문법으로 연결된 데이터베이스를 직접 조회하게 해줍니다. 전체 DSL 쿼리가 푸시다운되어 OpenSearch에서 처리됩니다. Trino에 없는 네이티브 기능에 접근하거나, 네이티브 실행이 더 빠른 상황에서 쿼리 성능을 높일 때 유용합니다.

연결된 데이터 소스에 전달되는 네이티브 쿼리는 결과 집합으로 테이블을 반환해야 합니다. 검증과 보안 검사는 오직 데이터 소스가 자체 설정으로 수행합니다. 패스스루 쿼리는 데이터 읽기에만 사용하세요.

raw_query 함수는 세 가지 파라미터가 필요합니다:

schema: 쿼리를 실행할 카탈로그의 스키마.
index: 검색할 OpenSearch 인덱스.
query: OpenSearch Query DSL로 작성한 실행할 쿼리.

실행되면 쿼리는 OpenSearch가 반환한 결과 JSON 페이로드를 포함하는 단일 행을 반환합니다.

예를 들어 example 카탈로그를 조회하고 raw_query 테이블 함수를 사용해 orders 인덱스에서 국가 이름이 ALGERIA인 문서를 검색합니다:

SELECT
  *
FROM
  TABLE(
    example.system.raw_query(
      schema => 'sales',
      index => 'orders',
      query => '{
        "query": {
          "match": {
            "name": "ALGERIA"
          }
        }
      }'
    )
  );

쿼리 엔진은 이 함수의 결과 순서를 보존하지 않습니다. 전달한 쿼리에 ORDER BY 절이 있으면 함수 결과 순서가 예상과 다를 수 있습니다.

성능 (Performance)

커넥터는 다음 섹션에 설명된 여러 성능 개선을 포함합니다.

병렬 데이터 접근 (Parallel data access)

커넥터는 쿼리 처리를 위해 OpenSearch 클러스터의 여러 노드에서 병렬로 데이터를 요청합니다.

조건 푸시다운 (Predicate push down)

커넥터는 다음 데이터 유형에 대해 조건 푸시다운을 지원합니다:

OpenSearch	Trino
`boolean`	`BOOLEAN`
`double`	`DOUBLE`
`float`	`REAL`
`byte`	`TINYINT`
`short`	`SMALLINT`
`integer`	`INTEGER`
`long`	`BIGINT`
`keyword`	`VARCHAR`
`date`	`TIMESTAMP`

그 외 데이터 유형은 조건 푸시다운을 지원하지 않습니다.

더 알아보기 (Learn more)

OpenSearch 커넥터로 다른 데이터 소스와 데이터를 조합해보세요. 커넥터의 일반적인 개념은 커넥터 개요 문서에서 확인할 수 있어요.