diff --git a/serverless/index-serverless-elasticsearch.asciidoc b/serverless/index-serverless-elasticsearch.asciidoc index bdeae99f0d..c139a65dcd 100644 --- a/serverless/index-serverless-elasticsearch.asciidoc +++ b/serverless/index-serverless-elasticsearch.asciidoc @@ -11,13 +11,6 @@ include::./pages/get-started.asciidoc[leveloffset=+2] include::./pages/connecting-to-es-endpoint.asciidoc[leveloffset=+2] include::./pages/clients.asciidoc[leveloffset=+2] -include::./pages/clients-go-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-java-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-dot-net-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-nodejs-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-php-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-python-getting-started.asciidoc[leveloffset=+3] -include::./pages/clients-ruby-getting-started.asciidoc[leveloffset=+3] include::./pages/apis-http-apis.asciidoc[leveloffset=+2] include::./pages/apis-elasticsearch-conventions.asciidoc[leveloffset=+3] diff --git a/serverless/pages/clients-dot-net-getting-started.asciidoc b/serverless/pages/clients-dot-net-getting-started.asciidoc deleted file mode 100644 index 1f9ab78819..0000000000 --- a/serverless/pages/clients-dot-net-getting-started.asciidoc +++ /dev/null @@ -1,147 +0,0 @@ -[[elasticsearch-dot-net-client-getting-started]] -= Get started with the serverless .NET client - -// :description: Set up and use the .NET client for {es3}. -// :keywords: serverless, elasticsearch, .net, how to - -[NOTE] -==== -This client is for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. -==== - -This page guides you through the installation process of the -.NET client for {es3}, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -[discrete] -[[elasticsearch-dot-net-client-getting-started-requirements]] -== Requirements - -* .NET Core, .NET 5+ or .NET Framework (4.6.1 and higher). - -[discrete] -[[elasticsearch-dot-net-client-getting-started-installation]] -== Installation - -You can install the .NET client with the following command: - -[source,bash] ----- -dotnet add package Elastic.Clients.Elasticsearch.Serverless ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,net] ----- -var client = new ElasticsearchClient("", new ApiKey("")); ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-dot-net-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can create an index and start ingesting -documents. - -[discrete] -[[elasticsearch-dot-net-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -The following is an example of creating a `my_index` index: - -[source,net] ----- -var response = await client.Indices.CreateAsync("my_index"); ----- - -This is a simple way of indexing a document into `my_index`: - -[source,net] ----- -var doc = new MyDoc -{ - Id = 1, - User = "xyz_user", - Message = "Trying out the client, so far so good?" -}; - -var response = await client.IndexAsync(doc, "my_index"); ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,net] ----- -var response = await client.GetAsync(id, idx => idx.Index("my_index")); - -if (response.IsValidResponse) -{ - var doc = response.Source; -} ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-searching]] -=== Searching - -This is how you can create a single match query with the .NET client: - -[source,net] ----- -var response = await client.SearchAsync(s => s - .Index("my_index") - .From(0) - .Size(10) - .Query(q => q - .Term(t => t.User, "flobernd") - ) -); - -if (response.IsValidResponse) -{ - var doc = response.Documents.FirstOrDefault(); -} ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-updating-a-document]] -=== Updating a document - -This is how you can update a document, for example to add a new field: - -[source,net] ----- -doc.Message = "This is a new message"; - -var response = await client.UpdateAsync("my_index", 1, u => u - .Doc(doc)); ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-deleting-a-document]] -=== Deleting a document - -[source,net] ----- -var response = await client.DeleteAsync("my_index", 1); ----- - -[discrete] -[[elasticsearch-dot-net-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,net] ----- -var response = await client.Indices.DeleteAsync("my_index"); ----- diff --git a/serverless/pages/clients-go-getting-started.asciidoc b/serverless/pages/clients-go-getting-started.asciidoc deleted file mode 100644 index 60764b332c..0000000000 --- a/serverless/pages/clients-go-getting-started.asciidoc +++ /dev/null @@ -1,239 +0,0 @@ -[[elasticsearch-go-client-getting-started]] -= Get started with the serverless Go client - -// :description: Set up and use the Go client for {es3}. -// :keywords: serverless, elasticsearch, go, how to - -[NOTE] -==== -This client is for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. -==== - -This page guides you through the installation process of the Go -client for {es3}, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -[discrete] -[[elasticsearch-go-client-getting-started-requirements]] -== Requirements - -* Go 1.20 or higher installed on your system. - -[discrete] -[[elasticsearch-go-client-getting-started-installation]] -== Installation - -[discrete] -[[elasticsearch-go-client-getting-started-using-the-command-line]] -=== Using the command line - -You can install the Go client with the following -commands: - -[source,bash] ----- -go get -u github.com/elastic/elasticsearch-serverless-go@latest ----- - -[discrete] -[[elasticsearch-go-client-getting-started-imports]] -== Imports - -The following snippets use these imports: - -[source,go] ----- -import ( - "context" - "encoding/json" - "fmt" - "log" - "strconv" - - "github.com/elastic/elasticsearch-serverless-go" - "github.com/elastic/elasticsearch-serverless-go/typedapi/types" - "github.com/elastic/elasticsearch-serverless-go/typedapi/types/enums/result" -) ----- - -[discrete] -[[elasticsearch-go-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,go] ----- -client, err := elasticsearch.NewClient(elasticsearch.Config{ - APIKey: "you_api_key", - Address: "https://my-project-url", -}) -if err != nil { - log.Fatal(err) -} ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-go-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can start ingesting documents. You can -use the `bulk` API for this. This API enables you to index, update, and delete -several documents in one request. - -[discrete] -[[elasticsearch-go-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -You can call the `bulk` API with a body parameter, an array of hashes that -define the action, and a document. - -The following is an example of indexing some classic books into the `books` -index: - -[source,go] ----- -type Book struct { - Name string `json:"name"` - Author string `json:"author"` - ReleaseDate string `json:"release_date"` - PageCount int `json:"page_count"` -} - -books := []Book{ - {Name: "Snow Crash", Author: "Neal Stephenson", ReleaseDate: "1992-06-01", PageCount: 470}, - {Name: "Revelation Space", Author: "Alastair Reynolds", ReleaseDate: "2000-03-15", PageCount: 585}, - {Name: "1984", Author: "George Orwell", ReleaseDate: "1949-06-08", PageCount: 328}, - {Name: "Fahrenheit 451", Author: "Ray Bradbury", ReleaseDate: "1953-10-15", PageCount: 227}, - {Name: "Brave New World", Author: "Aldous Huxley", ReleaseDate: "1932-06-01", PageCount: 268}, - {Name: "The Handmaid's Tale", Author: "Margaret Atwood", ReleaseDate: "1985-06-01", PageCount: 311}, -} -indexName := "books" - -bulk := client.Bulk() -for i, book := range books { - id := strconv.Itoa(i) - err := bulk.CreateOp(types.CreateOperation{Index_: &indexName, Id_: &id}, book) - if err != nil { - log.Fatal(err) - } -} -bulkRes, err := bulk.Do(context.TODO()) -if err != nil { - log.Fatal(err) -} - -fmt.Printf("Bulk: %#v\n", bulkRes.Items) ----- - -When you use the client to make a request to {es-serverless}, it returns an API -response object. You can access the body values directly as seen on -the previous example with `bulkRes`. - -[discrete] -[[elasticsearch-go-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,go] ----- -getRes, err := client.Get(indexName, "5").Do(context.TODO()) -if err != nil { - log.Fatal(err) -} -book := Book{} -if err := json.Unmarshal(getRes.Source_, &book); err != nil { - log.Fatal(err) -} -fmt.Printf("Get book: %#v\n", book) ----- - -[discrete] -[[elasticsearch-go-client-getting-started-searching]] -=== Searching - -Now that some data is available, you can search your documents using the -`search` API: - -[source,go] ----- -searchRes, err := client.Search(). - Index("books"). - Q("snow"). - Do(context.TODO()) -if err != nil { - log.Fatal(err) -} - -bookSearch := []Book{} -for _, hit := range searchRes.Hits.Hits { - book := Book{} - if err := json.Unmarshal(hit.Source_, &book); err != nil { - log.Fatal(err) - } - bookSearch = append(bookSearch, book) -} -fmt.Printf("Search books: %#v\n", bookSearch) ----- - -[discrete] -[[elasticsearch-go-client-getting-started-updating-a-document]] -=== Updating a document - -You can call the `Update` API to update a document, in this example updating the -`page_count` for "The Handmaid's Tale" with id "5": - -[source,go] ----- -updateRes, err := client.Update("books", "5"). - Doc( - struct { - PageCount int `json:"page_count"` - }{PageCount: 312}, - ). - Do(context.TODO()) -if err != nil { - log.Fatal(err) -} - -if updateRes.Result == result.Updated { - fmt.Printf("Update book: %#v\n", updateRes) -} ----- - -[discrete] -[[elasticsearch-go-client-getting-started-deleting-a-document]] -=== Deleting a document - -You can call the `Delete` API to delete a document: - -[source,go] ----- -deleteRes, err := client.Delete("books", "5").Do(context.TODO()) -if err != nil { - log.Fatal(err) -} - -if deleteRes.Result == result.Deleted { - fmt.Printf("Delete book: %#v\n", deleteRes) -} ----- - -[discrete] -[[elasticsearch-go-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,go] ----- -indexDeleteRes, err := client.Indices.Delete("books").Do(context.TODO()) -if err != nil { - log.Fatal(err) -} - -if indexDeleteRes.Acknowledged { - fmt.Printf("Delete index: %#v\n", indexDeleteRes) -} ----- diff --git a/serverless/pages/clients-java-getting-started.asciidoc b/serverless/pages/clients-java-getting-started.asciidoc deleted file mode 100644 index b3e8dcdf65..0000000000 --- a/serverless/pages/clients-java-getting-started.asciidoc +++ /dev/null @@ -1,202 +0,0 @@ -[[elasticsearch-java-client-getting-started]] -= Get started with the Java client - -// :description: Set up and use the Java client for {es3}. -// :keywords: serverless, elasticsearch, java, how to - -This page guides you through the installation process of the Java -client, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -See the https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/index.html[Java client] documentation for more detailed usage instructions. - -[NOTE] -==== -The same client is used for {es3}, on-premise and managed Elasticsearch. Some API endpoints are however not available in {es3}. -==== - -[discrete] -[[elasticsearch-java-client-getting-started-requirements]] -== Requirements - -* Java 8 or later. -* A JSON object mapping library to allow seamless integration of -your application classes with the {es} API. The examples below -show usage with Jackson. - -[discrete] -[[elasticsearch-java-client-getting-started-installation]] -== Installation - -You can add the Java client to your Java project using -either Gradle or Maven. - -Use the version with the highest version number found on https://search.maven.org/artifact/co.elastic.clients/elasticsearch-java[Maven Central], like `8.16.1`. We refer to it as `elasticVersion` in the configuration examples below. - -[discrete] -[[elasticsearch-java-client-getting-started-using-gradle]] -=== Using Gradle - -You can install the Java client as a Gradle dependency: - -[source,groovy] ----- -dependencies { - implementation "co.elastic.clients:elasticsearch-java:${elasticVersion}" - implementation "com.fasterxml.jackson.core:jackson-databind:2.17.0" -} ----- - -[discrete] -[[elasticsearch-java-client-getting-started-using-maven]] -=== Using Maven - -You can install the Java client as a Maven dependency, add -the following to the `pom.xml` of your project: - -[source,xml] ----- - - - - - co.elastic.clients - elasticsearch-java - ${elasticVersion} - - - - com.fasterxml.jackson.core - jackson-databind - 2.17.0 - - - - ----- - -[discrete] -[[elasticsearch-java-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,java] ----- -// URL and API key -String serverUrl = "https://...elastic.cloud"; -String apiKey = "VnVhQ2ZHY0JDZGJrU..."; - -// Create the low-level client -RestClient restClient = RestClient - .builder(HttpHost.create(serverUrl)) - .setDefaultHeaders(new Header[]{ - new BasicHeader("Authorization", "ApiKey " + apiKey) - }) - .build(); - -// Create the transport with a Jackson mapper -ElasticsearchTransport transport = new RestClientTransport( - restClient, new JacksonJsonpMapper()); - -// And create the API client -ElasticsearchClient esClient = new ElasticsearchClient(transport); ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-java-client-getting-started-using-the-api]] -== Using the API - -After you initialized the client, you can start ingesting documents. - -[discrete] -[[elasticsearch-java-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -The following is an example of indexing a document, here a `Product` application -object in the `products` index: - -[source,java] ----- -Product product = new Product("bk-1", "City bike", 123.0); - -IndexResponse response = esClient.index(i -> i - .index("products") - .id(product.getSku()) - .document(product) -); - -logger.info("Indexed with version " + response.version()); ----- - -[discrete] -[[elasticsearch-java-client-getting-started-searching]] -=== Searching - -Now that some data is available, you can search your documents using the -`search` API: - -[source,java] ----- -String searchText = "bike"; - -SearchResponse response = esClient.search(s -> s - .index("products") - .query(q -> q - .match(t -> t - .field("name") - .query(searchText) - ) - ), - Product.class -); ----- - -A few things to note in the above example: - -* The search query is built using a hierarchy of lambda expressions that closely -follows the {es} HTTP API. Lambda expressions allows you to be guided -by your IDE's autocompletion, without having to import (or even know!) the -actual classes representing a query. -* The last parameter `Product.class` instructs the client to return results as -`Product` application objects instead of raw JSON. - -[discrete] -[[elasticsearch-java-client-getting-started-updating]] -=== Updating - -You can update your documents using the `update` API: - -[source,java] ----- -Product product = new Product("bk-1", "City bike", 123.0); - -esClient.update(u -> u - .index("products") - .id("bk-1") - .upsert(product), - Product.class -); ----- - -[discrete] -[[elasticsearch-java-client-getting-started-delete]] -=== Delete - -You can also delete documents: - -[source,java] ----- -esClient.delete(d -> d.index("products").id("bk-1")); ----- - -[discrete] -[[elasticsearch-java-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,java] ----- -esClient.indices().delete(d -> d.index("products")); ----- diff --git a/serverless/pages/clients-nodejs-getting-started.asciidoc b/serverless/pages/clients-nodejs-getting-started.asciidoc deleted file mode 100644 index d4c57d03c4..0000000000 --- a/serverless/pages/clients-nodejs-getting-started.asciidoc +++ /dev/null @@ -1,180 +0,0 @@ -[[elasticsearch-nodejs-client-getting-started]] -= Get started with the serverless Node.js client - -// :description: Set up and use the Node.js client for {es3}. -// :keywords: serverless, elasticsearch, nodejs, how to - -[NOTE] -==== -This client is for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. -==== - -This page guides you through the installation process of the Node.js -client for {es3}, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -[discrete] -[[elasticsearch-nodejs-client-getting-started-requirements]] -== Requirements - -* Node.js 16 or higher installed on your system. - -[discrete] -[[elasticsearch-nodejs-client-getting-started-installation]] -== Installation - -[discrete] -[[elasticsearch-nodejs-client-getting-started-using-the-command-line]] -=== Using the command line - -You can install the Node.js client with the following -commands: - -[source,bash] ----- -npm install @elastic/elasticsearch-serverless ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch-serverless') -const client = new Client({ - node: 'https://', // serverless project URL - auth: { apiKey: 'your_api_key' }, // project API key -}) ----- - -To get API keys for the URL for a project, see <>. - -[discrete] -[[elasticsearch-nodejs-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can start ingesting documents. -You can use the `bulk` API for this. -This API enables you to index, update, and delete several documents in one request. - -[discrete] -[[elasticsearch-nodejs-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -You can call the `bulk` helper API with a list of documents and a handler for -what action to perform on each document. - -The following is an example of bulk indexing some classic books into the `books` -index: - -[source,js] ----- -// First we build our data: -const body = [ - {name: "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470}, - {name: "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585}, - {name: "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328}, - {name: "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227}, - {name: "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268}, - {name: "The Handmaid's Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311} -] - -// Then we send the data using the bulk API helper: -const result = await client.helpers.bulk({ - datasource: body, - onDocument (doc) { - // instructs the bulk indexer to add each item in `body` to the books index - // you can optionally inspect each `doc` object to alter what action is performed per document - return { - index: { _index: 'books' } - } - } -}) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,js] ----- -await client.get({ - index: 'books', - id: 'a_document_id', -}) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-searching]] -=== Searching - -Now that some data is available, you can search your documents using the `search` API: - -[source,js] ----- -const result = await client.search({ - index: 'books', - query: { - match: { - author: 'ray bradbury' - } - } -}) -console.log(result.hits.hits) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-updating-a-document]] -=== Updating a document - -You can call the `update` API to update a document: - -[source,js] ----- -await client.update({ - index: 'books', - id: 'a_document_id', - doc: { - author: 'S.E. Hinton', - new_field: 'new value' - } -}) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-deleting-a-document]] -=== Deleting a document - -You can call the `delete` API to delete a document: - -[source,js] ----- -await client.delete({ - index: 'books', - id: 'a_document_id', -}) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,js] ----- -await client.indices.delete({ index: 'books' }) ----- - -[discrete] -[[elasticsearch-nodejs-client-getting-started-typescript]] -== TypeScript - -The Node.js client is implemented in TypeScript. IDEs that support -TypeScript-based autocompletion should automatically find and load the -appropriate declaration files in the package's `lib` directory. -The source TypeScript can also be -https://github.com/elastic/elasticsearch-serverless-js/tree/main/src[viewed on GitHub]. diff --git a/serverless/pages/clients-php-getting-started.asciidoc b/serverless/pages/clients-php-getting-started.asciidoc deleted file mode 100644 index 87522d283f..0000000000 --- a/serverless/pages/clients-php-getting-started.asciidoc +++ /dev/null @@ -1,215 +0,0 @@ -[[elasticsearch-php-client-getting-started]] -= Get started with the serverless PHP client - -// :description: Set up and use the PHP client for {es3}. -// :keywords: serverless, elasticsearch, php, how to - -[NOTE] -==== -This client is for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. -==== - -This page guides you through the installation process of the -PHP client for {es3}, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -[discrete] -[[elasticsearch-php-client-getting-started-requirements]] -== Requirements - -* PHP 8.0 or higher installed on your system. - -[discrete] -[[elasticsearch-php-client-getting-started-installation]] -== Installation - -[discrete] -[[elasticsearch-php-client-getting-started-using-the-command-line]] -=== Using the command line - -You can install the PHP client using -https://getcomposer.org/[composer] with the following commands: - -[source,bash] ----- -composer require elastic/elasticsearch-serverless ----- - -[discrete] -[[elasticsearch-php-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,php] ----- -require 'vendor/autoload.php'; - -use Elastic\Elasticsearch\Serverless\ClientBuilder; - -$client = ClientBuilder::create() - ->setEndpoint('') - ->setApiKey('') - ->build(); ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-php-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can start ingesting documents. You can -use the `bulk` API for this. This API enables you to index, update, and delete -several documents in one request. - -[discrete] -[[elasticsearch-php-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -You can call the `bulk` API with a body parameter, an array of actions (index) -and documents. - -The following is an example of indexing some classic books into the `books` -index: - -[source,php] ----- -$body = [ - [ "index" => [ "_index" => "books" ]], - [ "name" => "Snow Crash", "author" => "Neal Stephenson", "release_date" => "1992-06-01", "page_count" => 470], - [ "index" => [ "_index" => "books" ]], - [ "name" => "Revelation Space", "author" => "Alastair Reynolds", "release_date" => "2000-03-15", "page_count" => 585], - [ "index" => [ "_index" => "books" ]], - [ "name" => "1984", "author" => "George Orwell", "release_date" => "1949-06-08", "page_count" => 328], - [ "index" => [ "_index" => "books" ]], - [ "name" => "Fahrenheit 451", "author" => "Ray Bradbury", "release_date" => "1953-10-15", "page_count" => 227], - [ "index" => [ "_index" => "books" ]], - [ "name" => "Brave New World", "author" => "Aldous Huxley", "release_date" => "1932-06-01", "page_count" => 268], - [ "index" => [ "_index" => "books" ]], - [ "name" => "The Handmaid's Tale", "author" => "Margaret Atwood", "release_date" => "1985-06-01", "page_count" => 311] -]; - -$response = $client->bulk(body: $body); -# You can check the response if the items are indexed and have an ID -print_r($response['items']); ----- - -When you use the client to make a request to {es}, it returns an API response -object. This object implements the https://www.php-fig.org/psr/psr-7/[PSR-7] -interface, that means you can check the for the HTTP status using the following -method: - -[source,php] ----- -print($response->getStatusCode()); ----- - -or get the HTTP response headers using the following: - -[source,php] ----- -print_r($response->getHeaders()); ----- - -or reading the HTTP response body as follows: - -[source,php] ----- -print($response->getBody()->getContents()); -# or using the asString() dedicated method -print($response->asString()); ----- - -The response body can be accessed as associative array or as object. - -[source,php] ----- -var_dump($response['items']); # associative array -var_dump($response->items); # object ----- - -There are also methods to render the response as array, object, string and -boolean values. - -[source,php] ----- -var_dump($response->asArray()); // response body content as array -var_dump($response->asObject()); // response body content as object -var_dump($response->asString()); // response body as string (JSON) -var_dump($response->asBool()); // true if HTTP response code between 200 and 300 ----- - -[discrete] -[[elasticsearch-php-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,php] ----- -$response = $client->get(index: "books", id: $id); ----- - -[discrete] -[[elasticsearch-php-client-getting-started-searching]] -=== Searching - -You can search your documents using the `search` API: - -[source,php] ----- -# Search for all the books written by Ray Bradbury -$query = [ 'query' => [ 'match' => [ 'author' => 'Ray Bradbury' ]]]; -$response = $client->search(index: "books", body: $query); - -printf("Documents found: %d\n", $response['hits']['total']['value']); # total documents found -print_r($response['hits']['hits']); # list of books ----- - -For more information about the `search` API's query parameters and the response type, -refer to the -https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-search[Search API] -docs. - -[discrete] -[[elasticsearch-php-client-getting-started-updating-documents]] -=== Updating documents - -You can call the `update` API to update a document: - -[source,php] ----- -$id = ''; -# update the "page_count" value to 300 -$body = [ "doc" => [ "page_count" => 300 ]]; -$response = $client->update(index: "books", id: $id, body: $body); -printf("Operation result: %s\n", $response['result']); # You get 'updated' as a result. ----- - -[discrete] -[[elasticsearch-php-client-getting-started-deleting-documents]] -=== Deleting documents - -You can call the `delete` API to delete a document: - -[source,php] ----- -$id = ''; -$response = $client->delete(index: "books", id: $id); -printf("Operation result: %s\n", $response['result']); # You get "deleted" a as result. ----- - -[discrete] -[[elasticsearch-php-client-getting-started-deleting-an-index]] -=== Deleting an index - -You can delete an entire index as follows: - -[source,php] ----- -$response = $client->indices()->delete(index: "books"); -if ($response['acknowledged']) { - print("Index successfully removed!"); -} ----- diff --git a/serverless/pages/clients-python-getting-started.asciidoc b/serverless/pages/clients-python-getting-started.asciidoc deleted file mode 100644 index 803ce00403..0000000000 --- a/serverless/pages/clients-python-getting-started.asciidoc +++ /dev/null @@ -1,164 +0,0 @@ -[[elasticsearch-python-client-getting-started]] -= Get started with the Elasticsearch Python client - -// :description: Set up and use the Python client for {es3}. -// :keywords: serverless, elasticsearch, python, how to - -This page guides you through the installation process of the Python -client, shows you how to initialize the client, and how to perform basic -{es} operations with it. - -See the -https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html[Python -client] documentation for more detailed usage instructions. - -[NOTE] -==== -The same client is used for {es3}, on-premise and managed Elasticsearch. Some API endpoints are however not available in {es3}. -==== - -[discrete] -[[elasticsearch-python-client-getting-started-requirements]] -== Requirements - -* Python 3.9 or higher -* https://pip.pypa.io/en/stable/[`pip`] - -[discrete] -[[elasticsearch-python-client-getting-started-documentation]] -== Documentation - -Find the full documentation for the Python client on https://elasticsearch-serverless-python.readthedocs.io/en/latest/[readthedocs]. - -[discrete] -[[elasticsearch-python-client-getting-started-installation]] -== Installation - -[discrete] -[[elasticsearch-python-client-getting-started-using-the-command-line]] -=== Using the command line - -You can install the Python client with the following -commands: - -[source,bash] ----- -python -m pip install elasticsearch ----- - -[discrete] -[[elasticsearch-python-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,python] ----- -from elasticsearch import Elasticsearch - -client = Elasticsearch( - "https://...", # Your project's Elasticsearch endpoint - api_key='api-key', # API key for your project -) ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-python-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can start ingesting documents. You can use -the `bulk` API for this. This API enables you to index, update, and delete several -documents in one request. - -[discrete] -[[elasticsearch-python-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -You can call the `bulk` API with a body parameter, an array of hashes that -define the action, and a document. - -The following is an example of indexing some classic books into the `books` -index: - -[source,python] ----- -from datetime import datetime - -client.bulk( - body=[ - {"index": {"_index": "books", "_id": "1"}}, - {"title": "Infinite Jest", "author": "David Foster Wallace", "published_on": datetime(1996, 2, 1)}, - {"index": {"_index": "books", "_id": "2"}}, - {"title": "Ulysses", "author": "James Joyce", "published_on": datetime(1922, 2, 2)}, - {"index": {"_index": "books", "_id": "3"}}, - {"title": "Just Kids", "author": "Patti Smith", "published_on": datetime(2010, 1, 19)}, - ], -) ----- - -[discrete] -[[elasticsearch-python-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,python] ----- -response = client.get(index="books", id="1") -print(response.body) ----- - -[discrete] -[[elasticsearch-python-client-getting-started-searching]] -=== Searching - -Now that some data is available, you can search your documents using the -`search` API: - -[source,python] ----- -response = client.search(index="books", query={ - "match": { - "title": "infinite" - } -}) - -for hit in response["hits"]["hits"]: - print(hit["_source"]) ----- - -[discrete] -[[elasticsearch-python-client-getting-started-updating-a-document]] -=== Updating a document - -You can call the `update` API to update a document: - -[source,python] ----- -client.update(index="books", id="2", doc={ - "author": "James Augustine Aloysius Joyce", - "pages": 732, -}) ----- - -[discrete] -[[elasticsearch-python-client-getting-started-deleting-a-document]] -=== Deleting a document - -You can call the `delete` API to delete a document: - -[source,python] ----- -client.delete(index="books", id="3") ----- - -[discrete] -[[elasticsearch-python-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,python] ----- -client.indices.delete(index="books") ----- diff --git a/serverless/pages/clients-ruby-getting-started.asciidoc b/serverless/pages/clients-ruby-getting-started.asciidoc deleted file mode 100644 index f71553923c..0000000000 --- a/serverless/pages/clients-ruby-getting-started.asciidoc +++ /dev/null @@ -1,218 +0,0 @@ -[[elasticsearch-ruby-client-getting-started]] -= Get started with the serverless Ruby client - -// :description: Set up and use the Ruby client for {es3}. -// :keywords: serverless, elasticsearch, ruby, how to - -[NOTE] -==== -This client is for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. -==== - -This page guides you through the installation process Ruby -client for {es3}, shows you how to initialize the client, and how to perform basic -{es-serverless} operations with it. - -[discrete] -[[elasticsearch-ruby-client-getting-started-requirements]] -== Requirements - -* Ruby 3.0 or higher installed on your system. -* To use the `elasticsearch-serverless` gem, you must have an API key and {es} endpoint for an {es3} project. - -[discrete] -[[elasticsearch-ruby-client-getting-started-installation]] -== Installation - -[discrete] -[[elasticsearch-ruby-client-getting-started-from-githubs-releases]] -=== From GitHub's releases - -You can install the Ruby Client from RubyGems: - -[source,bash] ----- -gem install elasticsearch-serverless --pre ----- - -Check https://github.com/elastic/elasticsearch-serverless-ruby/releases[releases] -for the latest available versions. - -[discrete] -[[elasticsearch-ruby-client-getting-started-from-the-source-code]] -=== From the source code - -You can install the Ruby client from the client's https://github.com/elastic/elasticsearch-serverless-ruby[source -code] with the -following commands: - -[source,bash] ----- -# From the project's root directory: -gem build elasticsearch-serverless.gemspec -gem install elasticsearch-serverless-x.x.x.gem ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-using-the-gemfile]] -=== Using the Gemfile - -Alternatively, you can include the client gem in your Ruby project's Gemfile: - -[source,ruby] ----- -gem 'elasticsearch-serverless' ----- - -Once installed, require it in your code: - -[source,ruby] ----- -require 'elasticsearch-serverless' ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-running-a-ruby-console]] -=== Running a Ruby console - -You can also run the client from a Ruby console using the client's https://github.com/elastic/elasticsearch-serverless-ruby[source -code]. To start the -console, run the following commands: - -[source,bash] ----- -# From the project's root directory: -bundle install -bundle exec rake console ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-initialize-the-client]] -== Initialize the client - -Initialize the client using your API key and {es} endpoint: - -[source,ruby] ----- -client = ElasticsearchServerless::Client.new( - api_key: 'your_api_key', - url: 'https://...' -) ----- - -To get API keys for the {es} endpoint for a project, see <>. - -[discrete] -[[elasticsearch-ruby-client-getting-started-using-the-api]] -== Using the API - -After you've initialized the client, you can start ingesting documents. You can use -the `bulk` API for this. This API enables you to index, update, and delete several -documents in one request. - -[NOTE] -==== -The code examples in this section use the Ruby console. To set up the console, <>. -==== - -[discrete] -[[elasticsearch-ruby-client-getting-started-creating-an-index-and-ingesting-documents]] -=== Creating an index and ingesting documents - -You can call the `bulk` API with a body parameter, an array of hashes that -define the action, and a document. - -The following is an example of indexing some classic books into the `books` -index: - -[source,ruby] ----- -# First, build your data: -> body = [ - { index: { _index: 'books', data: {name: "Snow Crash", author: "Neal Stephenson", release_date: "1992-06-01", page_count: 470} } }, - { index: { _index: 'books', data: {name: "Revelation Space", author: "Alastair Reynolds", release_date: "2000-03-15", page_count: 585} } }, - { index: { _index: 'books', data: {name: "1984", author: "George Orwell", release_date: "1949-06-08", page_count: 328} } }, - { index: { _index: 'books', data: {name: "Fahrenheit 451", author: "Ray Bradbury", release_date: "1953-10-15", page_count: 227} } }, - { index: { _index: 'books', data: {name: "Brave New World", author: "Aldous Huxley", release_date: "1932-06-01", page_count: 268} } }, - { index: { _index: 'books', data: {name: "The Handmaid's Tale", author: "Margaret Atwood", release_date: "1985-06-01", page_count: 311} } } -] -# Then ingest the data via the bulk API: -> response = client.bulk(body: body) -# You can check the response if the items are indexed and have a document (doc) ID: -> response['items'] -# Returns: -# => -# [{"index"=>{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>0, "_primary_term"=>1, "status"=>201}}, -# {"index"=>{"_index"=>"books", "_id"=>"Ptink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>1, "_primary_term"=>1, "status"=>201}}, -# {"index"=>{"_index"=>"books", "_id"=>"P9ink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>2, "_primary_term"=>1, "status"=>201}}, -# {"index"=>{"_index"=>"books", "_id"=>"QNink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>3, "_primary_term"=>1, "status"=>201}}, -# {"index"=>{"_index"=>"books", "_id"=>"Qdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>4, "_primary_term"=>1, "status"=>201}}, -# {"index"=>{"_index"=>"books", "_id"=>"Qtink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>5, "_primary_term"=>1, "status"=>201}}] ----- - -When you use the client to make a request to {es}, it returns an API -response object. You can check the HTTP return code by calling `status` and the -HTTP headers by calling `headers` on the response object. The response object -also behaves as a Hash, so you can access the body values directly as seen on -the previous example with `response['items']`. - -[discrete] -[[elasticsearch-ruby-client-getting-started-getting-documents]] -=== Getting documents - -You can get documents by using the following code: - -[source,ruby] ----- -> client.get(index: 'books', id: 'id') # Replace 'id' with a valid doc ID ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-searching]] -=== Searching - -Now that some data is available, you can search your documents using the -`search` API: - -[source,ruby] ----- -> response = client.search(index: 'books', q: 'snow') -> response['hits']['hits'] -# Returns: -# => [{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_score"=>1.5904956, "_source"=>{"name"=>"Snow Crash", "author"=>"Neal Stephenson", "release_date"=>"1992-06-01", "page_count"=>470}}] ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-updating-a-document]] -=== Updating a document - -You can call the `update` API to update a document: - -[source,ruby] ----- -> response = client.update( - index: 'books', - id: 'id', # Replace 'id' with a valid doc ID - body: { doc: { page_count: 312 } } -) ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-deleting-a-document]] -=== Deleting a document - -You can call the `delete` API to delete a document: - -[source,ruby] ----- -> client.delete(index: 'books', id: 'id') # Replace 'id' with a valid doc ID ----- - -[discrete] -[[elasticsearch-ruby-client-getting-started-deleting-an-index]] -=== Deleting an index - -[source,ruby] ----- -> client.indices.delete(index: 'books') ----- diff --git a/serverless/pages/clients.asciidoc b/serverless/pages/clients.asciidoc index 9590ed2441..eae567adb1 100644 --- a/serverless/pages/clients.asciidoc +++ b/serverless/pages/clients.asciidoc @@ -4,24 +4,24 @@ // :description: Index, search, and manage {es} data in your preferred language. // :keywords: serverless, elasticsearch, clients, overview -{es3} provides official language clients for {es} REST APIs. +{es-serverless} uses https://www.elastic.co/guide/en/elasticsearch/client/index.html[standard language clients] for {es} REST APIs. [NOTE] ==== -These clients are for use with {es-serverless} only. See also the https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients]. +Some API endpoints are not available in {es-serverless}. Error responses include information about endpoint availability. ==== -Currently, the following language clients are supported: +{es-serverless} supports the following clients: -* <> | https://github.com/elastic/elasticsearch-serverless-go[Repository] -* <> | https://github.com/elastic/elasticsearch-java/tree/main/java-client-serverless[Repository] -* <> | https://github.com/elastic/elasticsearch-net[Repository] -* <> | https://github.com/elastic/elasticsearch-serverless-js[Repository] -* <> | https://github.com/elastic/elasticsearch-serverless-php[Repository] -* <> | https://github.com/elastic/elasticsearch-serverless-python[Repository] -* <> | https://github.com/elastic/elasticsearch-serverless-ruby[Repository] +* https://www.elastic.co/guide/en/elasticsearch/client/go-api/current/index.html[Go] +* https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/index.html[Java] +* https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/index.html[.NET] +* https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html[Node.js] +* https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/index.html[PHP] +* https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html[Python] +* https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/index.html[Ruby] [TIP] ==== -Learn how to <>. +To use a client, you'll need to <>. ====