Disable objects 매핑 파라미터

기본적으로 OpenSearch는 점(.)을 포함한 필드 이름을 계층적 객체 경로로 해석해요. disable_objects 매핑 파라미터는 이러한 확장을 방지해 점이 있는 필드 이름을 평평한(flat) 리터럴 식별자로 저장해요.

출처: 문서

본문

기본적으로 OpenSearch는 점(.)을 포함한 필드 이름을 계층적 객체 경로로 해석합니다. 예를 들어 metrics.cpu.usage라는 필드는 metrics를 최상위 객체로, 그 안에 cpu 객체를, 다시 그 안에 usage 필드를 포함하는 중첩 객체 구조로 확장됩니다.

이 동작은 점이 있는 이름이 중첩 객체가 아닌 평평한 필드 식별자를 나타내는 분석/지표(analytics and metrics) 워크로드에서 매핑 충돌을 일으킬 수 있습니다. 예를 들어 많은 수집 파이프라인은 metrics.cpu.usage, metrics.cpu.idle, system.memory.free 같은 평평한 지표 스타일 필드를 생성합니다. 개입이 없다면 OpenSearch가 이 점 필드들을 중첩 객체로 자동 확장하면서, 같은 경로 접두사가 값 필드와 객체로 동시에 사용될 때 매핑 충돌, 수집 순서에 따른 비결정적 실패, 대량 수집 불안정이 발생할 수 있습니다.

disable_objects 매핑 파라미터는 이러한 확장을 방지합니다. 활성화되면 점이 있는 필드 이름이 리터럴 평평한 식별자로 저장되고, 중첩 JSON 입력은 수집 시점에 자동으로 점이 있는 필드 이름으로 평평해지며, 수집 순서가 매핑 결과에 영향을 주지 않습니다.

disable_objects 파라미터는 여러 수준에서 설정할 수 있습니다. 여러 수준이 구성되면 다음 우선순위가 적용됩니다(높은 것부터 낮은 것 순).

필드 수준 (Field level)
객체 수준 (Object level)
인덱스 수준 매핑 정의 ("mappings": { "disable_objects": true })
전역 기본값(false)

파라미터

다음 표는 disable_objects 파라미터가 받는 값을 나열합니다.

파라미터	설명
`false` (기본값)	점이 있는 필드 이름이 중첩 객체 구조로 확장됩니다.
`true`	점이 있는 필드 이름이 리터럴 평평한 필드 식별자로 취급됩니다. 중간 경로 세그먼트에 대해 객체 매퍼가 생성되지 않습니다.

예제: 인덱스 수준 구성

전체 인덱스에 대해 평평한 점 필드 의미론을 활성화하려면 매핑 정의의 인덱스 수준에서 disable_objects를 설정하세요.

PUT /metrics-index
{
  "mappings": {
    "disable_objects": true
  }
}

다음 요청은 점이 있는 필드 이름을 사용해 문서를 인덱싱합니다.

POST /metrics-index/_doc
{
  "metrics.cpu.usage": 0.82
}

metrics.cpu.usage 필드는 단일 평평한 필드로 저장됩니다. metrics 또는 metrics.cpu에 대해 객체 매퍼가 생성되지 않습니다.

다음 요청은 중첩 JSON을 사용해 문서를 인덱싱합니다.

POST /metrics-index/_doc
{
  "metrics": {
    "cpu": {
      "usage": 0.65
    }
  }
}

중첩 입력은 자동으로 metrics.cpu.usage로 평평해지고 0.65로 설정되어 이전 문서와 같은 평평한 필드를 생성합니다.

다음 요청은 중첩 객체가 생성되지 않았는지 확인하기 위해 매핑을 검색합니다.

GET /metrics-index/_mapping

응답은 metrics.cpu.usage가 평평한 필드로 저장되었음을 보여 줍니다.

{
  "metrics-index": {
    "mappings": {
      "properties": {
        "metrics.cpu.usage": {
          "type": "float"
        }
      }
    }
  }
}

예제: 객체 수준 구성

특정 객체 아래의 필드에만 평평한 의미론을 적용하려면 해당 객체 필드에 disable_objects를 설정하세요.

PUT /my-index
{
  "mappings": {
    "properties": {
      "metrics": {
        "type": "object",
        "disable_objects": true
      }
    }
  }
}

metrics 아래의 필드만 평평한 점 필드로 취급됩니다. 인덱스의 다른 필드는 기본 객체 확장 동작을 유지합니다.

예제: 필드 수준 구성

인덱스 수준과 객체 수준 기본값을 재정의하려면 특정 필드에 disable_objects를 적용하세요.

PUT /my-index
{
  "mappings": {
    "properties": {
      "metrics.cpu.usage": {
        "type": "float",
        "disable_objects": true
      }
    }
  }
}

점 필드 검색(Searching dotted fields)

disable_objects가 활성화되면 OpenSearch는 점 필드에 대해 전체 경로(full-path) 검색과 짧은 이름(short-name) 검색을 모두 지원합니다. 점 필드가 중첩 객체가 아닌 평평한 리터럴 식별자로 저장되므로, 검색 동작은 기본 객체 확장 모드와 다릅니다. 전체 경로 검색과 짧은 이름 검색이 모두 같은 평평한 필드로 해석됩니다.

전체 경로 검색

전체 경로 검색에서는 쿼리에 전체 점 필드 이름을 제공합니다.

POST /metrics-index/_search
{
  "query": {
    "term": {
      "metrics.cpu.usage": {
        "value": 0.82
      }
    }
  }
}

짧은 이름 검색

짧은 이름 검색에서는 쿼리에 필드 이름의 마지막 세그먼트만 제공합니다.

POST /metrics-index/_search
{
  "query": {
    "term": {
      "usage": {
        "value": 0.82
      }
    }
  }
}

짧은 이름 검색을 사용할 때 여러 점 필드가 같은 마지막 세그먼트를 공유하면 모호성이 생길 수 있습니다. 예를 들어 인덱스에 metrics.cpu.usage와 metrics.memory.usage가 모두 있다면 usage에 대한 짧은 이름 검색이 의도한 필드로 해석되지 않을 수 있습니다. 이런 경우 모호함을 피하려면 전체 필드 경로를 사용하세요.

제한 사항(Limitations)

disable_objects 파라미터에는 다음 제한 사항이 적용됩니다.

disable_objects 파라미터는 인덱스 생성 후에는 변경할 수 없습니다.
disable_objects가 활성화되면 중첩(nested) 쿼리와 객체 기반 필드 그룹화는 지원되지 않습니다.
구체적인 필드 이름(예: address)이 기존 점 필드(예: address.city)와 접두사를 공유하면, 둘 다 독립적인 평평한 필드로 저장됩니다. 공유 접두사에 대해 객체 매퍼가 생성되지 않으므로 충돌이 발생하지 않습니다.

더 알아보기 (Learn more)

OpenSearch 공식 문서

Disable objects 매핑 파라미터