diff --git a/.doc/getting-started.asciidoc b/.doc/getting-started.asciidoc new file mode 100644 index 0000000000..b11a1e708b --- /dev/null +++ b/.doc/getting-started.asciidoc @@ -0,0 +1,228 @@ +[[getting-started-go]] +== Getting started + +This page guides you through the installation process of the Go client, shows +you how to instantiate the client, and how to perform basic Elasticsearch +operations with it. You can use the client with either a low-level API or a +fully typed API. This getting started shows you examples of both APIs. + +[discrete] +=== Requirements + +Go version 1.13+ + +[discrete] +=== Installation + +To install the latest version of the client, run the following command: + +[source,shell] +-------------------------- +go get github.com/elastic/go-elasticsearch/v8@latest +-------------------------- + +Refer to the <> page to learn more. + + +[discrete] +=== Connecting + +You can connect to the Elastic Cloud using an API key and the Elasticsearch +endpoint for the low level API: + +[source,go] +---- +client, err := elasticsearch.NewClient(elasticsearch.Config{ + CloudID: "", + APIKey: "", +}) +---- + +This is the same for the fully-typed API: + +[source,go] +---- +typedClient, err := elasticsearch.NewTypedClient(elasticsearch.Config{ + CloudID: "", + APIKey: "", +}) +---- + + +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 with the low level API: + +[source,go] +---- +client.Indices.Create("my_index") +---- + +This is how you create the `my_index` index with the fully-typed API: + +[source,go] +---- +typedClient.Indices.Create("my_index").Do(context.TODO()) +---- + + +[discrete] +==== Indexing documents + +This is a simple way of indexing a document by using the low-level API: + +[source,go] +---- +document := struct { + Name string `json:"name"` +}{ + "go-elasticsearch", +} +data, _ := json.Marshal(document) +client.Index("my_index", bytes.NewReader(data)) +---- + +The same operation by using the fully-typed API: + +[source,go] +---- +document := struct { + Name string `json:"name"` +}{ + "go-elasticsearch", +} +typedClient.Index("my_index"). + Id("1"). + Request(document). + Do(context.TODO()) +---- + +[discrete] +==== Getting documents + +You can get documents by using the following code with the low-level API: + +[source,go] +---- +client.Get("my_index", "id") +---- + +This is how you can get documents by using the fully-typed API: + +[source,go] +---- +typedClient.Get("my_index", "id").Do(context.TODO()) +---- + + +[discrete] +==== Searching documents + +This is how you can create a single match query with the low-level API: + +[source,go] +---- +query := `{ query: { match_all: {} } }` +client.Search( + client.Search.WithIndex("my_index"), + client.Search.WithBody(strings.NewReader(query)), +) +---- + +You can perform a single match query with the fully-typed API, too: + +[source,go] +---- +typedClient.Search(). + Index("my_index"). + Request(&search.Request{ + Query: &types.Query{MatchAll: &types.MatchAllQuery{}}, + }). + Do(context.TODO()) +---- + + +[discrete] +==== Updating documents + +This is how you can update a document, for example to add a new field, by using +the low-level API: + +[source,go] +---- +client.Update("my_index", "id", strings.NewReader(`{doc: { language: "Go" }}`)) +---- + +And this is how you can update a document with the fully-typed API: + +[source,go] +---- +typedClient.Update("my_index", "id"). + Request(&update.Request{ + Doc: json.RawMessage(`{ language: "Go" }`), + }).Do(context.TODO()) +---- + + +[discrete] +==== Deleting documents + +Low-level API: + +[source,go] +---- +client.Delete("my_index", "id") +---- + +Fully-typed API: + +[source,go] +---- +typedClient.Delete("my_index", "id").Do(context.TODO()) +---- + + +[discrete] +==== Deleting an index + +Low-level API: + +[source,go] +---- +client.Indices.Delete([]string{"my_index"}) +---- + +Fully-typed API: + +[source,go] +---- +typedClient.Indices.Delete("my_index").Do(context.TODO()) +---- + + +[discrete] +== Further reading + +* Learn more about the <>, a strongly typed Golang API +for {es}. \ No newline at end of file diff --git a/.doc/images/create-api-key.png b/.doc/images/create-api-key.png new file mode 100644 index 0000000000..d75c230300 Binary files /dev/null and b/.doc/images/create-api-key.png differ diff --git a/.doc/images/es-endpoint.jpg b/.doc/images/es-endpoint.jpg new file mode 100644 index 0000000000..6da2e75659 Binary files /dev/null and b/.doc/images/es-endpoint.jpg differ diff --git a/.doc/index.asciidoc b/.doc/index.asciidoc index e60b1a5714..aad855fb9c 100644 --- a/.doc/index.asciidoc +++ b/.doc/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[] diff --git a/.doc/typedapi.asciidoc b/.doc/typedapi.asciidoc deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/.doc/typedapi/index.asciidoc b/.doc/typedapi/index.asciidoc index fdc327a54e..1fc98afe5f 100644 --- a/.doc/typedapi/index.asciidoc +++ b/.doc/typedapi/index.asciidoc @@ -1,20 +1,26 @@ [[typedapi]] == Typed API -The goal for this API is to provide a strongly typed, fluent-like Golang API for {es}. +The goal for this API is to provide a strongly typed Golang API for +{es}. -This was designed with structures and the Golang runtime in mind, following as closely as possible the API and its objects. +This was designed with structures and the Golang runtime in mind, following as +closely as possible the API and its objects. + +The first version focuses on the requests and does not yet include NDJSON +endpoints such as `bulk` or `msearch`. These will be added later on along with +typed responses and error handling. -The first version focuses on the requests and does not yet include NDJSON endpoints such as `bulk` or `msearch`. -These will be added later on along with typed responses and error handling. [getting-started] -=== Getting started +=== Getting started with the API -The new typed client can be obtained from the `elasticsearch` package using the `NewTypedClient` function. -This new API takes the same arguments as the previous one and uses the same transport underneath. +The new typed client can be obtained from the `elasticsearch` package using the +`NewTypedClient` function. This new API takes the same arguments as the previous +one and uses the same transport underneath. -Connection to an {es} cluster is identical to the existing client, only the API changes: +Connection to an {es} cluster is identical to the existing client, only the API +changes: [source,go] ----- @@ -23,7 +29,8 @@ client, err := elasticsearch.NewTypedClient(elasticsearch.Config{ }) ----- -The code is generated from the https://github.com/elastic/elasticsearch-specification[elasticsearch-specification]. +The code is generated from the +https://github.com/elastic/elasticsearch-specification[elasticsearch-specification]. include::conventions/index.asciidoc[] include::queries.asciidoc[]