SQL 설정

SQL 설정 (SQL settings)

SQL 플러그인은 표준 OpenSearch 클러스터 설정에 몇 가지 설정을 추가해요. 대부분은 동적(dynamic) 설정이라 클러스터를 재시작하지 않고도 플러그인의 기본 동작을 바꿀 수 있어요. 정적 설정과 동적 설정에 대한 자세한 내용은 Configuring OpenSearch 문서를 참고하세요.

PPL 또는 SQL 질의 처리를 독립적으로 비활성화할 수 있어요.

다른 클러스터 설정처럼 이 설정들도 업데이트할 수 있어요.

PUT _cluster/settings
{
  "transient" : {
    "plugins.sql.enabled" : false
  }
}

또는 다음 요청 형식을 사용할 수 있어요.

PUT _cluster/settings
{
  "transient": {
    "plugins": {
      "ppl": {
        "enabled": "false"
      }
    }
  }
}

마찬가지로 _plugins/_query/settings 엔드포인트에 요청을 보내서 설정을 업데이트할 수도 있어요.

PUT _plugins/_query/settings
{
  "transient" : {
    "plugins.sql.enabled" : false
  }
}

또는 다음 요청 형식을 사용할 수 있어요.

PUT _plugins/_query/settings
{
  "transient": {
    "plugins": {
      "ppl": {
        "enabled": "false"
      }
    }
  }
}

_plugins/_ppl 및 _plugins/_sql 엔드포인트에 대한 요청은 요청 본문에 인덱스 이름을 포함하므로, bulk, mget, msearch 연산과 동일한 접근 정책 고려 사항을 가져요. rest.action.multi.allow_explicit_index 파라미터를 false로 설정하면 SQL과 PPL 엔드포인트가 모두 비활성화돼요.

출처: 문서

본문

사용 가능한 설정 (Available settings)

Setting	Default	Description
`plugins.sql.enabled`	`true`	`false`로 바꾸면 플러그인의 `SQL` 지원을 비활성화해요.
`plugins.ppl.enabled`	`true`	`false`로 바꾸면 플러그인의 `PPL` 지원을 비활성화해요.
`plugins.sql.slowlog`	`2`	느린 질의(slow query)의 시간 제한(초 단위)을 구성해요. 플러그인은 느린 질의를 `opensearch.log`에 `Slow query: elapsed=xxx (ms)`로 기록해요.
`plugins.sql.cursor.keep_alive`	`1m`	커서 컨텍스트가 열려 있는 시간을 구성해요. 커서 컨텍스트는 리소스를 많이 사용하므로 낮은 값을 권장해요.
`plugins.query.memory_limit`	`85%`	질의 엔진의 회로 차단기(circuit breaker)에 대한 힙 메모리 사용 한도를 구성해요.
`plugins.query.size_limit`	`10000`	질의 실행에서 반환되는 최대 행 수를 설정해요.
`plugins.query.datasources.enabled`	`true`	`false`로 바꾸면 플러그인의 데이터 소스 지원을 비활성화해요.
`plugins.query.field_type_tolerance`	`true`	`false`면 어떤 중첩 수준에서든 배열이 첫 번째 비배열 값으로 축소돼요. 예를 들어 `[[1, 2], [3, 4]]`는 `1`로 축소되고, `true`면 배열이 유지돼요. 기본값은 `true`예요.
`plugins.query.buckets`	`10000`	단일 응답에서 반환되는 집계 버킷 수를 설정해요. 기본값은 `plugins.query.size_limit` 값이에요.
`plugins.calcite.enabled`	`true`	Apache Calcite 질의 엔진을 활성화하며, subsearch, `join`, `lookup` 연산 같은 고급 SQL 및 PPL 기능을 포함해요.
`plugins.calcite.pushdown.enabled`	`true`	`false`로 바꾸면 연산자 푸시다운 최적화를 비활성화해요. 기본값 사용을 권장해요.
`plugins.calcite.fallback.allowed`	`false`	`true`로 바꾸면 v2 엔진으로의 폴백을 허용해요.
`plugins.calcite.pushdown.rowcount.estimation.factor`	`0.9`	테이블 스캔의 행 수를 곱해서 결과 행 수를 추정하는 데 사용되는 계수예요. 기본값 사용을 권장해요.
`plugins.calcite.all_join_types.allowed`	`false`	`RIGHT`, `FULL`, `CROSS` 조인 같은 성능에 민감한 조인 유형을 활성화해요. `true`로 바꾸면 이 조인 연산을 허용해요.
`plugins.ppl.syntax.legacy.preferred`	`true`	기본 인자 값 등을 포함한 PPL 문법 동작을 제어해요. `false`면 더 최신 문법 표준을 사용해요. 자세한 내용은 legacy syntax 문서를 참고하세요.
`plugins.ppl.values.max.limit`	`0`	`VALUES` 집계 함수가 반환할 수 있는 고유 값의 최대 개수를 설정해요. 값이 `0`이면 제한이 없음을 의미해요.
`plugins.ppl.rex.max_match.limit`	`10`	`rex` 명령이 추출하는 최대 일치 개수를 설정해요.
`plugins.ppl.subsearch.maxout`	`10000`	subsearch에서 반환할 최대 행 수를 설정해요.
`plugins.ppl.join.subsearch_maxout`	`50000`	join 연산에 사용되는 subsearch에서 반환할 최대 행 수를 설정해요.
`plugins.ppl.pattern.method`	`simple_pattern`	`patterns` 명령의 방법을 설정해요. 유효한 값은 `simple_pattern`과 `brain`이에요. 자세한 내용은 patterns syntax를 참고하세요.
`plugins.ppl.pattern.mode`	`label`	`patterns` 명령의 모드를 설정해요. 유효한 값은 `label`과 `aggregation`이에요. 자세한 내용은 patterns syntax를 참고하세요.
`plugins.ppl.pattern.max.sample.count`	`10`	집계 모드에서 패턴당 반환되는 최대 샘플 로그 수를 설정해요.
`plugins.ppl.pattern.buffer.limit`	`100000`	`brain` 알고리즘이 사용하는 내부 임시 버퍼의 크기를 설정해요.
`plugins.ppl.pattern.show.numbered.token`	`false`	`true`로 바꾸면 번호가 매겨진 토큰 출력 형식을 활성화해요.
`plugins.ppl.query.timeout`	`5m`	PPL 질의가 실행될 수 있는 최대 시간을 구성해요. 질의가 이 한도를 초과하면 실행이 중지되고 타임아웃 오류가 반환돼요.

Spark 커넥터 설정 (Spark connector settings)

SQL 플러그인은 Apache Spark를 증강된 컴퓨팅 소스(augmented compute source)로 지원해요. 데이터 소스가 Apache Spark에서 테이블로 정의되면 OpenSearch가 그 테이블을 사용할 수 있어요. 이를 통해 OpenSearch Dashboard의 Discover와 observability 로그 안에서 외부 소스에 대해 SQL 질의를 실행할 수 있어요.

시작하려면 다음 설정을 활성화해서 Spark를 데이터 소스로 추가하고 올바른 권한을 부여하세요.

Setting	Description
`spark.uri`	Spark 데이터 소스의 식별자예요.
`spark.auth.type`	Spark에 인증할 때 사용하는 인가 유형이에요.
`spark.auth.username`	Spark 데이터 소스의 사용자 이름이에요.
`spark.auth.password`	Spark 데이터 소스의 비밀번호예요.
`spark.datasource.flint.host`	Spark 데이터 소스의 호스트예요. 기본값은 `localhost`예요.
`spark.datasource.flint.port`	Spark의 포트 번호예요. 기본값은 `9200`이에요.
`spark.datasource.flint.scheme`	Spark 질의에서 사용하는 데이터 스킴이에요. 유효한 값은 `http`와 `https`예요.
`spark.datasource.flint.auth`	Spark 데이터 소스에 접근하는 데 필요한 인가예요. 유효한 값은 `false`와 `sigv4`예요.
`spark.datasource.flint.region`	OpenSearch 클러스터가 위치한 AWS 리전이에요. `auth`가 `sigv4`로 설정된 경우에만 사용해요. 기본값은 `us-west-2`예요.
`spark.datasource.flint.write.id_name`	Spark 커넥터가 쓰는 인덱스의 이름이에요.
`spark.datasource.flint.ignore.id_column`	질의에서 데이터를 내보낼 때 `id` 열을 제외해요. 기본값은 `true`예요.
`spark.datasource.flint.write.batch_size`	Spark 연결 인덱스에 쓸 때 배치 크기를 설정해요. 기본값은 `1000`이에요.
`spark.datasource.flint.write.refresh_policy`	커넥터가 OpenSearch에 데이터를 쓰지 못했을 때 Spark 연결에 대한 새로고침 정책을 설정해요. 새로고침 없음(`false`), 즉시 새로고침(`true`), 또는 대기 시간(`wait_for: X`)이에요. 기본값은 `false`예요.
`spark.datasource.flint.read.scroll_size`	Spark를 사용해 실행한 질의가 반환하는 결과 수를 설정해요. 기본값은 `100`이에요.
`spark.flint.optimizer.enabled`	OpenSearch가 Spark 연결에 최적화되도록 활성화해요. 기본값은 `true`예요.
`spark.flint.index.hybridscan.enabled`	OpenSearch가 데이터 소스의 비파티션 장치에서 쓰기 데이터를 스캔하도록 활성화해요. 기본값은 `false`예요.

설정을 마치면 다음 API 호출로 Spark 연결을 테스트할 수 있어요.

POST /_plugins/_ppl
content-type: application/json

{
   "query": "source = my_spark.sql('select * from alb_logs')"
}

SQL 설정

SQL 설정 (SQL settings)

본문

사용 가능한 설정 (Available settings)

Spark 커넥터 설정 (Spark connector settings)

더 알아보기 (Learn more)