From 6d7f85a80abac1756c7da96b465a24d44272cc52 Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 1 Apr 2020 16:04:58 +0200 Subject: [PATCH 1/3] Add basic docs for searchable snapshots REST APIs --- docs/reference/rest-api/index.asciidoc | 2 + .../apis/clear-cache.asciidoc | 77 +++++++++++ .../apis/get-stats.asciidoc | 77 +++++++++++ .../apis/mount-snapshot.asciidoc | 125 ++++++++++++++++++ .../apis/searchable-snapshots-apis.asciidoc | 16 +++ 5 files changed, 297 insertions(+) create mode 100644 docs/reference/searchable-snapshots/apis/clear-cache.asciidoc create mode 100644 docs/reference/searchable-snapshots/apis/get-stats.asciidoc create mode 100644 docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc create mode 100644 docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 8f3a011beb798..dc4c70b7e210e 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -28,6 +28,7 @@ not be included yet. * <> * <> * <> +* <> * <> * <> * <> @@ -54,6 +55,7 @@ include::{es-repo-dir}/migration/migration.asciidoc[] include::{es-repo-dir}/indices/apis/reload-analyzers.asciidoc[] include::{es-repo-dir}/rollup/rollup-api.asciidoc[] include::{es-repo-dir}/search.asciidoc[] +include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc[] include::{xes-repo-dir}/rest-api/security.asciidoc[] include::{es-repo-dir}/slm/apis/slm-api.asciidoc[] include::{es-repo-dir}/transform/apis/index.asciidoc[] diff --git a/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc b/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc new file mode 100644 index 0000000000000..2f4d516bbe6de --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc @@ -0,0 +1,77 @@ +[role="xpack"] +[testenv="basic"] +[[searchable-snapshots-api-clear-cache]] +=== Clear cache API +++++ +Clear cache +++++ + +experimental[] + +Clear the cache of searchable snapshots. + +[[searchable-snapshots-api-clear-cache-request]] +==== {api-request-title} + +`POST /_searchable_snapshots/cache/clear` + +`POST //_searchable_snapshots/cache/clear` + +[[searchable-snapshots-api-clear-cache-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the +`manage` cluster privilege and the `manage` index privilege +for any included indices to use this API. +For more information, see <>. + +[[searchable-snapshots-api-clear-cache-desc]] +==== {api-description-title} + + +[[searchable-snapshots-api-clear-cache-path-params]] +==== {api-path-parms-title} + +``:: +(Optional, string) +A comma-separated list of index names for which the +searchable snapshots cache must be cleared. + + +[[searchable-snapshots-api-clear-cache-example]] +==== {api-examples-title} +//// +[source,console] +----------------------------------- +PUT /my_docs +{ + "settings" : { + "index.number_of_shards" : 1, + "index.number_of_replicas" : 0 + } +} + +PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true +{ + "include_global_state": false, + "indices": "docs" +} + +DELETE /my_docs + +PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +{ + "index": "my_docs", + "renamed_index": "docs" +} +----------------------------------- +// TEST[setup:setup-repository] +//// + +Clears the cache of the index `docs`: + +[source,console] +-------------------------------------------------- +POST /docs/_searchable_snapshots/cache/clear +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/reference/searchable-snapshots/apis/get-stats.asciidoc b/docs/reference/searchable-snapshots/apis/get-stats.asciidoc new file mode 100644 index 0000000000000..734d4b1f6b047 --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/get-stats.asciidoc @@ -0,0 +1,77 @@ +[role="xpack"] +[testenv="basic"] +[[searchable-snapshots-api-stats]] +=== Searchable snapshot statistics API +++++ +Searchable snapshot statistics +++++ + +experimental[] + +Retrieve various statistics about searchable snapshots. + +[[searchable-snapshots-api-stats-request]] +==== {api-request-title} + +`GET /_searchable_snapshots/stats` + +`GET //_searchable_snapshots/stats` + +[[searchable-snapshots-api-stats-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the +`manage` cluster privilege and the `manage` index privilege +for any included indices to use this API. +For more information, see <>. + +[[searchable-snapshots-api-stats-desc]] +==== {api-description-title} + + +[[searchable-snapshots-api-stats-path-params]] +==== {api-path-parms-title} + +``:: +(Optional, string) +A comma-separated list of index names for which the +statistics must be retrieved. + + +[[searchable-snapshots-api-stats-example]] +==== {api-examples-title} +//// +[source,console] +----------------------------------- +PUT /my_docs +{ + "settings" : { + "index.number_of_shards" : 1, + "index.number_of_replicas" : 0 + } +} + +PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true +{ + "include_global_state": false, + "indices": "docs" +} + +DELETE /my_docs + +PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +{ + "index": "my_docs", + "renamed_index": "docs" +} +----------------------------------- +// TEST[setup:setup-repository] +//// + +Retrieves the statistics of the index `docs`: + +[source,console] +-------------------------------------------------- +GET /docs/_searchable_snapshots/stats +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc b/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc new file mode 100644 index 0000000000000..1347881dc59aa --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc @@ -0,0 +1,125 @@ +[role="xpack"] +[testenv="basic"] +[[searchable-snapshots-api-mount-snapshot]] +=== Mount snapshot API +++++ +Mount snapshot +++++ + +experimental[] + +Mount a snapshot as a searchable index. + +[[searchable-snapshots-api-mount-request]] +==== {api-request-title} + +`POST /_snapshot///_mount` + +[[searchable-snapshots-api-mount-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the +`manage` cluster privilege and the `manage` index privilege +for any included indices to use this API. +For more information, see <>. + +[[searchable-snapshots-api-mount-desc]] +==== {api-description-title} + + +[[searchable-snapshots-api-mount-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +The name of the repository containing +the snapshot of the index to mount. + +``:: +(Required, string) +The name of the snapshot of the index +to mount. + +[[searchable-snapshots-api-mount-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion] + +[[searchable-snapshots-api-mount-request-body]] +==== {api-request-body-title} + +`index`:: +(Required, string) +Name of the index contained in the snapshot +whose data is to be mounted. + +If no `renamed_index` is specified this name +will also be used to create the new index. + +`renamed_index`:: ++ +-- +(Optional, string) +Name of the index that will be created. +-- + +`index_settings`:: ++ +-- +(Optional, object) +Settings that should be added to the index when it is mounted. +-- + +`ignore_index_settings`:: ++ +-- +(Optional, array of strings) +Names of settings that should be removed from the index when it is mounted. +-- + +[[searchable-snapshots-api-mount-example]] +==== {api-examples-title} +//// +[source,console] +----------------------------------- +PUT /my_docs +{ + "settings" : { + "index.number_of_shards" : 1, + "index.number_of_replicas" : 0 + } +} + +PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true +{ + "include_global_state": false, + "indices": "docs" +} +----------------------------------- +// TEST[setup:setup-repository] +//// + +Mounts the index `my_docs` from an existing snapshot named `my_snapshot` stored +in the `my_repository` as a new index `docs`: + +[source,console] +-------------------------------------------------- +PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true <1> +{ + "index": "my_docs", <2> + "renamed_index": "docs", <3> + "index_settings": { <4> + "index.number_of_replicas": 0 + }, + "ignored_index_settings": [ "index.refresh_interval" ] <5> +} +-------------------------------------------------- +// TESTRESPONSE + +<1> Wait for the operation to be completed before returning +<2> The name of the index in the snapshot to mount +<3> The name of the index to create +<4> Any index settings to add to the new index +<5> List of indices to ignore when mounting the snapshotted index diff --git a/docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc b/docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc new file mode 100644 index 0000000000000..5b56c64409057 --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc @@ -0,0 +1,16 @@ +[role="xpack"] +[testenv="basic"] +[[searchable-snapshots-apis]] +== Searchable snapshots APIs + +experimental[] + +You can use the following APIs to perform searchable snapshots operations. + +* <> +* <> +* <> + +include::mount-snapshot.asciidoc[] +include::clear-cache.asciidoc[] +include::get-stats.asciidoc[] From d601c33bb27993fad356e79ae18e171efe81690b Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 1 Apr 2020 16:11:50 +0200 Subject: [PATCH 2/3] Update links --- .../rest-api-spec/api/searchable_snapshots.clear_cache.json | 2 +- .../resources/rest-api-spec/api/searchable_snapshots.mount.json | 2 +- .../resources/rest-api-spec/api/searchable_snapshots.stats.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json index def34d9383bb7..216cedd93ea9a 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json @@ -1,7 +1,7 @@ { "searchable_snapshots.clear_cache": { "documentation": { - "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." + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-clear-cache.html" }, "stability": "experimental", "url": { diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json index 4a9a0ad4c3235..995944cf8f9ec 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json @@ -1,7 +1,7 @@ { "searchable_snapshots.mount": { "documentation": { - "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." + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot" }, "stability": "experimental", "url": { diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json index 604e30a7cac5e..b34fd7084b137 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json @@ -1,7 +1,7 @@ { "searchable_snapshots.stats": { "documentation": { - "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." + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-stats.html" }, "stability": "experimental", "url": { From efa9d83f71673ba8bd69bcbe1adc878dbe4e4918 Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 1 Apr 2020 17:18:18 +0200 Subject: [PATCH 3/3] Fix tests --- .../apis/clear-cache.asciidoc | 11 ++++---- .../apis/get-stats.asciidoc | 11 ++++---- .../apis/mount-snapshot.asciidoc | 25 ++++++++++--------- 3 files changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc b/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc index 2f4d516bbe6de..9d5685fdc6834 100644 --- a/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc +++ b/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc @@ -43,7 +43,7 @@ searchable snapshots cache must be cleared. //// [source,console] ----------------------------------- -PUT /my_docs +PUT /docs { "settings" : { "index.number_of_shards" : 1, @@ -57,12 +57,11 @@ PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true "indices": "docs" } -DELETE /my_docs +DELETE /docs -PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true { - "index": "my_docs", - "renamed_index": "docs" + "index": "docs" } ----------------------------------- // TEST[setup:setup-repository] @@ -74,4 +73,4 @@ Clears the cache of the index `docs`: -------------------------------------------------- POST /docs/_searchable_snapshots/cache/clear -------------------------------------------------- -// TESTRESPONSE +// TEST[continued] diff --git a/docs/reference/searchable-snapshots/apis/get-stats.asciidoc b/docs/reference/searchable-snapshots/apis/get-stats.asciidoc index 734d4b1f6b047..c54fe96d9f807 100644 --- a/docs/reference/searchable-snapshots/apis/get-stats.asciidoc +++ b/docs/reference/searchable-snapshots/apis/get-stats.asciidoc @@ -43,7 +43,7 @@ statistics must be retrieved. //// [source,console] ----------------------------------- -PUT /my_docs +PUT /docs { "settings" : { "index.number_of_shards" : 1, @@ -57,12 +57,11 @@ PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true "indices": "docs" } -DELETE /my_docs +DELETE /docs -PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true { - "index": "my_docs", - "renamed_index": "docs" + "index": "docs" } ----------------------------------- // TEST[setup:setup-repository] @@ -74,4 +73,4 @@ Retrieves the statistics of the index `docs`: -------------------------------------------------- GET /docs/_searchable_snapshots/stats -------------------------------------------------- -// TESTRESPONSE +// TEST[continued] diff --git a/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc b/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc index 1347881dc59aa..7522e64944ef0 100644 --- a/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc +++ b/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc @@ -95,8 +95,10 @@ PUT /my_docs PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true { "include_global_state": false, - "indices": "docs" + "indices": "my_docs" } + +DELETE /my_docs ----------------------------------- // TEST[setup:setup-repository] //// @@ -106,20 +108,19 @@ in the `my_repository` as a new index `docs`: [source,console] -------------------------------------------------- -PUT /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true <1> +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true { - "index": "my_docs", <2> - "renamed_index": "docs", <3> - "index_settings": { <4> + "index": "my_docs", <1> + "renamed_index": "docs", <2> + "index_settings": { <3> "index.number_of_replicas": 0 }, - "ignored_index_settings": [ "index.refresh_interval" ] <5> + "ignored_index_settings": [ "index.refresh_interval" ] <4> } -------------------------------------------------- -// TESTRESPONSE +// TEST[continued] -<1> Wait for the operation to be completed before returning -<2> The name of the index in the snapshot to mount -<3> The name of the index to create -<4> Any index settings to add to the new index -<5> List of indices to ignore when mounting the snapshotted index +<1> The name of the index in the snapshot to mount +<2> The name of the index to create +<3> Any index settings to add to the new index +<4> List of indices to ignore when mounting the snapshotted index