diff --git a/docs/guide/getting-started.asciidoc b/docs/guide/getting-started.asciidoc new file mode 100644 index 000000000..4fd275aa0 --- /dev/null +++ b/docs/guide/getting-started.asciidoc @@ -0,0 +1,153 @@ +[[getting-started-python]] +== 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. + +[discrete] +=== Requirements + +* https://www.python.org/[Python] 3.6 or newer +* https://pip.pypa.io/en/stable/[`pip`], installed by default alongside Python + +[discrete] +=== Installation + +To install the latest version of the client, run the following command: + +[source,shell] +-------------------------- +python -m pip install elasticsearch +-------------------------- + +Refer to the <> page to learn more. + + +[discrete] +=== Connecting + +You can connect to the Elastic Cloud using an API key and the Elasticsearch +endpoint. + +[source,py] +---- +from elasticsearch import Elasticsearch + +client = Elasticsearch( + "https://...", # Elasticsearch endpoint + api_key=('api-key-id', 'api-key-secret'), # API key ID and secret +) +---- + +Your Elasticsearch endpoint can be found on the **My deployment** page of your +deployment: + +image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"] + +You can generate an API key on the **Management** page under Security. + +image::images/create-api-key.png[alt="Create API key",align="center"] + +For other connection options, refer to the <> section. + + +[discrete] +=== 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 <> page. + + +[discrete] +==== Creating an index + +This is how you create the `my_index` index: + +[source,py] +---- +client.indices.create(index="my_index") +---- + + +[discrete] +==== Indexing documents + +This is a simple way of indexing a document: + +[source,py] +---- +client.index( + index="my_index", + id="my_document_id", + document={ + "foo": "foo", + "bar": "bar", + } +) +---- + + +[discrete] +==== Getting documents + +You can get documents by using the following code: + +[source,py] +---- +client.get(index="my_index", id="my_document_id") +---- + + +[discrete] +==== Searching documents + +This is how you can create a single match query with the Python client: + +[source,py] +---- +client.search(index="my_index", query={ + "match": { + "foo": "foo" + } +}) +---- + + +[discrete] +==== Updating documents + +This is how you can update a document, for example to add a new field: + +[source,py] +---- +client.update(index="my_index", id="my_document_id", doc={ + "foo": "bar", + "new_field": "new value", +}) +---- + + +[discrete] +==== Deleting documents + +[source,py] +---- +client.delete(index="my_index", id="my_document_id") +---- + + +[discrete] +==== Deleting an index + +[source,py] +---- +client.indices.delete(index="my_index") +---- + + +[discrete] +== Further reading + +* Use <> for a more comfortable experience with the APIs. diff --git a/docs/guide/images/create-api-key.png b/docs/guide/images/create-api-key.png new file mode 100644 index 000000000..d75c23030 Binary files /dev/null and b/docs/guide/images/create-api-key.png differ diff --git a/docs/guide/images/es-endpoint.jpg b/docs/guide/images/es-endpoint.jpg new file mode 100644 index 000000000..6da2e7565 Binary files /dev/null and b/docs/guide/images/es-endpoint.jpg differ diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc index 85f6eab6e..d2ae4ab63 100644 --- a/docs/guide/index.asciidoc +++ b/docs/guide/index.asciidoc @@ -8,6 +8,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] include::overview.asciidoc[] +include::getting-started.asciidoc[] + include::installation.asciidoc[] include::connecting.asciidoc[]