Skip to content

Commit e8cf4f9

Browse files
tlrxtlrx
authored
Add basic documentation for Searchable Snapshots REST APIs (#54581)
This commit adds basic documentation for the searchable snapshots REST APIs. The main motivations are to not break downstream projects (see #53871) and to provide a simple example of how to mount a snapshot. It adds a new "Searchable Snapshots APIs" sub section in the REST APIs section. The "Mount Snapshot API" is the more complete documentation and provides an example of how to create a new index backed by a snapshot. Those API are experimental and marked as such. I've not seen any mention of the license, except the [testenv="basic"] tags that I copied from other doc.
1 parent 19772b6 commit e8cf4f9

File tree

8 files changed

+299
-3
lines changed

8 files changed

+299
-3
lines changed

‎docs/reference/rest-api/index.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ endif::[]
3131
* <<indices-reload-analyzers,Reload Search Analyzers API>>
3232
* <<rollup-apis,Rollup APIs>>
3333
* <<search, Search APIs>>
34+
* <<searchable-snapshots-apis, Searchable snapshots APIs>>
3435
* <<security-api,Security APIs>>
3536
* <<snapshot-lifecycle-management-api,Snapshot lifecycle management APIs>>
3637
* <<transform-apis,{transform-cap} APIs>>
@@ -59,6 +60,7 @@ include::{es-repo-dir}/migration/migration.asciidoc[]
5960
include::{es-repo-dir}/indices/apis/reload-analyzers.asciidoc[]
6061
include::{es-repo-dir}/rollup/rollup-api.asciidoc[]
6162
include::{es-repo-dir}/search.asciidoc[]
63+
include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc[]
6264
include::{xes-repo-dir}/rest-api/security.asciidoc[]
6365
include::{es-repo-dir}/slm/apis/slm-api.asciidoc[]
6466
include::{es-repo-dir}/transform/apis/index.asciidoc[]

‎docs/reference/searchable-snapshots/apis/clear-cache.asciidoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[searchable-snapshots-api-clear-cache]]
4+
=== Clear cache API
5+
++++
6+
<titleabbrev>Clear cache</titleabbrev>
7+
++++
8+
9+
experimental[]
10+
11+
Clear the cache of searchable snapshots.
12+
13+
[[searchable-snapshots-api-clear-cache-request]]
14+
==== {api-request-title}
15+
16+
`POST /_searchable_snapshots/cache/clear`
17+
18+
`POST /<index>/_searchable_snapshots/cache/clear`
19+
20+
[[searchable-snapshots-api-clear-cache-prereqs]]
21+
==== {api-prereq-title}
22+
23+
If the {es} {security-features} are enabled, you must have the
24+
`manage` cluster privilege and the `manage` index privilege
25+
for any included indices to use this API.
26+
For more information, see <<security-privileges>>.
27+
28+
[[searchable-snapshots-api-clear-cache-desc]]
29+
==== {api-description-title}
30+
31+
32+
[[searchable-snapshots-api-clear-cache-path-params]]
33+
==== {api-path-parms-title}
34+
35+
`<index>`::
36+
(Optional, string)
37+
A comma-separated list of index names for which the
38+
searchable snapshots cache must be cleared.
39+
40+
41+
[[searchable-snapshots-api-clear-cache-example]]
42+
==== {api-examples-title}
43+
////
44+
[source,console]
45+
-----------------------------------
46+
PUT /docs
47+
{
48+
"settings" : {
49+
"index.number_of_shards" : 1,
50+
"index.number_of_replicas" : 0
51+
}
52+
}
53+
54+
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
55+
{
56+
"include_global_state": false,
57+
"indices": "docs"
58+
}
59+
60+
DELETE /docs
61+
62+
POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
63+
{
64+
"index": "docs"
65+
}
66+
-----------------------------------
67+
// TEST[setup:setup-repository]
68+
////
69+
70+
Clears the cache of the index `docs`:
71+
72+
[source,console]
73+
--------------------------------------------------
74+
POST /docs/_searchable_snapshots/cache/clear
75+
--------------------------------------------------
76+
// TEST[continued]

‎docs/reference/searchable-snapshots/apis/get-stats.asciidoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[searchable-snapshots-api-stats]]
4+
=== Searchable snapshot statistics API
5+
++++
6+
<titleabbrev>Searchable snapshot statistics</titleabbrev>
7+
++++
8+
9+
experimental[]
10+
11+
Retrieve various statistics about searchable snapshots.
12+
13+
[[searchable-snapshots-api-stats-request]]
14+
==== {api-request-title}
15+
16+
`GET /_searchable_snapshots/stats`
17+
18+
`GET /<index>/_searchable_snapshots/stats`
19+
20+
[[searchable-snapshots-api-stats-prereqs]]
21+
==== {api-prereq-title}
22+
23+
If the {es} {security-features} are enabled, you must have the
24+
`manage` cluster privilege and the `manage` index privilege
25+
for any included indices to use this API.
26+
For more information, see <<security-privileges>>.
27+
28+
[[searchable-snapshots-api-stats-desc]]
29+
==== {api-description-title}
30+
31+
32+
[[searchable-snapshots-api-stats-path-params]]
33+
==== {api-path-parms-title}
34+
35+
`<index>`::
36+
(Optional, string)
37+
A comma-separated list of index names for which the
38+
statistics must be retrieved.
39+
40+
41+
[[searchable-snapshots-api-stats-example]]
42+
==== {api-examples-title}
43+
////
44+
[source,console]
45+
-----------------------------------
46+
PUT /docs
47+
{
48+
"settings" : {
49+
"index.number_of_shards" : 1,
50+
"index.number_of_replicas" : 0
51+
}
52+
}
53+
54+
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
55+
{
56+
"include_global_state": false,
57+
"indices": "docs"
58+
}
59+
60+
DELETE /docs
61+
62+
POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
63+
{
64+
"index": "docs"
65+
}
66+
-----------------------------------
67+
// TEST[setup:setup-repository]
68+
////
69+
70+
Retrieves the statistics of the index `docs`:
71+
72+
[source,console]
73+
--------------------------------------------------
74+
GET /docs/_searchable_snapshots/stats
75+
--------------------------------------------------
76+
// TEST[continued]

‎docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[searchable-snapshots-api-mount-snapshot]]
4+
=== Mount snapshot API
5+
++++
6+
<titleabbrev>Mount snapshot</titleabbrev>
7+
++++
8+
9+
experimental[]
10+
11+
Mount a snapshot as a searchable index.
12+
13+
[[searchable-snapshots-api-mount-request]]
14+
==== {api-request-title}
15+
16+
`POST /_snapshot/<repository>/<snapshot>/_mount`
17+
18+
[[searchable-snapshots-api-mount-prereqs]]
19+
==== {api-prereq-title}
20+
21+
If the {es} {security-features} are enabled, you must have the
22+
`manage` cluster privilege and the `manage` index privilege
23+
for any included indices to use this API.
24+
For more information, see <<security-privileges>>.
25+
26+
[[searchable-snapshots-api-mount-desc]]
27+
==== {api-description-title}
28+
29+
30+
[[searchable-snapshots-api-mount-path-params]]
31+
==== {api-path-parms-title}
32+
33+
`<repository>`::
34+
(Required, string)
35+
The name of the repository containing
36+
the snapshot of the index to mount.
37+
38+
`<snapshot>`::
39+
(Required, string)
40+
The name of the snapshot of the index
41+
to mount.
42+
43+
[[searchable-snapshots-api-mount-query-params]]
44+
==== {api-query-parms-title}
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
47+
48+
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
49+
50+
[[searchable-snapshots-api-mount-request-body]]
51+
==== {api-request-body-title}
52+
53+
`index`::
54+
(Required, string)
55+
Name of the index contained in the snapshot
56+
whose data is to be mounted.
57+
58+
If no `renamed_index` is specified this name
59+
will also be used to create the new index.
60+
61+
`renamed_index`::
62+
+
63+
--
64+
(Optional, string)
65+
Name of the index that will be created.
66+
--
67+
68+
`index_settings`::
69+
+
70+
--
71+
(Optional, object)
72+
Settings that should be added to the index when it is mounted.
73+
--
74+
75+
`ignore_index_settings`::
76+
+
77+
--
78+
(Optional, array of strings)
79+
Names of settings that should be removed from the index when it is mounted.
80+
--
81+
82+
[[searchable-snapshots-api-mount-example]]
83+
==== {api-examples-title}
84+
////
85+
[source,console]
86+
-----------------------------------
87+
PUT /my_docs
88+
{
89+
"settings" : {
90+
"index.number_of_shards" : 1,
91+
"index.number_of_replicas" : 0
92+
}
93+
}
94+
95+
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
96+
{
97+
"include_global_state": false,
98+
"indices": "my_docs"
99+
}
100+
101+
DELETE /my_docs
102+
-----------------------------------
103+
// TEST[setup:setup-repository]
104+
////
105+
106+
Mounts the index `my_docs` from an existing snapshot named `my_snapshot` stored
107+
in the `my_repository` as a new index `docs`:
108+
109+
[source,console]
110+
--------------------------------------------------
111+
POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
112+
{
113+
"index": "my_docs", <1>
114+
"renamed_index": "docs", <2>
115+
"index_settings": { <3>
116+
"index.number_of_replicas": 0
117+
},
118+
"ignored_index_settings": [ "index.refresh_interval" ] <4>
119+
}
120+
--------------------------------------------------
121+
// TEST[continued]
122+
123+
<1> The name of the index in the snapshot to mount
124+
<2> The name of the index to create
125+
<3> Any index settings to add to the new index
126+
<4> List of indices to ignore when mounting the snapshotted index

‎docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[searchable-snapshots-apis]]
4+
== Searchable snapshots APIs
5+
6+
experimental[]
7+
8+
You can use the following APIs to perform searchable snapshots operations.
9+
10+
* <<searchable-snapshots-api-mount-snapshot,Mount snapshot>>
11+
* <<searchable-snapshots-api-clear-cache,Clear cache>>
12+
* <<searchable-snapshots-api-stats,Get stats>>
13+
14+
include::mount-snapshot.asciidoc[]
15+
include::clear-cache.asciidoc[]
16+
include::get-stats.asciidoc[]

‎x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"searchable_snapshots.clear_cache": {
33
"documentation": {
4-
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-clear-indices.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
4+
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-clear-cache.html"
55
},
66
"stability": "experimental",
77
"url": {

‎x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"searchable_snapshots.mount": {
33
"documentation": {
4-
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-mount.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
4+
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot"
55
},
66
"stability": "experimental",
77
"url": {

‎x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"searchable_snapshots.stats": {
33
"documentation": {
4-
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-get-stats.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
4+
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-stats.html"
55
},
66
"stability": "experimental",
77
"url": {

0 commit comments

Comments
 (0)