Field capabilities API

1.0에서 도입

_field_caps API는 하나 이상의 인덱스에 걸쳐 필드의 기능(capabilities)에 대한 정보를 제공해요. 보통 클라이언트가 필드가 어떻게 매핑되어 있는지, 그리고 여러 인덱스에서 검색·정렬·집계에 쓸 수 있는지 판단할 때 사용해요.

인덱스마다 매핑이 다르고, 쿼리가 인덱스 간 필드 호환성을 평가해야 할 때 특히 유용해요.

출처: 문서

본문

엔드포인트 (Endpoints)

GET  /_field_caps
POST /_field_caps
GET  /{index}/_field_caps
POST /{index}/_field_caps

경로 매개변수 (Path parameters)

다음 표는 사용 가능한 경로 매개변수예요.

매개변수	데이터 타입	설명
`index`	List 또는 String	요청을 제한하는 데 사용하는 데이터 스트림, 인덱스, 별칭의 쉼표로 구분된 목록이에요. 와일드카드()를 지원해요. 모든 데이터 스트림과 인덱스를 대상으로 하려면 이 매개변수를 생략하거나 `` 또는 `_all`을 사용해요. 선택 사항이에요.

쿼리 매개변수 (Query parameters)

다음 표는 사용 가능한 쿼리 매개변수예요. 모든 쿼리 매개변수는 선택 사항이에요.

매개변수	데이터 타입	설명
`allow_no_indices`	Boolean	`false`면 와일드카드 표현식, 인덱스 별칭, `_all` 값이 존재하지 않거나 닫힌 인덱스만 대상으로 하면 오류를 반환해요. 요청이 다른 열린 인덱스도 대상으로 하더라도 마찬가지예요. 예를 들어 `foo,bar`를 대상으로 하는 요청은 foo로 시작하는 인덱스는 있지만 bar로 시작하는 인덱스가 없으면 오류를 반환해요. 기본값은 `true`예요.
`expand_wildcards`	List 또는 String	와일드카드 패턴이 일치할 수 있는 인덱스 유형이에요. 요청이 데이터 스트림을 대상으로 할 수 있다면, 이 인수는 와일드카드 표현식이 숨은(hidden) 데이터 스트림과 일치하는지 결정해요. `open,hidden` 같은 쉼표로 구분된 값을 지원해요.
		유효한 값은 다음과 같아요:
		- `all`: 숨은 인덱스를 포함해 모든 인덱스와 일치해요.
		- `closed`: 닫힌, 숨지 않은 인덱스와 일치해요.
		- `hidden`: 숨은 인덱스와 일치해요. `open`, `closed` 또는 둘 다와 함께 사용해야 해요.
		- `none`: 와일드카드 표현식을 허용하지 않아요.
		- `open`: 열린, 숨지 않은 인덱스와 일치해요.
		기본값은 `open`이에요.
`fields`	List 또는 String	기능을 조회할 필드의 쉼표로 구분된 목록이에요. 와일드카드(*) 표현식을 지원해요.
`ignore_unavailable`	Boolean	`true`면 존재하지 않거나 닫힌 인덱스가 응답에 포함되지 않아요. 기본값은 `false`예요.
`include_unmapped`	Boolean	`true`면 매핑되지 않은(unmapped) 필드가 응답에 포함돼요. 기본값은 `false`예요.

요청 본문 필드 (Request body fields)

다음 표는 사용 가능한 요청 본문 필드예요.

필드	데이터 타입	설명
`index_filter`	Object	요청에 포함할 인덱스를 필터링하는 데 사용하는 query DSL 객체예요. 예시: 인덱스 필터 사용하기를 참고해요. 선택 사항이에요.

예시 요청 (Example requests)

같은 필드에 서로 다른 매핑을 가진 두 인덱스를 만들어요:

PUT /store-west
{
"mappings": {
"properties": {
"product": { "type": "text" },
"price": { "type": "float" }
}
}
}

PUT /store-east
{
"mappings": {
"properties": {
"product": { "type": "keyword" },
"price": { "type": "float" }
}
}
}

두 인덱스에 걸쳐 필드 기능을 조회해요:

GET /store-west,store-east/_field_caps?fields=product,price

Python 클라이언트로는 이렇게 호출해요:

response = client.field_caps(
index = "store-west,store-east",
params = { "fields": "product,price" },
body = { "Insert body here" }
)

예시 응답 (Example response)

응답은 사용 가능한 필드의 기능을 제공해요:

{
"indices": [
"store-east",
"store-west"
],
"fields": {
"product": {
"text": {
"type": "text",
"searchable": true,
"aggregatable": false,
"indices": [
"store-west"
]
},
"keyword": {
"type": "keyword",
"searchable": true,
"aggregatable": true,
"indices": [
"store-east"
]
}
},
"price": {
"float": {
"type": "float",
"searchable": true,
"aggregatable": true
}
}
}
}

예시: 인덱스 필터 사용하기 (Example: Using an index filter)

index_filter로 고려할 인덱스를 제한할 수 있어요. index_filter는 실제 문서 내용이 아니라 필드 수준 메타데이터를 기준으로 인덱스를 걸러내요. 다음 요청은 문서가 색인되어 있지 않아도 product 필드를 포함한 매핑이 있는 인덱스로 선택을 제한해요:

POST /_field_caps?fields=product,price
{
"index_filter": {
"term": {
"product": "notebook"
}
}
}

Python 클라이언트로는 이렇게 호출해요:

response = client.field_caps(
params = { "fields": "product,price" },
body =   {
"index_filter": {
"term": {
"product": "notebook"
}
}
}
)

예시 응답 (Example response)

응답에는 값이 notebook인 product 필드를 가진 인덱스의 필드만 포함돼요:

{
"indices": [
"store-east",
"store-west"
],
"fields": {
"product": {
"text": {
"type": "text",
"searchable": true,
"aggregatable": false,
"indices": [
"store-west"
]
},
"keyword": {
"type": "keyword",
"searchable": true,
"aggregatable": true,
"indices": [
"store-east"
]
}
},
"price": {
"float": {
"type": "float",
"searchable": true,
"aggregatable": true
}
}
}
}

응답 본문 필드 (Response body fields)

다음 표는 모든 응답 본문 필드를 정리한 거예요.

필드	데이터 타입	설명
`indices`	List	응답에 포함된 인덱스 목록이에요.
`fields`	Object	타입을 필드 기능으로 매핑한 맵이에요. 각 키는 필드 이름이고 값은 객체예요.
`fields.<field>.<type>.type`	String	필드의 데이터 타입이에요(예: `float`, `text`, `keyword`).
`fields.<field>.<type>.searchable`	Boolean	필드가 색인되고 검색 가능한지 여부예요.
`fields.<field>.<type>.aggregatable`	Boolean	`sum`, `terms` 같은 집계에서 필드를 사용할 수 있는지 여부예요.
`fields.<field>.<type>.indices`	List	해당 타입으로 필드가 나타나는 인덱스 목록이에요.
`fields.<field>.<type>.non_searchable_indices`	List 또는 null	필드가 검색 불가능한 인덱스 목록이에요. `null`은 어떤 인덱스에서도 필드를 검색할 수 없다는 뜻이에요.
`fields.<field>.<type>.non_aggregatable_indices`	List 또는 null	필드가 집계 불가능한 인덱스 목록이에요. `null`은 어떤 인덱스에서도 필드를 집계할 수 없다는 뜻이에요.
`fields.<field>.<type>.meta`	Object	모든 매핑에서 병합된 메타데이터 값이에요. 키는 사용자 지정 메타데이터 키이고, 값은 인덱스 전체 값을 담은 배열이에요.

필요한 권한 (Required permissions)

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: indices:data/read/field_caps 및 indices:data/read/field_caps*.

Field capabilities API