From 9819ca0c806ed38da00e45a643856b1963eccfd1 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 20 Aug 2025 14:26:52 -0700 Subject: [PATCH 1/2] Move Elasticsearch API basics quickstart to Get started --- explore-analyze/query-filter.md | 3 +-- redirects.yml | 2 ++ solutions/search/api-quickstarts.md | 2 +- .../index-basics.md} | 22 +++++++++---------- solutions/toc.yml | 2 +- 5 files changed, 16 insertions(+), 15 deletions(-) rename solutions/search/{elasticsearch-basics-quickstart.md => get-started/index-basics.md} (90%) diff --git a/explore-analyze/query-filter.md b/explore-analyze/query-filter.md index 2473e95dca..d65669759c 100644 --- a/explore-analyze/query-filter.md +++ b/explore-analyze/query-filter.md @@ -26,8 +26,7 @@ You’ll use a combination of an API endpoint and a query language to interact w - A number of [tools](/explore-analyze/query-filter/tools.md) are available for you to save, debug, and optimize your queries. -% todo: update link to the best target -If you're just getting started with Elasticsearch, try the hands-on [API quickstart](/solutions/search/elasticsearch-basics-quickstart.md) to learn how to add data and run basic searches using Query DSL and the `_search` endpoint. +If you're just getting started with {{es}}, try the hands-on [](/solutions/search/get-started/index-basics.md) to learn how to add data and run basic searches using Query DSL and the `_search` endpoint. ## Filtering diff --git a/redirects.yml b/redirects.yml index 360ef55b25..a1a759ba51 100644 --- a/redirects.yml +++ b/redirects.yml @@ -308,3 +308,5 @@ redirects: 'solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md': 'solutions/security/configure-elastic-defend/enable-access-for-macos.md' 'solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md': 'solutions/security/configure-elastic-defend/enable-access-for-macos.md' +# Related to https://github.com/elastic/docs-content/pull/2245/ + 'solutions/search/elasticsearch-basics-quickstart.md': 'solutions/search/get-started/index-basics.md' \ No newline at end of file diff --git a/solutions/search/api-quickstarts.md b/solutions/search/api-quickstarts.md index 92793acec7..1b7dafdb27 100644 --- a/solutions/search/api-quickstarts.md +++ b/solutions/search/api-quickstarts.md @@ -15,7 +15,7 @@ Prefer working in Python? Check out our executable [Python notebooks](https://gi Use the following quickstarts to get hands-on experience with Elasticsearch APIs and tools: -- [Index and search data using Elasticsearch APIs](elasticsearch-basics-quickstart.md): Learn about indices, documents, and mappings, and perform a basic search using the Query DSL. +- [Index and search data using Elasticsearch APIs](get-started/index-basics.md): Learn about indices, documents, and mappings, and perform a basic search using the Query DSL. - [Basic full-text search and filtering in Elasticsearch](querydsl-full-text-filter-tutorial.md): Learn about different options for querying data, including full-text search and filtering, using the Query DSL. - [Analyze eCommerce data with aggregations using Query DSL](/explore-analyze/query-filter/aggregations/tutorial-analyze-ecommerce-data-with-aggregations-using-query-dsl.md): Learn how to analyze data using different types of aggregations, including metrics, buckets, and pipelines. % - [Getting started with {{esql}}](esql-getting-started.md): Learn how to query and aggregate your data using {{esql}}. diff --git a/solutions/search/elasticsearch-basics-quickstart.md b/solutions/search/get-started/index-basics.md similarity index 90% rename from solutions/search/elasticsearch-basics-quickstart.md rename to solutions/search/get-started/index-basics.md index 8bfce9494a..d2e687369c 100644 --- a/solutions/search/elasticsearch-basics-quickstart.md +++ b/solutions/search/get-started/index-basics.md @@ -6,16 +6,16 @@ applies_to: # Basics quickstart [getting-started] -This quickstart provides a hands-on introduction to the fundamental concepts of {{es}}: [indices, documents, and field type mappings](../../manage-data/data-store/index-basics.md). You'll learn how to create an index, add documents, work with dynamic and explicit mappings, and perform your first basic searches. +This quickstart provides a hands-on introduction to the fundamental concepts of {{es}}: [indices, documents, and field type mappings](../../../manage-data/data-store/index-basics.md). You'll learn how to create an index, add documents, work with dynamic and explicit mappings, and perform your first basic searches. ::::{tip} -The code examples in this tutorial are in [Console](../../explore-analyze/query-filter/tools/console.md) syntax by default. You can [convert into other programming languages](../../explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI. +The code examples in this tutorial are in [Console](../../../explore-analyze/query-filter/tools/console.md) syntax by default. You can [convert into other programming languages](../../../explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI. :::: ## Requirements [getting-started-requirements] -You can follow this guide using any {{es}} deployment. If you have a deployment ready, skip ahead to the [first step](#getting-started-index-creation). If not, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) to see all deployment options. To get started quickly, spin up a cluster [locally in Docker](run-elasticsearch-locally.md): +You can follow this guide using any {{es}} deployment. If you have a deployment ready, skip ahead to the [first step](#getting-started-index-creation). If not, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) to see all deployment options. To get started quickly, spin up a cluster [locally in Docker](../run-elasticsearch-locally.md): ```sh curl -fsSL https://elastic.co/start-local | sh @@ -46,7 +46,7 @@ The following response indicates the index was created successfully. ## Step 2: Add data to your index [getting-started-add-documents] ::::{tip} -This tutorial uses {{es}} APIs, but there are many other ways to [add data to {{es}}](ingest-for-search.md). +This tutorial uses {{es}} APIs, but there are many other ways to [add data to {{es}}](../ingest-for-search.md). :::: @@ -97,7 +97,7 @@ The response includes metadata that {{es}} generates for the document, including 2. `_id`: The unique identifier for the document. 3. `_version`: The version of the document. 4. `result`: The result of the indexing operation. -5. `_shards`: Information about the number of [shards](../../deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded. +5. `_shards`: Information about the number of [shards](../../../deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded. 6. `total`: The total number of shards for the index. 7. `successful`: The number of shards that the indexing operation was performed on. 8. `failed`: The number of shards that failed during the indexing operation. *0* indicates no failures. @@ -222,7 +222,7 @@ You should receive a response indicating there were no errors. ## Step 3: Define mappings [getting-started-mappings-and-data-types] -[Mappings](../../manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database. +[Mappings](../../../manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database. ### Use dynamic mapping [getting-started-dynamic-mapping] @@ -340,12 +340,12 @@ The following response indicates a successful operation. Explicit mappings are defined at index creation, and documents must conform to these mappings. You can also use the [Update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-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 explicit and dynamic mappings. Learn more about [managing and updating mappings](../../manage-data/data-store/mapping.md#mapping-manage-update). +This allows you to combine explicit and dynamic mappings. Learn more about [managing and updating mappings](../../../manage-data/data-store/mapping.md#mapping-manage-update). ## Step 4: Search your data [getting-started-search-data] -Indexed documents are available for search in near real-time, using the [`_search` API](querying-for-search.md). +Indexed documents are available for search in near real-time, using the [`_search` API](../querying-for-search.md). ### Search all documents [getting-started-search-all-documents] @@ -483,7 +483,7 @@ Deleting an index permanently deletes its documents, shards, and metadata. This tutorial introduced the basics of creating indices, adding data and performing basic searches with {{es}}. The following resources will help you understand {{es}} concepts better and dive into the basics of query languages for searching data: -* [Fundamentals of Elasticsearch](../../manage-data/data-store.md) -* [Search and filter with Query DSL](querydsl-full-text-filter-tutorial.md) -* [Search using ES|QL](esql-search-tutorial.md) +* [Fundamentals of Elasticsearch](../../../manage-data/data-store.md) +* [Search and filter with Query DSL](../querydsl-full-text-filter-tutorial.md) +* [Search using ES|QL](../esql-search-tutorial.md) diff --git a/solutions/toc.yml b/solutions/toc.yml index 54af20115c..29f2a68512 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -10,11 +10,11 @@ toc: - file: search/search-connection-details.md - file: search/get-started/quickstarts.md children: + - file: search/get-started/index-basics.md - file: search/get-started/keyword-search-python.md - file: search/get-started/semantic-search.md - file: search/api-quickstarts.md children: - - file: search/elasticsearch-basics-quickstart.md - file: search/querydsl-full-text-filter-tutorial.md - file: search/esql-search-tutorial.md - file: search/ingest-for-search.md From c60360af03cdb2a50ad20e19f5d208b7c5c17e19 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 20 Aug 2025 15:23:19 -0700 Subject: [PATCH 2/2] Edit style --- solutions/search/get-started/index-basics.md | 162 +++++++++---------- 1 file changed, 76 insertions(+), 86 deletions(-) diff --git a/solutions/search/get-started/index-basics.md b/solutions/search/get-started/index-basics.md index d2e687369c..007abc8d87 100644 --- a/solutions/search/get-started/index-basics.md +++ b/solutions/search/get-started/index-basics.md @@ -3,26 +3,32 @@ applies_to: stack: serverless: --- -# Basics quickstart [getting-started] - +# Index and search basics This quickstart provides a hands-on introduction to the fundamental concepts of {{es}}: [indices, documents, and field type mappings](../../../manage-data/data-store/index-basics.md). You'll learn how to create an index, add documents, work with dynamic and explicit mappings, and perform your first basic searches. ::::{tip} -The code examples in this tutorial are in [Console](../../../explore-analyze/query-filter/tools/console.md) syntax by default. You can [convert into other programming languages](../../../explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI. - +The code examples are in [Console](/explore-analyze/query-filter/tools/console.md) syntax by default. +You can [convert into other programming languages](/explore-analyze/query-filter/tools/console.md#import-export-console-requests) in the Console UI. :::: ## Requirements [getting-started-requirements] -You can follow this guide using any {{es}} deployment. If you have a deployment ready, skip ahead to the [first step](#getting-started-index-creation). If not, refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) to see all deployment options. To get started quickly, spin up a cluster [locally in Docker](../run-elasticsearch-locally.md): +You can follow this guide using any {{es}} deployment. +To see all deployment options, refer to [](/deploy-manage/deploy.md#choosing-your-deployment-type). +To get started quickly, spin up a cluster [locally in Docker](/solutions/search/run-elasticsearch-locally.md). -```sh -curl -fsSL https://elastic.co/start-local | sh -``` +## Add data to {{es}} [getting-started-index-creation] +::::{tip} +This quickstart uses {{es}} APIs, but there are many other ways to [add data to {{es}}](/solutions/search/ingest-for-search.md). +:::: + +You add data to {{es}} as JSON objects called documents. +{{es}} stores these documents in searchable indices. -## Step 1: Create an index [getting-started-index-creation] +:::::{stepper} +::::{step} Create an index Create a new index named `books`: @@ -32,7 +38,8 @@ PUT /books The following response indicates the index was created successfully. -::::{dropdown} Example response +:::{dropdown} Example response + ```console-result { "acknowledged": true, @@ -41,29 +48,13 @@ The following response indicates the index was created successfully. } ``` +::: :::: - -## Step 2: Add data to your index [getting-started-add-documents] - -::::{tip} -This tutorial uses {{es}} APIs, but there are many other ways to [add data to {{es}}](../ingest-for-search.md). - -:::: - - -You add data to {{es}} as JSON objects called documents. {{es}} stores these documents in searchable indices. - - -### Add a single document [getting-started-add-single-document] +::::{step} Add a single document Use the following request to add a single document to the `books` index. - -::::{note} If the index doesn't already exist, this request will automatically create it. -:::: - - ```console POST books/_doc { @@ -76,7 +67,8 @@ POST books/_doc The response includes metadata that {{es}} generates for the document, including a unique `_id` for the document within the index. -::::{dropdown} Example response +:::{dropdown} Example response + ```console-result { "_index": "books", <1> @@ -97,19 +89,18 @@ The response includes metadata that {{es}} generates for the document, including 2. `_id`: The unique identifier for the document. 3. `_version`: The version of the document. 4. `result`: The result of the indexing operation. -5. `_shards`: Information about the number of [shards](../../../deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded. +5. `_shards`: Information about the number of [shards](/deploy-manage/distributed-architecture/clusters-nodes-shards.md) that the indexing operation was executed on and the number that succeeded. 6. `total`: The total number of shards for the index. 7. `successful`: The number of shards that the indexing operation was performed on. 8. `failed`: The number of shards that failed during the indexing operation. *0* indicates no failures. 9. `_seq_no`: A monotonically increasing number incremented for each indexing operation on a shard. 10. `_primary_term`: A monotonically increasing number incremented each time a primary shard is assigned to a different node. - - +::: :::: +::::{step} Add multiple documents -### Add multiple documents [getting-started-add-multiple-documents] - -Use the [`_bulk` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to add multiple documents in a single request. Bulk data must be formatted as newline-delimited JSON (NDJSON). +Use the [`_bulk` endpoint]({{es-apis}}operation/operation-bulk) to add multiple documents in a single request. +Bulk data must be formatted as newline-delimited JSON (NDJSON). ```console POST /_bulk @@ -124,9 +115,11 @@ POST /_bulk { "index" : { "_index" : "books" } } {"name": "The Handmaids Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311} ``` + You should receive a response indicating there were no errors. -::::{dropdown} Example response +:::{dropdown} Example response + ```console-result { "errors": false, @@ -216,18 +209,14 @@ You should receive a response indicating there were no errors. } ``` +::: :::: +::::{step} Use dynamic mapping +[Mappings](/manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database. - -## Step 3: Define mappings [getting-started-mappings-and-data-types] - -[Mappings](../../../manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings) define how data is stored and indexed in {{es}}, like a schema in a relational database. - - -### Use dynamic mapping [getting-started-dynamic-mapping] - -When you use dynamic mapping, {{es}} automatically creates mappings for new fields by default. The documents you’ve added so far have used dynamic mapping, because you didn’t specify a mapping while creating the index. +If you use dynamic mapping, {{es}} automatically creates mappings for new fields. +The documents you've added so far have used dynamic mapping, because you didn't specify a mapping while creating the index. To see how dynamic mapping works, add a new document to the `books` index with a field that isn't available in the existing documents. @@ -244,13 +233,15 @@ POST /books/_doc 1. The new field. -View the mapping for the `books` index with the [Get mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-mapping). The new field `language` has been added to the mapping with a `text` data type. +View the mapping for the `books` index with the [get mapping API]({{es-apis}}operation/operation-indices-get-mapping). +The new field `language` has been added to the mapping with a `text` data type. ```console GET /books/_mapping ``` + The following response displays the mappings that were created by {{es}}. -::::{dropdown} Example response +:::{dropdown} Example response ```console-result { @@ -295,14 +286,13 @@ The following response displays the mappings that were created by {{es}}. } } ``` - +::: :::: +::::{step} Define explicit mapping - - -### Define explicit mapping [getting-started-explicit-mapping] - -Create an index named `my-explicit-mappings-books` and specify the mappings yourself. Pass each field’s properties as a JSON object. This object should contain the [field data type](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) and any additional [mapping parameters](elasticsearch://reference/elasticsearch/mapping-reference/mapping-parameters.md). +Create an index named `my-explicit-mappings-books` and specify the mappings yourself. +Pass each field's properties as a JSON object. +This object should contain the [field data type](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) and any additional [mapping parameters](elasticsearch://reference/elasticsearch/mapping-reference/mapping-parameters.md). ```console PUT /my-explicit-mappings-books @@ -319,11 +309,11 @@ PUT /my-explicit-mappings-books } ``` -1. `dynamic`: Disables dynamic mapping for the index. If you don't define fields in the mapping, they'll still be stored in the document's `_source` field, but you can't index or search them. +1. `dynamic`: Turns off dynamic mapping for the index. If you don't define fields in the mapping, they'll still be stored in the document's `_source` field, but you can't index or search them. 2. `properties`: Defines the fields and their corresponding data types. The following response indicates a successful operation. -::::{dropdown} Example response +:::{dropdown} Example response ```console-result { "acknowledged": true, @@ -331,24 +321,21 @@ The following response indicates a successful operation. "index": "my-explicit-mappings-books" } ``` +::: +Explicit mappings are defined at index creation, and documents must conform to these mappings. +You can also use the [update mapping API]({{es-apis}}operation/operation-indices-put-mapping). +When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping, which allows you to combine explicit and dynamic mappings. +Learn more about [managing and updating mappings](/manage-data/data-store/mapping.md#mapping-manage-update). :::: +::::: +## Search your data [getting-started-search-data] +Indexed documents are available for search in near real-time, using the [`_search` API](/solutions/search/querying-for-search.md). -### Combine dynamic and explicit mappings [getting-started-combined-mapping] - -Explicit mappings are defined at index creation, and documents must conform to these mappings. You can also use the [Update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-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 explicit and dynamic mappings. Learn more about [managing and updating mappings](../../../manage-data/data-store/mapping.md#mapping-manage-update). - - -## Step 4: Search your data [getting-started-search-data] - -Indexed documents are available for search in near real-time, using the [`_search` API](../querying-for-search.md). - - -### Search all documents [getting-started-search-all-documents] +:::::{stepper} +::::{step} Search all documents Use the following request to search all documents in the `books` index: @@ -356,7 +343,7 @@ Use the following request to search all documents in the `books` index: GET books/_search ``` -::::{dropdown} Example response +:::{dropdown} Example response ```console-result { "took": 2, <1> @@ -398,14 +385,13 @@ GET books/_search 5. `total`: Information about the total number of matching documents 6. `max_score`: The highest relevance score among all matching documents 7. `_index`: The index the document belongs to -8. `_id`: The document’s unique identifier +8. `_id`: The document's unique identifier 9. `_score`: The relevance score of the document 10. `_source`: The original JSON object submitted during indexing - +::: :::: - -### Search using `match` query [getting-started-match-query] +::::{step} Search with a match query Use the [`match` query](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) to search for documents that contain a specific value in a specific field. This is the standard query for full-text searches. @@ -422,7 +408,11 @@ GET books/_search } ``` -::::{dropdown} Example response +:::{tip} +This example uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md), which is the primary query language for {{es}}. +::: + +:::{dropdown} Example response ```console-result { "took": 9, @@ -457,17 +447,15 @@ GET books/_search ``` 1. `max_score`: 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. - - +::: :::: +::::: +## Delete your indices [getting-started-delete-indices] +If you want to delete an index to start from scratch at any point, use the [delete index API]({{es-apis}}operation/operation-indices-delete). -## Step 5: Delete your indices [getting-started-delete-indices] - -If you want to delete an index to start from scratch at any point, use the [Delete index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete). - -For example, use the following request to delete the indices created in this tutorial: +For example, use the following request to delete the indices created in this quickstart: ```console DELETE /books @@ -479,11 +467,13 @@ Deleting an index permanently deletes its documents, shards, and metadata. :::: -## Learn more [full-text-filter-tutorial-learn-more] +## Next steps -This tutorial introduced the basics of creating indices, adding data and performing basic searches with {{es}}. The following resources will help you understand {{es}} concepts better and dive into the basics of query languages for searching data: +This quickstart introduced the basics of creating indices, adding data, and performing basic searches with {{es}}. +To try out similar steps from the {{es}} Python client, go to [](/solutions/search/get-started/keyword-search-python.md). +The following resources will help you understand {{es}} concepts better and dive into the basics of query languages for searching data: -* [Fundamentals of Elasticsearch](../../../manage-data/data-store.md) -* [Search and filter with Query DSL](../querydsl-full-text-filter-tutorial.md) -* [Search using ES|QL](../esql-search-tutorial.md) +* [Fundamentals of Elasticsearch](/manage-data/data-store.md) +* [Search and filter with Query DSL](/solutions/search/querydsl-full-text-filter-tutorial.md) +* [Search using ES|QL](/solutions/search/esql-search-tutorial.md)