From 5c41916021ebef9886f1028f2db93f84d3d449b8 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 25 Sep 2024 19:54:54 +0200 Subject: [PATCH 01/26] [DOCS] Update first quick start with mappings examples --- .../quickstart/getting-started.asciidoc | 145 ++++++++++++++---- docs/reference/quickstart/index.asciidoc | 4 +- 2 files changed, 118 insertions(+), 31 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index e674dda147bcc..4967ce526b38b 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -1,29 +1,16 @@ [[getting-started]] -== Quick start: Add data using Elasticsearch APIs +== Quick start: Indices, documents, and mappings ++++ -Basics: Add data using APIs +Basics: Indices, documents, and mappings ++++ In this quick start guide, you'll learn how to do the following tasks: -* Add a small, non-timestamped dataset to {es} using Elasticsearch REST APIs. -* Run basic searches. - -[discrete] -[[add-data]] -=== Add data - -You add data to {es} as JSON objects called documents. -{es} stores these -documents in searchable indices. - -[discrete] -[[add-single-document]] -==== Add a single document - -Submit the following indexing request to add a single document to the -`books` index. -The request automatically creates the index. +* Create an index +* Add documents +* Inspect a document's structure +* Use dynamic and explicit mappings of data types +* Do basic searches //// [source,console] @@ -40,6 +27,46 @@ DELETE books //// +[discrete] +[[getting-started-index-creation]] +=== Create an index + +Create a new index named `books`: + +[source,console] +---- +PUT /books +---- +// TEST + +List all indices to confirm creation: + +[source,console] +---- +GET /_cat/indices +---- +// TEST[continued] + +[discrete] +[[getting-started-add-documents]] +=== Add documents + +You add data to {es} as JSON objects called documents. +{es} stores these +documents in searchable indices. + +[discrete] +[[getting-started-add-single-document]] +==== Add a single document + +Submit the following indexing request to add a single document to the +`books` index. + +[TIP] +==== +If the index didn't already exist, the request would automatically create it. +==== + [source,console] ---- POST books/_doc @@ -72,12 +99,11 @@ The response includes metadata that {es} generates for the document including a =============== [discrete] -[[add-multiple-documents]] +[[getting-started-add-multiple-documents]] ==== Add multiple documents -Use the `_bulk` endpoint to add multiple documents in one request. Bulk data -must be newline-delimited JSON (NDJSON). Each line must end in a newline -character (`\n`), including the last line. +Use the <> to add multiple documents in one request. Bulk data +must be newline-delimited JSON (NDJSON). [source,console] ---- @@ -193,31 +219,92 @@ You should receive a response indicating there were no errors. =============== [discrete] -[[qs-search-data]] +[[getting-started-mappings-and-data-types]] +=== Mappings and data types + +[discrete] +[[getting-started-dynamic-mapping]] +==== Dynamic mapping + +When using dynamic mapping, {es} automatically creates mappings for new fields by default. +The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index. + +Let's add a new document to the `books` index with a field that doesn't exist, to see how dynamic mapping works. + +[source,console] +---- +PUT /books/_doc +{"name": "The Great Gatsby", "author": "F. Scott Fitzgerald", "release_date": "1925-04-10", "page_count": 180, "new_field": "This is a dynamically added field"} +---- +// TEST[continued] + +View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `keyword` data type. + +[source,console] +---- +GET /books/_mapping +---- +// TEST[continued] + +[discrete] +[[getting-started-explicit-mapping]] +==== Explicit mapping + +Create an index named `my-explicit-mappings-books` with explicit mappings: + +[source,console] +---- +PUT /my-explicit-mappings-books +{ + "mappings": { + "dynamic": false, <1> + "properties": { + "name": { "type": "text" }, + "author": { "type": "text" }, + "release_date": { "type": "date", "format": "yyyy-MM-dd" }, + "page_count": { "type": "integer" } + } + } +} +---- +// TEST[continued] +<1> Disables dynamic mapping for the index. Documents containing fields not defined in the mapping will be rejected. + +[discrete] +[[getting-started-combined-mapping]] +=== Combine dynamic and explicit mappings + +As long as an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. +This allows you to combine dynamic and explicit mappings. + +[discrete] +[[getting-started-search-data]] === Search data Indexed documents are available for search in near real-time. +// TODO: You'll find more detailed quick start guides in TODO [discrete] -[[search-all-documents]] +[[getting-started-search-all-documents]] ==== Search all documents Run the following command to search the `books` index for all documents: + [source,console] ---- GET books/_search ---- // TEST[continued] -The `_source` of each hit contains the original +The `_source` metadata field of each hit contains the original JSON object submitted during indexing. [discrete] -[[qs-match-query]] +[[getting-started-match-query]] ==== `match` query You can use the <> to search for documents that contain a specific value in a specific field. -This is the standard query for performing full-text search, including fuzzy matching and phrase searches. +This is the standard query for full-text searches. Run the following command to search the `books` index for documents containing `brave` in the `name` field: diff --git a/docs/reference/quickstart/index.asciidoc b/docs/reference/quickstart/index.asciidoc index 6bfed4c198c75..26793c96b43a8 100644 --- a/docs/reference/quickstart/index.asciidoc +++ b/docs/reference/quickstart/index.asciidoc @@ -15,7 +15,7 @@ Get started <> , or see our <>. Learn how to add data to {es} and perform basic searches. +* <>. Learn about indices, documents, and mappings, and perform a basic search. [discrete] [[quickstart-python-links]] @@ -26,4 +26,4 @@ If you're interested in using {es} with Python, check out Elastic Search Labs: * https://github.com/elastic/elasticsearch-labs[`elasticsearch-labs` repository]: Contains a range of Python https://github.com/elastic/elasticsearch-labs/tree/main/notebooks[notebooks] and https://github.com/elastic/elasticsearch-labs/tree/main/example-apps[example apps]. * https://www.elastic.co/search-labs/tutorials/search-tutorial/welcome[Tutorial]: This walks you through building a complete search solution with {es} from the ground up using Flask. -include::getting-started.asciidoc[] \ No newline at end of file +include::getting-started.asciidoc[] From 8a6515fe562eb1793dce8feb04f8f64958736cd3 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 09:29:43 +0200 Subject: [PATCH 02/26] Fix test? --- docs/reference/quickstart/getting-started.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 4967ce526b38b..a011dad118ca4 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -37,7 +37,6 @@ Create a new index named `books`: ---- PUT /books ---- -// TEST List all indices to confirm creation: From 5ee1ec97a8ceefbc5a75e691a35397efef895cff Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 12:30:17 +0200 Subject: [PATCH 03/26] Fix tests, update verbiage Added my-explicit-mappings-books to TESTSETUP and TEARDOWN. Skipped the initial PUT /books test as the index is already set up. Modified the GET /_cat/indices command to include specific parameters. Changed a PUT request to POST for adding a document. Updated the description of the dynamically added field's data type from keyword to text. Made minor wording adjustments throughout the document. --- .../quickstart/getting-started.asciidoc | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index a011dad118ca4..33e8b67f2adab 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -16,12 +16,14 @@ In this quick start guide, you'll learn how to do the following tasks: [source,console] ---- PUT books +PUT my-explicit-mappings-books ---- // TESTSETUP [source,console] -------------------------------------------------- DELETE books +DELETE my-explicit-mappings-books -------------------------------------------------- // TEARDOWN @@ -37,15 +39,18 @@ Create a new index named `books`: ---- PUT /books ---- +// TEST[skip: index already setup] -List all indices to confirm creation: +List all indices to confirm the `books` index was created: [source,console] ---- -GET /_cat/indices +GET /_cat/indices?v&h=index,docs.count&s=index:asc ---- // TEST[continued] +Here, the query parameters `v` and `h` are used to filter and format the default output of the <>. + [discrete] [[getting-started-add-documents]] === Add documents @@ -71,7 +76,7 @@ If the index didn't already exist, the request would automatically create it. POST books/_doc {"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} ---- -// TEST[s/_doc/_doc?refresh=wait_for/] +// TEST[continued] The response includes metadata that {es} generates for the document including a unique `_id` for the document within the index. @@ -232,12 +237,18 @@ Let's add a new document to the `books` index with a field that doesn't exist, t [source,console] ---- -PUT /books/_doc -{"name": "The Great Gatsby", "author": "F. Scott Fitzgerald", "release_date": "1925-04-10", "page_count": 180, "new_field": "This is a dynamically added field"} +POST /books/_doc +{ + "name": "The Great Gatsby", + "author": "F. Scott Fitzgerald", + "release_date": "1925-04-10", + "page_count": 180, + "new_field": "This is a dynamically added field" +} ---- // TEST[continued] -View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `keyword` data type. +View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `text` data type. [source,console] ---- @@ -273,7 +284,7 @@ PUT /my-explicit-mappings-books [[getting-started-combined-mapping]] === Combine dynamic and explicit mappings -As long as an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. +When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. This allows you to combine dynamic and explicit mappings. [discrete] From 119c32ee4ea2b69137a847001f4ffe1bcff1faf1 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 12:55:28 +0200 Subject: [PATCH 04/26] Fix heading level --- docs/reference/quickstart/getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 33e8b67f2adab..f273edeae3460 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -282,7 +282,7 @@ PUT /my-explicit-mappings-books [discrete] [[getting-started-combined-mapping]] -=== Combine dynamic and explicit mappings +==== Combine dynamic and explicit mappings When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. This allows you to combine dynamic and explicit mappings. From ce595bf302d769a8874b4d65b23fc47a43cce334 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 13:08:14 +0200 Subject: [PATCH 05/26] Use verbs for heading consistency --- .../quickstart/getting-started.asciidoc | 29 ++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index f273edeae3460..75f759171c344 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -7,7 +7,7 @@ In this quick start guide, you'll learn how to do the following tasks: * Create an index -* Add documents +* Add data as documents * Inspect a document's structure * Use dynamic and explicit mappings of data types * Do basic searches @@ -31,7 +31,7 @@ DELETE my-explicit-mappings-books [discrete] [[getting-started-index-creation]] -=== Create an index +=== Create index Create a new index named `books`: @@ -53,7 +53,7 @@ Here, the query parameters `v` and `h` are used to filter and format the default [discrete] [[getting-started-add-documents]] -=== Add documents +=== Add data You add data to {es} as JSON objects called documents. {es} stores these @@ -224,11 +224,11 @@ You should receive a response indicating there were no errors. [discrete] [[getting-started-mappings-and-data-types]] -=== Mappings and data types +=== Define mappings and data types [discrete] [[getting-started-dynamic-mapping]] -==== Dynamic mapping +==== Use dynamic mapping When using dynamic mapping, {es} automatically creates mappings for new fields by default. The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index. @@ -258,7 +258,7 @@ GET /books/_mapping [discrete] [[getting-started-explicit-mapping]] -==== Explicit mapping +==== Define explicit mapping Create an index named `my-explicit-mappings-books` with explicit mappings: @@ -329,4 +329,19 @@ GET books/_search } } ---- -// TEST[continued] \ No newline at end of file +// TEST[continued] + +[discrete] +[[getting-started-delete-indices]] +=== Delete index + +Delete indices using the <>. + +[source,console] +---- +DELETE /books +DELETE /my-explicit-mappings-books +---- +// TEST[skip:handled by setup/teardown] + + From 6a5a17a8d7d8a7d78be7c6690dc7352738eed69c Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 13:21:26 +0200 Subject: [PATCH 06/26] Remove superfluous list item --- docs/reference/quickstart/getting-started.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 75f759171c344..1c309b01cd9bb 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -8,7 +8,6 @@ In this quick start guide, you'll learn how to do the following tasks: * Create an index * Add data as documents -* Inspect a document's structure * Use dynamic and explicit mappings of data types * Do basic searches From f534690102a1d928e31c602ad7dbf6316f4a103d Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 14:33:02 +0200 Subject: [PATCH 07/26] I guess need some context right --- docs/reference/quickstart/getting-started.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 1c309b01cd9bb..c81abf5a0a963 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -225,6 +225,8 @@ You should receive a response indicating there were no errors. [[getting-started-mappings-and-data-types]] === Define mappings and data types +<> define how data is stored and indexed in {es}, much like a schema for a relationaldatabase. + [discrete] [[getting-started-dynamic-mapping]] ==== Use dynamic mapping From a2e5aeb9aeb2e3e8974ec966856cc6fae490c499 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 26 Sep 2024 14:33:37 +0200 Subject: [PATCH 08/26] Fix typo --- docs/reference/quickstart/getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index c81abf5a0a963..f9bbe5ac7b396 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -225,7 +225,7 @@ You should receive a response indicating there were no errors. [[getting-started-mappings-and-data-types]] === Define mappings and data types -<> define how data is stored and indexed in {es}, much like a schema for a relationaldatabase. +<> define how data is stored and indexed in {es}, much like a schema for a relational database. [discrete] [[getting-started-dynamic-mapping]] From 31d8006392b2eb3e578309b43493ad420c6a99e6 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 27 Sep 2024 16:12:58 +0200 Subject: [PATCH 09/26] Expand intro, add prerequisites, add hints for Console usage --- .../quickstart/getting-started.asciidoc | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index f9bbe5ac7b396..9b5c287c1d6af 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -4,12 +4,21 @@ Basics: Indices, documents, and mappings ++++ -In this quick start guide, you'll learn how to do the following tasks: +This quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: indices, documents, and field type mappings. +You'll learn how to create an index, add data as documents, work with dynamic and explicit mappings, and perform your first basic searches. -* Create an index -* Add data as documents -* Use dynamic and explicit mappings of data types -* Do basic searches +[TIP] +==== +By default the examples are in Dev Tools Console syntax, but you can {kibana-ref}/console-kibana.html#import-export-console-requests[export to other programming languages] in the Console UI. +==== + +[discrete] +[[getting-started-prerequisites]] +=== Prerequisites + +Before you begin, you need to have a running {es} cluster. + +Set up a fast <>, or refer to <> for other deployment options. //// [source,console] From c0eba9fcafe7b01d0321ce6a732782752b269b33 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Mon, 30 Sep 2024 12:26:26 +0200 Subject: [PATCH 10/26] Update mappings page with combo info --- docs/reference/mapping.asciidoc | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 239614345d782..aa1e9e437a322 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -75,9 +75,23 @@ reindexing. You can use runtime fields in conjunction with indexed fields to balance resource usage and performance. Your index will be smaller, but with slower search performance. +[discrete] +[[mapping-combine-explicit-dynamic]] +== Combine explicit and dynamic mappings + +Explicit mappings should almost always be defined at index creation, because +you can't change mappings for fields that already contain data. + +You can _update_ mappings for existing fields under certain conditions: + +. You can add new fields to an existing mapping. +. You can change the mapping for fields that don't contain any data. +. You can add new <> for existing fields. + [discrete] [[mapping-limit-settings]] -== Settings to prevent mapping explosion +== Prevent mapping explosions + Defining too many fields in an index can lead to a mapping explosion, which can cause out of memory errors and difficult situations to recover from. From 3a3a9a47ef0606ad91544f4d13c4c8d6b6cb7b7e Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Mon, 30 Sep 2024 12:27:42 +0200 Subject: [PATCH 11/26] Updates per feedback - Updated title and titleabbrev to focus on indexing and searching using APIs - Added links - Clarified explanation about code examples and language conversion - Added numbered steps (1-5) - Added example responses - Included more detailed explanations with numbered annotations in code snippets - Added tip about other ways to add data to Elasticsearch - Added more context and explanations for search operations --- .../quickstart/getting-started.asciidoc | 276 +++++++++++++++--- 1 file changed, 232 insertions(+), 44 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 9b5c287c1d6af..226cd10caa1d9 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -1,15 +1,17 @@ [[getting-started]] -== Quick start: Indices, documents, and mappings +== Index and search data using {es} APIs ++++ -Basics: Indices, documents, and mappings +Basics: Index and search using APIs ++++ -This quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: indices, documents, and field type mappings. +This quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: <>. + You'll learn how to create an index, add data as documents, work with dynamic and explicit mappings, and perform your first basic searches. [TIP] ==== -By default the examples are in Dev Tools Console syntax, but you can {kibana-ref}/console-kibana.html#import-export-console-requests[export to other programming languages] in the Console UI. +The code examples in this tutorial are in {kibana-ref}/console-kibana.html[Console] syntax by default. +You can {kibana-ref}/console-kibana.html#import-export-console-requests[convert into other programming languages] in the Console UI. ==== [discrete] @@ -17,8 +19,8 @@ By default the examples are in Dev Tools Console syntax, but you can {kibana-ref === Prerequisites Before you begin, you need to have a running {es} cluster. - -Set up a fast <>, or refer to <> for other deployment options. +The fastest way to get started is with a <>. +Refer to <> for other deployment options. //// [source,console] @@ -39,7 +41,7 @@ DELETE my-explicit-mappings-books [discrete] [[getting-started-index-creation]] -=== Create index +=== Step 1: Create an index Create a new index named `books`: @@ -49,19 +51,31 @@ PUT /books ---- // TEST[skip: index already setup] -List all indices to confirm the `books` index was created: +A `200` response indicates the index was created successfully. -[source,console] +.Expand to see example response +[%collapsible] +=============== +[source,console-result] ---- -GET /_cat/indices?v&h=index,docs.count&s=index:asc +{ + "acknowledged": true, + "shards_acknowledged": true, + "index": "books" +} ---- -// TEST[continued] - -Here, the query parameters `v` and `h` are used to filter and format the default output of the <>. +// TEST[skip: index already setup] +=============== [discrete] [[getting-started-add-documents]] -=== Add data +=== Step 2: Add data to your index + +[TIP] +==== +This tutorial uses {es} APIs, but there are many other ways to +<>. +==== You add data to {es} as JSON objects called documents. {es} stores these @@ -76,7 +90,7 @@ Submit the following indexing request to add a single document to the [TIP] ==== -If the index didn't already exist, the request would automatically create it. +If the index didn't already exist, this request would automatically create it. ==== [source,console] @@ -86,7 +100,7 @@ POST books/_doc ---- // TEST[continued] -The response includes metadata that {es} generates for the document including a unique `_id` for the document within the index. +The response includes metadata that {es} generates for the document, including a unique `_id` for the document within the index. .Expand to see example response [%collapsible] @@ -94,20 +108,30 @@ The response includes metadata that {es} generates for the document including a [source,console-result] ---- { - "_index": "books", - "_id": "O0lG2IsBaSa7VYx_rEia", - "_version": 1, - "result": "created", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 + "_index": "books", <1> + "_id": "O0lG2IsBaSa7VYx_rEia", <2> + "_version": 1, <3> + "result": "created", <4> + "_shards": { <5> + "total": 2, <6> + "successful": 2, <7> + "failed": 0 <8> }, - "_seq_no": 0, - "_primary_term": 1 + "_seq_no": 0, <9> + "_primary_term": 1 <10> } ---- -// TEST[skip:TODO] +// TEST[s/O0lG2IsBaSa7VYx_rEia/*/] +<1> The `_index` field indicates the index the document was added to. +<2> The `_id` field is the unique identifier for the document. +<3> The `_version` field indicates the version of the document. +<4> The `result` field indicates the result of the indexing operation. +<5> The `_shards` field contains information about the number of <> that the indexing operation was executed on and the number that succeeded. +<6> The `total` field indicates the total number of shards for the index. +<7> The `successful` field indicates the number of shards that the indexing operation was executed on. +<8> The `failed` field indicates the number of shards that failed during the indexing operation. '0' indicates no failures. +<9> The `_seq_no` field holds a monotonically increasing number incremented for each indexing operation on a shard. +<10> The `_primary_term` field is a monotonically increasing number incremented each time a primary shard is assigned to a different node. =============== [discrete] @@ -115,7 +139,7 @@ The response includes metadata that {es} generates for the document including a ==== Add multiple documents Use the <> to add multiple documents in one request. Bulk data -must be newline-delimited JSON (NDJSON). +must be formatted as newline-delimited JSON (NDJSON). [source,console] ---- @@ -232,9 +256,9 @@ You should receive a response indicating there were no errors. [discrete] [[getting-started-mappings-and-data-types]] -=== Define mappings and data types +=== Step 3: Define mappings and data types -<> define how data is stored and indexed in {es}, much like a schema for a relational database. +<> define how data is stored and indexed in {es}, like a schema in a relational database. [discrete] [[getting-started-dynamic-mapping]] @@ -243,7 +267,7 @@ You should receive a response indicating there were no errors. When using dynamic mapping, {es} automatically creates mappings for new fields by default. The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index. -Let's add a new document to the `books` index with a field that doesn't exist, to see how dynamic mapping works. +Add a new document to the `books` index with a field that doesn't exist, to see how dynamic mapping works. [source,console] ---- @@ -253,11 +277,11 @@ POST /books/_doc "author": "F. Scott Fitzgerald", "release_date": "1925-04-10", "page_count": 180, - "new_field": "This is a dynamically added field" + "new_field": "I'm a new field added dynamically" <1> } ---- // TEST[continued] - +<1> This field is dynamically added to the document. View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `text` data type. [source,console] @@ -266,6 +290,56 @@ GET /books/_mapping ---- // TEST[continued] +.Expand to see example response +[%collapsible] +=============== +[source,console-result] +---- +{ + "books": { + "mappings": { + "properties": { + "author": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "name": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "new_field": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "page_count": { + "type": "long" + }, + "release_date": { + "type": "date" + } + } + } + } +} +---- +// TEST[continued] +=============== + [discrete] [[getting-started-explicit-mapping]] ==== Define explicit mapping @@ -278,30 +352,49 @@ PUT /my-explicit-mappings-books { "mappings": { "dynamic": false, <1> - "properties": { - "name": { "type": "text" }, + "properties": { <2> + "name": { "type": "text" }, <3> "author": { "type": "text" }, - "release_date": { "type": "date", "format": "yyyy-MM-dd" }, - "page_count": { "type": "integer" } + "release_date": { "type": "date", "format": "yyyy-MM-dd" }, <4> + "page_count": { "type": "integer" } <5> } } } ---- // TEST[continued] <1> Disables dynamic mapping for the index. Documents containing fields not defined in the mapping will be rejected. +<2> The `properties` object defines the fields and their data types for documents in this index. +<3> Defines the "name" field as type "text", suitable for full-text search on book titles. +<4> Specifies the "release_date" field as a "date" type with the specific format `yyyy-MM-dd`. +<5> Sets the "page_count" field as an "integer" type for storing the number of pages. + +.Expand to see example response +[%collapsible] +=============== +[source,console-result] +---- +{ + "acknowledged": true, + "shards_acknowledged": true, + "index": "my-explicit-mappings-books" +} +---- +// TEST[skip:already created in setup] +=============== [discrete] [[getting-started-combined-mapping]] ==== Combine dynamic and explicit mappings +Explicit mappings are defined at index creation, and documents must conform to these mappings. When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. -This allows you to combine dynamic and explicit mappings. +This allows you to <>. [discrete] [[getting-started-search-data]] -=== Search data +=== Step 4: Search your index -Indexed documents are available for search in near real-time. +Indexed documents are available for search in near real-time, using the <>. // TODO: You'll find more detailed quick start guides in TODO [discrete] @@ -316,8 +409,55 @@ GET books/_search ---- // TEST[continued] -The `_source` metadata field of each hit contains the original -JSON object submitted during indexing. +.Expand to see example response (truncated) +[%collapsible] +=============== +[source,console-result] +---- +{ + "took": 2, <1> + "timed_out": false, <2> + "_shards": { <3> + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { <4> + "total": { <5> + "value": 7, + "relation": "eq" + }, + "max_score": 1, <6> + "hits": [ + { + "_index": "books", <7> + "_id": "CwICQpIBO6vvGGiC_3Ls", <8> + "_score": 1, <9> + "_source": { <10> + "name": "Brave New World", + "author": "Aldous Huxley", + "release_date": "1932-06-01", + "page_count": 268 + } + }, + ... (truncated) + ] + } +} +---- +// TEST[continued] +<1> The `took` field indicates the time in milliseconds for {es} to execute the search +<2> The `timed_out` field indicates whether the search timed out +<3> The `_shards` field contains information about the number of <> that the search was executed on and the number that succeeded +<4> The `hits` object contains the search results +<5> The `total` object provides information about the total number of matching documents +<6> The `max_score` field indicates the highest relevance score among all matching documents +<7> The `_index` field indicates the index the document belongs to +<8> The `_id` field is the document's unique identifier +<9> The `_score` field indicates the relevance score of the document +<10> The `_source` field contains the original JSON object submitted during indexing +=============== [discrete] [[getting-started-match-query]] @@ -341,11 +481,54 @@ GET books/_search ---- // TEST[continued] +.Expand to see example response +[%collapsible] +=============== +[source,console-result] +---- +{ + "took": 9, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 0.6931471, <1> + "hits": [ + { + "_index": "books", + "_id": "CwICQpIBO6vvGGiC_3Ls", + "_score": 0.6931471, + "_source": { + "name": "Brave New World", + "author": "Aldous Huxley", + "release_date": "1932-06-01", + "page_count": 268 + } + } + ] + } +} +---- +// TEST[continued] +<1> The `max_score` is the score of the highest-scoring document in the results. In this case, there is only one matching document, so the `max_score` is the score of that document. +=============== + [discrete] [[getting-started-delete-indices]] -=== Delete index +=== Step 5: Delete your indices (optional) + +When following along with examples, you might want to delete an index to start from scratch. +You can delete indices using the <>. -Delete indices using the <>. +For example, run the following command to delete the indices created in this tutorial: [source,console] ---- @@ -354,4 +537,9 @@ DELETE /my-explicit-mappings-books ---- // TEST[skip:handled by setup/teardown] +[CAUTION] +==== +Deleting an index permanently deletes its documents, shards, and metadata. +==== + From 6ca87ff0c114a58ab89a3e7d4d59116d8479d2e8 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 30 Sep 2024 12:47:42 +0200 Subject: [PATCH 12/26] Update link text --- docs/reference/quickstart/index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/quickstart/index.asciidoc b/docs/reference/quickstart/index.asciidoc index 26793c96b43a8..2d9114882254f 100644 --- a/docs/reference/quickstart/index.asciidoc +++ b/docs/reference/quickstart/index.asciidoc @@ -15,7 +15,7 @@ Get started <> , or see our <>. Learn about indices, documents, and mappings, and perform a basic search. +* <>. Learn about indices, documents, and mappings, and perform a basic search. [discrete] [[quickstart-python-links]] From f6b77d10d9c67c9c0cce43d68d5d628f4d6890cc Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 1 Oct 2024 13:43:34 +0200 Subject: [PATCH 13/26] Minor touchups, mainly to rerun CI --- docs/reference/quickstart/getting-started.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 226cd10caa1d9..d5b7d9ff7cb64 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -102,7 +102,7 @@ POST books/_doc The response includes metadata that {es} generates for the document, including a unique `_id` for the document within the index. -.Expand to see example response +.Expand to see example response with annotations [%collapsible] =============== [source,console-result] @@ -409,7 +409,7 @@ GET books/_search ---- // TEST[continued] -.Expand to see example response (truncated) +.Expand to see (truncated) example response with annotations [%collapsible] =============== [source,console-result] @@ -481,7 +481,7 @@ GET books/_search ---- // TEST[continued] -.Expand to see example response +.Expand to see example response with annotations [%collapsible] =============== [source,console-result] From 39f8ebc1a357086fa273451742a4291671ad3be8 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Wed, 2 Oct 2024 13:07:17 +0200 Subject: [PATCH 14/26] Apply suggestions from code review Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- docs/reference/mapping.asciidoc | 6 +++--- docs/reference/quickstart/getting-started.asciidoc | 11 ++++++----- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index aa1e9e437a322..72dfc6030ce02 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -84,9 +84,9 @@ you can't change mappings for fields that already contain data. You can _update_ mappings for existing fields under certain conditions: -. You can add new fields to an existing mapping. -. You can change the mapping for fields that don't contain any data. -. You can add new <> for existing fields. +* You can add new fields to an existing mapping. +* You can change the mapping for fields that don't contain any data. +* You can add new <> for existing fields. [discrete] [[mapping-limit-settings]] diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index d5b7d9ff7cb64..690e8351ddd78 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -53,7 +53,7 @@ PUT /books A `200` response indicates the index was created successfully. -.Expand to see example response +.Example response [%collapsible] =============== [source,console-result] @@ -267,7 +267,7 @@ You should receive a response indicating there were no errors. When using dynamic mapping, {es} automatically creates mappings for new fields by default. The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index. -Add a new document to the `books` index with a field that doesn't exist, to see how dynamic mapping works. +To see how dynamic mapping works, add a new document to the `books` index with a field that doesn't exist. [source,console] ---- @@ -277,11 +277,12 @@ POST /books/_doc "author": "F. Scott Fitzgerald", "release_date": "1925-04-10", "page_count": 180, - "new_field": "I'm a new field added dynamically" <1> + "language": "EN" <1> } ---- // TEST[continued] -<1> This field is dynamically added to the document. +<1> The new field. + View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `text` data type. [source,console] @@ -526,7 +527,7 @@ GET books/_search === Step 5: Delete your indices (optional) When following along with examples, you might want to delete an index to start from scratch. -You can delete indices using the <>. +You can delete indices using the <>. For example, run the following command to delete the indices created in this tutorial: From dbae1232c81d4a94c52f4a836b4b134207027a31 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:22:06 +0200 Subject: [PATCH 15/26] Further edits per review --- .../quickstart/getting-started.asciidoc | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 690e8351ddd78..6290bf5dcf4d8 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -51,7 +51,7 @@ PUT /books ---- // TEST[skip: index already setup] -A `200` response indicates the index was created successfully. +The following response indicates the index was created successfully. .Example response [%collapsible] @@ -96,13 +96,18 @@ If the index didn't already exist, this request would automatically create it. [source,console] ---- POST books/_doc -{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} +{ + "name": "Snow Crash", + "author": "Neal Stephenson", + "release_date": "1992-06-01", + "page_count": 470 +} ---- // TEST[continued] The response includes metadata that {es} generates for the document, including a unique `_id` for the document within the index. -.Expand to see example response with annotations +.Example response [%collapsible] =============== [source,console-result] @@ -159,7 +164,7 @@ POST /_bulk You should receive a response indicating there were no errors. -.Expand to see example response +.Example response [%collapsible] =============== [source,console-result] @@ -291,7 +296,7 @@ GET /books/_mapping ---- // TEST[continued] -.Expand to see example response +.Example response [%collapsible] =============== [source,console-result] @@ -345,7 +350,8 @@ GET /books/_mapping [[getting-started-explicit-mapping]] ==== Define explicit mapping -Create an index named `my-explicit-mappings-books` with explicit mappings: +Create an index named `my-explicit-mappings-books` with explicit mappings. +Pass each field's properties as a JSON object. This object should contain the field type and any additional <>. [source,console] ---- @@ -354,10 +360,10 @@ PUT /my-explicit-mappings-books "mappings": { "dynamic": false, <1> "properties": { <2> - "name": { "type": "text" }, <3> + "name": { "type": "text" }, "author": { "type": "text" }, - "release_date": { "type": "date", "format": "yyyy-MM-dd" }, <4> - "page_count": { "type": "integer" } <5> + "release_date": { "type": "date", "format": "yyyy-MM-dd" }, + "page_count": { "type": "integer" } } } } @@ -365,11 +371,8 @@ PUT /my-explicit-mappings-books // TEST[continued] <1> Disables dynamic mapping for the index. Documents containing fields not defined in the mapping will be rejected. <2> The `properties` object defines the fields and their data types for documents in this index. -<3> Defines the "name" field as type "text", suitable for full-text search on book titles. -<4> Specifies the "release_date" field as a "date" type with the specific format `yyyy-MM-dd`. -<5> Sets the "page_count" field as an "integer" type for storing the number of pages. -.Expand to see example response +.Example response [%collapsible] =============== [source,console-result] @@ -410,7 +413,7 @@ GET books/_search ---- // TEST[continued] -.Expand to see (truncated) example response with annotations +.Example response [%collapsible] =============== [source,console-result] @@ -482,7 +485,7 @@ GET books/_search ---- // TEST[continued] -.Expand to see example response with annotations +.Example response [%collapsible] =============== [source,console-result] @@ -542,5 +545,3 @@ DELETE /my-explicit-mappings-books ==== Deleting an index permanently deletes its documents, shards, and metadata. ==== - - From 0f09807c617f6a600c0b1575a4185a472ea5fc75 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:28:10 +0200 Subject: [PATCH 16/26] Reword mappings update, add clarity --- docs/reference/mapping.asciidoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 72dfc6030ce02..c265a0b239d07 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -77,17 +77,19 @@ slower search performance. [discrete] [[mapping-combine-explicit-dynamic]] -== Combine explicit and dynamic mappings +== Managing and updating mappings -Explicit mappings should almost always be defined at index creation, because -you can't change mappings for fields that already contain data. +Explicit mappings should be defined at index creation for fields you know in advance. +However, you can still add new fields to explicit mappings at any time, as your data evolves. +Alternatively, you can allow dynamic mapping to automatically add new fields to the mapping. -You can _update_ mappings for existing fields under certain conditions: +You can also _update_ mappings for existing fields under certain conditions: -* You can add new fields to an existing mapping. +* You can add new fields to an existing mapping at any time. * You can change the mapping for fields that don't contain any data. * You can add new <> for existing fields. + [discrete] [[mapping-limit-settings]] == Prevent mapping explosions From 2d0626dc273266d8732d4fcdf94191679c105793 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:36:35 +0200 Subject: [PATCH 17/26] Tweak mapping updates wording --- docs/reference/mapping.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index c265a0b239d07..cdc465a74f7ba 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -83,13 +83,15 @@ Explicit mappings should be defined at index creation for fields you know in adv However, you can still add new fields to explicit mappings at any time, as your data evolves. Alternatively, you can allow dynamic mapping to automatically add new fields to the mapping. -You can also _update_ mappings for existing fields under certain conditions: +You can't change mappings for fields that already contain data. +These changes require <>. + +However, you can _update_ mappings for existing fields under certain conditions: * You can add new fields to an existing mapping at any time. * You can change the mapping for fields that don't contain any data. * You can add new <> for existing fields. - [discrete] [[mapping-limit-settings]] == Prevent mapping explosions From 43895ae4dba308f4fd769082cba60afecb4b850d Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:39:50 +0200 Subject: [PATCH 18/26] Really clarify this time --- docs/reference/mapping.asciidoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index cdc465a74f7ba..e2f87a374178f 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -80,15 +80,14 @@ slower search performance. == Managing and updating mappings Explicit mappings should be defined at index creation for fields you know in advance. -However, you can still add new fields to explicit mappings at any time, as your data evolves. -Alternatively, you can allow dynamic mapping to automatically add new fields to the mapping. +You can still add _new fields_ to mappings at any time, as your data evolves. You can't change mappings for fields that already contain data. These changes require <>. However, you can _update_ mappings for existing fields under certain conditions: -* You can add new fields to an existing mapping at any time. +* You can add new fields to an existing mapping at any time, explicitly or dynamically. * You can change the mapping for fields that don't contain any data. * You can add new <> for existing fields. From 536fe601d5f9363b57de15e46606b9cc354f15d7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:44:10 +0200 Subject: [PATCH 19/26] Edit update verbiage --- docs/reference/mapping.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index e2f87a374178f..bed7175b65162 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -85,7 +85,7 @@ You can still add _new fields_ to mappings at any time, as your data evolves. You can't change mappings for fields that already contain data. These changes require <>. -However, you can _update_ mappings for existing fields under certain conditions: +However, you can _update_ mappings for under certain conditions: * You can add new fields to an existing mapping at any time, explicitly or dynamically. * You can change the mapping for fields that don't contain any data. From 5971c2b2bd48e8993113d3dab8fb7445025f850f Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 13:44:31 +0200 Subject: [PATCH 20/26] Typo --- docs/reference/mapping.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index bed7175b65162..d6f5da506bfa9 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -85,7 +85,7 @@ You can still add _new fields_ to mappings at any time, as your data evolves. You can't change mappings for fields that already contain data. These changes require <>. -However, you can _update_ mappings for under certain conditions: +However, you can _update_ mappings under certain conditions: * You can add new fields to an existing mapping at any time, explicitly or dynamically. * You can change the mapping for fields that don't contain any data. From e679e74623925e0b7b728d5b9e946940c8a94e47 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Wed, 2 Oct 2024 14:51:49 +0200 Subject: [PATCH 21/26] Apply Kathleen's suggestions Co-authored-by: Kathleen DeRusso --- docs/reference/mapping.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index d6f5da506bfa9..27a6f7e16f4d7 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -82,13 +82,12 @@ slower search performance. Explicit mappings should be defined at index creation for fields you know in advance. You can still add _new fields_ to mappings at any time, as your data evolves. -You can't change mappings for fields that already contain data. +In most cases, you can't change mappings for fields that are already mapped. These changes require <>. However, you can _update_ mappings under certain conditions: * You can add new fields to an existing mapping at any time, explicitly or dynamically. -* You can change the mapping for fields that don't contain any data. * You can add new <> for existing fields. [discrete] From 11a38d0913e102cd525e55cbd46c9393ca4a8514 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 14:56:05 +0200 Subject: [PATCH 22/26] Clarify multi-field mapping updates --- docs/reference/mapping.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 27a6f7e16f4d7..fa5e655359218 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -89,6 +89,7 @@ However, you can _update_ mappings under certain conditions: * You can add new fields to an existing mapping at any time, explicitly or dynamically. * You can add new <> for existing fields. +** Documents indexed before the mapping update will not have values for the new multi-fields until they are updated or reindexed. Documents indexed after the mapping change will automatically have values for the new multi-fields. [discrete] [[mapping-limit-settings]] From b20e506027eecdd275a7bf7e4ba38945804b096b Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 14:58:40 +0200 Subject: [PATCH 23/26] Link to update mapping API --- docs/reference/mapping.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index fa5e655359218..439dd7a03d4a2 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -82,6 +82,8 @@ slower search performance. Explicit mappings should be defined at index creation for fields you know in advance. You can still add _new fields_ to mappings at any time, as your data evolves. +Use the <> to update an existing mapping. + In most cases, you can't change mappings for fields that are already mapped. These changes require <>. From 88b71be04270623403f40d8e66c496a838e22ce3 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 15:01:53 +0200 Subject: [PATCH 24/26] Mention some mapping params can be updated --- docs/reference/mapping.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 439dd7a03d4a2..97193b252a1a8 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -92,6 +92,7 @@ However, you can _update_ mappings under certain conditions: * You can add new fields to an existing mapping at any time, explicitly or dynamically. * You can add new <> for existing fields. ** Documents indexed before the mapping update will not have values for the new multi-fields until they are updated or reindexed. Documents indexed after the mapping change will automatically have values for the new multi-fields. +* Some <> can be updated for existing fields of certain <>. [discrete] [[mapping-limit-settings]] From 33a56194d91e9f15428ce5c477a4c1b188df9c0f Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 15:23:09 +0200 Subject: [PATCH 25/26] Further clarifications --- docs/reference/mapping.asciidoc | 2 +- docs/reference/quickstart/getting-started.asciidoc | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 97193b252a1a8..5d6245a964104 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -76,7 +76,7 @@ balance resource usage and performance. Your index will be smaller, but with slower search performance. [discrete] -[[mapping-combine-explicit-dynamic]] +[[mapping-manage-update]] == Managing and updating mappings Explicit mappings should be defined at index creation for fields you know in advance. diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 6290bf5dcf4d8..65b6b9f342ab1 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -391,8 +391,11 @@ PUT /my-explicit-mappings-books ==== Combine dynamic and explicit mappings Explicit mappings are defined at index creation, and documents must conform to these mappings. +You can also use the <>. When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping. -This allows you to <>. + +This allows you to combine explicit and dynamic mappings. +Learn more about <>. [discrete] [[getting-started-search-data]] From 015a345c5f148db2f7eaeb8cb50e5745cdf6fd1f Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Oct 2024 19:32:33 +0200 Subject: [PATCH 26/26] Add tweaks and links --- docs/reference/quickstart/getting-started.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/quickstart/getting-started.asciidoc b/docs/reference/quickstart/getting-started.asciidoc index 65b6b9f342ab1..a6d233d8b8abc 100644 --- a/docs/reference/quickstart/getting-started.asciidoc +++ b/docs/reference/quickstart/getting-started.asciidoc @@ -272,7 +272,7 @@ You should receive a response indicating there were no errors. When using dynamic mapping, {es} automatically creates mappings for new fields by default. The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index. -To see how dynamic mapping works, add a new document to the `books` index with a field that doesn't exist. +To see how dynamic mapping works, add a new document to the `books` index with a field that doesn't appear in the existing documents. [source,console] ---- @@ -288,7 +288,7 @@ POST /books/_doc // TEST[continued] <1> The new field. -View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `text` data type. +View the mapping for the `books` index with the <>. The new field `new_field` has been added to the mapping with a `text` data type. [source,console] ---- @@ -351,7 +351,7 @@ GET /books/_mapping ==== Define explicit mapping Create an index named `my-explicit-mappings-books` with explicit mappings. -Pass each field's properties as a JSON object. This object should contain the field type and any additional <>. +Pass each field's properties as a JSON object. This object should contain the <> and any additional <>. [source,console] ----