[[connecting]]
== Connecting

This page contains the information you need to connect and use the Client with 
{es}.

**On this page**

* <<authentication>>
* <<client-usage, Using the client>>

[discrete]
[[authentication]]
=== Authentication

This section contains code snippets to show you how to connect to various {es} 
providers.


[discrete]
[[auth-ec]]
==== Elastic Cloud

Cloud ID is an easy way to configure your client to work with your Elastic Cloud 
deployment. Combine the `cloud_id` with either `http_auth` or `api_key` to 
authenticate with your Elastic Cloud deployment.

Using `cloud_id` enables TLS verification and HTTP compression by default and 
sets the port to 443 unless otherwise overwritten via the port parameter or the 
port value encoded within `cloud_id`. Using Cloud ID also disables sniffing.

[source,py]
----------------------------
from elasticsearch import Elasticsearch

es = Elasticsearch(
    cloud_id=”cluster-1:dXMa5Fx...”
)
----------------------------


[discrete]
[[auth-http]]
==== HTTP Authentication

HTTP authentication uses the `http_auth` parameter by passing in a username and 
password within a tuple:

[source,py]
----------------------------
from elasticsearch import Elasticsearch

es = Elasticsearch(
    http_auth=(“username”, “password”)
)
----------------------------


[discrete]
[[auth-apikey]]
==== ApiKey authentication

You can configure the client to use {es}'s API Key for connecting to your 
cluster.

[source,py]
----------------------------
from elasticsearch import Elasticsearch

es = Elasticsearch(
    api_key=(“api_key_id”, “api_key_secret”)
)
----------------------------


[discrete]
[[client-usage]]
=== Usage

This section is a brief overview of the client and its syntax.


[discrete]
==== Indexing a document
  
To index a document, you need to specify four pieces of information: `index`, 
`id`, and a `body`:

[source,py]
----------------------------
from datetime import datetime
from elasticsearch import Elasticsearch
es = Elasticsearch()

doc = {
    'author': 'author_name',
    'text': 'Interensting content...',
    'timestamp': datetime.now(),
}
res = es.index(index="test-index", id=1, body=doc)
print(res['result'])
----------------------------


[discrete]
==== Getting a document 

To get a document, you need to specify its `index` and `id`:

[source,py]
----------------------------
res = es.get(index="test-index", id=1)
print(res['_source'])
----------------------------


[discrete]
==== Refreshing an index

You can perform the refresh operation on an index:

[source,py]
----------------------------
es.indices.refresh(index="test-index")
----------------------------


[discrete]
==== Searching for a document

The `search()` method returns results that are matching a query:

[source,py]
----------------------------
res = es.search(index="test-index", body={"query": {"match_all": {}}})
print("Got %d Hits:" % res['hits']['total']['value'])
for hit in res['hits']['hits']:
    print("%(timestamp)s %(author)s: %(text)s" % hit["_source"])
----------------------------


[discrete]
==== Deleting a document

You can delete a document by specifying its `index`, and `id` in the `delete()` 
method:

----------------------------
es.delete(index="test-index", id=1)
----------------------------