diff --git a/docs/sphinx/api_helpers.rst b/docs/sphinx/api_helpers.rst new file mode 100644 index 000000000..31d5b241d --- /dev/null +++ b/docs/sphinx/api_helpers.rst @@ -0,0 +1,26 @@ +.. _helpers: + +Helpers +======= + +.. py:module:: elasticsearch.helpers + +Streaming Bulk +-------------- +.. autofunction:: streaming_bulk + +Parallel Bulk +------------- +.. autofunction:: parallel_bulk + +Bulk +---- +.. autofunction:: bulk + +Scan +---- +.. autofunction:: scan + +Reindex +------- +.. autofunction:: reindex diff --git a/docs/sphinx/async.rst b/docs/sphinx/async.rst deleted file mode 100644 index 22a49b312..000000000 --- a/docs/sphinx/async.rst +++ /dev/null @@ -1,237 +0,0 @@ -Using asyncio with Elasticsearch -================================ - - .. py:module:: elasticsearch - :no-index: - -The ``elasticsearch`` package supports async/await with -`asyncio `_ and `aiohttp `_. -You can either install ``aiohttp`` directly or use the ``[async]`` extra: - - .. code-block:: bash - - $ python -m pip install elasticsearch aiohttp - - # - OR - - - $ python -m pip install elasticsearch[async] - -Getting Started with Async --------------------------- - -After installation all async API endpoints are available via :class:`~elasticsearch.AsyncElasticsearch` -and are used in the same way as other APIs, just with an extra ``await``: - - .. code-block:: python - - import asyncio - from elasticsearch import AsyncElasticsearch - - client = AsyncElasticsearch() - - async def main(): - resp = await client.search( - index="documents", - body={"query": {"match_all": {}}}, - size=20, - ) - print(resp) - - loop = asyncio.get_event_loop() - loop.run_until_complete(main()) - -All APIs that are available under the sync client are also available under the async client. - -ASGI Applications and Elastic APM ---------------------------------- - -`ASGI `_ (Asynchronous Server Gateway Interface) is a new way to -serve Python web applications making use of async I/O to achieve better performance. -Some examples of ASGI frameworks include FastAPI, Django 3.0+, and Starlette. -If you're using one of these frameworks along with Elasticsearch then you -should be using :py:class:`~elasticsearch.AsyncElasticsearch` to avoid blocking -the event loop with synchronous network calls for optimal performance. - -`Elastic APM `_ -also supports tracing of async Elasticsearch queries just the same as -synchronous queries. For an example on how to configure ``AsyncElasticsearch`` with -a popular ASGI framework `FastAPI `_ and APM tracing -there is a `pre-built example `_ -in the ``examples/fastapi-apm`` directory. - -Frequently Asked Questions --------------------------- - -ValueError when initializing ``AsyncElasticsearch``? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If when trying to use ``AsyncElasticsearch`` you receive ``ValueError: You must -have 'aiohttp' installed to use AiohttpHttpNode`` you should ensure that you -have ``aiohttp`` installed in your environment (check with ``$ python -m pip -freeze | grep aiohttp``). Otherwise, async support won't be available. - -What about the ``elasticsearch-async`` package? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Previously asyncio was supported separately via the `elasticsearch-async `_ -package. The ``elasticsearch-async`` package has been deprecated in favor of -``AsyncElasticsearch`` provided by the ``elasticsearch`` package -in v7.8 and onwards. - -Receiving 'Unclosed client session / connector' warning? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This warning is created by ``aiohttp`` when an open HTTP connection is -garbage collected. You'll typically run into this when closing your application. -To resolve the issue ensure that :meth:`~elasticsearch.AsyncElasticsearch.close` -is called before the :py:class:`~elasticsearch.AsyncElasticsearch` instance is garbage collected. - -For example if using FastAPI that might look like this: - - .. code-block:: python - - import os - from contextlib import asynccontextmanager - - from fastapi import FastAPI - from elasticsearch import AsyncElasticsearch - - ELASTICSEARCH_URL = os.environ["ELASTICSEARCH_URL"] - client = None - - @asynccontextmanager - async def lifespan(app: FastAPI): - global client - client = AsyncElasticsearch(ELASTICSEARCH_URL) - yield - await client.close() - - app = FastAPI(lifespan=lifespan) - - @app.get("/") - async def main(): - return await client.info() - -You can run this example by saving it to ``main.py`` and executing -``ELASTICSEARCH_URL=http://localhost:9200 uvicorn main:app``. - - -Async Helpers -------------- - -Async variants of all helpers are available in ``elasticsearch.helpers`` -and are all prefixed with ``async_*``. You'll notice that these APIs -are identical to the ones in the sync :ref:`helpers` documentation. - -All async helpers that accept an iterator or generator also accept async iterators -and async generators. - - .. py:module:: elasticsearch.helpers - :no-index: - -Bulk and Streaming Bulk -~~~~~~~~~~~~~~~~~~~~~~~ - - .. autofunction:: async_bulk - - .. code-block:: python - - import asyncio - from elasticsearch import AsyncElasticsearch - from elasticsearch.helpers import async_bulk - - client = AsyncElasticsearch() - - async def gendata(): - mywords = ['foo', 'bar', 'baz'] - for word in mywords: - yield { - "_index": "mywords", - "doc": {"word": word}, - } - - async def main(): - await async_bulk(client, gendata()) - - loop = asyncio.get_event_loop() - loop.run_until_complete(main()) - - .. autofunction:: async_streaming_bulk - - .. code-block:: python - - import asyncio - from elasticsearch import AsyncElasticsearch - from elasticsearch.helpers import async_streaming_bulk - - client = AsyncElasticsearch() - - async def gendata(): - mywords = ['foo', 'bar', 'baz'] - for word in mywords: - yield { - "_index": "mywords", - "word": word, - } - - async def main(): - async for ok, result in async_streaming_bulk(client, gendata()): - action, result = result.popitem() - if not ok: - print("failed to %s document %s" % ()) - - loop = asyncio.get_event_loop() - loop.run_until_complete(main()) - -Scan -~~~~ - - .. autofunction:: async_scan - - .. code-block:: python - - import asyncio - from elasticsearch import AsyncElasticsearch - from elasticsearch.helpers import async_scan - - client = AsyncElasticsearch() - - async def main(): - async for doc in async_scan( - client=client, - query={"query": {"match": {"title": "python"}}}, - index="orders-*" - ): - print(doc) - - loop = asyncio.get_event_loop() - loop.run_until_complete(main()) - -Reindex -~~~~~~~ - - .. autofunction:: async_reindex - - -API Reference -------------- - - .. py:module:: elasticsearch - :no-index: - -The API of :class:`~elasticsearch.AsyncElasticsearch` is nearly identical -to the API of :class:`~elasticsearch.Elasticsearch` with the exception that -every API call like :py:func:`~elasticsearch.AsyncElasticsearch.search` is -an ``async`` function and requires an ``await`` to properly return the response -body. - -AsyncElasticsearch -~~~~~~~~~~~~~~~~~~ - - .. note:: - - To reference Elasticsearch APIs that are namespaced like ``.indices.create()`` - refer to the sync API reference. These APIs are identical between sync and async. - - .. autoclass:: AsyncElasticsearch - :members: diff --git a/docs/sphinx/async_api_helpers.rst b/docs/sphinx/async_api_helpers.rst new file mode 100644 index 000000000..61dbb5c24 --- /dev/null +++ b/docs/sphinx/async_api_helpers.rst @@ -0,0 +1,29 @@ +Async Helpers +============= + +Async variants of all helpers are available in ``elasticsearch.helpers`` +and are all prefixed with ``async_*``. You'll notice that these APIs +are identical to the ones in the sync :ref:`helpers` documentation. + +All async helpers that accept an iterator or generator also accept async iterators +and async generators. + + .. py:module:: elasticsearch.helpers + :no-index: + +Streaming Bulk +-------------- + .. autofunction:: async_streaming_bulk + +Bulk +---- + .. autofunction:: async_bulk + +Scan +---- + .. autofunction:: async_scan + +Reindex +------- + .. autofunction:: async_reindex + diff --git a/docs/sphinx/async_dsl.rst b/docs/sphinx/async_dsl.rst new file mode 100644 index 000000000..89ac8565d --- /dev/null +++ b/docs/sphinx/async_dsl.rst @@ -0,0 +1,49 @@ +.. _async_dsl: + +Async DSL +========= + +.. py:module:: elasticsearch.dsl + :no-index: + +Search +------ +.. autoclass:: AsyncSearch + :inherited-members: + :members: + +Multi-Search +------------ +.. autoclass:: AsyncMultiSearch + :inherited-members: + :members: + +Document +-------- +.. autoclass:: AsyncDocument + :inherited-members: + :members: + +Index +----- +.. autoclass:: AsyncIndex + :inherited-members: + :members: + +Mapping +------- +.. autoclass:: AsyncMapping + :inherited-members: + :members: + +Faceted Search +-------------- +.. autoclass:: AsyncFacetedSearch + :inherited-members: + :members: + +Update by Query +--------------- +.. autoclass:: AsyncUpdateByQuery + :inherited-members: + :members: diff --git a/docs/sphinx/async_es_api.rst b/docs/sphinx/async_es_api.rst new file mode 100644 index 000000000..d4acf2ff0 --- /dev/null +++ b/docs/sphinx/async_es_api.rst @@ -0,0 +1,15 @@ +Async Elasticsearch API +======================= + + .. py:module:: elasticsearch + :no-index: + + .. note:: + + To reference Elasticsearch APIs that are namespaced like ``.indices.create()`` + refer to the sync API reference. These APIs are identical between sync and async. + +Elasticsearch +------------- + .. autoclass:: AsyncElasticsearch + :members: diff --git a/docs/sphinx/dsl.rst b/docs/sphinx/dsl.rst new file mode 100644 index 000000000..08ab3c935 --- /dev/null +++ b/docs/sphinx/dsl.rst @@ -0,0 +1,49 @@ +.. _dsl: + +DSL +=== + +.. py:module:: elasticsearch.dsl + +Search +------ +.. autoclass:: Search + :inherited-members: + :members: + +Multi-Search +------------ +.. autoclass:: MultiSearch + :inherited-members: + :members: + +Document +-------- +.. autoclass:: Document + :inherited-members: + :members: + +Index +----- +.. autoclass:: Index + :inherited-members: + :members: + +Mapping +------- +.. autoclass:: Mapping + :inherited-members: + :members: + +Faceted Search +-------------- +.. autoclass:: FacetedSearch + :inherited-members: + :members: + +Update by Query +--------------- +.. autoclass:: UpdateByQuery + :inherited-members: + :members: + diff --git a/docs/sphinx/api.rst b/docs/sphinx/es_api.rst similarity index 95% rename from docs/sphinx/api.rst rename to docs/sphinx/es_api.rst index 61d3214e6..d246ec6f5 100644 --- a/docs/sphinx/api.rst +++ b/docs/sphinx/es_api.rst @@ -1,7 +1,7 @@ .. _api: -Elasticsearch API Reference -=========================== +Elasticsearch API +================= All the API calls map the raw REST API as closely as possible, including the distinction between required and optional arguments to the calls. Keyword diff --git a/docs/sphinx/helpers.rst b/docs/sphinx/helpers.rst deleted file mode 100644 index 3390958a8..000000000 --- a/docs/sphinx/helpers.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. _helpers: - -Helpers -======= - -Collection of simple helper functions that abstract some specifics of the raw API. - -Connecting ----------- - -.. code-block:: python - - from elasticsearch import Elasticsearch - - client = Elasticsearch("https://.../", api_key="YOUR_API_KEY") - - -Bulk helpers ------------- - -There are several helpers for the ``bulk`` API since its requirement for -specific formatting and other considerations can make it cumbersome if used directly. - -All bulk helpers accept an instance of ``Elasticsearch`` class and an iterable -``actions`` (any iterable, can also be a generator, which is ideal in most -cases since it will allow you to index large datasets without the need of -loading them into memory). - -The items in the ``action`` iterable should be the documents we wish to index -in several formats. The most common one is the same as returned by -:meth:`~elasticsearch.Elasticsearch.search`, for example: - -.. code:: python - - { - '_index': 'index-name', - '_id': 42, - '_routing': 5, - 'pipeline': 'my-ingest-pipeline', - '_source': { - "title": "Hello World!", - "body": "..." - } - } - -Alternatively, if `_source` is not present, it will pop all metadata fields -from the doc and use the rest as the document data: - -.. code:: python - - { - "_id": 42, - "_routing": 5, - "title": "Hello World!", - "body": "..." - } - -The :meth:`~elasticsearch.Elasticsearch.bulk` api accepts ``index``, ``create``, -``delete``, and ``update`` actions. Use the ``_op_type`` field to specify an -action (``_op_type`` defaults to ``index``): - -.. code:: python - - { - '_op_type': 'delete', - '_index': 'index-name', - '_id': 42, - } - { - '_op_type': 'update', - '_index': 'index-name', - '_id': 42, - 'doc': {'question': 'The life, universe and everything.'} - } - - -Example: -~~~~~~~~ - -Lets say we have an iterable of data. Lets say a list of words called ``mywords`` -and we want to index those words into individual documents where the structure of the -document is like ``{"word": ""}``. - -.. code:: python - - from elasticsearch.helpers import bulk - - def gendata(): - mywords = ['foo', 'bar', 'baz'] - for word in mywords: - yield { - "_index": "mywords", - "word": word, - } - - bulk(client, gendata()) - - -For a more complete and complex example please take a look at -https://github.com/elastic/elasticsearch-py/blob/main/examples/bulk-ingest - -The :meth:`~elasticsearch.Elasticsearch.parallel_bulk` api is a wrapper around the :meth:`~elasticsearch.Elasticsearch.bulk` api to provide threading. :meth:`~elasticsearch.Elasticsearch.parallel_bulk` returns a generator which must be consumed to produce results. - -To see the results use: - -.. code:: python - - for success, info in parallel_bulk(...): - if not success: - print('A document failed:', info) - -If you don't care about the results, you can use deque from collections: - -.. code:: python - - from collections import deque - deque(parallel_bulk(...), maxlen=0) - -.. note:: - - When reading raw json strings from a file, you can also pass them in - directly (without decoding to dicts first). In that case, however, you lose - the ability to specify anything (index, op_type and even id) on a per-record - basis, all documents will just be sent to elasticsearch to be indexed - as-is. - - -.. py:module:: elasticsearch.helpers - -.. autofunction:: streaming_bulk - -.. autofunction:: parallel_bulk - -.. autofunction:: bulk - - -Scan ----- - -.. autofunction:: scan - - -Reindex -------- - -.. autofunction:: reindex diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 70ab257d3..7c7b5d6fa 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -1,140 +1,22 @@ Python Elasticsearch Client =========================== -Official low-level client for Elasticsearch. Its goal is to provide common -ground for all Elasticsearch-related code in Python; because of this it tries -to be opinion-free and very extendable. - -`Download the latest version of Elasticsearch `_ -or -`sign-up `_ -for a free trial of Elastic Cloud. - - -Installation ------------- - -Install the ``elasticsearch`` package with `pip -`_: - -.. code-block:: console - - $ python -m pip install elasticsearch - -If your application uses async/await in Python you can install with -the ``async`` extra: - -.. code-block:: console - - $ python -m pip install elasticsearch[async] - -Read more about `how to use asyncio with this project `_. - - -Compatibility -------------- - -Language clients are forward compatible; meaning that the clients support -communicating with greater or equal minor versions of Elasticsearch without -breaking. It does not mean that the clients automatically support new features -of newer Elasticsearch versions; it is only possible after a release of a new -client version. For example, a 8.12 client version won't automatically support -the new features of the 8.13 version of Elasticsearch, the 8.13 client version -is required for that. Elasticsearch language clients are only backwards -compatible with default distributions and without guarantees made. - -+-----------------------+-------------------------+-----------+ -| Elasticsearch version | elasticsearch-py branch | Supported | -+=======================+=========================+===========+ -| main | main | | -+-----------------------+-------------------------+-----------+ -| 8.x | 8.x | 8.x | -+-----------------------+-------------------------+-----------+ -| 7.x | 7.x | 7.17 | -+-----------------------+-------------------------+-----------+ - -If you need multiple versions installed at the same time, versions are -also released, such as ``elasticsearch7`` and ``elasticsearch8``. - - -Example Usage -------------- - -.. code-block:: python - - from datetime import datetime - from elasticsearch import Elasticsearch - - client = Elasticsearch("http://localhost:9200/", api_key="YOUR_API_KEY") - - doc = { - "author": "kimchy", - "text": "Elasticsearch: cool. bonsai cool.", - "timestamp": datetime.now(), - } - resp = client.index(index="test-index", id=1, document=doc) - print(resp["result"]) - - resp = client.get(index="test-index", id=1) - print(resp["_source"]) - - client.indices.refresh(index="test-index") - - resp = client.search(index="test-index", query={"match_all": {}}) - print("Got {} hits:".format(resp["hits"]["total"]["value"])) - for hit in resp["hits"]["hits"]: - print("{timestamp} {author} {text}".format(**hit["_source"])) - -See more examples in the :ref:`quickstart` page. - - - -Features --------- - -This client was designed as very thin wrapper around Elasticsearch's REST API to -allow for maximum flexibility. This means that there are no opinions in this -client; it also means that some of the APIs are a little cumbersome to use from -Python. We have created some :ref:`helpers` to help with this issue as well as -a more high level library (`elasticsearch-dsl`_) on top of this one to provide -a more convenient way of working with Elasticsearch. - - - -Elasticsearch-DSL ------------------ - -For a more high level client library with more limited scope, have a look at -`elasticsearch-dsl`_ - a more pythonic library sitting on top of -``elasticsearch-py``. - -`elasticsearch-dsl`_ provides a more convenient and idiomatic way to write and manipulate -`queries`_ by mirroring the terminology and structure of Elasticsearch JSON DSL -while exposing the whole range of the DSL from Python -either directly using defined classes or a queryset-like expressions. - -It also provides an optional `persistence layer`_ for working with documents as -Python objects in an ORM-like fashion: defining mappings, retrieving and saving -documents, wrapping the document data in user-defined classes. - -.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/ -.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html -.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype - +.. toctree:: + :maxdepth: 2 -Contents --------- + es_api + dsl + api_helpers + exceptions .. toctree:: - :maxdepth: 3 + :caption: Async + :maxdepth: 2 + + async_es_api + async_dsl + async_api_helpers - quickstart - interactive - api - exceptions - async - helpers - Release Notes License ------- diff --git a/docs/sphinx/interactive.rst b/docs/sphinx/interactive.rst deleted file mode 100644 index 257d2aad1..000000000 --- a/docs/sphinx/interactive.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _interactive: - -Interactive examples -==================== - -The `elasticsearch-labs `_ repo contains interactive and executable `Python notebooks `_, sample apps, and resources for testing out Elasticsearch, using the Python client. -These examples are mainly focused on vector search, hybrid search and generative AI use cases, but you'll also find examples of basic operations like creating index mappings and performing lexical search. - -Search notebooks ----------------- - -The `Search `_ folder is a good place to start if you're new to Elasticsearch. -This folder contains a number of notebooks that demonstrate the fundamentals of Elasticsearch, like indexing vectors, running lexical, semantic and *hybrid* searches, and more. - -The following notebooks are available: - -0. `Quick start `_ -1. `Keyword, querying, filtering `_ -2. `Hybrid search `_ -3. `Semantic search with ELSER `_ -4. `Multilingual semantic search `_ -5. `Query rules `_ -6. `Synonyms API quick start `_ - -Here's a brief overview of what you'll learn in each notebook. - -Quick start -^^^^^^^^^^^ - -In the `00-quick-start.ipynb `_ notebook you'll learn how to: - -- Use the Elasticsearch Python client for various operations. -- Create and define an index for a sample dataset with ``dense_vector`` fields. -- Transform book titles into embeddings using `Sentence Transformers `_ and index them into Elasticsearch. -- Perform k-nearest neighbors (knn) semantic searches. -- Integrate traditional text-based search with semantic search, for a hybrid search system. -- Use reciprocal rank fusion (RRF) to intelligently combine search results from different retrieval systems. - -Keyword, querying, filtering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the `01-keyword-querying-filtering.ipynb `_ notebook, you'll learn how to: - -- Use `query and filter contexts `_ to search and filter documents in Elasticsearch. -- Execute full-text searches with ``match`` and ``multi-match`` queries. -- Query and filter documents based on ``text``, ``number``, ``date``, or ``boolean`` values. -- Run multi-field searches using the ``multi-match`` query. -- Prioritize specific fields in the ``multi-match`` query for tailored results. - -Hybrid search -^^^^^^^^^^^^^ - -In the `02-hybrid-search.ipynb `_ notebook, you'll learn how to: - -- Combine results of traditional text-based search with semantic search, for a hybrid search system. -- Transform fields in the sample dataset into embeddings using the Sentence Transformer model and index them into Elasticsearch. -- Use the `RRF API `_ to combine the results of a ``match`` query and a ``kNN`` semantic search. -- Walk through a super simple toy example that demonstrates, step by step, how RRF ranking works. - -Semantic search with ELSER -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the `03-ELSER.ipynb `_ notebook, you'll learn how to: - -- Use the Elastic Learned Sparse Encoder (ELSER) for text expansion-powered semantic search, out of the box — without training, fine-tuning, or embeddings generation. -- Download and deploy the ELSER model in your Elastic environment. -- Create an Elasticsearch index named `search-movies` with specific mappings and index a dataset of movie descriptions. -- Create an ingest pipeline containing an inference processor for ELSER model execution. -- Reindex the data from `search-movies` into another index, `elser-movies`, using the ELSER pipeline for text expansion. -- Observe the results of running the documents through the model by inspecting the additional terms it adds to documents, which enhance searchability. -- Perform simple keyword searches on the `elser-movies` index to assess the impact of ELSER's text expansion. -- Execute ELSER-powered semantic searches using the ``text_expansion`` query. - -Multilingual semantic search -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the `04-multilingual.ipynb `_ notebook, you'll learn how to: - -- Use a multilingual embedding model for semantic search across languages. -- Transform fields in the sample dataset into embeddings using the Sentence Transformer model and index them into Elasticsearch. -- Use filtering with a ``kNN`` semantic search. -- Walk through a super simple toy example that demonstrates, step by step, how multilingual search works across languages, and within non-English languages. - -Query rules -^^^^^^^^^^^ - -In the `05-query-rules.ipynb `_ notebook, you'll learn how to: - -- Use the query rules management APIs to create and edit promotional rules based on contextual queries. -- Apply these query rules by using the ``rule_query`` in Query DSL. - -Synonyms API quick start -^^^^^^^^^^^^^^^^^^^^^^^^ - -In the `06-synonyms-api.ipynb `_ notebook, you'll learn how to: - -- Use the synonyms management API to create a synonyms set to enhance your search recall. -- Configure an index to use search-time synonyms. -- Update synonyms in real time. -- Run queries that are enhanced by synonyms. - -Other notebooks ---------------- - -- `Generative AI `_. Notebooks that demonstrate various use cases for Elasticsearch as the retrieval engine and vector store for LLM-powered applications. -- `Integrations `_. Notebooks that demonstrate how to integrate popular services and projects with Elasticsearch, including OpenAI, Hugging Face, and LlamaIndex -- `Langchain `_. Notebooks that demonstrate how to integrate Elastic with LangChain, a framework for developing applications powered by language models. diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst deleted file mode 100644 index 563ea6f23..000000000 --- a/docs/sphinx/quickstart.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. _quickstart: - -Quickstart -========== - -This guide shows you how to install the Elasticsearch Python client and perform basic -operations like indexing or searching documents. - -Requirements ------------- - -- `Python `_ 3.8 or newer -- `pip `_ - - -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 - -Confirm that the connection was successful. - -.. code-block:: python - - print(client.info()) - -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. - -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 - - mappings = { - "properties": { - "foo": {"type": "text"}, - "bar": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256, - } - }, - }, - } - } - - client.indices.create(index="my_index", mappings=mappings) - -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", - }, - ) - -You can also index multiple documents at once with the bulk helper function: - -.. code-block:: python - - from elasticsearch import helpers - - 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 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 -^^^^^^^^^^^^^^^^^ - -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")