elasticsearch/docs/reference/search/uri-request.asciidoc

[[search-uri-request]]
=== URI Search

Specifies search criteria as query parameters in the request URI.

[source,console]
--------------------------------------------------
GET twitter/_search?q=user:kimchy
--------------------------------------------------
// TEST[setup:twitter]


[[search-uri-request-api-request]]
==== {api-request-title}

`GET /<index>/_search?q=<parameter>`


[[search-uri-request-api-desc]]
==== {api-description-title}

You can use query parameters to define your search criteria directly in the 
request URI, rather than in the request body. Request URI searches do not 
support the full {es} Query DSL, but are handy for testing.


[[search-uri-request-api-path-params]]
==== {api-path-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=index]


[[search-uri-request-api-query-params]]
==== {api-query-parms-title}

`allow_partial_search_results`:: 
  (Optional, boolean) Set to `false` to fail the request if only partial results 
  are available. Defaults to `true`, which returns partial results in the event 
  of timeouts or partial failures You can override the default behavior for all 
  requests by setting `search.default_allow_partial_results` to `false` in the 
  cluster settings.

include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
  
include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]

`batched_reduce_size`:: 
  (Optional, integer) The number of shard results that should be reduced at once 
  on the coordinating node. This value should be used as a protection mechanism 
  to reduce the memory overhead per search request if the potential number of 
  shards in the request can be large.

include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]

include::{docdir}/rest-api/common-parms.asciidoc[tag=df]

`explain`:: 
  (Optional, string) For each hit, include an explanation of how the score was 
  computed.

include::{docdir}/rest-api/common-parms.asciidoc[tag=from]

include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]

include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]

include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]

`size`:: 
  (Optional, integer) The number of hits to return. Defaults to `10`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=source]

include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]

include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]

`stored_fields`:: 
  (Optional, string) The selective stored fields of the document to return for 
  each hit, comma delimited. Not specifying any value will cause no fields to 
  return.

`sort`:: 
  (Optional, string) Sorting to perform. Can either be in the form of 
  `fieldName`, or `fieldName:asc`/`fieldName:desc`. The fieldName can either be 
  an actual field within the document, or the special `_score` name to indicate 
  sorting based on scores. There can be several `sort` parameters (order is 
  important).

`track_scores`:: 
  (Optional, boolean) When sorting, set to `true` in order to still track scores 
  and return them as part of each hit.

`track_total_hits`:: 
  (Optional, integer) Defaults to `10,000`. Set to `false` in order to disable 
  the tracking of the total number of hits that match the query. It also accepts 
  an integer which in this case represents the number of hits to count 
  accurately. (See the <<request-body-search-track-total-hits, request body>> 
  documentation for more details).

`timeout`::
  (Optional, <<time-units, time units>>) A search timeout, bounding the search 
  request to be executed within the specified time value and bail with the hits 
  accumulated up to that point when expired. Defaults to no timeout.

include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]


[[search-uri-request-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET twitter/_search?q=user:kimchy
--------------------------------------------------
// TEST[setup:twitter]


The API returns the following response:

[source,console-result]
--------------------------------------------------
{
    "timed_out": false,
    "took": 62,
    "_shards":{
        "total" : 1,
        "successful" : 1,
        "skipped" : 0,
        "failed" : 0
    },
    "hits":{
        "total" : {
            "value": 1,
            "relation": "eq"
        },
        "max_score": 1.3862942,
        "hits" : [
            {
                "_index" : "twitter",
                "_id" : "0",
                "_score": 1.3862942,
                "_source" : {
                    "user" : "kimchy",
                    "date" : "2009-11-15T14:12:12",
                    "message" : "trying out Elasticsearch",
                    "likes": 0
                }
            }
        ]
    }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 62/"took": "$body.took"/]