diff options
Diffstat (limited to 'docs/reference/indices')
23 files changed, 1821 insertions, 0 deletions
diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc new file mode 100644 index 0000000..53f484c --- /dev/null +++ b/docs/reference/indices/aliases.asciidoc @@ -0,0 +1,348 @@ +[[indices-aliases]] +== Index Aliases + +APIs in elasticsearch accept an index name when working against a +specific index, and several indices when applicable. The index aliases +API allow to alias an index with a name, with all APIs automatically +converting the alias name to the actual index name. An alias can also be +mapped to more than one index, and when specifying it, the alias will +automatically expand to the aliases indices. An alias can also be +associated with a filter that will automatically be applied when +searching, and routing values. + +Here is a sample of associating the alias `alias1` with index `test1`: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { "add" : { "index" : "test1", "alias" : "alias1" } } + ] +}' +-------------------------------------------------- + +An alias can also be removed, for example: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { "remove" : { "index" : "test1", "alias" : "alias1" } } + ] +}' +-------------------------------------------------- + +Renaming an alias is a simple `remove` then `add` operation within the +same API. This operation is atomic, no need to worry about a short +period of time where the alias does not point to an index: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { "remove" : { "index" : "test1", "alias" : "alias1" } }, + { "add" : { "index" : "test1", "alias" : "alias2" } } + ] +}' +-------------------------------------------------- + +Associating an alias with more than one index are simply several `add` +actions: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { "add" : { "index" : "test1", "alias" : "alias1" } }, + { "add" : { "index" : "test2", "alias" : "alias1" } } + ] +}' +-------------------------------------------------- + +It is an error to index to an alias which points to more than one index. + +[float] +[[filtered]] +=== Filtered Aliases + +Aliases with filters provide an easy way to create different "views" of +the same index. The filter can be defined using Query DSL and is applied +to all Search, Count, Delete By Query and More Like This operations with +this alias. Here is an example: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { + "add" : { + "index" : "test1", + "alias" : "alias2", + "filter" : { "term" : { "user" : "kimchy" } } + } + } + ] +}' +-------------------------------------------------- + +[float] +[[aliases-routing]] +==== Routing + +It is possible to associate routing values with aliases. This feature +can be used together with filtering aliases in order to avoid +unnecessary shard operations. + +The following command creates a new alias `alias1` that points to index +`test`. After `alias1` is created, all operations with this alias are +automatically modified to use value `1` for routing: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { + "add" : { + "index" : "test", + "alias" : "alias1", + "routing" : "1" + } + } + ] +}' +-------------------------------------------------- + +It's also possible to specify different routing values for searching +and indexing operations: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/_aliases' -d ' +{ + "actions" : [ + { + "add" : { + "index" : "test", + "alias" : "alias2", + "search_routing" : "1,2", + "index_routing" : "2" + } + } + ] +}' +-------------------------------------------------- + +As shown in the example above, search routing may contain several values +separated by comma. Index routing can contain only a single value. + +If an operation that uses routing alias also has a routing parameter, an +intersection of both alias routing and routing specified in the +parameter is used. For example the following command will use "2" as a +routing value: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/alias2/_search?q=user:kimchy&routing=2,3' +-------------------------------------------------- + +[float] +[[alias-adding]] +=== Add a single alias + +An alias can also be added with the endpoint + +`PUT /{index}/_alias/{name}` + + +where + +[horizontal] +`index`:: The index to alias refers to. Can be any of `blank | * | _all | glob pattern | name1, name2, …` +`name`:: The name of the alias. This is a required option. +`routing`:: An optional routing that can be associated with an alias. +`filter`:: An optional filter that can be associated with an alias. + +You can also use the plural `_aliases`. + +[float] +==== Examples: + +Adding time based alias: + +[source,js] +-------------------------------------------------- +curl -XPUT 'localhost:9200/logs_201305/_alias/2013' +-------------------------------------------------- + +Adding user alias: + +[source,js] +-------------------------------------------------- +curl -XPUT 'localhost:9200/users/_alias/user_12' -d '{ + "routing" : "12", + "filter" : { + "term" : { + "user_id" : 12 + } + } +}' +-------------------------------------------------- + +[float] +[[deleting]] +=== Delete aliases + + +The rest endpoint is: `/{index}/_alias/{name}` + +where + +[horizontal] +`index`:: `* | _all | glob pattern | name1, name2, …` +`name`:: `* | _all | glob pattern | name1, name2, …` + +Alternatively you can use the plural `_aliases`. Example: + +[source,js] +-------------------------------------------------- +curl -XDELETE 'localhost:9200/users/_alias/user_12' +-------------------------------------------------- + +[float] +[[alias-retrieving]] +=== Retrieving existing aliases + +The get index alias api allows to filter by +alias name and index name. This api redirects to the master and fetches +the requested index aliases, if available. This api only serialises the +found index aliases. + +Possible options: +[horizontal] +`index`:: + + The index name to get aliases for. Partially names are + supported via wildcards, also multiple index names can be specified + separated with a comma. Also the alias name for an index can be used. + +`alias`:: + The name of alias to return in the response. Like the index + option, this option supports wildcards and the option the specify + multiple alias names separated by a comma. + +`ignore_unavailable`:: + What to do is an specified index name doesn't + exist. If set to `true` then those indices are ignored. + +The rest endpoint is: `/{index}/_alias/{alias}`. + +[float] +==== Examples: + +All aliases for the index users: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/users/_alias/*' +-------------------------------------------------- + +Response: + +[source,js] +-------------------------------------------------- + { + "users" : { + "aliases" : { + "user_13" : { + "filter" : { + "term" : { + "user_id" : 13 + } + }, + "index_routing" : "13", + "search_routing" : "13" + }, + "user_14" : { + "filter" : { + "term" : { + "user_id" : 14 + } + }, + "index_routing" : "14", + "search_routing" : "14" + }, + "user_12" : { + "filter" : { + "term" : { + "user_id" : 12 + } + }, + "index_routing" : "12", + "search_routing" : "12" + } + } + } +} +-------------------------------------------------- + +All aliases with the name 2013 in any index: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/_alias/2013' +-------------------------------------------------- + +Response: + +[source,js] +-------------------------------------------------- +{ + "logs_201304" : { + "aliases" : { + "2013" : { } + } + }, + "logs_201305" : { + "aliases" : { + "2013" : { } + } + } +} +-------------------------------------------------- + +All aliases that start with 2013_01 in any index: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/_alias/2013_01*' +-------------------------------------------------- + +Response: + +[source,js] +-------------------------------------------------- +{ + "logs_20130101" : { + "aliases" : { + "2013_01" : { } + } + } +} +-------------------------------------------------- + +There is also a HEAD variant of the get indices aliases api to check if +index aliases exist. The indices aliases exists api supports the same +option as the get indices aliases api. Examples: + +[source,js] +-------------------------------------------------- +curl -XHEAD 'localhost:9200/_alias/2013' +curl -XHEAD 'localhost:9200/_alias/2013_01*' +curl -XHEAD 'localhost:9200/users/_alias/*' +-------------------------------------------------- diff --git a/docs/reference/indices/analyze.asciidoc b/docs/reference/indices/analyze.asciidoc new file mode 100644 index 0000000..a9712d6 --- /dev/null +++ b/docs/reference/indices/analyze.asciidoc @@ -0,0 +1,50 @@ +[[indices-analyze]] +== Analyze + +Performs the analysis process on a text and return the tokens breakdown +of the text. + +Can be used without specifying an index against one of the many built in +analyzers: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/_analyze?analyzer=standard' -d 'this is a test' +-------------------------------------------------- + +Or by building a custom transient analyzer out of tokenizers and +filters: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/_analyze?tokenizer=keyword&filters=lowercase' -d 'this is a test' +-------------------------------------------------- + +It can also run against a specific index: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/test/_analyze?text=this+is+a+test' +-------------------------------------------------- + +The above will run an analysis on the "this is a test" text, using the +default index analyzer associated with the `test` index. An `analyzer` +can also be provided to use a different analyzer: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/test/_analyze?analyzer=whitespace' -d 'this is a test' +-------------------------------------------------- + +Also, the analyzer can be derived based on a field mapping, for example: + +[source,js] +-------------------------------------------------- +curl -XGET 'localhost:9200/test/_analyze?field=obj1.field1' -d 'this is a test' +-------------------------------------------------- + +Will cause the analysis to happen based on the analyzer configure in the +mapping for `obj1.field1` (and if not, the default index analyzer). + +Also, the text can be provided as part of the request body, and not as a +parameter. diff --git a/docs/reference/indices/clearcache.asciidoc b/docs/reference/indices/clearcache.asciidoc new file mode 100644 index 0000000..aed2470 --- /dev/null +++ b/docs/reference/indices/clearcache.asciidoc @@ -0,0 +1,34 @@ +[[indices-clearcache]] +== Clear Cache + +The clear cache API allows to clear either all caches or specific cached +associated with one ore more indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/twitter/_cache/clear' +-------------------------------------------------- + +The API, by default, will clear all caches. Specific caches can be +cleaned explicitly by setting `filter`, `field_data` or `id_cache` to +`true`. + +All caches relating to a specific field(s) can also be cleared by +specifying `fields` parameter with a comma delimited list of the +relevant fields. + +[float] +=== Multi Index + +The clear cache API can be applied to more than one index with a single +call, or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/kimchy,elasticsearch/_cache/clear' + +$ curl -XPOST 'http://localhost:9200/_cache/clear' +-------------------------------------------------- + +NOTE: The `filter` cache is not cleared immediately but is scheduled to be +cleared within 60 seconds. diff --git a/docs/reference/indices/create-index.asciidoc b/docs/reference/indices/create-index.asciidoc new file mode 100644 index 0000000..0b069d3 --- /dev/null +++ b/docs/reference/indices/create-index.asciidoc @@ -0,0 +1,106 @@ +[[indices-create-index]] +== Create Index + +The create index API allows to instantiate an index. Elasticsearch +provides support for multiple indices, including executing operations +across several indices. + +[float] +[[create-index-settings]] +=== Index Settings + +Each index created can have specific settings +associated with it. + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/twitter/' + +$ curl -XPUT 'http://localhost:9200/twitter/' -d ' +index : + number_of_shards : 3 + number_of_replicas : 2 +' +-------------------------------------------------- + +The above second curl example shows how an index called `twitter` can be +created with specific settings for it using http://www.yaml.org[YAML]. +In this case, creating an index with 3 shards, each with 2 replicas. The +index settings can also be defined with http://www.json.org[JSON]: + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/twitter/' -d '{ + "settings" : { + "index" : { + "number_of_shards" : 3, + "number_of_replicas" : 2 + } + } +}' +-------------------------------------------------- + +or more simplified + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/twitter/' -d '{ + "settings" : { + "number_of_shards" : 3, + "number_of_replicas" : 2 + } +}' +-------------------------------------------------- + +[NOTE] +You do not have to explicitly specify `index` section inside the +`settings` section. + +For more information regarding all the different index level settings +that can be set when creating an index, please check the +<<index-modules,index modules>> section. + + +[float] +[[mappings]] +=== Mappings + +The create index API allows to provide a set of one or more mappings: + +[source,js] +-------------------------------------------------- +curl -XPOST localhost:9200/test -d '{ + "settings" : { + "number_of_shards" : 1 + }, + "mappings" : { + "type1" : { + "_source" : { "enabled" : false }, + "properties" : { + "field1" : { "type" : "string", "index" : "not_analyzed" } + } + } + } +}' +-------------------------------------------------- + +[float] +[[warmers]] +=== Warmers + +The create index API allows also to provide a set of <<indices-warmers,warmers>>: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test -d '{ + "warmers" : { + "warmer_1" : { + "source" : { + "query" : { + ... + } + } + } + } +}' +-------------------------------------------------- diff --git a/docs/reference/indices/delete-index.asciidoc b/docs/reference/indices/delete-index.asciidoc new file mode 100644 index 0000000..25d1766 --- /dev/null +++ b/docs/reference/indices/delete-index.asciidoc @@ -0,0 +1,19 @@ +[[indices-delete-index]] +== Delete Index + +The delete index API allows to delete an existing index. + +[source,js] +-------------------------------------------------- +$ curl -XDELETE 'http://localhost:9200/twitter/' +-------------------------------------------------- + +The above example deletes an index called `twitter`. Specifying an index, +alias or wildcard expression is required. + +The delete index API can also be applied to more than one index, or on +all indices (be careful!) by using `_all` or `*` as index. + +In order to disable allowing to delete indices via wildcards or `_all`, +set `action.destructive_requires_name` setting in the config to `true`. +This setting can also be changed via the cluster update settings api.
\ No newline at end of file diff --git a/docs/reference/indices/delete-mapping.asciidoc b/docs/reference/indices/delete-mapping.asciidoc new file mode 100644 index 0000000..9b72d9c --- /dev/null +++ b/docs/reference/indices/delete-mapping.asciidoc @@ -0,0 +1,25 @@ +[[indices-delete-mapping]] +== Delete Mapping + +Allow to delete a mapping (type) along with its data. The REST endpoints are + +[source,js] +-------------------------------------------------- + +[DELETE] /{index}/{type} + +[DELETE] /{index}/{type}/_mapping + +[DELETE] /{index}/_mapping/{type} + +-------------------------------------------------- + +where + +[horizontal] + +`index`:: `* | _all | glob pattern | name1, name2, …` +`type`:: `* | _all | glob pattern | name1, name2, …` + +Note, most times, it make more sense to reindex the data into a fresh +index compared to delete large chunks of it. diff --git a/docs/reference/indices/flush.asciidoc b/docs/reference/indices/flush.asciidoc new file mode 100644 index 0000000..75b935a --- /dev/null +++ b/docs/reference/indices/flush.asciidoc @@ -0,0 +1,27 @@ +[[indices-flush]] +== Flush + +The flush API allows to flush one or more indices through an API. The +flush process of an index basically frees memory from the index by +flushing data to the index storage and clearing the internal +<<index-modules-translog,transaction log>>. By +default, Elasticsearch uses memory heuristics in order to automatically +trigger flush operations as required in order to clear memory. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/twitter/_flush' +-------------------------------------------------- + +[float] +=== Multi Index + +The flush API can be applied to more than one index with a single call, +or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/kimchy,elasticsearch/_flush' + +$ curl -XPOST 'http://localhost:9200/_flush' +-------------------------------------------------- diff --git a/docs/reference/indices/gateway-snapshot.asciidoc b/docs/reference/indices/gateway-snapshot.asciidoc new file mode 100644 index 0000000..188d1aa --- /dev/null +++ b/docs/reference/indices/gateway-snapshot.asciidoc @@ -0,0 +1,29 @@ +[[indices-gateway-snapshot]] +== Gateway Snapshot + +The gateway snapshot API allows to explicitly perform a snapshot through +the gateway of one or more indices (backup them). By default, each index +gateway periodically snapshot changes, though it can be disabled and be +controlled completely through this API. + +Note, this API only applies when using shared storage gateway +implementation, and does not apply when using the (default) local +gateway. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/twitter/_gateway/snapshot' +-------------------------------------------------- + +[float] +=== Multi Index + +The gateway snapshot API can be applied to more than one index with a +single call, or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/kimchy,elasticsearch/_gateway/snapshot' + +$ curl -XPOST 'http://localhost:9200/_gateway/snapshot' +-------------------------------------------------- diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc new file mode 100644 index 0000000..0633744 --- /dev/null +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -0,0 +1,140 @@ +[[indices-get-field-mapping]] +== Get Field Mapping + +The get field mapping API allows you to retrieve mapping definitions for one or more fields. +This is useful when you do not need the complete type mapping returned by +the <<indices-get-mapping>> API. + +The following returns the mapping of the field `text` only: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter/tweet/_mapping/field/text' +-------------------------------------------------- + +For which the response is (assuming `text` is a default string field): + +[source,js] +-------------------------------------------------- +{ + "twitter": { + "tweet": { + "text": { + "full_name": "text", + "mapping": { + "text": { "type": "string" } + } + } + } + } +} +-------------------------------------------------- + + + +[float] +=== Multiple Indices, Types and Fields + +The get field mapping API can be used to get the mapping of multiple fields from more than one index or type +with a single call. General usage of the API follows the +following syntax: `host:port/{index}/{type}/_mapping/field/{field}` where +`{index}`, `{type}` and `{field}` can stand for comma-separated list of names or wild cards. To +get mappings for all indices you can use `_all` for `{index}`. The +following are some examples: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter,kimchy/_mapping/field/message' + +curl -XGET 'http://localhost:9200/_all/tweet,book/_mapping/field/message,user.id' + +curl -XGET 'http://localhost:9200/_all/tw*/_mapping/field/*.id' +-------------------------------------------------- + +[float] +=== Specifying fields + +The get mapping api allows you to specify one or more fields separated with by a comma. +You can also use wildcards. The field names can be any of the following: + +[horizontal] +Full names:: the full path, including any parent object name the field is + part of (ex. `user.id`). +Index names:: the name of the lucene field (can be different than the + field name if the `index_name` option of the mapping is used). +Field names:: the name of the field without the path to it (ex. `id` for `{ "user" : { "id" : 1 } }`). + +The above options are specified in the order the `field` parameter is resolved. +The first field found which matches is returned. This is especially important +if index names or field names are used as those can be ambiguous. + +For example, consider the following mapping: + +[source,js] +-------------------------------------------------- + { + "article": { + "properties": { + "id": { "type": "string" }, + "title": { "type": "string", "index_name": "text" }, + "abstract": { "type": "string", "index_name": "text" }, + "author": { + "properties": { + "id": { "type": "string" }, + "name": { "type": "string", "index_name": "author" } + } + } + } + } + } +-------------------------------------------------- + +To select the `id` of the `author` field, you can use its full name `author.id`. Using `text` will return +the mapping of `abstract` as it is one of the fields which map to the Lucene field `text`. `name` will return +the field `author.name`: + +[source,js] +-------------------------------------------------- +curl -XGET "http://localhost:9200/publications/article/_mapping/field/author.id,text,name" +-------------------------------------------------- + +returns: + +[source,js] +-------------------------------------------------- +{ + "publications": { + "article": { + "text": { + "full_name": "abstract", + "mapping": { + "abstract": { "type": "string", "index_name": "text" } + } + }, + "author.id": { + "full_name": "author.id", + "mapping": { + "id": { "type": "string" } + } + }, + "name": { + "full_name": "author.name", + "mapping": { + "name": { "type": "string", "index_name": "author" } + } + } + } + } +} +-------------------------------------------------- + +Note how the response always use the same fields specified in the request as keys. +The `full_name` in every entry contains the full name of the field whose mapping were returned. +This is useful when the request can refer to to multiple fields (like `text` above). + +[float] +=== Other options + +[horizontal] +include_defaults:: adding `include_defaults=true` to the query string will cause the response to +include default values, which are normally suppressed. diff --git a/docs/reference/indices/get-mapping.asciidoc b/docs/reference/indices/get-mapping.asciidoc new file mode 100644 index 0000000..a64b14d --- /dev/null +++ b/docs/reference/indices/get-mapping.asciidoc @@ -0,0 +1,37 @@ +[[indices-get-mapping]] +== Get Mapping + +The get mapping API allows to retrieve mapping definition of index or +index/type. + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter/tweet/_mapping' +-------------------------------------------------- + +[float] +=== Multiple Indices and Types + +The get mapping API can be used to get more than one index or type +mapping with a single call. General usage of the API follows the +following syntax: `host:port/{index}/{type}/_mapping` where both +`{index}` and `{type}` can stand for comma-separated list of names. To +get mappings for all indices you can use `_all` for `{index}`. The +following are some examples: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter,kimchy/_mapping' + +curl -XGET 'http://localhost:9200/_all/tweet,book/_mapping' +-------------------------------------------------- + +If you want to get mappings of all indices and types then the following +two examples are equivalent: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/_all/_mapping' + +curl -XGET 'http://localhost:9200/_mapping' +-------------------------------------------------- diff --git a/docs/reference/indices/get-settings.asciidoc b/docs/reference/indices/get-settings.asciidoc new file mode 100644 index 0000000..a5950c2 --- /dev/null +++ b/docs/reference/indices/get-settings.asciidoc @@ -0,0 +1,50 @@ +[[indices-get-settings]] +== Get Settings + +The get settings API allows to retrieve settings of index/indices: + +[source,js] +-------------------------------------------------- +$ curl -XGET 'http://localhost:9200/twitter/_settings' +-------------------------------------------------- + +[float] +=== Multiple Indices and Types + +The get settings API can be used to get settings for more than one index +with a single call. General usage of the API follows the +following syntax: `host:port/{index}/_settings` where +`{index}` can stand for comma-separated list of index names and aliases. To +get settings for all indices you can use `_all` for `{index}`. +Wildcard expressions are also supported. The following are some examples: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter,kimchy/_settings' + +curl -XGET 'http://localhost:9200/_all/_settings' + +curl -XGET 'http://localhost:9200/2013-*/_settings' +-------------------------------------------------- + +[float] +=== Prefix option + +There is also support for a `prefix` query string option +that allows to include only settings matches the specified prefix. + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/my-index/_settings?prefix=index.' + +curl -XGET 'http://localhost:9200/_all/_settings?prefix=index.routing.allocation.' + +curl -XGET 'http://localhost:9200/2013-*/_settings?name=index.merge.*' + +curl -XGET 'http://localhost:9200/2013-*/_settings/index.merge.*' +-------------------------------------------------- + +The first example returns all index settings the start with `index.` in the index `my-index`, +the second example gets all index settings that start with `index.routing.allocation.` for +all indices, lastly the third example returns all index settings that start with `index.merge.` +in indices that start with `2013-`. diff --git a/docs/reference/indices/indices-exists.asciidoc b/docs/reference/indices/indices-exists.asciidoc new file mode 100644 index 0000000..422dcba --- /dev/null +++ b/docs/reference/indices/indices-exists.asciidoc @@ -0,0 +1,12 @@ +[[indices-exists]] +== Indices Exists + +Used to check if the index (indices) exists or not. For example: + +[source,js] +-------------------------------------------------- +curl -XHEAD 'http://localhost:9200/twitter' +-------------------------------------------------- + +The HTTP status code indicates if the index exists or not. A `404` means +it does not exist, and `200` means it does. diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc new file mode 100644 index 0000000..29259d2 --- /dev/null +++ b/docs/reference/indices/open-close.asciidoc @@ -0,0 +1,29 @@ +[[indices-open-close]] +== Open / Close Index API + +The open and close index APIs allow to close an index, and later on +opening it. A closed index has almost no overhead on the cluster (except +for maintaining its metadata), and is blocked for read/write operations. +A closed index can be opened which will then go through the normal +recovery process. + +The REST endpoint is `/{index}/_close` and `/{index}/_open`. For +example: + +[source,js] +-------------------------------------------------- +curl -XPOST 'localhost:9200/my_index/_close' + +curl -XPOST 'localhost:9200/my_index/_open' +-------------------------------------------------- + +It is possible to open and close multiple indices. An error will be thrown +if the request explicitly refers to a missing index. This behaviour can be +disabled using the `ignore_unavailable=true` parameter. + +All indices can be opened or closed at once using `_all` as the index name +or specifying patterns that identify them all (e.g. `*`). + +Identifying indices via wildcards or `_all` can be disabled by setting the +`action.destructive_requires_name` flag in the config file to `true`. +This setting can also be changed via the cluster update settings api.
\ No newline at end of file diff --git a/docs/reference/indices/optimize.asciidoc b/docs/reference/indices/optimize.asciidoc new file mode 100644 index 0000000..d8ebc8b --- /dev/null +++ b/docs/reference/indices/optimize.asciidoc @@ -0,0 +1,51 @@ +[[indices-optimize]] +== Optimize + +The optimize API allows to optimize one or more indices through an API. +The optimize process basically optimizes the index for faster search +operations (and relates to the number of segments a Lucene index holds +within each shard). The optimize operation allows to reduce the number +of segments by merging them. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/twitter/_optimize' +-------------------------------------------------- + +[float] +[[optimize-parameters]] +=== Request Parameters + +The optimize API accepts the following request parameters: + +[horizontal] +`max_num_segments`:: The number of segments to optimize to. To fully +optimize the index, set it to `1`. Defaults to simply checking if a +merge needs to execute, and if so, executes it. + +`only_expunge_deletes`:: Should the optimize process only expunge segments +with deletes in it. In Lucene, a document is not deleted from a segment, +just marked as deleted. During a merge process of segments, a new +segment is created that does not have those deletes. This flag allow to +only merge segments that have deletes. Defaults to `false`. + +`flush`:: Should a flush be performed after the optimize. Defaults to +`true`. + +`wait_for_merge`:: Should the request wait for the merge to end. Defaults +to `true`. Note, a merge can potentially be a very heavy operation, so +it might make sense to run it set to `false`. + +[float] +[[optimize-multi-index]] +=== Multi Index + +The optimize API can be applied to more than one index with a single +call, or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/kimchy,elasticsearch/_optimize' + +$ curl -XPOST 'http://localhost:9200/_optimize' +-------------------------------------------------- diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc new file mode 100644 index 0000000..7748625 --- /dev/null +++ b/docs/reference/indices/put-mapping.asciidoc @@ -0,0 +1,83 @@ +[[indices-put-mapping]] +== Put Mapping + +The put mapping API allows to register specific mapping definition for a +specific type. + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/twitter/tweet/_mapping' -d ' +{ + "tweet" : { + "properties" : { + "message" : {"type" : "string", "store" : true } + } + } +} +' +-------------------------------------------------- + +The above example creates a mapping called `tweet` within the `twitter` +index. The mapping simply defines that the `message` field should be +stored (by default, fields are not stored, just indexed) so we can +retrieve it later on using selective loading. + +More information on how to define type mappings can be found in the +<<mapping,mapping>> section. + +[float] +[[merging-conflicts]] +=== Merging & Conflicts + +When an existing mapping already exists under the given type, the two +mapping definitions, the one already defined, and the new ones are +merged. The `ignore_conflicts` parameters can be used to control if +conflicts should be ignored or not, by default, it is set to `false` +which means conflicts are *not* ignored. + +The definition of conflict is really dependent on the type merged, but +in general, if a different core type is defined, it is considered as a +conflict. New mapping definitions can be added to object types, and core +type mapping can be upgraded by specifying multi fields on a core type. + +[float] +[[put-mapping-multi-index]] +=== Multi Index + +The put mapping API can be applied to more than one index with a single +call, or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/kimchy,elasticsearch/tweet/_mapping' -d ' +{ + "tweet" : { + "properties" : { + "message" : {"type" : "string", "store" : true } + } + } +} +' +-------------------------------------------------- + +All options: + +[source,js] +-------------------------------------------------- + +PUT /{index}/_mapping/{type} + + +-------------------------------------------------- + + +where + +[horizontal] +`{index}`:: `blank | * | _all | glob pattern | name1, name2, …` + +`{type}`:: Name of the type to add. Must be the name of the type defined in the body. + + +Instead of `_mapping` you can also use the plural `_mappings`. +The uri `PUT /{index}/{type}/_mapping` is still supported for backwardscompatibility. diff --git a/docs/reference/indices/refresh.asciidoc b/docs/reference/indices/refresh.asciidoc new file mode 100644 index 0000000..bbc1f20 --- /dev/null +++ b/docs/reference/indices/refresh.asciidoc @@ -0,0 +1,26 @@ +[[indices-refresh]] +== Refresh + +The refresh API allows to explicitly refresh one or more index, making +all operations performed since the last refresh available for search. +The (near) real-time capabilities depend on the index engine used. For +example, the internal one requires refresh to be called, but by default a +refresh is scheduled periodically. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/twitter/_refresh' +-------------------------------------------------- + +[float] +=== Multi Index + +The refresh API can be applied to more than one index with a single +call, or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/kimchy,elasticsearch/_refresh' + +$ curl -XPOST 'http://localhost:9200/_refresh' +-------------------------------------------------- diff --git a/docs/reference/indices/segments.asciidoc b/docs/reference/indices/segments.asciidoc new file mode 100644 index 0000000..bc4a7ff --- /dev/null +++ b/docs/reference/indices/segments.asciidoc @@ -0,0 +1,76 @@ +[[indices-segments]] +== Indices Segments + +Provide low level segments information that a Lucene index (shard level) +is built with. Allows to be used to provide more information on the +state of a shard and an index, possibly optimization information, data +"wasted" on deletes, and so on. + +Endpoints include segments for a specific index, several indices, or +all: + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/test/_segments' +curl -XGET 'http://localhost:9200/test1,test2/_segments' +curl -XGET 'http://localhost:9200/_segments' +-------------------------------------------------- + +Response: + +[source,js] +-------------------------------------------------- +{ + ... + "_3": { + "generation": 3, + "num_docs": 1121, + "deleted_docs": 53, + "size_in_bytes": 228288, + "memory_in_bytes": 3211, + "committed": true, + "search": true, + "version": "4.6", + "compound": true + } + ... +} +-------------------------------------------------- + +_0:: The key of the JSON document is the name of the segment. This name + is used to generate file names: all files starting with this + segment name in the directory of the shard belong to this segment. + +generation:: A generation number that is basically incremented when needing to + write a new segment. The segment name is derived from this + generation number. + +num_docs:: The number of non-deleted documents that are stored in this segment. + +deleted_docs:: The number of deleted documents that are stored in this segment. + It is perfectly fine if this number is greater than 0, space is + going to be reclaimed when this segment gets merged. + +size_in_bytes:: The amount of disk space that this segment uses, in bytes. + +memory_in_bytes:: Segments need to store some data into memory in order to be + searchable efficiently. This number returns the number of bytes + that are used for that purpose. A value of -1 indicates that + Elasticsearch was not able to compute this number. + +committed:: Whether the segment has been sync'ed on disk. Segments that are + committed would survive a hard reboot. No need to worry in case + of false, the data from uncommitted segments is also stored in + the transaction log so that Elasticsearch is able to replay + changes on the next start. + +search:: Whether the segment is searchable. A value of false would most + likely mean that the segment has been written to disk but no + refresh occurred since then to make it searchable. + +version:: The version of Lucene that has been used to write this segment. + +compound:: Whether the segment is stored in a compound file. When true, this + means that Lucene merged all files from the segment in a single + one in order to save file descriptors. + diff --git a/docs/reference/indices/stats.asciidoc b/docs/reference/indices/stats.asciidoc new file mode 100644 index 0000000..b0dd311 --- /dev/null +++ b/docs/reference/indices/stats.asciidoc @@ -0,0 +1,76 @@ +[[indices-stats]] +== Indices Stats + +Indices level stats provide statistics on different operations happening +on an index. The API provides statistics on the index level scope +(though most stats can also be retrieved using node level scope). + +The following returns high level aggregation and index level stats for +all indices: + +[source,js] +-------------------------------------------------- +curl localhost:9200/_stats +-------------------------------------------------- + +Specific index stats can be retrieved using: + +[source,js] +-------------------------------------------------- +curl localhost:9200/index1,index2/_stats +-------------------------------------------------- + +By default, all stats are returned, returning only specific stats can be +specified as well in the URI. Those stats can be any of: + +[horizontal] +`docs`:: The number of docs / deleted docs (docs not yet merged out). + Note, affected by refreshing the index. + +`store`:: The size of the index. + +`indexing`:: Indexing statistics, can be combined with a comma + separated list of `types` to provide document type level stats. + +`get`:: Get statistics, including missing stats. + +`search`:: Search statistics. You can include statistics for custom groups by adding + an extra `groups` parameter (search operations can be associated with one or more + groups). The `groups` parameter accepts a comma separated list of group names. + Use `_all` to return statistics for all groups. + +`warmer`:: Warmer statistics. +`merge`:: Merge statistics. +`fielddata`:: Fielddata statistics. +`flush`:: Flush statistics. +`completion`:: Completion suggest statistics. +`refresh`:: Refresh statistics. + +Some statistics allow per field granularity which accepts a list comma-separated list of included fields. By default all fields are included: + +[horizontal] +`fields`:: List of fields to be included in the statistics. This is used as the default list unless a more specific field list is provided (see below). +`completion_fields`:: List of fields to be included in the Completion Suggest statistics +`fielddata_fields`:: List of fields to be included in the Fielddata statistics + +Here are some samples: + +[source,js] +-------------------------------------------------- +# Get back stats for merge and refresh only for all indices +curl 'localhost:9200/_stats/merge,refresh' +# Get back stats for type1 and type2 documents for the my_index index +curl 'localhost:9200/my_index/_stats/indexing?types=type1,type2 +# Get back just search stats for group1 and group2 +curl 'localhost:9200/_stats/search?groups=group1,group2 +-------------------------------------------------- + +The stats returned are aggregated on the index level, with +`primaries` and `total` aggregations. In order to get back shard level +stats, set the `level` parameter to `shards`. + +Note, as shards move around the cluster, their stats will be cleared as +they are created on other nodes. On the other hand, even though a shard +"left" a node, that node will still retain the stats that shard +contributed to. + diff --git a/docs/reference/indices/status.asciidoc b/docs/reference/indices/status.asciidoc new file mode 100644 index 0000000..c454b0f --- /dev/null +++ b/docs/reference/indices/status.asciidoc @@ -0,0 +1,27 @@ +[[indices-status]] +== Status + +The indices status API allows to get a comprehensive status information +of one or more indices. + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/twitter/_status' +-------------------------------------------------- + +In order to see the recovery status of shards, pass `recovery` flag and +set it to `true`. For snapshot status, pass the `snapshot` flag and set +it to `true`. + +[float] +=== Multi Index + +The status API can be applied to more than one index with a single call, +or even on `_all` the indices. + +[source,js] +-------------------------------------------------- +curl -XGET 'http://localhost:9200/kimchy,elasticsearch/_status' + +curl -XGET 'http://localhost:9200/_status' +-------------------------------------------------- diff --git a/docs/reference/indices/templates.asciidoc b/docs/reference/indices/templates.asciidoc new file mode 100644 index 0000000..ce1c33c --- /dev/null +++ b/docs/reference/indices/templates.asciidoc @@ -0,0 +1,155 @@ +[[indices-templates]] +== Index Templates + +Index templates allow to define templates that will automatically be +applied to new indices created. The templates include both settings and +mappings, and a simple pattern template that controls if the template +will be applied to the index created. For example: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/_template/template_1 -d ' +{ + "template" : "te*", + "settings" : { + "number_of_shards" : 1 + }, + "mappings" : { + "type1" : { + "_source" : { "enabled" : false } + } + } +} +' +-------------------------------------------------- + +Defines a template named template_1, with a template pattern of `te*`. +The settings and mappings will be applied to any index name that matches +the `te*` template. + +[float] +[[delete]] +=== Deleting a Template + +Index templates are identified by a name (in the above case +`template_1`) and can be delete as well: + +[source,js] +-------------------------------------------------- +curl -XDELETE localhost:9200/_template/template_1 +-------------------------------------------------- + +[float] +[[getting]] +=== GETting templates + +Index templates are identified by a name (in the above case +`template_1`) and can be retrieved using the following: + +[source,js] +-------------------------------------------------- +curl -XGET localhost:9200/_template/template_1 +-------------------------------------------------- + +You can also match several templates by using wildcards like: + +[source,js] +-------------------------------------------------- +curl -XGET localhost:9200/_template/temp* +curl -XGET localhost:9200/_template/template_1,template_2 +-------------------------------------------------- + +To get list of all index templates you can use +<<cluster-state,Cluster State>> API +and check for the metadata/templates section of the response. + +Or run: + +[source,js] +-------------------------------------------------- +curl -XGET localhost:9200/_template/ +-------------------------------------------------- + + +[float] +[[multiple-templates]] +=== Multiple Template Matching + +Multiple index templates can potentially match an index, in this case, +both the settings and mappings are merged into the final configuration +of the index. The order of the merging can be controlled using the +`order` parameter, with lower order being applied first, and higher +orders overriding them. For example: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/_template/template_1 -d ' +{ + "template" : "*", + "order" : 0, + "settings" : { + "number_of_shards" : 1 + }, + "mappings" : { + "type1" : { + "_source" : { "enabled" : false } + } + } +} +' + +curl -XPUT localhost:9200/_template/template_2 -d ' +{ + "template" : "te*", + "order" : 1, + "settings" : { + "number_of_shards" : 1 + }, + "mappings" : { + "type1" : { + "_source" : { "enabled" : true } + } + } +} +' +-------------------------------------------------- + +The above will disable storing the `_source` on all `type1` types, but +for indices of that start with `te*`, source will still be enabled. +Note, for mappings, the merging is "deep", meaning that specific +object/property based mappings can easily be added/overridden on higher +order templates, with lower order templates providing the basis. + +[float] +[[config]] +=== Config + +Index templates can also be placed within the config location +(`path.conf`) under the `templates` directory (note, make sure to place +them on all master eligible nodes). For example, a file called +`template_1.json` can be placed under `config/templates` and it will be +added if it matches an index. Here is a sample of the mentioned file: + +[source,js] +-------------------------------------------------- +{ + "template_1" : { + "template" : "*", + "settings" : { + "index.number_of_shards" : 2 + }, + "mappings" : { + "_default_" : { + "_source" : { + "enabled" : false + } + }, + "type1" : { + "_all" : { + "enabled" : false + } + } + } + } +} +-------------------------------------------------- diff --git a/docs/reference/indices/types-exists.asciidoc b/docs/reference/indices/types-exists.asciidoc new file mode 100644 index 0000000..87b0aa3 --- /dev/null +++ b/docs/reference/indices/types-exists.asciidoc @@ -0,0 +1,12 @@ +[[indices-types-exists]] +== Types Exists + +Used to check if a type/types exists in an index/indices. + +[source,js] +-------------------------------------------------- +curl -XHEAD 'http://localhost:9200/twitter/tweet' +-------------------------------------------------- + +The HTTP status code indicates if the type exists or not. A `404` means +it does not exist, and `200` means it does. diff --git a/docs/reference/indices/update-settings.asciidoc b/docs/reference/indices/update-settings.asciidoc new file mode 100644 index 0000000..19af576 --- /dev/null +++ b/docs/reference/indices/update-settings.asciidoc @@ -0,0 +1,226 @@ +[[indices-update-settings]] +== Update Indices Settings + +Change specific index level settings in real time. + +The REST endpoint is `/_settings` (to update all indices) or +`{index}/_settings` to update one (or more) indices settings. The body +of the request includes the updated settings, for example: + +[source,js] +-------------------------------------------------- +{ + "index" : { + "number_of_replicas" : 4 + } } +-------------------------------------------------- + +The above will change the number of replicas to 4 from the current +number of replicas. Here is a curl example: + +[source,js] +-------------------------------------------------- +curl -XPUT 'localhost:9200/my_index/_settings' -d ' +{ + "index" : { + "number_of_replicas" : 4 + } } +' +-------------------------------------------------- + +Below is the list of settings that can be changed using the update +settings API: + +`index.number_of_replicas`:: + The number of replicas each shard has. + +`index.auto_expand_replicas`:: + Set to an actual value (like `0-all`) or `false` to disable it. + +`index.blocks.read_only`:: + Set to `true` to have the index read only, `false` to allow writes + and metadata changes. + +`index.blocks.read`:: + Set to `true` to disable read operations againstthe index. + +`index.blocks.write`:: + Set to `true` to disable write operations against the index. + +`index.blocks.metadata`:: + Set to `true` to disable metadata operations against the index. + +`index.refresh_interval`:: + The async refresh interval of a shard. + +`index.index_concurrency`:: + Defaults to `8`. + +`index.codec`:: + Codec. Default to `default`. + +`index.codec.bloom.load`:: + Whether to load the bloom filter. Defaults to `true`. + See <<bloom-postings>>. + +`index.fail_on_merge_failure`:: + Default to `true`. + +`index.translog.flush_threshold_ops`:: + When to flush based on operations. + +`index.translog.flush_threshold_size`:: + When to flush based on translog (bytes) size. + +`index.translog.flush_threshold_period`:: + When to flush based on a period of not flushing. + +`index.translog.disable_flush`:: + Disables flushing. Note, should be set for a short + interval and then enabled. + +`index.cache.filter.max_size`:: + The maximum size of filter cache (per segment in shard). + Set to `-1` to disable. + +`index.cache.filter.expire`:: + The expire after access time for filter cache. + Set to `-1` to disable. + +`index.gateway.snapshot_interval`:: + The gateway snapshot interval (only applies to shared gateways). + Defaults to 10s. + +<<index-modules-merge,merge policy>>:: + All the settings for the merge policy currently configured. + A different merge policy can't be set. + +`index.routing.allocation.include.*`:: + A node matching any rule will be allowed to host shards from the index. + +`index.routing.allocation.exclude.*`:: + A node matching any rule will NOT be allowed to host shards from the index. + +`index.routing.allocation.require.*`:: + Only nodes matching all rules will be allowed to host shards from the index. + +`index.routing.allocation.disable_allocation`:: + Disable allocation. Defaults to `false`. Deprecated in favour for `index.routing.allocation.enable`. + +`index.routing.allocation.disable_new_allocation`:: + Disable new allocation. Defaults to `false`. Deprecated in favour for `index.routing.allocation.enable`. + +`index.routing.allocation.disable_replica_allocation`:: + Disable replica allocation. Defaults to `false`. Deprecated in favour for `index.routing.allocation.enable`. + +added[1.0.0.RC1] + +`index.routing.allocation.enable`:: + Enables shard allocation for a specific index. It can be set to: + * `all` (default) - Allows shard allocation for all shards. + * `primaries` - Allows shard allocation only for primary shards. + * `new_primaries` - Allows shard allocation only for primary shards for new indices. + * `none` - No shard allocation is allowed. + +`index.routing.allocation.total_shards_per_node`:: + Controls the total number of shards allowed to be allocated on a single node. Defaults to unbounded (`-1`). + +`index.recovery.initial_shards`:: + When using local gateway a particular shard is recovered only if there can be allocated quorum shards in the cluster. It can be set to: + * `quorum` (default) + * `quorum-1` (or `half`) + * `full` + * `full-1`. + * Number values are also supported, e.g. `1`. + +`index.gc_deletes`:: + +`index.ttl.disable_purge`:: + Disables temporarily the purge of expired docs. + +<<index-modules-store,store level throttling>>:: + All the settings for the store level throttling policy currently configured. + +`index.translog.fs.type`:: + Either `simple` or `buffered` (default). + +`index.compound_format`:: + See <<index-compound-format,`index.compound_format`>> in + <<index-modules-settings>>. + +`index.compound_on_flush`:: + See <<index-compound-on-flush,`index.compound_on_flush>> in + <<index-modules-settings>>. + +<<index-modules-slowlog>>:: + All the settings for slow log. + +`index.warmer.enabled`:: + See <<indices-warmers>>. Defaults to `true`. + +[float] +[[bulk]] +=== Bulk Indexing Usage + +For example, the update settings API can be used to dynamically change +the index from being more performant for bulk indexing, and then move it +to more real time indexing state. Before the bulk indexing is started, +use: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test/_settings -d '{ + "index" : { + "refresh_interval" : "-1" + } }' +-------------------------------------------------- + +(Another optimization option is to start the index without any replicas, +and only later adding them, but that really depends on the use case). + +Then, once bulk indexing is done, the settings can be updated (back to +the defaults for example): + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test/_settings -d '{ + "index" : { + "refresh_interval" : "1s" + } }' +-------------------------------------------------- + +And, an optimize should be called: + +[source,js] +-------------------------------------------------- +curl -XPOST 'http://localhost:9200/test/_optimize?max_num_segments=5' +-------------------------------------------------- + +[float] +[[update-settings-analysis]] +=== Updating Index Analysis + +It is also possible to define new <<analysis,analyzers>> for the index. +But it is required to <<indices-open-close,close>> the index +first and <<indices-open-close,open>> it after the changes are made. + +For example if `content` analyzer hasn't been defined on `myindex` yet +you can use the following commands to add it: + +[source,js] +-------------------------------------------------- +curl -XPOST 'localhost:9200/myindex/_close' + +curl -XPUT 'localhost:9200/myindex/_settings' -d '{ + "analysis" : { + "analyzer":{ + "content":{ + "type":"custom", + "tokenizer":"whitespace" + } + } + } +}' + +curl -XPOST 'localhost:9200/myindex/_open' +-------------------------------------------------- diff --git a/docs/reference/indices/warmers.asciidoc b/docs/reference/indices/warmers.asciidoc new file mode 100644 index 0000000..bc71094 --- /dev/null +++ b/docs/reference/indices/warmers.asciidoc @@ -0,0 +1,183 @@ +[[indices-warmers]] +== Warmers + +Index warming allows to run registered search requests to warm up the +index before it is available for search. With the near real time aspect +of search, cold data (segments) will be warmed up before they become +available for search. + +Warmup searches typically include requests that require heavy loading of +data, such as faceting or sorting on specific fields. The warmup APIs +allows to register warmup (search) under specific names, remove them, +and get them. + +Index warmup can be disabled by setting `index.warmer.enabled` to +`false`. It is supported as a realtime setting using update settings +API. This can be handy when doing initial bulk indexing, disabling pre +registered warmers to make indexing faster and less expensive and then +enable it. + +[float] +[[creation]] +=== Index Creation / Templates + +Warmers can be registered when an index gets created, for example: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test -d '{ + "warmers" : { + "warmer_1" : { + "types" : [], + "source" : { + "query" : { + ... + }, + "facets" : { + ... + } + } + } + } +}' +-------------------------------------------------- + +Or, in an index template: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/_template/template_1 -d ' +{ + "template" : "te*", + "warmers" : { + "warmer_1" : { + "types" : [], + "source" : { + "query" : { + ... + }, + "facets" : { + ... + } + } + } + } +}' +-------------------------------------------------- + +[float] +[[warmer-adding]] +=== Put Warmer + +Allows to put a warmup search request on a specific index (or indices), +with the body composing of a regular search request. Types can be +provided as part of the URI if the search request is designed to be run +only against the specific types. + +Here is an example that registers a warmup called `warmer_1` against +index `test` (can be alias or several indices), for a search request +that runs against all types: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test/_warmer/warmer_1 -d '{ + "query" : { + "match_all" : {} + }, + "facets" : { + "facet_1" : { + "terms" : { + "field" : "field" + } + } + } +}' +-------------------------------------------------- + +And an example that registers a warmup against specific types: + +[source,js] +-------------------------------------------------- +curl -XPUT localhost:9200/test/type1/_warmer/warmer_1 -d '{ + "query" : { + "match_all" : {} + }, + "facets" : { + "facet_1" : { + "terms" : { + "field" : "field" + } + } + } +}' +-------------------------------------------------- + +All options: + +[source,js] +-------------------------------------------------- + +PUT _warmer/{warmer_name} + +PUT /{index}/_warmer/{warmer_name} + +PUT /{index}/{type}/_warmer/{warmer_name} + +-------------------------------------------------- + + +where + +[horizontal] +`{index}`:: `* | _all | glob pattern | name1, name2, …` + +`{type}`:: `* | _all | glob pattern | name1, name2, …` + +Instead of `_warmer` you can also use the plural `_warmers`. + + + +[float] +[[removing]] +=== Delete Warmers + +Warmers can be deleted using the following endpoint: + + + +[source,js] +-------------------------------------------------- + +[DELETE] /{index}/_warmer/{name} + +-------------------------------------------------- + + +where + +[horizontal] +`{index}`:: `* | _all | glob pattern | name1, name2, …` + +`{name}`:: `* | _all | glob pattern | name1, name2, …` + +Instead of `_warmer` you can also use the plural `_warmers`. + +[float] +[[warmer-retrieving]] +=== GETting Warmer + +Getting a warmer for specific index (or alias, or several indices) based +on its name. The provided name can be a simple wildcard expression or +omitted to get all warmers. Some examples: + +[source,js] +-------------------------------------------------- +# get warmer named warmer_1 on test index +curl -XGET localhost:9200/test/_warmer/warmer_1 + +# get all warmers that start with warm on test index +curl -XGET localhost:9200/test/_warmer/warm* + +# get all warmers for test index +curl -XGET localhost:9200/test/_warmer/ +-------------------------------------------------- |