[DOCS] Reformat index segments API docs (#46345)

elastic · Sep 5, 2019 · 2da295b · 2da295b
1 parent 4c0849a
commit 2da295b
Show file tree

Hide file tree

Showing 3 changed files with 208 additions and 93 deletions.
diff --git a/docs/reference/cat/segments.asciidoc b/docs/reference/cat/segments.asciidoc
@@ -49,46 +49,40 @@ Valid columns are:
 (Default) IP address of the segment's shard, such as `127.0.1.1`.
 
 `segment`::
-(Default) Name of the segment, such as `_0`. The segment name is derived from
-the segment generation and used internally to create file names in the directory
-of the shard.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment]
 
 `generation`::
-(Default) Generation number, such as `0`. {es} increments this generation number
-for each segment written. {es} then uses this number to derive the segment name.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=generation]
 
 `docs.count`::
-(Default) Number of non-deleted documents in the segment, such as `25`. This
-number is based on Lucene documents and may include documents from
-<<nested,nested>> fields.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=docs-count]
 
 `docs.deleted`::
-(Default) Number of deleted documents in the segment, such as `0`. This number
-is based on Lucene documents. {es} reclaims the disk space of deleted Lucene
-documents when a segment is merged.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=docs-deleted]
 
 `size`::
-(Default) Disk space used by the segment, such as `50kb`.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-size]
 
 `size.memory`::
-(Default) Bytes of segment data stored in memory for efficient search, such as
-`1264`.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=memory]
 
 `committed`::
-(Default) If `true`, the segment is committed to disk. Segments committed to
-disk would survive a hard reboot. 
-+
-If `false`, the data from uncommitted segments is also stored in the transaction
-log. {es} replays those changes on the next start.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=committed]
 
 `searchable`::
-(Default) If `true`, the segment is searchable.
-+
-If `false`, likely means the segment is written to disk but has not been
-<<docs-refresh,refreshed>>.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-search]
 
 `version`::
-(Default) Version of Lucene used to write the segment.
+(Default)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-version]
 
 `compound`::
 (Default) If `true`, the segment is stored in a compound file. This means Lucene

diff --git a/docs/reference/indices/segments.asciidoc b/docs/reference/indices/segments.asciidoc
@@ -1,41 +1,136 @@
 [[indices-segments]]
-=== Indices Segments
+=== Index segments API
+++++
+<titleabbrev>Index segments</titleabbrev>
+++++
 
-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.
+Returns low-level information about the https://lucene.apache.org/core/[Lucene]
+segments in index shards.
 
-Endpoints include segments for a specific index:
+[source,console]
+----
+GET /twitter/_segments
+----
+// TEST[setup:twitter]
 
-[source,js]
+
+[[index-segments-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_segments`
+
+`GET /_segments`
+
+`GET /_cat/segments/<index>`
+
+
+[[index-segments-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[index-segments-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+`verbose`::
+experimental:[]
+(Optional, boolean)
+If `true`, the response includes detailed information
+about Lucene's memory usage.
+Defaults to `false`.
+
+
+[[index-segments-api-response-body]]
+==== {api-response-body-title}
+
+`<segment>`::
+(String)       
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment]
+
+`generation`::
+(Integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=generation]
+
+`num_docs`::
+(Integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=docs-count]
+
+`deleted_docs`::
+(Integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=docs-deleted]
+
+`size_in_bytes`::
+(Integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-size]
+
+`memory_in_bytes`::
+(Integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=memory]
+
+`committed`:: 
+(Boolean)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=committed]
+
+`search`::
+(Boolean)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-search]
+
+`version`::
+(String)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-version]
+
+`compound`::
+(Boolean)
+If `true`, Lucene merged all files from the segment
+into a single file to save file descriptors.
+
+`attributes`::
+(Object)
+Contains information about whether high compression was enabled.
+
+
+[[index-segments-api-example]]
+==== {api-examples-title}
+
+
+===== Get segment information for a specific index
+
+[source,console]
 --------------------------------------------------
 GET /test/_segments
 --------------------------------------------------
-// CONSOLE
 // TEST[s/^/PUT test\n{"settings":{"number_of_shards":1, "number_of_replicas": 0}}\nPOST test\/test\?refresh\n{"test": "test"}\n/]
-// TESTSETUP
 
-For several indices:
 
-[source,js]
+===== Get segment information for several indices
+
+[source,console]
 --------------------------------------------------
 GET /test1,test2/_segments
 --------------------------------------------------
-// CONSOLE
 // TEST[s/^/PUT test1\nPUT test2\n/]
 
-Or for all indices:
 
-[source,js]
+===== Get segment information for all indices
+
+[source,console]
 --------------------------------------------------
 GET /_segments
 --------------------------------------------------
-// CONSOLE
+// TEST[s/^/PUT test\n{"settings":{"number_of_shards":1, "number_of_replicas": 0}}\nPOST test\/test\?refresh\n{"test": "test"}\n/]
 
-Response:
+The API returns the following response:
 
-[source,js]
+[source,console-response]
 --------------------------------------------------
 {
   "_shards": ...
@@ -79,61 +174,23 @@ Response:
 // TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/]
 // TESTRESPONSE[s/7\.0\.0/$body.$_path/]
 
-_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.
-
-attributes:: Contains information about whether high compression was enabled
 
-[float]
-==== Verbose mode
+===== Verbose mode
 
-To add additional information that can be used for debugging, use the `verbose` flag.
+To add additional information that can be used for debugging,
+use the `verbose` flag.
 
-NOTE: The format of the additional detail information is labelled as experimental in Lucene and it may change in the future.
+experimental::[]
 
-[source,js]
+[source,console]
 --------------------------------------------------
 GET /test/_segments?verbose=true
 --------------------------------------------------
-// CONSOLE
+// TEST[continued]
 
-Response:
+The API returns the following response:
 
-[source,js]
+[source,console-response]
 --------------------------------------------------
 {
     ...
@@ -159,5 +216,4 @@ Response:
     ...
 }
 --------------------------------------------------
-// NOTCONSOLE
-//Response is too verbose to be fully shown in documentation, so we just show the relevant bit and don't test the response.
+// TESTRESPONSE[skip:Response is too verbose to be fully shown in documentation, so we just show the relevant bit and don't test the response.]