From 5edf34573cc95b8b0a4157206bc8b2605dde2bac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 13:13:38 +0200 Subject: [PATCH 01/10] [DOCS] Adds quickstart guide to ES Py Read The Docs. --- docs/sphinx/quickstart.rst | 148 +++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/sphinx/quickstart.rst diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst new file mode 100644 index 000000000..bd595c50a --- /dev/null +++ b/docs/sphinx/quickstart.rst @@ -0,0 +1,148 @@ +Quickstart +========== + +This guide shows you how to install Elasticsearch and perform basic operations +with it by using the Python client. + +Requirements +------------ + +- `Python _` 3.6 or newer +- `pip `_ + + +Installation +------------ + +To install the latest version of the client, run the following command: + +.. code-block:: console + + $ python -m pip install elasticsearch + + +Connecting +---------- + +You can connect to the Elastic Cloud using an API key and the Elasticsearch +endpoint. + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client = Elasticsearch( + "https://...", # Elasticsearch endpoint + api_key=('api-key-id', 'api-key-secret'), # API key ID and secret +) + +Your Elasticsearch endpoint can be found on the **My deployment** page of your +deployment: + +.. image:: ../guide/images/es-endpoint.jpg + +You can generate an API key on the **Management** page under Security. + +.. image:: ../guide/images/create-api-key.png + + +Using the client +---------------- + +Time to use Elasticsearch! This section walks you through the most important +operations of Elasticsearch. + + +Creating an index +^^^^^^^^^^^^^^^^^ + +This is how you create the `my_index` index: + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.indices.create(index="my_index") + + +Indexing documents +^^^^^^^^^^^^^^^^^^ + +This is a simple way of indexing a documentby using the index API: + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.index( + index="my_index", + id="my_document_id", + document={ + "foo": "foo", + "bar": "bar", + } + ) + + +Getting documents +^^^^^^^^^^^^^^^^^ + +You can get documents by using the following code: + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.get(index="my_index", id="my_document_id") + + +Searching documents +^^^^^^^^^^^^^^^^^^^ + +This is how you can create a single match query with the Python client: + + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.search(index="my_index", query={ + "match": { + "foo": "foo" + } + }) + + +Updating documents +^^^^^^^^^^^^^^^^^^ + +This is how you can update a document, for example to add a new field: + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.update(index="my_index", id="my_document_id", doc={ + "foo": "bar", + "new_field": "new value", + }) + + +Deleting documents +^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.delete(index="my_index", id="my_document_id") + + +Deleting an index +^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from elasticsearch import Elasticsearch + + client.indices.delete(index="my_index") From 0ae1b2dc0566e5eaddb5af723f668de2254104d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 13:15:30 +0200 Subject: [PATCH 02/10] [DOCS] Adds quickstart to TOC. --- docs/sphinx/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 122970f02..307827344 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -110,6 +110,7 @@ Contents .. toctree:: :maxdepth: 3 + quickstart api exceptions async From 08576716e6d9d2f3fd3c6b1b310644b3d0692cb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 13:23:48 +0200 Subject: [PATCH 03/10] [DOCS] Fixes link. --- docs/sphinx/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index bd595c50a..d298a87b4 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -7,7 +7,7 @@ with it by using the Python client. Requirements ------------ -- `Python _` 3.6 or newer +- `Python `_ 3.6 or newer - `pip `_ From eba181143b66fe8495022347df8c77c1b4c9cfb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 13:37:00 +0200 Subject: [PATCH 04/10] [DOCS] Fixes snippet. --- docs/sphinx/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index d298a87b4..6c9217c3e 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -34,7 +34,7 @@ endpoint. client = Elasticsearch( "https://...", # Elasticsearch endpoint api_key=('api-key-id', 'api-key-secret'), # API key ID and secret -) + ) Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment: From a384c7736b3f844a7a2902a9d76c0a0f8595f997 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 15:23:33 +0200 Subject: [PATCH 05/10] [DOCS] Changes connection snippet. --- docs/sphinx/quickstart.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 6c9217c3e..a606725b3 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -24,22 +24,19 @@ To install the latest version of the client, run the following command: Connecting ---------- -You can connect to the Elastic Cloud using an API key and the Elasticsearch -endpoint. +You can connect to the Elastic Cloud using an API key and the Cloud ID. .. code-block:: python from elasticsearch import Elasticsearch client = Elasticsearch( - "https://...", # Elasticsearch endpoint - api_key=('api-key-id', 'api-key-secret'), # API key ID and secret + cloud_id="YOUR_CLOUD_ID", + api_key="YOUR_API_KEY" ) -Your Elasticsearch endpoint can be found on the **My deployment** page of your -deployment: - -.. image:: ../guide/images/es-endpoint.jpg +Your Cloud ID can be found on the **My deployment** page of your deployment +under **Cloud ID**. You can generate an API key on the **Management** page under Security. From b5468ac676942804a83bab118d2e60282074d350 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 15:55:07 +0200 Subject: [PATCH 06/10] [DOCS] Makes indentation consistent. --- docs/sphinx/quickstart.rst | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index a606725b3..b206562c6 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -29,11 +29,8 @@ You can connect to the Elastic Cloud using an API key and the Cloud ID. .. code-block:: python from elasticsearch import Elasticsearch - - client = Elasticsearch( - cloud_id="YOUR_CLOUD_ID", - api_key="YOUR_API_KEY" - ) + + client = Elasticsearch(cloud_id="YOUR_CLOUD_ID", api_key="YOUR_API_KEY") Your Cloud ID can be found on the **My deployment** page of your deployment under **Cloud ID**. @@ -77,7 +74,7 @@ This is a simple way of indexing a documentby using the index API: document={ "foo": "foo", "bar": "bar", - } + }, ) @@ -102,12 +99,8 @@ This is how you can create a single match query with the Python client: .. code-block:: python from elasticsearch import Elasticsearch - - client.search(index="my_index", query={ - "match": { - "foo": "foo" - } - }) + + client.search(index="my_index", query={"match": {"foo": "foo"}}) Updating documents @@ -119,10 +112,14 @@ This is how you can update a document, for example to add a new field: from elasticsearch import Elasticsearch - client.update(index="my_index", id="my_document_id", doc={ - "foo": "bar", - "new_field": "new value", - }) + client.update( + index="my_index", + id="my_document_id", + doc={ + "foo": "bar", + "new_field": "new value", + }, + ) Deleting documents From ffef1c8324e2cd07a7f4806a8e0fc4fac57e23a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 16:15:12 +0200 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Quentin Pradet --- docs/sphinx/quickstart.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index b206562c6..22e57bcae 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -1,8 +1,8 @@ Quickstart ========== -This guide shows you how to install Elasticsearch and perform basic operations -with it by using the Python client. +This guide shows you how to install the Elasticsearch Python client and perform basic +operations like indexing or searching documents. Requirements ------------ @@ -24,7 +24,7 @@ To install the latest version of the client, run the following command: Connecting ---------- -You can connect to the Elastic Cloud using an API key and the Cloud ID. +You can connect to Elastic Cloud using an API key and the Cloud ID. .. code-block:: python @@ -62,7 +62,7 @@ This is how you create the `my_index` index: Indexing documents ^^^^^^^^^^^^^^^^^^ -This is a simple way of indexing a documentby using the index API: +This indexes a document with the index API: .. code-block:: python From bffe18b19ee1a1d844f59ebdf012fd8b2cb3389f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 10 Oct 2023 16:15:57 +0200 Subject: [PATCH 08/10] [DOCS] Addresses feedback. --- docs/sphinx/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 22e57bcae..6b3d55765 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -14,7 +14,7 @@ Requirements Installation ------------ -To install the latest version of the client, run the following command: +To install the client, run the following command: .. code-block:: console From 9522669ee7fe6b01c8c6a36e169c2620eb3f1dce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 12 Oct 2023 10:10:28 +0200 Subject: [PATCH 09/10] [DOCS] Removes include statements, adds explanation. --- docs/sphinx/quickstart.rst | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 6b3d55765..7359b6e62 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -44,7 +44,9 @@ Using the client ---------------- Time to use Elasticsearch! This section walks you through the most important -operations of Elasticsearch. +operations of Elasticsearch. The following examples assume that the Python +client has already initiated and don't contain the Elasticsearch `include` +statement. Creating an index @@ -54,8 +56,6 @@ This is how you create the `my_index` index: .. code-block:: python - from elasticsearch import Elasticsearch - client.indices.create(index="my_index") @@ -66,8 +66,6 @@ This indexes a document with the index API: .. code-block:: python - from elasticsearch import Elasticsearch - client.index( index="my_index", id="my_document_id", @@ -84,8 +82,6 @@ Getting documents You can get documents by using the following code: .. code-block:: python - - from elasticsearch import Elasticsearch client.get(index="my_index", id="my_document_id") @@ -98,8 +94,6 @@ This is how you can create a single match query with the Python client: .. code-block:: python - from elasticsearch import Elasticsearch - client.search(index="my_index", query={"match": {"foo": "foo"}}) @@ -110,8 +104,6 @@ This is how you can update a document, for example to add a new field: .. code-block:: python - from elasticsearch import Elasticsearch - client.update( index="my_index", id="my_document_id", @@ -126,8 +118,6 @@ Deleting documents ^^^^^^^^^^^^^^^^^^ .. code-block:: python - - from elasticsearch import Elasticsearch client.delete(index="my_index", id="my_document_id") @@ -136,7 +126,5 @@ Deleting an index ^^^^^^^^^^^^^^^^^ .. code-block:: python - - from elasticsearch import Elasticsearch client.indices.delete(index="my_index") From c5233a45ef1ad61c6ad6029659fc0a4aaf633401 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 13 Oct 2023 10:07:40 +0200 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Quentin Pradet --- docs/sphinx/quickstart.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 7359b6e62..e21cfe49f 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -45,8 +45,7 @@ Using the client Time to use Elasticsearch! This section walks you through the most important operations of Elasticsearch. The following examples assume that the Python -client has already initiated and don't contain the Elasticsearch `include` -statement. +client was instantiated as above. Creating an index @@ -94,7 +93,7 @@ This is how you can create a single match query with the Python client: .. code-block:: python - client.search(index="my_index", query={"match": {"foo": "foo"}}) + client.search(index="my_index", query={"match": {"foo": {"query": "foo"}}}) Updating documents