Elasticsearch - API Conventions

엘라스틱 REST API는 HTTP를 통해 JSON을 이용하여 노출되어 있다. 

이번에 볼 리스트된 컨벤션은 REST API를 통해 적용할 수 있다.

Multiple Indices

대부분은 API는 다수의 인덱스를 통한 실행을 지원하기 위해 test1,test2,test3과 같은 식으로 인덱스를 기술할 수 있다. 또한 wildcards를 지원해서 test* 라던지 +test*, -test3 등의 문법도 지원한다.

모든 멀티풀 인덱스 API는 다음과 같은 쿼리 파라미터를 지원한다.

ignore_unavailable - 특정 인덱스가 사라졌거나 닫혀서 이용가능하지 않을때 무시할 지 여부를 컨트롤 한다. true 나 false로 지정할 수 있다.

allow_no_indices - 와일드카드 인덱스가 없다면 실패로 판단할 지 여부를 컨트롤 한다. true/false로 지정할 수 있다. 예를 들어 와일드카드 표현식 foo*가 명시되었는데 foo로 시작하는 이용가능한 인덱스가 없다면 세팅에따라 실패를 리턴한다. 

expand_wildcards - 어떤 종류의 인덱스에 와일드카드 익스프레션을 적용할 지 여부를 컨트롤 한다. 만약 open이라고 명시되었다면 open 인덱스에만 접근하고 closed라고 명시하면 closed 인덱스에 접근한다. open,closed라고 둘다 명시 되어 있으면 모든 인덱스에 적용한다. none이라고 지정되면 와일드카드 표현식은 이용할 수 없으며 all이라고 지정하면 모든 인덱스에 확장될 것이다. 

위 파라미터의 디폴트 세팅은 api에 특성에 따라 다르다.

Single-index alias API 및 Document API와 같은 싱글 인덱스와 멀티풀 indices를 지원하지 않는다.

Common options

다음 옵션들은 모든 REST API에 적용할 수 있는 옵션들이다.

Pretty Results

?pretty=true 이라고 어떤 요청에라도 붙이되면 결과는 반환되는 JSON은 pretty 포맷으로 될 것이다. 또다른 옵션으로 ?format=yaml 이라고 붙인다면 결과는 yaml 포맷으로 반환될 것이다.

Human readable outputs

통계치가 사람이 읽기 쉬운 형태로 반환된다.  (for humans (eg "exists_time": "1h" or "size": "1kb"), for computers (eg "exists_time_in_millis": 3600000 or "size_in_bytes": 1024)). ?human=false 쿼리 스트링에 다음과 같은 내용을 붙임으로써 모니터링 툴과 같은 시스템이 사용하기에 더욱 의미있는 통계치가 나올 것이다. 기본값은 false이다.

Flat Settings

flat settings 플래그는 리스트의 렌더링에 영향을 준다. flat_settings flag가 true이면 리턴된 결과는 다음과 같다.

{

  "persistent" : { },

  "transient" : {

    "discovery.zen.minimum_master_nodes" : "1"

  }

}

false이면 더 사람이 인식하기 좋은 형태로 나타난다.

{

  "persistent" : { },

  "transient" : {

    "discovery" : {

      "zen" : {

        "minimum_master_nodes" : "1"

      }

    }

  }

}

기본값은 false이다.

Parameters

REST 파라미터는 언더스코어 형식의 규칙을 따른다.

Boolean Values

모든 REST API의 파라미터는 "false"를 제공한다. "false"는 false, 0, no 혹은 off를 의미한다. 또한 "true"를 제공한다. 

Number Values 

모든 REST API는 JSON 숫자 타입 지원과 더불어 String을 숫자 파라미터를 사용할 수 있도록 지원한다.

Time units

기간을 명시할 필요가 있을때, 예를 들어 타임아웃과 같은 것이다. 2d는 2일을 의미하며 지원되는 단위는 다음과 같다.

y - Year

M - Month

w - Week

d - Day

h - Hour

m - Minute

s - Second

Distance Units

거리를 명시할 필요가 있을때 명시를 하지 않으면 기본적으로 meter를 사용한다. 다른 단위들도 명시할 수 있으며 1km 또는 2mi등이다.

Mile - mi or miles

Yard - yd or yards

Feet - ft or feet

Inch - in or inch

Kilometer - km or kilometers

Meter - m or meters 

Centimeter - cm or centimeters

Millimeter - mm or millimeters

Nautical mile - NM, nmi or nauticalmiles

Geohash Cell Filter의 정밀도 파라미터는 거리로 인식되며 명시를 하지 않아도 된다.

Fuzziness

몇몇 쿼리와 API는 정확하지 않은 fuzziness 파라미터를 통해서 fuzzy 매칭을 지원한다. Fuzziness 파라미터는 context sensitive하며 이 의미는 쿼리의 필드의 타입에 의본성이 강하다.

Numeric, date and IPv4 fields

숫자, 날짜, IPv4 필드를 쿼리할 떄 fuzziness는 +/- 마진을 해석한다. 동작은 범위 쿼리와 비슷하게 행동한다.

-fuzziness <= field value <= +fuzziness

퍼지 파라미터는 숫자형으로 세팅될 수 있고 예를 들자면 2 또는 2.0이다. 날짜 필드는 밀리세컨드가 기본이지만 타임 값을 가진 1h같은 형태일 수도 있다. ip는 long 값으로 인식되거나 또다른 IPv4 어드레스로 조합할 수 있다.

String fields

문자열 필드가 쿼리될때 퍼지는 Levenshtein Distance로 해석된다. 

The fuzziness parameter can be specified as:

0, 1, 2

최대 허용되는 Levenshtein Distance

AUTO

단어의 길이에 따라 자동으로 거리가 결정된다.

 0..2 -무조건 같아야 함

 3..5 - 하나 정도 틀려도 됨

 >5 - 두개 정도 틀려되 됨

AUTO가 퍼지 검색에 가장 적합하다.

0.0..1.0

수식을 이용하여 distance를 교정한다. length(term) * (1.0 - fuzziness), eg 0.6 퍼지는 길이가 10자인 단어의 교정거리는 4이다.

Note: all APIs except for the Fuzzy Like This Query, the maximum allowed edit distance is 2.

Result Casing

모든 REST API는 케이스 파라미터를 허용한다. camelCase로 세팅하면 모든 결과 필드명이 camel case로 리턴되며, underscore로 세팅도 사용할 수 있다.

인덱스된 소스 도큐먼트에는 적용할 수 없다는 것에 주의하자.

JSONP

황성화 되면 모든 REST API는 JSONP 결과의 콜백 파라미터 결과를 받는다. config.yaml을 수정하면 된다.

http.jsonp.enable: true

활성화하면 엘라스틱 서치 아키텍처로 인해 보안 이슈가 발생할 수 있다. 

Request body in query string

소스 쿼리 파라미터 대신에 request body를 이용하여 쿼리 문자열을 전달할 수 있다.

URL-based access control

많은 유저들이 URL 기반 접속 제어를 프록시를 이용하여 엘라스틱 서치 인덱스에 보안 접근을 수행한다. 멀티 서치, 멀티 연산 및 벌크 요청을 위해 유저는 URL에 특정한 인덱스를 지정한다. 

특정 URL의 인덱스를 유저에 의해 오버라이딩되는 것을 방지하기 위해 config.yml에 대해 다음과 같은 세팅을 추가할 수 있다.

rest.action.multi.allow_explicit_index: false

기본값은 true이나 false로 세팅하면 요청 바디에 특정한 인덱스를 명시한 요청은 거부될 것이다.