ElasticSearch 2 (4) - API Convention
ElasticSearch 2.1.1 (4) - API Convention
The elasticsearch REST APIs are exposed using JSON over HTTP.
Mutiple Indices
Simple notation
test1,test2,test3
_all
Wildcards
test*
Add & Remove
+test*,-test3
API support
-
ignore_unavailable
true or false -
allow_no_indices
true or false -
expand_wildcards
open or close none or all
Data match support in index names
A date math index name takes the following form:
<static_name{date_math_expr{date_format|time_zone}}>
-
static_name
is the static text part of the name
-
date_math_expr
is a dynamic date math expression that computes the date dynamically
-
date_format
is the optional format in which the computed date should be rendered. Defaults to YYYY.MM.dd.
-
time_zone
is the optional time zone . Defaults to utc.
curl -XGET 'localhost:9200/<logstash-{now%2Fd-2d}>/_search' { "query" : { ... } }The / used for date rounding must be url encoded as %2F in any url.
Expression:
Given the current time is 22rd March 2024 noon utc.
----------------------------------------------------------------------
Expression | Resolves to
----------------------------------------------------------------------
<logstash-{now/d}> | logstash-2024.03.22
----------------------------------------------------------------------
<logstash-{now/M}> | logstash-2024.03.01
----------------------------------------------------------------------
<logstash-{now/M{YYYY.MM}}> | logstash-2024.03
----------------------------------------------------------------------
<logstash-{now/M-1M{YYYY.MM}}> | logstash-2024.02
----------------------------------------------------------------------
<logstash-{now/d{YYYY.MM.dd|+12:00}} | logstash-2024.03.23
----------------------------------------------------------------------
Static {}:
<elastic\\{ON\\}-{now/M}> resolves to elastic{ON}-2024.03.01
Searches the Logstash indices for the past three days:
curl -XGET 'localhost:9200/<logstash-{now%2Fd-2d}>,<logstash-{now%2Fd-1d}>,<logstash-{now%2Fd}>/_search' {
"query" : {
...
}
}
Common options
Pretty Results
?pretty=true
?format=yaml
Human readable outputedit
?human=false ("exists_time_in_millis": 3600000 or "size_in_bytes": 1024)
?human=true ("exists_time": "1h" or "size": "1kb")
Date Math
-
range queries
gt and lt -
daterange aggregations
from and to -
expression
now or ||followed:
-
+1h - add one hour
-
-1h - substract one hour
-
/d - round down to the nearest day
supported time units:
y (year), M (month), w (week), d (day), h (hour), m (minute), and s (second)
-
-
examples
----------------------------------------------------------------------------------------- now+1h | The current time plus one hour, with ms resolution. ----------------------------------------------------------------------------------------- now+1h+1m | The current time plus one hour plus one minute, with ms resolution. ----------------------------------------------------------------------------------------- now+1h/d | The current time plus one hour, rounded down to the nearest day. ----------------------------------------------------------------------------------------- 2015-01-01||+1M/d | 2015-01-01 plus one month, rounded down to the nearest day. -----------------------------------------------------------------------------------------
Response Filtering
-
filter_path
curl -XGET 'localhost:9200/_search?pretty&filter_path=took,hits.hits._id,hits.hits._score' { "took" : 3, "hits" : { "hits" : [ { "_id" : "3640", "_score" : 1.0 }, { "_id" : "3642", "_score" : 1.0 } ] } } -
* wildcard
curl -XGET 'localhost:9200/_nodes/stats?filter_path=nodes.*.ho*' { "nodes" : { "lvJHed8uQQu4brS-SXKsNA" : { "host" : "portable" } } } -
** wildcard
curl 'localhost:9200/_segments?pretty&filter_path=indices.**.version' { "indices" : { "movies" : { "shards" : { "0" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ], "2" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ] } }, "books" : { "shards" : { "0" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ] } } } } -
_source
curl -XGET 'localhost:9200/_search?pretty&filter_path=hits.hits._source&_source=title' { "hits" : { "hits" : [ { "_source":{"title":"Book #2"} }, { "_source":{"title":"Book #1"} }, { "_source":{"title":"Book #3"} } ] } }
Flat Setting
-
true
{ "persistent" : { }, "transient" : { "discovery.zen.minimum_master_nodes" : "1" } } -
false (default)
{ "persistent" : { }, "transient" : { "discovery" : { "zen" : { "minimum_master_nodes" : "1" } } } }
Parameters
Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing.
Boolean Values
-
"false"
false, 0, no and off -
"true"
others
Number Values
Native JSON number types
string
Time units
------------------------------
y | Year
------------------------------
M | Month
------------------------------
w | Week
------------------------------
d | Day
------------------------------
h | Hour
------------------------------
m | Minute
------------------------------
s | Second
------------------------------
ms | Milli-second
------------------------------
Distance Units
-----------------------------------------
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
-----------------------------------------
The precision parameter in the Geohash Cell Query accepts distances with the above units, but if no unit is specified, then the precision is interpreted as the length of the geohash.
Fuzziness
-
Numberic, date and IPv4 fields
Range Query
-fuzziness <= field value <= +fuzzinessfuzziness
-
numberic
2 or 2.0 -
date
a long as milliseconds -
string
1h -
ip
a long or IPv4 address (will be converted into a long)
-
-
String fields
Levenshtein Edit Distance
-
0, 1, 2
-
AUTO
For lengths:
0..2 - must match exactly
3..5 - one edit allowed
>5 - two edits allowed
-
Result Casing
-
underscore casing (default)
-
camelCase
Note, this does not apply to the source document indexed.
Request body in query string
For libraries that don’t accept a request body for non-POST requests, you can pass the request body as the source query string parameter instead.
URL-based access control
config.yml file:
rest.action.multi.allow_explicit_index: false
Reference
https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html
