From 8058861784cab41443be27baf7040a3b51e7c49a Mon Sep 17 00:00:00 2001 From: Iulia Feroli Date: Thu, 18 Jan 2024 13:24:46 +0100 Subject: [PATCH 1/4] Update quickstart.rst --- docs/sphinx/quickstart.rst | 54 +++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 68a1c52ba..599bdc6e6 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -41,6 +41,11 @@ You can generate an API key on the **Management** page under Security. .. image:: ../guide/images/create-api-key.png +Confirm that the connection was successful. + +.. code-block:: python + + print(client.info()) Using the client ---------------- @@ -49,6 +54,29 @@ Time to use Elasticsearch! This section walks you through the most important operations of Elasticsearch. The following examples assume that the Python client was instantiated as above. +Create a mapping for your index +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the expected types of your features. + +.. code-block:: python + + mappings = { + "properties": { + "foo": { + "type" : "text" + }, + "bar" : { + "type" : "text", + "fields" : { + "keyword" : { + "type" : "keyword", + "ignore_above" : 256 + } + } + } + } + } Creating an index ^^^^^^^^^^^^^^^^^ @@ -57,7 +85,7 @@ This is how you create the `my_index` index: .. code-block:: python - client.indices.create(index="my_index") + client.indices.create(index="my_index", mappings = mappings) Indexing documents @@ -76,6 +104,30 @@ This indexes a document with the index API: }, ) +You can also index multiple documents at once with the bulk API: + +.. code-block:: python + + def generate_operations(documents, index_name): + operations = [] + for i, document in enumerate(documents): + operations.append({"index": {"_index": index_name, "_id": i}}) + operations.append(document) + return operations + + client.bulk(index=index_name, operations=generate_operations(books, index_name), refresh=True) + +Alternatively, you can use one of the helper functions: + +.. code-block:: python + + from elasticsearch import helpers + + def generate_docs(documents, index_name): + for i, document in enumerate(documents): + yield dict(_index=index_name, _id=f"{i}", _source=document) + + helpers.bulk(client, generate_docs(books, index_name)) Getting documents ^^^^^^^^^^^^^^^^^ From dc66553858c6f5efeb4eb9173b24555b9171a5b5 Mon Sep 17 00:00:00 2001 From: Iulia Feroli Date: Thu, 8 Feb 2024 15:10:51 +0100 Subject: [PATCH 2/4] Update quickstart.rst --- docs/sphinx/quickstart.rst | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 599bdc6e6..038b41fea 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -104,20 +104,7 @@ This indexes a document with the index API: }, ) -You can also index multiple documents at once with the bulk API: - -.. code-block:: python - - def generate_operations(documents, index_name): - operations = [] - for i, document in enumerate(documents): - operations.append({"index": {"_index": index_name, "_id": i}}) - operations.append(document) - return operations - - client.bulk(index=index_name, operations=generate_operations(books, index_name), refresh=True) - -Alternatively, you can use one of the helper functions: +You can also index multiple documents at once with the bulk helper function: .. code-block:: python @@ -129,6 +116,8 @@ Alternatively, you can use one of the helper functions: helpers.bulk(client, generate_docs(books, index_name)) +These helpers are the recommended simple and streamlined way to abstract otherwise complicated and verbose functions such as `client.bulk`. + Getting documents ^^^^^^^^^^^^^^^^^ From 9fd57de547a05077053dcb46d582540a09346609 Mon Sep 17 00:00:00 2001 From: Iulia Feroli Date: Fri, 9 Feb 2024 13:50:09 +0100 Subject: [PATCH 3/4] added changes based on Quentin's comments --- docs/sphinx/quickstart.rst | 55 ++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 038b41fea..6e6d03888 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -54,40 +54,39 @@ Time to use Elasticsearch! This section walks you through the most important operations of Elasticsearch. The following examples assume that the Python client was instantiated as above. +Creating an index +^^^^^^^^^^^^^^^^^ + +This is how you create the `my_index` index: + +.. code-block:: python + + client.indices.create(index="my_index") + Create a mapping for your index ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Set the expected types of your features. +Optionally, you can first define the expected types of your features with a custom mapping. .. code-block:: python mappings = { "properties": { - "foo": { - "type" : "text" + "foo": {"type": "text"}, + "bar": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256, + } + }, }, - "bar" : { - "type" : "text", - "fields" : { - "keyword" : { - "type" : "keyword", - "ignore_above" : 256 - } - } - } } } -Creating an index -^^^^^^^^^^^^^^^^^ - -This is how you create the `my_index` index: - -.. code-block:: python - client.indices.create(index="my_index", mappings = mappings) - Indexing documents ^^^^^^^^^^^^^^^^^^ @@ -110,13 +109,17 @@ You can also index multiple documents at once with the bulk helper function: from elasticsearch import helpers - def generate_docs(documents, index_name): - for i, document in enumerate(documents): - yield dict(_index=index_name, _id=f"{i}", _source=document) - - helpers.bulk(client, generate_docs(books, index_name)) + def generate_docs(): + for i in range(10): + yield { + "_index": "my_index", + "foo": f"foo {i}", + "bar": "bar", + } + + helpers.bulk(client, generate_docs()) -These helpers are the recommended simple and streamlined way to abstract otherwise complicated and verbose functions such as `client.bulk`. +These helpers are the recommended way to perform bulk ingestion. While it is also possible to perform bulk ingestion using ``client.bulk`` directly, the helpers handle retries, ingesting chunk by chunk and more. See the :ref:`helpers` page for more details. Getting documents ^^^^^^^^^^^^^^^^^ From ee1dd75b9a3110d9e6d5e750feb00fa29d78a139 Mon Sep 17 00:00:00 2001 From: Iulia Feroli Date: Fri, 9 Feb 2024 14:45:35 +0100 Subject: [PATCH 4/4] formatting and removing the double index instructoins --- docs/sphinx/quickstart.rst | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst index 6e6d03888..51938e921 100644 --- a/docs/sphinx/quickstart.rst +++ b/docs/sphinx/quickstart.rst @@ -54,18 +54,10 @@ Time to use Elasticsearch! This section walks you through the most important operations of Elasticsearch. The following examples assume that the Python client was instantiated as above. -Creating an index -^^^^^^^^^^^^^^^^^ - -This is how you create the `my_index` index: - -.. code-block:: python - - client.indices.create(index="my_index") - -Create a mapping for your index -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create an index with mappings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is how you create the `my_index` index. Optionally, you can first define the expected types of your features with a custom mapping. .. code-block:: python @@ -85,7 +77,7 @@ Optionally, you can first define the expected types of your features with a cust } } - client.indices.create(index="my_index", mappings = mappings) + client.indices.create(index="my_index", mappings=mappings) Indexing documents ^^^^^^^^^^^^^^^^^^