From 77a2b45dd3eca98f94e559ae352408b6573f9aaa Mon Sep 17 00:00:00 2001 From: Anton Dosov Date: Tue, 25 May 2021 15:19:56 +0200 Subject: [PATCH 1/4] document existing index patterns rest api --- docs/api/index-patterns.asciidoc | 27 +++++ docs/api/index-patterns/create.asciidoc | 102 ++++++++++++++++ docs/api/index-patterns/delete.asciidoc | 41 +++++++ docs/api/index-patterns/get.asciidoc | 64 ++++++++++ .../api/index-patterns/update-fields.asciidoc | 100 ++++++++++++++++ docs/api/index-patterns/update.asciidoc | 109 ++++++++++++++++++ docs/api/saved-objects.asciidoc | 4 +- docs/user/api.asciidoc | 1 + 8 files changed, 447 insertions(+), 1 deletion(-) create mode 100644 docs/api/index-patterns.asciidoc create mode 100644 docs/api/index-patterns/create.asciidoc create mode 100644 docs/api/index-patterns/delete.asciidoc create mode 100644 docs/api/index-patterns/get.asciidoc create mode 100644 docs/api/index-patterns/update-fields.asciidoc create mode 100644 docs/api/index-patterns/update.asciidoc diff --git a/docs/api/index-patterns.asciidoc b/docs/api/index-patterns.asciidoc new file mode 100644 index 0000000000000..7cbc4e462c004 --- /dev/null +++ b/docs/api/index-patterns.asciidoc @@ -0,0 +1,27 @@ +[[index-patterns-api]] +== Index patterns APIs + +experimental[] Manage {kib} index patterns using REST API. + +WARNING: Do not write documents directly to the `.kibana` index. When you write directly +to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. + +WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <, saved objects API>. + +The following index patterns APIs are available: + +* Index patterns + ** <> to retrieve a single {kib} index pattern + ** <> to create {kib} index pattern + ** <> to partially updated {kib} index pattern + ** <> to delete {kib} index pattern +* Fields + ** <> to change field metadata, such as `count, `customLabel` and `format`. + + + +include::index-patterns/get.asciidoc[] +include::index-patterns/create.asciidoc[] +include::index-patterns/update.asciidoc[] +include::index-patterns/delete.asciidoc[] +include::index-patterns/update-fields.asciidoc[] diff --git a/docs/api/index-patterns/create.asciidoc b/docs/api/index-patterns/create.asciidoc new file mode 100644 index 0000000000000..148caf7dc3d7d --- /dev/null +++ b/docs/api/index-patterns/create.asciidoc @@ -0,0 +1,102 @@ +[[index-patterns-api-create]] +=== Create index pattern API +++++ +Create index pattern +++++ + +experimental[] Create {kib} index pattern. + +[[index-patterns-api-create-request]] +==== Request + +`POST :/api/index_patterns/index_pattern` + +`POST :/s//api/index_patterns/index_pattern` + +[[index-patterns-api-create-path-params]] +==== Path parameters + +`space_id`:: + (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. + +[[index-patterns-api-create-body-params]] +==== Request body + +`override`:: (Optional, boolean) If should override an existing index pattern if an +index pattern with the provided title already exists. Defaults to false. + +`refresh_fields`:: (Optional, boolean) If to reload index pattern fields after +the index pattern is stored. Defaults to false. + +`index_pattern`:: (Required, object) Index pattern spec object. All fields are optional. See example request below. + +[[index-patterns-api-create-request-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[index-patterns-api-create-example]] +==== Examples + +Create an index pattern with a custom title: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +{ + "index_pattern": { + "title": "hello" + } +}' +-------------------------------------------------- +// KIBANA + +Customize creation behavior: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +{ + "override": false, + "refresh_fields": true, + "index_pattern": { + "title": "hello" + } +}' +-------------------------------------------------- +// KIBANA + +At creation all index pattern fields are optional, and you can provide them: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +{ + "index_pattern": { + "id": "...", + "version": "...", + "title": "...", + "type": "...", + "timeFieldName": "...", + "sourceFilters": [], + "fields": {}, + "typeMeta": {}, + "fieldFormats": {}, + "fieldAttrs": {}, + "allowNoIndex": "..." + } +}' +-------------------------------------------------- +// KIBANA + + +The API returns created index pattern object: + +[source,sh] +-------------------------------------------------- +{ + "index_pattern": {...} +} +-------------------------------------------------- + diff --git a/docs/api/index-patterns/delete.asciidoc b/docs/api/index-patterns/delete.asciidoc new file mode 100644 index 0000000000000..e81f3d6e9e2f1 --- /dev/null +++ b/docs/api/index-patterns/delete.asciidoc @@ -0,0 +1,41 @@ +[[index-patterns-api-delete]] +=== Delete index pattern API +++++ +Delete index pattern +++++ + +experimental[] Delete {kib} index pattern. + +WARNING: Once you delete an index pattern, _it cannot be recovered_. + +[[index-patterns-api-delete-request]] +==== Request + +`DELETE :/api/index_patterns/index_pattern/` + +`DELETE :/s//api/index_patterns/index_pattern/` + +[[index-patterns-api-delete-path-params]] +==== Path parameters + +`space_id`:: + (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. + +`id`:: + (Required, string) The ID of an index pattern that you want to remove. + +[[index-patterns-api-delete-response-codes]] +==== Response code + +`200`:: + Indicates that index pattern is deleted. Returns an response empty body. + +==== Example + +Delete an index pattern object with the `my-pattern` ID: + +[source,sh] +-------------------------------------------------- +$ curl -X DELETE api/index_patterns/index_pattern/my-pattern +-------------------------------------------------- +// KIBANA diff --git a/docs/api/index-patterns/get.asciidoc b/docs/api/index-patterns/get.asciidoc new file mode 100644 index 0000000000000..684fde4998f31 --- /dev/null +++ b/docs/api/index-patterns/get.asciidoc @@ -0,0 +1,64 @@ +[[index-patterns-api-get]] +=== Get index pattern API +++++ +Get index pattern +++++ + +experimental[] Retrieve a single {kib} index pattern by ID. + +[[index-patterns-api-get-request]] +==== Request + +`GET :/api/index_patterns/index_pattern/` + +`GET :/s//api/index_patterns/index_pattern/` + +[[index-patterns-api-get-params]] +==== Path parameters + +`space_id`:: +(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. + +`id`:: +(Required, string) The ID of the index pattern to retrieve. + +[[index-patterns-api-get-codes]] +==== Response code + +`200`:: +Indicates a successful call. + +`404`:: +Index pattern with id `` doesn't exist. + +[[index-patterns-api-get-example]] +==== Example + +Retrieve the index pattern object with the `my-pattern` ID: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/index_patterns/index_pattern/my-pattern +-------------------------------------------------- +// KIBANA + +The API returns the index pattern object: + +[source,sh] +-------------------------------------------------- +{ + "index_pattern": { + "id": "my-pattern", + "version": "...", + "title": "...", + "type": "...", + "timeFieldName": "...", + "sourceFilters": [], + "fields": {}, + "typeMeta": {}, + "fieldFormats": {}, + "fieldAttrs": {}, + "allowNoIndex: "..." + } +} +-------------------------------------------------- diff --git a/docs/api/index-patterns/update-fields.asciidoc b/docs/api/index-patterns/update-fields.asciidoc new file mode 100644 index 0000000000000..9d4c6eb266662 --- /dev/null +++ b/docs/api/index-patterns/update-fields.asciidoc @@ -0,0 +1,100 @@ +[[index-patterns-fields-api-update]] +=== Update index pattern fields API +++++ +Update index pattern fields metadata +++++ + +experimental[] Update fields endpoint allows you to update fields presentation metadata, such as `count`, +`customLabel`, and `format`. You can update multiple fields in one request. Updates +are merged with persisted metadata. To remove existing metadata specify `null` as value. + +[[index-patterns-fields-api-update-request]] +==== Request + +`POST :/api/index_patterns/index_pattern//fields` + +`POST :/s//api/index_patterns/index_pattern//fields` + +[[index-patterns-fields-api-update-path-params]] +==== Path parameters + +`space_id`:: +(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. + +`id`:: +(Required, string) The ID of index pattern fields of which to update. + +[[index-patterns-fields-api-update-request-body]] +==== Request body + +`fields`:: +(Required, object) fields update spec. See examples below. + + +[[index-patterns-fields-api-update-errors-codes]] +==== Response code + +`200`:: +Indicates a successful call. + +[[index-patterns-fields-api-update-example]] +==== Examples + +Set popularity `count` for field `foo`: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields +{ + "fields": { + "foo": { + "count": 123 + } + } +} +-------------------------------------------------- +// KIBANA + +Update multiple metadata fields in one request: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields +{ + "fields": { + "foo": { + "count": 123, + "customLabel": "Foo" + }, + "bar": { + "customLabel": "Bar" + } + } +} +-------------------------------------------------- +// KIBANA + +Use `null` value to delete metadata: +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields +{ + "fields": { + "foo": { + "customLabel": null + } + } +} +-------------------------------------------------- +// KIBANA + + +The endpoint returns the updated index pattern object: +[source,sh] +-------------------------------------------------- +{ + "index_pattern": { + + } +} +-------------------------------------------------- diff --git a/docs/api/index-patterns/update.asciidoc b/docs/api/index-patterns/update.asciidoc new file mode 100644 index 0000000000000..8115930bf047d --- /dev/null +++ b/docs/api/index-patterns/update.asciidoc @@ -0,0 +1,109 @@ +[[index-patterns-api-update]] +=== Update index pattern API +++++ +Update index pattern +++++ + +experimental[] Update part of an index pattern. Only provided fields will be updated on the +index pattern, missing fields will stay as they are persisted. + +[[index-patterns-api-update-request]] +==== Request + +`POST :/api/index_patterns/index_pattern/` + +`POST :/s//api/index_patterns/index_pattern/` + +[[index-patterns-api-update-path-params]] +==== Path parameters + +`space_id`:: + (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. + +`id`:: + (Required, string) The ID of index pattern to update. + +[[index-patterns-api-update-request-body]] +==== Request body + +`refresh_fields`:: (Optional, boolean) If to reload index pattern fields after +the index pattern is updated. Defaults to false. + +`index_pattern`:: + (Required, object) the index patterns fields to update. ++ + +These fields can be updated partially: + +* `title` +* `timeFieldName` +* `fields` +* `sourceFilters` +* `fieldFormatMap` +* `type` +* `typeMeta` + +[[index-patterns-api-update-errors-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[index-patterns-api-update-example]] +==== Examples + +Update a title of a index pattern: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern +{ + "index_pattern": { + "title": "some-other-pattern-*" + } +} +-------------------------------------------------- +// KIBANA + +Customize update behavior: +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern +{ + "refresh_fields": true, + "index_pattern": { + "fields": {} + } +} +-------------------------------------------------- +// KIBANA + + +All update fields are optional, you can specify the following fields: +[source,sh] +-------------------------------------------------- +$ curl -X POST api/saved_objects/index-pattern/my-pattern +{ + "index_pattern": { + "title": "...", + "timeFieldName": "...", + "sourceFilters": [], + "fieldFormats": {}, + "type": "...", + "typeMeta": {}, + "fields": {} + } +} +-------------------------------------------------- +// KIBANA + +The API returns the updated index pattern object: + +[source,sh] +-------------------------------------------------- +{ + "index_pattern": { + + } +} +-------------------------------------------------- diff --git a/docs/api/saved-objects.asciidoc b/docs/api/saved-objects.asciidoc index ecf975134c64a..a716ba6d0e9ca 100644 --- a/docs/api/saved-objects.asciidoc +++ b/docs/api/saved-objects.asciidoc @@ -1,11 +1,13 @@ [[saved-objects-api]] == Saved objects APIs -Manage {kib} saved objects, including dashboards, visualizations, index patterns, and more. +Manage {kib} saved objects, including dashboards, visualizations, and more. WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. +NOTE: For managing {kib} index patterns use <> instead. + The following saved objects APIs are available: * <> to retrieve a single {kib} saved object by ID diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc index 6daf252c524dd..e4faa81c174e9 100644 --- a/docs/user/api.asciidoc +++ b/docs/user/api.asciidoc @@ -99,6 +99,7 @@ include::{kib-repo-dir}/api/spaces-management.asciidoc[] include::{kib-repo-dir}/api/role-management.asciidoc[] include::{kib-repo-dir}/api/session-management.asciidoc[] include::{kib-repo-dir}/api/saved-objects.asciidoc[] +include::{kib-repo-dir}/api/index-patterns.asciidoc[] include::{kib-repo-dir}/api/alerting.asciidoc[] include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[] include::{kib-repo-dir}/api/dashboard-api.asciidoc[] From 58cdb68d9283e0315fc90e8c74227f73db39ef29 Mon Sep 17 00:00:00 2001 From: Anton Dosov Date: Tue, 25 May 2021 16:41:40 +0200 Subject: [PATCH 2/4] fixes --- docs/api/index-patterns.asciidoc | 4 ++-- docs/api/index-patterns/create.asciidoc | 12 ++++++------ docs/api/index-patterns/get.asciidoc | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/api/index-patterns.asciidoc b/docs/api/index-patterns.asciidoc index 7cbc4e462c004..76b3441a51493 100644 --- a/docs/api/index-patterns.asciidoc +++ b/docs/api/index-patterns.asciidoc @@ -6,7 +6,7 @@ experimental[] Manage {kib} index patterns using REST API. WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. -WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <, saved objects API>. +WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <, saved objects API>>. The following index patterns APIs are available: @@ -16,7 +16,7 @@ The following index patterns APIs are available: ** <> to partially updated {kib} index pattern ** <> to delete {kib} index pattern * Fields - ** <> to change field metadata, such as `count, `customLabel` and `format`. + ** <> to change field metadata, such as `count`, `customLabel` and `format`. diff --git a/docs/api/index-patterns/create.asciidoc b/docs/api/index-patterns/create.asciidoc index 148caf7dc3d7d..b3d6365e825dd 100644 --- a/docs/api/index-patterns/create.asciidoc +++ b/docs/api/index-patterns/create.asciidoc @@ -43,12 +43,12 @@ Create an index pattern with a custom title: [source,sh] -------------------------------------------------- -$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +$ curl -X POST api/index_patterns/index_pattern { "index_pattern": { "title": "hello" } -}' +} -------------------------------------------------- // KIBANA @@ -56,14 +56,14 @@ Customize creation behavior: [source,sh] -------------------------------------------------- -$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +$ curl -X POST api/index_patterns/index_pattern { "override": false, "refresh_fields": true, "index_pattern": { "title": "hello" } -}' +} -------------------------------------------------- // KIBANA @@ -71,7 +71,7 @@ At creation all index pattern fields are optional, and you can provide them: [source,sh] -------------------------------------------------- -$ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +$ curl -X POST api/index_patterns/index_pattern { "index_pattern": { "id": "...", @@ -86,7 +86,7 @@ $ curl -X POST api/index_patterns/index_pattern -H 'kbn-xsrf: true' -H 'Content "fieldAttrs": {}, "allowNoIndex": "..." } -}' +} -------------------------------------------------- // KIBANA diff --git a/docs/api/index-patterns/get.asciidoc b/docs/api/index-patterns/get.asciidoc index 684fde4998f31..9c3aca32d2bf6 100644 --- a/docs/api/index-patterns/get.asciidoc +++ b/docs/api/index-patterns/get.asciidoc @@ -42,7 +42,7 @@ $ curl -X GET api/index_patterns/index_pattern/my-pattern -------------------------------------------------- // KIBANA -The API returns the index pattern object: +The API returns an index pattern object: [source,sh] -------------------------------------------------- From 7fcf1ea3252643d7fc18086bec6e838297e7f971 Mon Sep 17 00:00:00 2001 From: Anton Dosov Date: Tue, 25 May 2021 16:49:47 +0200 Subject: [PATCH 3/4] fix --- docs/api/index-patterns.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/index-patterns.asciidoc b/docs/api/index-patterns.asciidoc index 76b3441a51493..54bcf4fd08c27 100644 --- a/docs/api/index-patterns.asciidoc +++ b/docs/api/index-patterns.asciidoc @@ -6,7 +6,7 @@ experimental[] Manage {kib} index patterns using REST API. WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. -WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <, saved objects API>>. +WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <>. The following index patterns APIs are available: From 049559678382ace8014da470bb768a83d191241b Mon Sep 17 00:00:00 2001 From: Anton Dosov Date: Wed, 26 May 2021 12:57:37 +0200 Subject: [PATCH 4/4] @KOTungseth suggestions --- docs/api/index-patterns.asciidoc | 4 ++-- docs/api/index-patterns/create.asciidoc | 18 +++++++-------- docs/api/index-patterns/delete.asciidoc | 6 ++--- docs/api/index-patterns/get.asciidoc | 4 ++-- .../api/index-patterns/update-fields.asciidoc | 8 +++---- docs/api/index-patterns/update.asciidoc | 22 ++++++++++--------- docs/api/saved-objects.asciidoc | 2 +- 7 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/api/index-patterns.asciidoc b/docs/api/index-patterns.asciidoc index 54bcf4fd08c27..47906e1761138 100644 --- a/docs/api/index-patterns.asciidoc +++ b/docs/api/index-patterns.asciidoc @@ -1,12 +1,12 @@ [[index-patterns-api]] == Index patterns APIs -experimental[] Manage {kib} index patterns using REST API. +experimental[] Manage {kib} index patterns. WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. -WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <>. +WARNING: Use the index patterns API for managing {kib} index patterns instead of lower-level <>. The following index patterns APIs are available: diff --git a/docs/api/index-patterns/create.asciidoc b/docs/api/index-patterns/create.asciidoc index b3d6365e825dd..771292d6f934d 100644 --- a/docs/api/index-patterns/create.asciidoc +++ b/docs/api/index-patterns/create.asciidoc @@ -4,7 +4,7 @@ Create index pattern ++++ -experimental[] Create {kib} index pattern. +experimental[] Create {kib} index patterns. [[index-patterns-api-create-request]] ==== Request @@ -22,13 +22,13 @@ experimental[] Create {kib} index pattern. [[index-patterns-api-create-body-params]] ==== Request body -`override`:: (Optional, boolean) If should override an existing index pattern if an -index pattern with the provided title already exists. Defaults to false. +`override`:: (Optional, boolean) Overrides an existing index pattern if an +index pattern with the provided title already exists. The default is `false`. -`refresh_fields`:: (Optional, boolean) If to reload index pattern fields after -the index pattern is stored. Defaults to false. +`refresh_fields`:: (Optional, boolean) Reloads index pattern fields after +the index pattern is stored. The default is `false`. -`index_pattern`:: (Required, object) Index pattern spec object. All fields are optional. See example request below. +`index_pattern`:: (Required, object) The index pattern object. All fields are optional. [[index-patterns-api-create-request-codes]] ==== Response code @@ -52,7 +52,7 @@ $ curl -X POST api/index_patterns/index_pattern -------------------------------------------------- // KIBANA -Customize creation behavior: +Customize the creation behavior: [source,sh] -------------------------------------------------- @@ -67,7 +67,7 @@ $ curl -X POST api/index_patterns/index_pattern -------------------------------------------------- // KIBANA -At creation all index pattern fields are optional, and you can provide them: +At creation, all index pattern fields are optional: [source,sh] -------------------------------------------------- @@ -91,7 +91,7 @@ $ curl -X POST api/index_patterns/index_pattern // KIBANA -The API returns created index pattern object: +The API returns the index pattern object: [source,sh] -------------------------------------------------- diff --git a/docs/api/index-patterns/delete.asciidoc b/docs/api/index-patterns/delete.asciidoc index e81f3d6e9e2f1..a25f2f13e0b41 100644 --- a/docs/api/index-patterns/delete.asciidoc +++ b/docs/api/index-patterns/delete.asciidoc @@ -4,7 +4,7 @@ Delete index pattern ++++ -experimental[] Delete {kib} index pattern. +experimental[] Delete {kib} index patterns. WARNING: Once you delete an index pattern, _it cannot be recovered_. @@ -22,13 +22,13 @@ WARNING: Once you delete an index pattern, _it cannot be recovered_. (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. `id`:: - (Required, string) The ID of an index pattern that you want to remove. + (Required, string) The ID of the index pattern you want to delete. [[index-patterns-api-delete-response-codes]] ==== Response code `200`:: - Indicates that index pattern is deleted. Returns an response empty body. + Indicates that index pattern is deleted. Returns an empty response body. ==== Example diff --git a/docs/api/index-patterns/get.asciidoc b/docs/api/index-patterns/get.asciidoc index 9c3aca32d2bf6..3f53bf0726bf1 100644 --- a/docs/api/index-patterns/get.asciidoc +++ b/docs/api/index-patterns/get.asciidoc @@ -20,7 +20,7 @@ experimental[] Retrieve a single {kib} index pattern by ID. (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. `id`:: -(Required, string) The ID of the index pattern to retrieve. +(Required, string) The ID of the index pattern you want to retrieve. [[index-patterns-api-get-codes]] ==== Response code @@ -29,7 +29,7 @@ experimental[] Retrieve a single {kib} index pattern by ID. Indicates a successful call. `404`:: -Index pattern with id `` doesn't exist. +The specified index pattern and ID doesn't exist. [[index-patterns-api-get-example]] ==== Example diff --git a/docs/api/index-patterns/update-fields.asciidoc b/docs/api/index-patterns/update-fields.asciidoc index 9d4c6eb266662..e3f98631bb52a 100644 --- a/docs/api/index-patterns/update-fields.asciidoc +++ b/docs/api/index-patterns/update-fields.asciidoc @@ -4,9 +4,9 @@ Update index pattern fields metadata ++++ -experimental[] Update fields endpoint allows you to update fields presentation metadata, such as `count`, +experimental[] Update fields presentation metadata, such as `count`, `customLabel`, and `format`. You can update multiple fields in one request. Updates -are merged with persisted metadata. To remove existing metadata specify `null` as value. +are merged with persisted metadata. To remove existing metadata, specify `null` as the value. [[index-patterns-fields-api-update-request]] ==== Request @@ -22,13 +22,13 @@ are merged with persisted metadata. To remove existing metadata specify `null` a (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. `id`:: -(Required, string) The ID of index pattern fields of which to update. +(Required, string) The ID of the index pattern fields you want to update. [[index-patterns-fields-api-update-request-body]] ==== Request body `fields`:: -(Required, object) fields update spec. See examples below. +(Required, object) the field object [[index-patterns-fields-api-update-errors-codes]] diff --git a/docs/api/index-patterns/update.asciidoc b/docs/api/index-patterns/update.asciidoc index 8115930bf047d..8ed0ff89fb928 100644 --- a/docs/api/index-patterns/update.asciidoc +++ b/docs/api/index-patterns/update.asciidoc @@ -4,8 +4,8 @@ Update index pattern ++++ -experimental[] Update part of an index pattern. Only provided fields will be updated on the -index pattern, missing fields will stay as they are persisted. +experimental[] Update part of an index pattern. Only the specified fields are updated in the +index pattern. Unspecified fields stay as they are persisted. [[index-patterns-api-update-request]] ==== Request @@ -21,19 +21,19 @@ index pattern, missing fields will stay as they are persisted. (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used. `id`:: - (Required, string) The ID of index pattern to update. + (Required, string) The ID of the index pattern you want to update. [[index-patterns-api-update-request-body]] ==== Request body -`refresh_fields`:: (Optional, boolean) If to reload index pattern fields after -the index pattern is updated. Defaults to false. +`refresh_fields`:: (Optional, boolean) Reloads the index pattern fields after +the index pattern is updated. The default is `false`. `index_pattern`:: - (Required, object) the index patterns fields to update. + (Required, object) The index patterns fields you want to update. + -These fields can be updated partially: +You can partially update the following fields: * `title` * `timeFieldName` @@ -52,7 +52,7 @@ These fields can be updated partially: [[index-patterns-api-update-example]] ==== Examples -Update a title of a index pattern: +Update a title of the `` index pattern: [source,sh] -------------------------------------------------- @@ -65,7 +65,8 @@ $ curl -X POST api/saved_objects/index-pattern/my-pattern -------------------------------------------------- // KIBANA -Customize update behavior: +Customize the update behavior: + [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/index-pattern/my-pattern @@ -79,7 +80,8 @@ $ curl -X POST api/saved_objects/index-pattern/my-pattern // KIBANA -All update fields are optional, you can specify the following fields: +All update fields are optional, but you can specify the following fields: + [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/index-pattern/my-pattern diff --git a/docs/api/saved-objects.asciidoc b/docs/api/saved-objects.asciidoc index a716ba6d0e9ca..ba4e5a7e656fc 100644 --- a/docs/api/saved-objects.asciidoc +++ b/docs/api/saved-objects.asciidoc @@ -6,7 +6,7 @@ Manage {kib} saved objects, including dashboards, visualizations, and more. WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. -NOTE: For managing {kib} index patterns use <> instead. +NOTE: For managing {kib} index patterns, use the <>. The following saved objects APIs are available: