diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 9c7d52f0ae077..56b5214d7a03c 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -31,6 +31,7 @@ endif::[] * <> * <> * <> +* <> * <> * <> * <> @@ -59,6 +60,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..9d5685fdc6834 --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/clear-cache.asciidoc @@ -0,0 +1,76 @@ +[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 /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 /docs + +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +{ + "index": "docs" +} +----------------------------------- +// TEST[setup:setup-repository] +//// + +Clears the cache of the index `docs`: + +[source,console] +-------------------------------------------------- +POST /docs/_searchable_snapshots/cache/clear +-------------------------------------------------- +// TEST[continued] 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..c54fe96d9f807 --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/get-stats.asciidoc @@ -0,0 +1,76 @@ +[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 /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 /docs + +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +{ + "index": "docs" +} +----------------------------------- +// TEST[setup:setup-repository] +//// + +Retrieves the statistics of the index `docs`: + +[source,console] +-------------------------------------------------- +GET /docs/_searchable_snapshots/stats +-------------------------------------------------- +// TEST[continued] 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..7522e64944ef0 --- /dev/null +++ b/docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc @@ -0,0 +1,126 @@ +[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": "my_docs" +} + +DELETE /my_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] +-------------------------------------------------- +POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true +{ + "index": "my_docs", <1> + "renamed_index": "docs", <2> + "index_settings": { <3> + "index.number_of_replicas": 0 + }, + "ignored_index_settings": [ "index.refresh_interval" ] <4> +} +-------------------------------------------------- +// TEST[continued] + +<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 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[] 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": {