From 490046bfcf6cc683a5f43bd15253b676cde5e8a9 Mon Sep 17 00:00:00 2001 From: Thomas Farr Date: Fri, 24 Nov 2023 18:02:08 +1300 Subject: [PATCH] Update guide Signed-off-by: Thomas Farr --- USER_GUIDE.md | 6 +- ...ent_lifecycle.md => document-lifecycle.md} | 4 +- guides/json.md | 99 +++++++++++++------ 3 files changed, 77 insertions(+), 32 deletions(-) rename guides/{document_lifecycle.md => document-lifecycle.md} (99%) diff --git a/USER_GUIDE.md b/USER_GUIDE.md index a202f52ffd..1af340d722 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -309,4 +309,8 @@ Note the main difference here is that we are instantiating an `OpenSearchLowLeve ## Advanced Features -- [Making Raw JSON Requests](guides/json.md) \ No newline at end of file +- [Bulk Requests](guides/bulk.md) +- [Document Lifecycle](guides/document-lifecycle.md) +- [Index Template](guides/index-template.md) +- [Making Raw JSON REST Requests](guides/json.md) +- [Search](guides/search.md) diff --git a/guides/document_lifecycle.md b/guides/document-lifecycle.md similarity index 99% rename from guides/document_lifecycle.md rename to guides/document-lifecycle.md index a8031b136f..e0746f7e7c 100644 --- a/guides/document_lifecycle.md +++ b/guides/document-lifecycle.md @@ -1,5 +1,5 @@ # Document Lifecycle -This guide covers OpenSearch Ruby Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively. +This guide covers OpenSearch .NET Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively. ## Setup Assuming you have OpenSearch running locally on port 9200, you can create a client instance with the following code: @@ -238,4 +238,4 @@ To clean up the resources created in this guide, delete the `movies` index: ```csharp var deleteIndexResponse = client.Indices.Delete("movies"); Debug.Assert(deleteIndexResponse.IsValid, deleteIndexResponse.DebugInformation); -``` \ No newline at end of file +``` diff --git a/guides/json.md b/guides/json.md index b946b59000..97ab1a2688 100644 --- a/guides/json.md +++ b/guides/json.md @@ -4,14 +4,17 @@ - [PUT](#put) - [POST](#post) - [DELETE](#delete) - - [Using Different Types Of PostData](#using-different-types-of-postdata) - - [PostData.String](#postdatastring) - - [PostData.Bytes](#postdatabytes) - - [PostData.Serializable](#postdataserializable) - - [PostData.MultiJson](#postdatamultijson) + - [Request Bodies](#request-bodies) + - [String](#string) + - [Bytes](#bytes) + - [Serializable](#serializable) + - [Multi Json](#multi-json) + - [Response Bodies](#response-bodies) # Making Raw JSON REST Requests -The OpenSearch client implements many high-level REST DSLs that invoke OpenSearch APIs. However you may find yourself in a situation that requires you to invoke an API that is not supported by the client. You can use `client.LowLevel.DoRequest` to do so. See [samples/Samples/RawJson/RawJsonSample.cs](../samples/Samples/RawJson/RawJsonSample.cs) for a complete working sample. +The OpenSearch client implements many high-level REST DSLs that invoke OpenSearch APIs. However you may find yourself in a situation that requires you to invoke an API that is not supported by the client. You can use the methods defined within `client.Http` or `client.LowLevel.Http` to do so. See [samples/Samples/RawJson/RawJsonHighLevelSample.cs](../samples/Samples/RawJson/RawJsonHighLevelSample.cs) and [samples/Samples/RawJson/RawJsonLowLevelSample.cs](../samples/Samples/RawJson/RawJsonLowLevelSample.cs) for complete working samples. + +Older versions of the client that do not support the `client.Http` namespace can use the `client.LowLevel.DoRequest` method instead. ## HTTP Methods @@ -19,18 +22,35 @@ The OpenSearch client implements many high-level REST DSLs that invoke OpenSearc The following example returns the server version information via `GET /`. ```csharp -var info = await client.LowLevel.DoRequestAsync(HttpMethod.GET, "/", CancellationToken.None); +var info = await client.Http.GetAsync("/"); +// OR +var info = await client.LowLevel.Http.GetAsync("/"); + Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!"); ``` +### HEAD +The following example checks if an index exists via `HEAD /movies`. + +```csharp +var indexExists = await client.Http.HeadAsync("/movies"); +// OR +var indexExists = await client.LowLevel.Http.HeadAsync("/movies"); + +Console.WriteLine($"Index Exists: {indexExists.HttpStatusCode == 200}"); +``` + ### PUT The following example creates an index. ```csharp var indexBody = new { settings = new { index = new { number_of_shards = 4 } } }; -var createIndex = await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Serializable(indexBody)); -Debug.Assert(createIndex.Success && (bool)createIndex.Body.acknowledged, createIndex.DebugInformation); +var createIndex = await client.Http.PutAsync("/movies", d => d.SerializableBody(indexBody)); +// OR +var createIndex = await client.LowLevel.Http.PutAsync("/movies", PostData.Serializable(indexBody)); + +Console.WriteLine($"Create Index: {createIndex.Success && (bool)createIndex.Body.acknowledged}"); ``` ### POST @@ -45,25 +65,30 @@ var query = new query = new { multi_match = new { query = q, fields = new[] { "title^2", "director" } } } }; -var search = await client.LowLevel.DoRequestAsync(HttpMethod.POST, $"/{indexName}/_search", CancellationToken.None, PostData.Serializable(query)); -Debug.Assert(search.Success, search.DebugInformation); +var search = await client.Http.PostAsync("/movies/_search", d => d.SerializableBody(query)); +// OR +var search = await client.LowLevel.Http.PostAsync("/movies/_search", PostData.Serializable(query)); -foreach (var hit in search.Body.hits.hits) Console.WriteLine(hit["_source"]["title"]); +foreach (var hit in search.Body.hits.hits) Console.WriteLine($"Search Hit: {hit["_source"]["title"]}"); ``` ### DELETE The following example deletes an index. ```csharp -var deleteDocument = await client.LowLevel.DoRequestAsync(HttpMethod.DELETE, $"/{indexName}/_doc/{id}", CancellationToken.None); -Debug.Assert(deleteDocument.Success, deleteDocument.DebugInformation); +var deleteIndex = await client.Http.DeleteAsync("/movies"); +// OR +var deleteIndex = await client.LowLevel.Http.DeleteAsync("/movies"); + +Console.WriteLine($"Delete Index: {deleteIndex.Success && (bool)deleteIndex.Body.acknowledged}"); ``` -## Using Different Types Of PostData -The OpenSearch .NET client provides a `PostData` class that is used to provide the request body for a request. The `PostData` class has several static methods that can be used to create a `PostData` object from different types of data. +## Request Bodies +For the methods that take a request body (PUT/POST/PATCH) it is possible use several different types to specify the body. The high-level methods provided in `OpenSearch.Client` provide overloaded fluent-methods for setting the body. While the lower level methods in `OpenSearch.Net` accept instances of `PostData`. +The `PostData` class has several static methods that can be used to create a `PostData` object from different types of data. -### PostData.String -The following example shows how to use the `PostData.String` method to create a `PostData` object from a string. +### String +The following example shows how to pass a string as a request body: ```csharp string indexBody = @" @@ -75,11 +100,13 @@ string indexBody = @" } }}"; -await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.String(indexBody)); +await client.Http.PutAsync("/movies", d => d.Body(indexBody)); +// OR +await client.LowLevel.Http.PutAsync("/movies", PostData.String(indexBody)); ``` -### PostData.Bytes -The following example shows how to use the `PostData.Bytes` method to create a `PostData` object from a byte array. +### Bytes +The following example shows how to pass a byte array as a request body: ```csharp byte[] indexBody = Encoding.UTF8.GetBytes(@" @@ -91,11 +118,13 @@ byte[] indexBody = Encoding.UTF8.GetBytes(@" } }}"); -await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Bytes(indexBody)); +await client.Http.PutAsync("/movies", d => d.Body(indexBody)); +// OR +await client.LowLevel.Http.PutAsync("/movies", PostData.Bytes(indexBody)); ``` -### PostData.Serializable -The following example shows how to use the `PostData.Serializable` method to create a `PostData` object from a serializable object. +### Serializable +The following example shows how to pass an object that will be serialized to JSON as a request body: ```csharp var indexBody = new @@ -109,12 +138,14 @@ var indexBody = new } }; -await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Serializable(indexBody)); +await client.Http.PutAsync("/movies", d => d.SerializableBody(indexBody)); +// OR +await client.LowLevel.Http.PutAsync("/movies", PostData.Serializable(indexBody)); ``` -### PostData.MultiJson -The following example shows how to use the `PostData.MultiJson` method to create a `PostData` object from a collection of serializable objects. -The `PostData.MultiJson` method is useful when you want to send multiple documents in a bulk request. +### Multi JSON +The following example shows how to pass a collection of objects (or strings) that will be serialized to JSON and then newline-delimited as a request body. +This formatting is primarily used when you want to make a bulk request. ```csharp var bulkBody = new object[] @@ -125,5 +156,15 @@ var bulkBody = new object[] new { title = "The Godfather: Part II", director = "Francis Ford Coppola", year = 1974 } }; -await client.LowLevel.DoRequestAsync(HttpMethod.POST, "/_bulk", CancellationToken.None, PostData.MultiJson(bulkBody)); +await client.Http.PostAsync("/_bulk", d => d.MultiJsonBody(indexBody)); +// OR +await client.LowLevel.Http.PostAsync("/_bulk", PostData.MultiJson(indexBody)); ``` + +## Response Bodies +There are a handful of response type implementations that can be used to retrieve the response body. These are specified as the generic argument to the request methods. The content of the body will then be available via the `Body` property of the response object. The following response types are available: + +- `VoidResponse`: The response body will not be read. Useful when you only care about the response status code, such as a `HEAD` request to check an index exists. +- `StringResponse`: The response body will be read into a string. +- `BytesResponse`: The response body will be read into a byte array. +- `DynamicResponse`: The response body will be deserialized as JSON into a dynamic object.