From 37ed61807f5310ccd8a7e72ec7b5a117148f3acc Mon Sep 17 00:00:00 2001 From: Clinton Gormley Date: Sun, 26 Apr 2015 18:49:15 +0200 Subject: [PATCH] Docs: Updated the experimental annotations in the docs as follows: * Removed the docs for `index.compound_format` and `index.compound_on_flush` - these are expert settings which should probably be removed (see https://github.com/elastic/elasticsearch/issues/10778) * Removed the docs for `index.index_concurrency` - another expert setting * Labelled the segments verbose output as experimental * Marked the `compression`, `precision_threshold` and `rehash` options as experimental in the cardinality and percentile aggs * Improved the experimental text on `significant_terms`, `execution_hint` in the terms agg, and `terminate_after` param on count and search * Removed the experimental flag on the `geobounds` agg * Marked the settings in the `merge` and `store` modules as experimental, rather than the modules themselves Closes #10782 --- docs/reference/index-modules.asciidoc | 25 +------------------ docs/reference/index-modules/merge.asciidoc | 8 +----- docs/reference/index-modules/store.asciidoc | 5 ++-- docs/reference/indices/segments.asciidoc | 4 +-- .../indices/update-settings.asciidoc | 15 ++--------- docs/reference/modules/scripting.asciidoc | 5 +--- .../significantterms-aggregation.asciidoc | 2 +- .../bucket/terms-aggregation.asciidoc | 2 +- .../metrics/cardinality-aggregation.asciidoc | 8 +++--- .../metrics/geobounds-aggregation.asciidoc | 2 -- .../metrics/percentile-aggregation.asciidoc | 2 +- docs/reference/search/count.asciidoc | 3 ++- docs/reference/search/request-body.asciidoc | 3 ++- docs/reference/search/uri-request.asciidoc | 3 ++- 14 files changed, 22 insertions(+), 65 deletions(-) diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc index eb85f8d231e..f74eda35bed 100644 --- a/docs/reference/index-modules.asciidoc +++ b/docs/reference/index-modules.asciidoc @@ -15,29 +15,6 @@ all the relevant modules settings can be provided when creating an index There are specific index level settings that are not associated with any specific module. These include: -[[index-compound-format]]`index.compound_format`:: - - experimental[] - Should the compound file format be used (boolean setting). - The compound format was created to reduce the number of open - file handles when using file based storage. However, by default it is set - to `false` as the non-compound format gives better performance. It is important - that OS is configured to give Elasticsearch ``enough'' file handles. - See <>. -+ -Alternatively, `compound_format` can be set to a number between `0` and -`1`, where `0` means `false`, `1` means `true` and a number inbetween -represents a percentage: if the merged segment is less than this -percentage of the total index, then it is written in compound format, -otherwise it is written in non-compound format. - -[[index-compound-on-flush]]`index.compound_on_flush`:: - - experimental[] - Should a new segment (create by indexing, not by merging) be written - in compound format or non-compound format? Defaults to `true`. - This is a dynamic setting. - `index.refresh_interval`:: A time setting controlling how often the refresh operation will be executed. Defaults to `1s`. Can be set to `-1` @@ -59,7 +36,7 @@ otherwise it is written in non-compound format. When `checksum`, check for physical corruption. When `true`, check for both physical and logical corruption. This is much more expensive in terms of CPU and memory usage. - When `fix`, check for both physical and logical corruption, and segments + When `fix`, check for both physical and logical corruption, and segments that were reported as corrupted will be automatically removed. Default value is `false`, which performs no checks. diff --git a/docs/reference/index-modules/merge.asciidoc b/docs/reference/index-modules/merge.asciidoc index 3ad2dd5c0a8..036d2b8d16f 100644 --- a/docs/reference/index-modules/merge.asciidoc +++ b/docs/reference/index-modules/merge.asciidoc @@ -1,7 +1,7 @@ [[index-modules-merge]] == Merge -experimental[] +experimental[All of the settings exposed in the `merge` module are expert only and may be removed in the future] A shard in elasticsearch is a Lucene index, and a Lucene index is broken down into segments. Segments are internal storage elements in the index @@ -72,12 +72,6 @@ This policy has the following settings: Higher values favor selecting merges that reclaim deletions. A value of `0.0` means deletions don't impact merge selection. Defaults to `2.0`. -`index.compound_format`:: - - Should the index be stored in compound format or not. Defaults to `false`. - See <> in - <>. - For normal merging, this policy first computes a "budget" of how many segments are allowed to be in the index. If the index is over-budget, then the policy sorts segments by decreasing size (proportionally considering percent diff --git a/docs/reference/index-modules/store.asciidoc b/docs/reference/index-modules/store.asciidoc index b34536db811..12fcf0c3509 100644 --- a/docs/reference/index-modules/store.asciidoc +++ b/docs/reference/index-modules/store.asciidoc @@ -1,8 +1,6 @@ [[index-modules-store]] == Store -experimental[] - The store module allows you to control how index data is stored. The index can either be stored in-memory (no persistence) or on-disk @@ -20,6 +18,7 @@ heap space* using the "Memory" (see below) storage type. It translates to the fact that there is no need for extra large JVM heaps (with their own consequences) for storing the index in memory. +experimental[All of the settings exposed in the `store` module are expert only and may be removed in the future] [float] [[file-system]] @@ -28,7 +27,7 @@ own consequences) for storing the index in memory. File system based storage is the default storage used. There are different implementations or _storage types_. The best one for the operating environment will be automatically chosen: `mmapfs` on -Windows 64bit, `simplefs` on Windows 32bit, and `default` +Windows 64bit, `simplefs` on Windows 32bit, and `default` (hybrid `niofs` and `mmapfs`) for the rest. This can be overridden for all indices by adding this to the diff --git a/docs/reference/indices/segments.asciidoc b/docs/reference/indices/segments.asciidoc index f432697f54d..f2d51068a64 100644 --- a/docs/reference/indices/segments.asciidoc +++ b/docs/reference/indices/segments.asciidoc @@ -78,7 +78,7 @@ compound:: Whether the segment is stored in a compound file. When true, this To add additional information that can be used for debugging, use the `verbose` flag. -NOTE: The format of additional verbose information is experimental and can change at any time. +experimental[The format of the additional verbose information is experimental and can change at any time] [source,js] -------------------------------------------------- @@ -108,7 +108,7 @@ Response: }, ... ] - + } ... } diff --git a/docs/reference/indices/update-settings.asciidoc b/docs/reference/indices/update-settings.asciidoc index 3810bfbdca0..d4888103eb2 100644 --- a/docs/reference/indices/update-settings.asciidoc +++ b/docs/reference/indices/update-settings.asciidoc @@ -12,7 +12,7 @@ of the request includes the updated settings, for example: { "index" : { "number_of_replicas" : 4 - } + } } -------------------------------------------------- @@ -25,7 +25,7 @@ curl -XPUT 'localhost:9200/my_index/_settings' -d ' { "index" : { "number_of_replicas" : 4 - } + } }' -------------------------------------------------- @@ -61,9 +61,6 @@ settings API: `index.refresh_interval`:: The async refresh interval of a shard. -`index.index_concurrency`:: - experimental[] Defaults to `8`. - `index.translog.flush_threshold_ops`:: When to flush based on operations. @@ -151,14 +148,6 @@ settings API: `index.translog.fs.type`:: experimental[] Either `simple` or `buffered` (default). -`index.compound_format`:: - experimental[] See <> in - <>. - -`index.compound_on_flush`:: - experimental[] See <> in - <>. - <>:: All the settings for slow log. diff --git a/docs/reference/modules/scripting.asciidoc b/docs/reference/modules/scripting.asciidoc index 26b50c97ac1..2725e05a6e0 100644 --- a/docs/reference/modules/scripting.asciidoc +++ b/docs/reference/modules/scripting.asciidoc @@ -424,10 +424,7 @@ automatically loaded. [float] === Lucene Expressions Scripts -[WARNING] -======================== -This feature is *experimental* and subject to change in future versions. -======================== +experimental[The Lucene expressions module is undergoing significant development and the exposed functionality is likely to change in the future] Lucene's expressions module provides a mechanism to compile a `javascript` expression to bytecode. This allows very fast execution, diff --git a/docs/reference/search/aggregations/bucket/significantterms-aggregation.asciidoc b/docs/reference/search/aggregations/bucket/significantterms-aggregation.asciidoc index 9cf729765f9..1e329db1df4 100644 --- a/docs/reference/search/aggregations/bucket/significantterms-aggregation.asciidoc +++ b/docs/reference/search/aggregations/bucket/significantterms-aggregation.asciidoc @@ -3,7 +3,7 @@ An aggregation that returns interesting or unusual occurrences of terms in a set. -experimental[] +experimental[The `significant_terms` aggregation can be very heavy when run on large indices. Work is in progress to provide more lightweight sampling techniques. As a result, the API for this feature may change in non-backwards compatible ways] .Example use cases: * Suggesting "H5N1" when users search for "bird flu" in text diff --git a/docs/reference/search/aggregations/bucket/terms-aggregation.asciidoc b/docs/reference/search/aggregations/bucket/terms-aggregation.asciidoc index 12f04c0a2bb..58a6ca2449c 100644 --- a/docs/reference/search/aggregations/bucket/terms-aggregation.asciidoc +++ b/docs/reference/search/aggregations/bucket/terms-aggregation.asciidoc @@ -613,7 +613,7 @@ this would typically be too costly in terms of RAM. [[search-aggregations-bucket-terms-aggregation-execution-hint]] ==== Execution hint -experimental[] +experimental[The automated execution optimization is experimental, so this parameter is provided temporarily as a way to override the default behaviour] There are different mechanisms by which terms aggregations can be executed: diff --git a/docs/reference/search/aggregations/metrics/cardinality-aggregation.asciidoc b/docs/reference/search/aggregations/metrics/cardinality-aggregation.asciidoc index d4d3ee67015..07943a06c2d 100644 --- a/docs/reference/search/aggregations/metrics/cardinality-aggregation.asciidoc +++ b/docs/reference/search/aggregations/metrics/cardinality-aggregation.asciidoc @@ -23,10 +23,10 @@ match a query: ==== Precision control -experimental[] - This aggregation also supports the `precision_threshold` and `rehash` options: +experimental[The `precision_threshold` and `rehash` options are specific to the current internal implementation of the `cardinality` agg, which may change in the future] + [source,js] -------------------------------------------------- { @@ -42,14 +42,14 @@ This aggregation also supports the `precision_threshold` and `rehash` options: } -------------------------------------------------- -<1> experimental[] The `precision_threshold` options allows to trade memory for accuracy, and +<1> The `precision_threshold` options allows to trade memory for accuracy, and defines a unique count below which counts are expected to be close to accurate. Above this value, counts might become a bit more fuzzy. The maximum supported value is 40000, thresholds above this number will have the same effect as a threshold of 40000. Default value depends on the number of parent aggregations that multiple create buckets (such as terms or histograms). -<2> experimental[] If you computed a hash on client-side, stored it into your documents and want +<2> If you computed a hash on client-side, stored it into your documents and want Elasticsearch to use them to compute counts using this hash function without rehashing values, it is possible to specify `rehash: false`. Default value is `true`. Please note that the hash must be indexed as a long when `rehash` is diff --git a/docs/reference/search/aggregations/metrics/geobounds-aggregation.asciidoc b/docs/reference/search/aggregations/metrics/geobounds-aggregation.asciidoc index 548436b93b6..ade59477ee3 100644 --- a/docs/reference/search/aggregations/metrics/geobounds-aggregation.asciidoc +++ b/docs/reference/search/aggregations/metrics/geobounds-aggregation.asciidoc @@ -1,8 +1,6 @@ [[search-aggregations-metrics-geobounds-aggregation]] === Geo Bounds Aggregation -experimental[] - A metric aggregation that computes the bounding box containing all geo_point values for a field. diff --git a/docs/reference/search/aggregations/metrics/percentile-aggregation.asciidoc b/docs/reference/search/aggregations/metrics/percentile-aggregation.asciidoc index 253663a9cfe..6bd10110077 100644 --- a/docs/reference/search/aggregations/metrics/percentile-aggregation.asciidoc +++ b/docs/reference/search/aggregations/metrics/percentile-aggregation.asciidoc @@ -155,7 +155,7 @@ it. It would not be the case on more skewed distributions. [[search-aggregations-metrics-percentile-aggregation-compression]] ==== Compression -experimental[] +experimental[The `compression` parameter is specific to the current internal implementation of percentiles, and may change in the future] Approximate algorithms must balance memory utilization with estimation accuracy. This balance can be controlled using a `compression` parameter: diff --git a/docs/reference/search/count.asciidoc b/docs/reference/search/count.asciidoc index a04c3950987..258e3c94b40 100644 --- a/docs/reference/search/count.asciidoc +++ b/docs/reference/search/count.asciidoc @@ -64,7 +64,8 @@ query. |default_operator |The default operator to be used, can be `AND` or `OR`. Defaults to `OR`. -|terminate_after |experimental[] The maximum count for each shard, upon +|terminate_after |experimental[The API for this feature may change in the future] +The maximum count for each shard, upon reaching which the query execution will terminate early. If set, the response will have a boolean field `terminated_early` to indicate whether the query execution has actually terminated_early. diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index 4dbb7e006dc..fadfbb191f5 100644 --- a/docs/reference/search/request-body.asciidoc +++ b/docs/reference/search/request-body.asciidoc @@ -77,7 +77,8 @@ And here is a sample response: `terminate_after`:: - experimental[] The maximum number of documents to collect for each shard, + experimental[The API for this feature may change in the future] + The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early. If set, the response will have a boolean field `terminated_early` to indicate whether the query execution has actually terminated_early. Defaults to no diff --git a/docs/reference/search/uri-request.asciidoc b/docs/reference/search/uri-request.asciidoc index b1509a3da68..a367dc679db 100644 --- a/docs/reference/search/uri-request.asciidoc +++ b/docs/reference/search/uri-request.asciidoc @@ -82,7 +82,8 @@ scores and return them as part of each hit. within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to no timeout. -|`terminate_after` |experimental[] The maximum number of documents to collect for +|`terminate_after` |experimental[The API for this feature may change in the future] +The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early. If set, the response will have a boolean field `terminated_early` to indicate whether the query execution has actually terminated_early.