The simplest way to query ElasticSearch is to use the URI request query. For example, if we wanted to search for the word "crime" in the title field, we would send a query like this one:

curl -XGET 'localhost:9200/library/book/_search?q=title:crime&pretty=true'

If we look from the ElasticSearch Query DSL point of view, the simplest query is the term query, which searches for the documents that have a given term (a word) in a given field. For example, if we wanted to search for the term "crime" (please remember that the term query is not analyzed, and thus, you need to provide the exact term you are searching for) in the title field, we would send the following query to ElasticSearch:

{
 "query" : {
  "term" : { "title" : "crime" }
 }
}

But, how do we query our data? We send the GET HTTP request to the _search REST end point, pointing to the index/type we want to search (of course, we can omit type, index, or both at the same time). So, if we wanted to search our example library index, we would use the following command:

curl -XGET 'localhost:9200/library/book/_search?pretty=true' -d '{
 "query" : {
  "term" : { "title" : "crime" }
 }
}'

As you can see, we used the request body (the -d switch) to send the whole JSON-structured query to ElasticSearch. The pretty=true request parameter tells ElasticSearch to structure the response in a way such that we humans can read it more easily. In response, we got the following text:

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 0.19178301,
    "hits" : [ {
      "_index" : "library",
      "_type" : "book",
      "_id" : "4",
      "_score" : 0.19178301, "_source" : { "title": "Crime and Punishment","otitle": "Преступлéние и наказáние","author": "Fyodor Dostoevsky","year": 1886,"characters": ["Raskolnikov", "Sofia Semyonovna Marmeladova"],"tags": [],"copies": 0, "available" : true}
    } ]
  }
}

As we said earlier, a query can be directed to a particular index and type, but this is not the only possibility. We can query several indices in parallel or query one index regardless of the type. Let's sum up the possible call types and see what the addressing looks like:

Neat! We got our first search results!

As we would expect, ElasticSearch allows us to control how many results we want to get (at most) and from which result we want to start. There are two additional properties that can be set in the request body:

So, if we wanted our query to get documents starting from the tenth on the list and get 20 of them, we would send the following query:

{
 "from" :  9,
 "size" : 20,
 "query" : {
  "term" : { "title" : "crime" }
 }
}

In addition to all the information returned, ElasticSearch can return the version of the document. To do that, we need to add the version property with the value true to our JSON object (to its top level) so it looks like the following mapping:

{
 "version" : true,
 "query" : {
 "term" : { "title" : "crime" }
 }
}

After running it, we get the following results:

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 0.19178301,
    "hits" : [ {
      "_index" : "library",
      "_type" : "book",
      "_id" : "4",
      "_version" : 1,
      "_score" : 0.19178301, "_source" : { "title": "Crime and Punishment","otitle": "Преступлéние и наказáние","author": "Fyodor Dostoevsky","year": 1886,"characters": ["Raskolnikov", "Sofia Semyonovna Marmeladova"],"tags": [],"copies": 0, "available" : true}
    } ]
  }
}

As you can see, the _version section is present for the single hit we got.

For nonstandard use cases, ElasticSearch provides a feature that lets one filter the results on the basis of the minimum score value that the document must have to be considered a match. In order to use it, we must provide the min_score property on the top level of our JSON object with the value of the minimum score. For example, if we wanted our query to only return documents with scores higher than 0.75, we would send the following query:

{
 "min_score" : 0.75,
 "query" : {
  "term" : { "title" : "crime" }
 }
}

We get the following response after running the preceding query:

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 0,
    "max_score" : null,
    "hits" : [ ]
  }
}

Look at the previous examples; the score of our document was 0.19178301, which is lower than 0.75, and thus, we didn't get any document in response.

Limiting the score doesn't make much sense, usually, because comparing scores between queries is quite hard. However, maybe in your case this functionality will be needed.

With the use of the fields array in the request body, ElasticSearch allows us to define which fields should be included in the response. Please remember that you can only return fields that are marked as stored in the mappings used to create the index or if the _source field was used (ElasticSearch will use the _source field to provide the stored values). So, for example, if we want to return only the title and year fields in the results (for each document), we would send the following query to ElasticSearch:

{
 "fields" : [ "title", "year" ],
 "query" : {
  "term" : { "title" : "crime" }
 }
}

And, in response, we would get the following result:

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 0.19178301,
    "hits" : [ {
      "_index" : "library",
      "_type" : "book",
      "_id" : "4",
      "_score" : 0.19178301,
      "fields" : {
        "title" : "Crime and Punishment",
        "year" : 1886
      }
    } ]
  }
}

As you can see, everything worked as we wanted it to behave.

There are three things I would like to share with you:

{
 "partial_fields" : {
  "partial1" : {
   "include" : [ "titl*" ],
   "exclude" : [ "chara*" ]
  }
 },
 "query" : {
  "term" : { "title" : "crime" }
 }
}

ElasticSearch allows us to use script evaluated values to be returned with result documents. In order to use script fields, we need to add the script_fields section to our JSON query object and an object with the name we choose for each scripted value we want to return. For example, to return a value named correctYear that is calculated as the year field minus 1800, we would run the following query:

{
 "script_fields" : {
  "correctYear" : {
   "script" : "doc['year'].value – 1800"
  }
 },
 "query" : {
  "term" : { "title" : "crime" }
 }
}

However, if you run the preceding query against our sample data, you get an exception in the response as we don't store the year field. Yes, that's right. Only stored fields or the ones available in _source can be used. So, we will modify our query to use the _source field. After modifications, it should look like the following code:

{
 "script_fields" : {
  "correctYear" : {
   "script" : "_source.year – 1800"
  }
 },
 "query" : {
  "term" : { "title" : "crime" }
 }
}

Notice that we didn't use the value part of the equation. The following response will be returned by ElasticSearch for this query:

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 0.19178301,
    "hits" : [ {
      "_index" : "library",
      "_type" : "book",
      "_id" : "4",
      "_score" : 0.19178301,
      "fields" : {
        "correctYear" : 86
      }
    } ]
  }
}

As you can see, the correctYear field is in the response.

{
 "script_fields" : {
  "correctYear" : {
   "script" : "_source.year – paramYear",
   "params" : {
    "paramYear" : 1800
   }
  }
 },
 "query" : {
  "term" : { "title" : "crime" }
 }
}

ElasticSearch allows us to choose how we want our query to be processed internally. This is exposed to the end user because there are different situations where different search types are appropriate. To control how queries are executed, we can pass the search_type request parameter and set it to one of the following values:

So, if we wanted to use the simplest search type, we would run the following command:

curl -XGET 'localhost:9200/library/book/_search?pretty=true&search_type=query_and_fetch' -d '{
 "query" : {
  "term" : { "title" : "crime" }
 }
}'

In addition to all the previous possibilities of controlling your search, you have one more; you can control what types of shards the search will be executed on. By default, ElasticSearch uses both shards and replicas, available both on the node we've sent the request on and on the other nodes in the cluster. And the default behavior is mostly the proper method of shard preference for queries. But there may be times when we would want to change the default behavior. To do that, we can set the preference request parameter to one of the following values: