Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Sep 5, 2019
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 18 additions & 24 deletions docs/reference/cat/segments.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
171 changes: 116 additions & 55 deletions docs/reference/indices/segments.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,119 @@
[[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,js]
----
GET /twitter/_segments
----
// CONSOLE
// TEST[setup:twitter]


[[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,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,js]
--------------------------------------------------
Expand All @@ -25,15 +122,17 @@ GET /test1,test2/_segments
// CONSOLE
// TEST[s/^/PUT test1\nPUT test2\n/]

Or for all indices:

===== Get segment information for all indices

[source,js]
--------------------------------------------------
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]
--------------------------------------------------
Expand Down Expand Up @@ -79,59 +178,22 @@ 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.
===== Verbose mode

num_docs:: The number of non-deleted documents that are stored in this segment.
To add additional information that can be used for debugging,
use the `verbose` flag.

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

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]
--------------------------------------------------
GET /test/_segments?verbose=true
--------------------------------------------------
// 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]
--------------------------------------------------
Expand Down Expand Up @@ -159,5 +221,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.]
Loading