Skip to content

Commit

Permalink
Revert "[DOCS] Reformat index segments API docs (#46345)"
Browse files Browse the repository at this point in the history 
This reverts commit 1b6c7a8.
  • Loading branch information
@jrodewig
jrodewig committed Sep 5, 2019
1 parent 1b6c7a8 commit 8c8a6b6
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 208 deletions.
42 changes: 24 additions & 18 deletions docs/reference/cat/segments.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,40 +49,46 @@ Valid columns are:
(Default) IP address of the segment's shard, such as `127.0.1.1`.

`segment`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=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.

`generation`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=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.

`docs.count`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=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.

`docs.deleted`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=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.

`size`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-size]
(Default) Disk space used by the segment, such as `50kb`.

`size.memory`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=memory]
(Default) Bytes of segment data stored in memory for efficient search, such as
`1264`.

`committed`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=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.

`searchable`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-search]
(Default) If `true`, the segment is searchable.
+
If `false`, likely means the segment is written to disk but has not been
<<docs-refresh,refreshed>>.

`version`::
(Default)
include::{docdir}/rest-api/common-parms.asciidoc[tag=segment-version]
(Default) Version of Lucene used to write the segment.

`compound`::
(Default) If `true`, the segment is stored in a compound file. This means Lucene
Expand Down
186 changes: 65 additions & 121 deletions docs/reference/indices/segments.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,136 +1,41 @@
[[indices-segments]]
=== Index segments API
++++
<titleabbrev>Index segments</titleabbrev>
++++
=== Indices Segments

Returns low-level information about the https://lucene.apache.org/core/[Lucene]
segments in index shards.
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.

[source,console]
----
GET /twitter/_segments
----
// TEST[setup:twitter]
Endpoints include segments for a specific index:


[[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]
[source,js]
--------------------------------------------------
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:

===== Get segment information for several indices

[source,console]
[source,js]
--------------------------------------------------
GET /test1,test2/_segments
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT test1\nPUT test2\n/]

Or for all indices:

===== Get segment information for all indices

[source,console]
[source,js]
--------------------------------------------------
GET /_segments
--------------------------------------------------
// TEST[s/^/PUT test\n{"settings":{"number_of_shards":1, "number_of_replicas": 0}}\nPOST test\/test\?refresh\n{"test": "test"}\n/]
// CONSOLE

The API returns the following response:
Response:

[source,console-response]
[source,js]
--------------------------------------------------
{
"_shards": ...
Expand Down Expand Up @@ -174,23 +79,61 @@ The API returns the following 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

===== Verbose mode
[float]
==== 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.

experimental::[]
NOTE: The format of the additional detail information is labelled as experimental in Lucene and it may change in the future.

[source,console]
[source,js]
--------------------------------------------------
GET /test/_segments?verbose=true
--------------------------------------------------
// TEST[continued]
// CONSOLE

The API returns the following response:
Response:

[source,console-response]
[source,js]
--------------------------------------------------
{
...
Expand All @@ -216,4 +159,5 @@ The API returns the following 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.]
// NOTCONSOLE
//Response is too verbose to be fully shown in documentation, so we just show the relevant bit and don't test the response.
Loading

0 comments on commit 8c8a6b6

Please sign in to comment.