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 <= +fuzziness
  

  fuzziness

  • 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