﻿---
title: Getting started
description: This page guides you through the installation process of the Python client, shows you how to instantiate the client, and how to perform basic Elasticsearch...
url: https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/getting-started
---

# Getting started
This page guides you through the installation process of the Python client, shows you how to instantiate the client, and how to perform basic Elasticsearch operations with it.

### Requirements

- [Python](https://www.python.org/) 3.10 or newer
- [`pip`](https://pip.pypa.io/en/stable/), installed by default alongside Python


### Installation

To install the latest version of the client, run the following command:
```shell
python -m pip install elasticsearch
```

Refer to the [*Installation*](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/installation) page to learn more.

### Connecting

You can connect to the Elastic Cloud using an API key and the Elasticsearch endpoint.
```py
from elasticsearch import Elasticsearch

client = Elasticsearch(
    "https://...", 
    api_key="api_key",
)
```

Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment:
![Finding Elasticsearch endpoint](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/images/es-endpoint.jpg)
You can generate an API key on the **Management** page under Security.
![Create API key](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/images/create-api-key.png)
For other connection options, refer to the [*Connecting*](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/connecting) section.

### Operations

Time to use Elasticsearch! This section walks you through the basic, and most important, operations of Elasticsearch. For more operations and more advanced examples, refer to the [*Examples*](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/examples) page.

#### Creating an index

This is how you create the `my_index` index:
```py
client.indices.create(index="my_index")
```

Optionally, you can first define the expected types of your features with a custom mapping.
```py
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:
```py
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:
```py
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 [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/client-helpers) page for more details.

#### Getting documents

You can get documents by using the following code:
```py
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:
```py
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:
```py
client.update(
    index="my_index",
    id="my_document_id",
    doc={
        "foo": "bar",
        "new_field": "new value",
    }
)
```


#### Deleting documents

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


#### Deleting an index

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


## Further reading

- Use [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/2423/reference/elasticsearch/clients/python/client-helpers) for a more comfortable experience with the APIs.