From 183e888ea01d3affe80a8227608394ac59dd77ff Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 10 Jul 2025 15:59:01 -0700 Subject: [PATCH 01/19] Add new python keyword search quickstart --- .../get-started/keyword-search-python.md | 177 ++++++++++++++++++ solutions/toc.yml | 1 + 2 files changed, 178 insertions(+) create mode 100644 solutions/search/get-started/keyword-search-python.md diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md new file mode 100644 index 0000000000..c95110427b --- /dev/null +++ b/solutions/search/get-started/keyword-search-python.md @@ -0,0 +1,177 @@ +--- +description: An introduction to building an Elasticsearch query in Python. +applies_to: + serverless: all +products: + - id: elasticsearch +--- +# Build your first search query with Python + +{{es}} provides a range of search techniques, starting with BM25, the industry standard for textual search. +It provides official clients for multiple programming languages, including Python, Rust, Java, JavaScript, and others. +These clients offer full API support for indexing, searching, and cluster management. +They are optimized for performance and kept up to date with {{es}} releases, ensuring compatibility and security. + +In this quickstart guide, you will index a couple documents and query them using Python. +By the end of this guide, you’ll have learned how to connect a backend application to {{es}} to answer your queries. + +## Prerequisites + +- If you're using [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. + + +To learn about role-based access control, check out [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). + +## Create an index + +An index is a collection of documents uniquely identified by a name or an alias. +Go to **{{es}} > Home**, select keyword search, and follow the guided index workflow. + + +You've created your first index! +Next, create an API key so your application can talk to {{es}}. + +:::{tip} +For an introduction to the concept of indices, check out [](/manage-data/data-store/index-basics.md). +::: + +## Install an {{es}} client + +Select your preferred language in the keyword search workflow. For this example, leverage Python. + +![Client installation step in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) + +In your terminal, install the {{es}} client using `pip`: + +```py +pip install elasticsearch +``` + +Copy your API key from the top right corner and add it to the client’s configuration alongside the project URL. + +```py +from elasticsearch import Elasticsearch + +client = Elasticsearch( + "https://my-project-bff300.es.us-east-1.aws.elastic.cloud:443", + api_key="YOUR-API-KEY" +) + +index_name = "my-index" +``` + +## Create field mappings + +At this stage, you can define the mappings for your index, including a single text field — named "text". + +```py +mappings = { + "properties": { + "text": { + "type": "text" + } + } +} + +mapping_response = client.indices.put_mapping(index=index_name, body=mappings) +print(mapping_response) +``` + +## Add documents + +Next, use a bulk request to index three documents in {{es}}. +Bulk requests are the preferred method for indexing large volumes of data, from hundreds to billions of documents. + +```py +docs = [ + { + "text": "Yellowstone National Park is one of the largest national parks in the United States. It ranges from the Wyoming to Montana and Idaho, and contains an area of 2,219,791 acress across three different states. Its most famous for hosting the geyser Old Faithful and is centered on the Yellowstone Caldera, the largest super volcano on the American continent. Yellowstone is host to hundreds of species of animal, many of which are endangered or threatened. Most notably, it contains free-ranging herds of bison and elk, alongside bears, cougars and wolves. The national park receives over 4.5 million visitors annually and is a UNESCO World Heritage Site." + }, + { + "text": "Yosemite National Park is a United States National Park, covering over 750,000 acres of land in California. A UNESCO World Heritage Site, the park is best known for its granite cliffs, waterfalls and giant sequoia trees. Yosemite hosts over four million visitors in most years, with a peak of five million visitors in 2016. The park is home to a diverse range of wildlife, including mule deer, black bears, and the endangered Sierra Nevada bighorn sheep. The park has 1,200 square miles of wilderness, and is a popular destination for rock climbers, with over 3,000 feet of vertical granite to climb. Its most famous and cliff is the El Capitan, a 3,000 feet monolith along its tallest face." + }, + { + "text": "Rocky Mountain National Park is one of the most popular national parks in the United States. It receives over 4.5 million visitors annually, and is known for its mountainous terrain, including Longs Peak, which is the highest peak in the park. The park is home to a variety of wildlife, including elk, mule deer, moose, and bighorn sheep. The park is also home to a variety of ecosystems, including montane, subalpine, and alpine tundra. The park is a popular destination for hiking, camping, and wildlife viewing, and is a UNESCO World Heritage Site." + } +] + +bulk_response = helpers.bulk(client, docs, index=index_name) +print(bulk_response) +``` + +## Explore the data + +You should be able to see the documents in {{es}}! + +![Viewing data in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt0ac36402cde2a645/67d0a443b8764e72b9e8e1f3/view_docs_in_elasticsearch.png) + + +## Test keyword search + +Create a new script (for instance `search.py`), which defines a query and runs the following search request: + +```esql +FROM my-index +| WHERE MATCH(text, "yosemite") +| LIMIT 5 +``` + +Add this query inside `client.esql.query`: + +```py +from elasticsearch import Elasticsearch + +client = Elasticsearch( + "https://my-project-bff307.es.us-east-1.aws.elastic.cloud:443", + api_key="YOUR-API-KEY" +) + +# Run the search query +response = client.esql.query( + query=""" + FROM my-index + | WHERE MATCH(text, "yosemite") + | LIMIT 5 + """, + format="csv" +) + +print(response) +``` + +## Analyze the results + +Check your result: + +```txt +"Yosemite National Park is a United States National Park, covering over 750,000 acres of land in California. A UNESCO World Heritage Site, the park is best known for its granite cliffs, waterfalls and giant sequoia trees. Yosemite hosts over four million visitors in most years, with a peak of five million visitors in 2016. The park is home to a diverse range of wildlife, including mule deer, black bears, and the endangered Sierra Nevada bighorn sheep. The park has 1,200 square miles of wilderness, and is a popular destination for rock climbers, with over 3,000 feet of vertical granite to climb. Its most famous and cliff is the El Capitan, a 3,000 feet monolith along its tallest face." +Now you are ready to use the client to query Elasticsearch from any Python backend like Flask, Django, etc. Check out the Elasticsearch Python Client documentation to explore further +``` + + + +## Next steps + +Thanks for taking the time to learn how to build an application on top of {{es}}. + +For a deeper dive, check out the following resources: + +- [Getting started with the Python client](elasticsearch-py://reference/getting-started.md) +- [Python notebooks](https://github.com/elastic/elasticsearch-labs/tree/main/notebooks/README.md) +- [](/manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md) \ No newline at end of file diff --git a/solutions/toc.yml b/solutions/toc.yml index 918381a427..98ca6bb788 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -10,6 +10,7 @@ toc: - file: search/search-connection-details.md - file: search/get-started/quickstarts.md children: + - file: search/get-started/keyword-search-python.md - file: search/get-started/semantic-search.md - file: search/api-quickstarts.md children: From 43e494434e1a02f46519b0b11dc0aba1023482d6 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:26:58 -0700 Subject: [PATCH 02/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index c95110427b..ea2b84282f 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -12,7 +12,7 @@ It provides official clients for multiple programming languages, including Pytho These clients offer full API support for indexing, searching, and cluster management. They are optimized for performance and kept up to date with {{es}} releases, ensuring compatibility and security. -In this quickstart guide, you will index a couple documents and query them using Python. +In this quickstart, you'll index a couple of documents and query them using Python. By the end of this guide, you’ll have learned how to connect a backend application to {{es}} to answer your queries. ## Prerequisites From 6b4a5072b7efe6b8a27087aa0e50caf4cc5d2249 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:27:30 -0700 Subject: [PATCH 03/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 1 + 1 file changed, 1 insertion(+) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index ea2b84282f..f4e82a1de4 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -1,4 +1,5 @@ --- +navigation_title: "Keyword search with Python" description: An introduction to building an Elasticsearch query in Python. applies_to: serverless: all From ee2b737e31ce0ff3d7d6bc2bb8ed504a371cbde2 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:27:46 -0700 Subject: [PATCH 04/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index f4e82a1de4..3636a77f2b 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -71,7 +71,7 @@ index_name = "my-index" ## Create field mappings -At this stage, you can define the mappings for your index, including a single text field — named "text". +At this stage, you can define the mappings for your index, including a single text field named `text`. ```py mappings = { From d82810875a7a43e03370caf59c935fd7925519d3 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:28:00 -0700 Subject: [PATCH 05/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 3636a77f2b..06cced7eb8 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -119,7 +119,7 @@ To familiarize yourself with this data set, open [Discover](/explore-analyze/dis ## Test keyword search -Create a new script (for instance `search.py`), which defines a query and runs the following search request: +Create a new script (for instance, `search.py`) that defines a query and runs the following search request: ```esql FROM my-index From e679259ca2ce86cb2bbe6718b05b4dae619bbdc1 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:28:08 -0700 Subject: [PATCH 06/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 06cced7eb8..4482505eca 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -169,7 +169,7 @@ DELETE /semantic-index ## Next steps -Thanks for taking the time to learn how to build an application on top of {{es}}. +This quickstart covered the basics of working with {{es}}. For a deeper dive, check out the following resources: From 3ebeca2afafc5ecb05bf28b6dcfc9ed50276ba92 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 15:28:14 -0700 Subject: [PATCH 07/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 4482505eca..4d2df19ac7 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -171,7 +171,7 @@ DELETE /semantic-index This quickstart covered the basics of working with {{es}}. -For a deeper dive, check out the following resources: +For a deeper dive, refer to the following resources: - [Getting started with the Python client](elasticsearch-py://reference/getting-started.md) - [Python notebooks](https://github.com/elastic/elasticsearch-labs/tree/main/notebooks/README.md) From c547fabf159343da50cd9d8e2cdc82e9600ff314 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 17:27:02 -0700 Subject: [PATCH 08/19] Address feedback about introduction --- .../search/get-started/keyword-search-python.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 4d2df19ac7..7d52027fa0 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -2,23 +2,24 @@ navigation_title: "Keyword search with Python" description: An introduction to building an Elasticsearch query in Python. applies_to: - serverless: all + serverless: + elasticsearch: ga products: - id: elasticsearch + - id: elasticsearch-client --- # Build your first search query with Python -{{es}} provides a range of search techniques, starting with BM25, the industry standard for textual search. -It provides official clients for multiple programming languages, including Python, Rust, Java, JavaScript, and others. +In this quickstart, you'll index a couple of documents and query them using Python. +These concepts and techniques will help you connect a backend application to {{es}} to answer your queries. + +This quickstart also introduces you to the [official {{es}} clients](/reference/elasticsearch-clients/index.md), which are available for multiple programming languages. These clients offer full API support for indexing, searching, and cluster management. They are optimized for performance and kept up to date with {{es}} releases, ensuring compatibility and security. -In this quickstart, you'll index a couple of documents and query them using Python. -By the end of this guide, you’ll have learned how to connect a backend application to {{es}} to answer your queries. - ## Prerequisites -- If you're using [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. +In [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. @@ -44,7 +45,7 @@ TBD: Describe how to create the key For an introduction to the concept of indices, check out [](/manage-data/data-store/index-basics.md). ::: -## Install an {{es}} client +## Install the Python client Select your preferred language in the keyword search workflow. For this example, leverage Python. From 55f0cb058fef916dfea79a1e78bcdb3b759d5322 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 17:28:31 -0700 Subject: [PATCH 09/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 7d52027fa0..aa4fdc757b 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -24,7 +24,7 @@ In [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md If you're using [{{ech}}](/deploy-manage/deploy/elastic-cloud/cloud-hosted.md) or [running {{es}} locally](/solutions/search/run-elasticsearch-locally.md), start {{es}} and {{kib}}. To add the sample data, log in with a user that has the `superuser` built-in role. --> -To learn about role-based access control, check out [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). +To learn about role-based access control, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). ## Create an index From 1761a005735e0e9d95eeb90285b7ae9eca710b2c Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 17:30:28 -0700 Subject: [PATCH 10/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index aa4fdc757b..7f5a57244d 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -29,7 +29,7 @@ To learn about role-based access control, refer to [](/deploy-manage/users-roles ## Create an index An index is a collection of documents uniquely identified by a name or an alias. -Go to **{{es}} > Home**, select keyword search, and follow the guided index workflow. +To create an index, go to **{{es}} > Home**, select keyword search, and follow the guided workflow. :::{tip} -For an introduction to the concept of indices, check out [](/manage-data/data-store/index-basics.md). +For an introduction to the concept of indices, refer to [](/manage-data/data-store/index-basics.md). ::: ## Install the Python client From 9014c1fcd82507f38bb300f58ef93af0011fa896 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 16 Jul 2025 17:31:13 -0700 Subject: [PATCH 12/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index fc3f40b951..c359ab5b79 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -47,7 +47,7 @@ For an introduction to the concept of indices, refer to [](/manage-data/data-sto ## Install the Python client -Select your preferred language in the keyword search workflow. For this example, leverage Python. +Select your preferred language in the keyword search workflow. For this quickstart, use Python. ![Client installation step in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) From 26261e5547b59d0f7314f319631c73a94f791b58 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 19:52:43 -0700 Subject: [PATCH 13/19] Add project creation step and python prereqs --- .../get-started/keyword-search-python.md | 49 ++++++++++--------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index c359ab5b79..7689450130 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -10,7 +10,7 @@ products: --- # Build your first search query with Python -In this quickstart, you'll index a couple of documents and query them using Python. +In this quickstart, you'll index a couple of documents and query them using [Python](https://www.python.org/). These concepts and techniques will help you connect a backend application to {{es}} to answer your queries. This quickstart also introduces you to the [official {{es}} clients](/reference/elasticsearch-clients/index.md), which are available for multiple programming languages. @@ -19,30 +19,25 @@ They are optimized for performance and kept up to date with {{es}} releases, ens ## Prerequisites -In [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. - - -To learn about role-based access control, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). +This quickstart assumes you have no previous knowledge of {{es}} but expects you'll have a basic familiarity with Python development. +To follow the steps, you must have a recent version of a Python interpreter. + +## Create an {{es-serverless}} project + +In [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. +To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. +To learn about role-based access control, check out [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). -## Create an index +## Create an index and API key An index is a collection of documents uniquely identified by a name or an alias. To create an index, go to **{{es}} > Home**, select keyword search, and follow the guided workflow. - -You've created your first index! -Next, create an API key so your application can talk to {{es}}. - +To enable the client to talk to {{es}} you must also create an API key. +Click **Create API Key** and use the default values, which are sufficient for this quickstart. + :::{tip} -For an introduction to the concept of indices, refer to [](/manage-data/data-store/index-basics.md). +For more information about indices and API keys, go to [](/manage-data/data-store/index-basics.md) and [](/deploy-manage/api-keys/serverless-project-api-keys.md). ::: ## Install the Python client @@ -51,25 +46,33 @@ Select your preferred language in the keyword search workflow. For this quicksta ![Client installation step in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) -In your terminal, install the {{es}} client using `pip`: +The {{es}} client library is a Python package that is installed with `pip`: ```py pip install elasticsearch ``` -Copy your API key from the top right corner and add it to the client’s configuration alongside the project URL. +## Connect your client to your project + +Copy the code example from the guided index workflow, which follows this pattern: ```py from elasticsearch import Elasticsearch client = Elasticsearch( - "https://my-project-bff300.es.us-east-1.aws.elastic.cloud:443", + "YOUR-PROJECT-URL", api_key="YOUR-API-KEY" ) -index_name = "my-index" +index_name = "YOUR-INDEX" ``` +:::{tip} +The code examples can be copied into your Python interpreter in interactive mode. +::: + +You must provide your API key, index name, and project URL. + ## Create field mappings At this stage, you can define the mappings for your index, including a single text field named `text`. From d43d8af324278c2c2c2e903a267e405c47cf3f39 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 22:28:07 -0700 Subject: [PATCH 14/19] More edits --- .../get-started/keyword-search-python.md | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 7689450130..19cf531a3c 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -44,20 +44,21 @@ For more information about indices and API keys, go to [](/manage-data/data-stor Select your preferred language in the keyword search workflow. For this quickstart, use Python. -![Client installation step in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) +![Client installation step in the keyword search workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) The {{es}} client library is a Python package that is installed with `pip`: ```py -pip install elasticsearch +python -m pip install elasticsearch ``` ## Connect your client to your project -Copy the code example from the guided index workflow, which follows this pattern: +Copy the code example from the guided workflow to connect to the project: +For example: ```py -from elasticsearch import Elasticsearch +from elasticsearch import Elasticsearch, helpers client = Elasticsearch( "YOUR-PROJECT-URL", @@ -73,9 +74,9 @@ The code examples can be copied into your Python interpreter in interactive mode You must provide your API key, index name, and project URL. -## Create field mappings +## Define field mappings -At this stage, you can define the mappings for your index, including a single text field named `text`. +At this stage, you can create the mappings for your index, including a single text field named `text`. ```py mappings = { @@ -90,9 +91,15 @@ mapping_response = client.indices.put_mapping(index=index_name, body=mappings) print(mapping_response) ``` -## Add documents +A successful response will acknowledge the creation of the mappings: + +```py +{'acknowledged': True} +``` + +## Ingest documents -Next, use a bulk request to index three documents in {{es}}. +Next, use a bulk helper function to add three documents to your index. Bulk requests are the preferred method for indexing large volumes of data, from hundreds to billions of documents. ```py @@ -112,18 +119,21 @@ bulk_response = helpers.bulk(client, docs, index=index_name) print(bulk_response) ``` +For more details about bulker helpers, refer to [Client helpers](elasticsearch-py://reference/client-helpers.md). + ## Explore the data -You should be able to see the documents in {{es}}! +You should now be able to see the documents in the guided workflow: -![Viewing data in the index management workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt0ac36402cde2a645/67d0a443b8764e72b9e8e1f3/view_docs_in_elasticsearch.png) - +![Viewing data in the guided workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt0ac36402cde2a645/67d0a443b8764e72b9e8e1f3/view_docs_in_elasticsearch.png) + +Optionally open [Discover](/explore-analyze/discover.md) from the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md) to familiarize yourself with this data set. ## Test keyword search -Create a new script (for instance, `search.py`) that defines a query and runs the following search request: +A keyword search query finds relevant documents in your indices using exact matches, patterns, or similarity scoring. +The guided workflow provides an example that uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md). +If you prefer to try out [{{es}} Query Language](/explore-analyze/query-filter/languages/esql.md) ({{esql}}), create a new script (for instance, `search.py`) that defines a query and runs the following search request: ```esql FROM my-index From 56d3454a6f0f4f747cc42703d52e3dca595b63b7 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 23:56:39 -0700 Subject: [PATCH 15/19] Improve query and next steps --- .../get-started/keyword-search-python.md | 76 ++++++++----------- solutions/search/get-started/quickstarts.md | 1 + 2 files changed, 31 insertions(+), 46 deletions(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 19cf531a3c..7046f3e387 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -19,21 +19,21 @@ They are optimized for performance and kept up to date with {{es}} releases, ens ## Prerequisites -This quickstart assumes you have no previous knowledge of {{es}} but expects you'll have a basic familiarity with Python development. +This quickstart does not require previous knowledge of {{es}} but assumes a basic familiarity with Python development. To follow the steps, you must have a recent version of a Python interpreter. ## Create an {{es-serverless}} project -In [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md), create a general purpose project. -To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. -To learn about role-based access control, check out [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). +Create an [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md) general purpose project. +To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. +To learn about role-based access control, go to [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). -## Create an index and API key +## Create an index An index is a collection of documents uniquely identified by a name or an alias. To create an index, go to **{{es}} > Home**, select keyword search, and follow the guided workflow. -To enable the client to talk to {{es}} you must also create an API key. +To enable your client to talk to your project, you must also create an API key. Click **Create API Key** and use the default values, which are sufficient for this quickstart. :::{tip} @@ -42,7 +42,8 @@ For more information about indices and API keys, go to [](/manage-data/data-stor ## Install the Python client -Select your preferred language in the keyword search workflow. For this quickstart, use Python. +Select your preferred language in the keyword search workflow. +For this quickstart, use Python. ![Client installation step in the keyword search workflow](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltbf810f73fd4082fb/67c21c06304ea9790b82ee4d/screenshot-my-index.png) @@ -52,10 +53,10 @@ The {{es}} client library is a Python package that is installed with `pip`: python -m pip install elasticsearch ``` -## Connect your client to your project +## Connect to your project -Copy the code example from the guided workflow to connect to the project: -For example: +Copy the code example from the guided workflow into your Python interpreter in interactive mode. +For example, connect from your client to your {{es-serverless}} project: ```py from elasticsearch import Elasticsearch, helpers @@ -68,15 +69,12 @@ client = Elasticsearch( index_name = "YOUR-INDEX" ``` -:::{tip} -The code examples can be copied into your Python interpreter in interactive mode. -::: - -You must provide your API key, index name, and project URL. +You must replace the project URL, API key, and index name with the appropriate values. ## Define field mappings -At this stage, you can create the mappings for your index, including a single text field named `text`. +An index has mappings that define how data is stored and indexed. +Create mappings for your index, including a single text field named `text`: ```py mappings = { @@ -131,30 +129,14 @@ Optionally open [Discover](/explore-analyze/discover.md) from the navigation men ## Test keyword search -A keyword search query finds relevant documents in your indices using exact matches, patterns, or similarity scoring. +A keyword search, also known as lexical search or [full-text search](/solutions/search/full-text.md) finds relevant documents in your indices using exact matches, patterns, or similarity scoring. The guided workflow provides an example that uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md). -If you prefer to try out [{{es}} Query Language](/explore-analyze/query-filter/languages/esql.md) ({{esql}}), create a new script (for instance, `search.py`) that defines a query and runs the following search request: - -```esql -FROM my-index -| WHERE MATCH(text, "yosemite") -| LIMIT 5 -``` - -Add this query inside `client.esql.query`: +Alternatively, try out [{{es}} Query Language](/explore-analyze/query-filter/languages/esql.md) ({{esql}}) to find documents that match a specific keyword: ```py -from elasticsearch import Elasticsearch - -client = Elasticsearch( - "https://my-project-bff307.es.us-east-1.aws.elastic.cloud:443", - api_key="YOUR-API-KEY" -) - -# Run the search query response = client.esql.query( query=""" - FROM my-index + FROM * | WHERE MATCH(text, "yosemite") | LIMIT 5 """, @@ -164,29 +146,31 @@ response = client.esql.query( print(response) ``` -## Analyze the results +:::{tip} +Instead of using the `*` wildcard, you can narrow the query by using your index name. +For more details, go to the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) +::: -Check your result: +The results in this case contain the document that matches the query: ```txt "Yosemite National Park is a United States National Park, covering over 750,000 acres of land in California. A UNESCO World Heritage Site, the park is best known for its granite cliffs, waterfalls and giant sequoia trees. Yosemite hosts over four million visitors in most years, with a peak of five million visitors in 2016. The park is home to a diverse range of wildlife, including mule deer, black bears, and the endangered Sierra Nevada bighorn sheep. The park has 1,200 square miles of wilderness, and is a popular destination for rock climbers, with over 3,000 feet of vertical granite to climb. Its most famous and cliff is the El Capitan, a 3,000 feet monolith along its tallest face." Now you are ready to use the client to query Elasticsearch from any Python backend like Flask, Django, etc. Check out the Elasticsearch Python Client documentation to explore further ``` - +Test some more keyword search queries or go to the **{{index-manage-app}}** page and follow the workflows for vector search or semantic search queries. -## Next steps +When you finish your tests and no longer need the sample data set, delete your index: -This quickstart covered the basics of working with {{es}}. +```py +client.indices.delete(index=index_name) +``` +This quickstart covered the basics of working with {{es}}. For a deeper dive, refer to the following resources: - [Getting started with the Python client](elasticsearch-py://reference/getting-started.md) +- [](/manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md) - [Python notebooks](https://github.com/elastic/elasticsearch-labs/tree/main/notebooks/README.md) -- [](/manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md) \ No newline at end of file diff --git a/solutions/search/get-started/quickstarts.md b/solutions/search/get-started/quickstarts.md index 364d1d6ed8..fe86e90a48 100644 --- a/solutions/search/get-started/quickstarts.md +++ b/solutions/search/get-started/quickstarts.md @@ -15,6 +15,7 @@ Each quickstart provides: Follow the steps in these guides to get started quickly: +- [](/solutions/search/get-started/keyword-search-python.md) - [](/solutions/search/get-started/semantic-search.md) - [](/solutions/search/vector/bring-own-vectors.md) From 1a19a32616ba88cab969dbb336ff9d49f4a6da6e Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 17 Jul 2025 08:42:26 -0700 Subject: [PATCH 16/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: ketkee-aryamane --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 7046f3e387..e9fcf57356 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -55,7 +55,7 @@ python -m pip install elasticsearch ## Connect to your project -Copy the code example from the guided workflow into your Python interpreter in interactive mode. +To connect from your client to your {{es-serverless}} project, copy the following code example from the guided workflow into your Python interpreter in interactive mode: For example, connect from your client to your {{es-serverless}} project: ```py From a5bf9fb46a0bea7b2e82171aa041fa4d41a0a642 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 17 Jul 2025 08:42:38 -0700 Subject: [PATCH 17/19] Update solutions/search/get-started/keyword-search-python.md Co-authored-by: ketkee-aryamane --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index e9fcf57356..88a4c609ec 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -148,7 +148,7 @@ print(response) :::{tip} Instead of using the `*` wildcard, you can narrow the query by using your index name. -For more details, go to the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) +For more details, refer the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) ::: The results in this case contain the document that matches the query: From 77795d49438fbcaab323d1cedebb993f14f8eed0 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Jul 2025 08:50:43 -0700 Subject: [PATCH 18/19] Fix typo --- solutions/search/get-started/keyword-search-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 88a4c609ec..583dbce972 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -148,7 +148,7 @@ print(response) :::{tip} Instead of using the `*` wildcard, you can narrow the query by using your index name. -For more details, refer the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) +For more details, refer to the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) ::: The results in this case contain the document that matches the query: From 3469afd4f87207b58a57d62f833b01870bae2860 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Jul 2025 09:01:34 -0700 Subject: [PATCH 19/19] Add stepper component --- .../get-started/keyword-search-python.md | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/solutions/search/get-started/keyword-search-python.md b/solutions/search/get-started/keyword-search-python.md index 583dbce972..9836f1e292 100644 --- a/solutions/search/get-started/keyword-search-python.md +++ b/solutions/search/get-started/keyword-search-python.md @@ -17,18 +17,19 @@ This quickstart also introduces you to the [official {{es}} clients](/reference/ These clients offer full API support for indexing, searching, and cluster management. They are optimized for performance and kept up to date with {{es}} releases, ensuring compatibility and security. -## Prerequisites - This quickstart does not require previous knowledge of {{es}} but assumes a basic familiarity with Python development. To follow the steps, you must have a recent version of a Python interpreter. -## Create an {{es-serverless}} project +:::::{stepper} + +::::{step} Create a project Create an [{{es-serverless}}](/solutions/search/serverless-elasticsearch-get-started.md) general purpose project. To add the sample data, you must have a `developer` or `admin` predefined role or an equivalent custom role. To learn about role-based access control, go to [](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md). -## Create an index +:::: +::::{step} Create an index An index is a collection of documents uniquely identified by a name or an alias. To create an index, go to **{{es}} > Home**, select keyword search, and follow the guided workflow. @@ -39,8 +40,8 @@ Click **Create API Key** and use the default values, which are sufficient for th :::{tip} For more information about indices and API keys, go to [](/manage-data/data-store/index-basics.md) and [](/deploy-manage/api-keys/serverless-project-api-keys.md). ::: - -## Install the Python client +:::: +::::{step} Install the Python client Select your preferred language in the keyword search workflow. For this quickstart, use Python. @@ -53,7 +54,8 @@ The {{es}} client library is a Python package that is installed with `pip`: python -m pip install elasticsearch ``` -## Connect to your project +:::: +::::{step} Connect to your project To connect from your client to your {{es-serverless}} project, copy the following code example from the guided workflow into your Python interpreter in interactive mode: For example, connect from your client to your {{es-serverless}} project: @@ -71,7 +73,8 @@ index_name = "YOUR-INDEX" You must replace the project URL, API key, and index name with the appropriate values. -## Define field mappings +:::: +::::{step} Define field mappings An index has mappings that define how data is stored and indexed. Create mappings for your index, including a single text field named `text`: @@ -95,7 +98,8 @@ A successful response will acknowledge the creation of the mappings: {'acknowledged': True} ``` -## Ingest documents +:::: +::::{step} Ingest documents Next, use a bulk helper function to add three documents to your index. Bulk requests are the preferred method for indexing large volumes of data, from hundreds to billions of documents. @@ -119,7 +123,8 @@ print(bulk_response) For more details about bulker helpers, refer to [Client helpers](elasticsearch-py://reference/client-helpers.md). -## Explore the data +:::: +::::{step} Explore the data You should now be able to see the documents in the guided workflow: @@ -127,7 +132,8 @@ You should now be able to see the documents in the guided workflow: Optionally open [Discover](/explore-analyze/discover.md) from the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md) to familiarize yourself with this data set. -## Test keyword search +:::: +::::{step} Test keyword search A keyword search, also known as lexical search or [full-text search](/solutions/search/full-text.md) finds relevant documents in your indices using exact matches, patterns, or similarity scoring. The guided workflow provides an example that uses [Query DSL](/explore-analyze/query-filter/languages/querydsl.md). @@ -158,6 +164,9 @@ The results in this case contain the document that matches the query: Now you are ready to use the client to query Elasticsearch from any Python backend like Flask, Django, etc. Check out the Elasticsearch Python Client documentation to explore further ``` +:::: +::::: + ## Next steps Test some more keyword search queries or go to the **{{index-manage-app}}** page and follow the workflows for vector search or semantic search queries.