Skip to content

[Backport 8.10] [DOCS] Adds quickstart guide to ES Py Read The Docs #2339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/sphinx/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ Contents
.. toctree::
:maxdepth: 3

quickstart
api
exceptions
async
Expand Down
129 changes: 129 additions & 0 deletions docs/sphinx/quickstart.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
Quickstart
==========

This guide shows you how to install the Elasticsearch Python client and perform basic
operations like indexing or searching documents.

Requirements
------------

- `Python <https://www.python.org/>`_ 3.6 or newer
- `pip <https://pip.pypa.io/en/stable/>`_


Installation
------------

To install the client, run the following command:

.. code-block:: console

$ python -m pip install elasticsearch


Connecting
----------

You can connect to 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")

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.

.. 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. 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")


Indexing documents
^^^^^^^^^^^^^^^^^^

This indexes a document with the index API:

.. code-block:: python

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

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

client.search(index="my_index", query={"match": {"foo": {"query": "foo"}}})


Updating documents
^^^^^^^^^^^^^^^^^^

This is how you can update a document, for example to add a new field:

.. code-block:: python

client.update(
index="my_index",
id="my_document_id",
doc={
"foo": "bar",
"new_field": "new value",
},
)


Deleting documents
^^^^^^^^^^^^^^^^^^

.. code-block:: python

client.delete(index="my_index", id="my_document_id")


Deleting an index
^^^^^^^^^^^^^^^^^

.. code-block:: python

client.indices.delete(index="my_index")