diff --git a/OpenSearch.sln b/OpenSearch.sln index 8fa85ddfc4..de0aba5da9 100644 --- a/OpenSearch.sln +++ b/OpenSearch.sln @@ -98,6 +98,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenSearch.Stack.ArtifactsA EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{22DF419F-9A90-4317-957D-E239EB3F95DF}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{E89FE975-FA94-405F-B748-BF2EC8AFFEEE}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Samples", "samples\Samples\Samples.csproj", "{0D084660-06BF-4F3A-A041-DAAB4837378F}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -137,6 +141,7 @@ Global {22DF419F-9A90-4317-957D-E239EB3F95DF} = {87ABA679-F3F4-48CE-82B3-1AAE5D0A5935} {C80D225C-F072-4B24-9ACE-82EFD9362237} = {22DF419F-9A90-4317-957D-E239EB3F95DF} {1F5A7B1A-2566-481F-91B5-A63D7F939973} = {22DF419F-9A90-4317-957D-E239EB3F95DF} + {0D084660-06BF-4F3A-A041-DAAB4837378F} = {E89FE975-FA94-405F-B748-BF2EC8AFFEEE} EndGlobalSection GlobalSection(ProjectConfigurationPlatforms) = postSolution {5B393962-7586-49BA-BD99-3B1E35F48E94}.Debug|Any CPU.ActiveCfg = Debug|Any CPU @@ -231,5 +236,9 @@ Global {E7C0BDC2-28AD-4582-8FEA-0F6327A42C0E}.Debug|Any CPU.Build.0 = Debug|Any CPU {E7C0BDC2-28AD-4582-8FEA-0F6327A42C0E}.Release|Any CPU.ActiveCfg = Release|Any CPU {E7C0BDC2-28AD-4582-8FEA-0F6327A42C0E}.Release|Any CPU.Build.0 = Release|Any CPU + {0D084660-06BF-4F3A-A041-DAAB4837378F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {0D084660-06BF-4F3A-A041-DAAB4837378F}.Debug|Any CPU.Build.0 = Debug|Any CPU + {0D084660-06BF-4F3A-A041-DAAB4837378F}.Release|Any CPU.ActiveCfg = Release|Any CPU + {0D084660-06BF-4F3A-A041-DAAB4837378F}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection EndGlobal diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 24ebaddce9..a202f52ffd 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -14,6 +14,8 @@ - [OpenSearch.Net](#opensearchnet) - [Getting Started](#getting-started-2) - [Connecting](#connecting-2) + - [Advanced Features](#advanced-features) + # User Guide This user guide specifies how to include and use the .NET client in your application. @@ -303,3 +305,8 @@ var client = new OpenSearchLowLevelClient(config); ``` Note the main difference here is that we are instantiating an `OpenSearchLowLevelClient` rather than `OpenSearchClient`, and `ConnectionConfiguration` instead of `ConnectionSettings`. + + +## Advanced Features + +- [Making Raw JSON Requests](guides/json.md) \ No newline at end of file diff --git a/guides/json.md b/guides/json.md new file mode 100644 index 0000000000..c2cb16bc25 --- /dev/null +++ b/guides/json.md @@ -0,0 +1,131 @@ +- [Making Raw JSON REST Requests](#making-raw-json-rest-requests) + - [HTTP Methods](#http-methods) + - [GET](#get) + - [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) + +# Making Raw JSON REST Requests +OpenSearch exposes a REST API that you can use to interact with OpenSearch. The OpenSearch .NET client provides a low-level API that allows you to send raw JSON requests to OpenSearch. This API is useful if you want to use a feature that is not yet supported by the OpenSearch .NET client, but it supported by the OpenSearch REST API. + +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/RawJsonSample/Program.cs](../samples/Samples/RawJsonSample/Program.cs) for a complete working sample. + +## HTTP Methods + +### GET +The following example returns the server version information via `GET /`. + +```csharp +var info = await client.LowLevel.DoRequestAsync(HttpMethod.GET, "/", CancellationToken.None); +Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!"); +``` + +### 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); +``` + +### POST +The following example searches for a document. + +```csharp +const string q = "miller"; + +var query = new +{ + size = 5, + 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); + +foreach (var hit in search.Body.hits.hits) Console.WriteLine(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); +``` + +## 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. + +### PostData.String +The following example shows how to use the `PostData.String` method to create a `PostData` object from a string. + +```csharp +string indexBody = @" +{{ + ""settings"": { + ""index"": { + ""number_of_shards"": 4 + } + } +}}"; + +await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, 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. + +```csharp +byte[] indexBody = Encoding.UTF8.GetBytes(@" +{{ + ""settings"": { + ""index"": { + ""number_of_shards"": 4 + } + } +}}"); + +await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, 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. + +```csharp +var indexBody = new +{ + settings = new + { + index = new + { + number_of_shards = 4 + } + } +}; + +await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies", CancellationToken.None, 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. + +```csharp +var bulkBody = new object[] +{ + new { index = new { _index = "movies", _id = "1" } }, + new { title = "The Godfather", director = "Francis Ford Coppola", year = 1972 }, + new { index = new { _index = "movies", _id = "2" } }, + new { title = "The Godfather: Part II", director = "Francis Ford Coppola", year = 1974 } +}; + +await client.LowLevel.DoRequestAsync(HttpMethod.POST, "/_bulk", CancellationToken.None, PostData.MultiJson(bulkBody)); +``` diff --git a/samples/Samples/RawJsonSample/Program.cs b/samples/Samples/RawJsonSample/Program.cs new file mode 100644 index 0000000000..2ad5796a72 --- /dev/null +++ b/samples/Samples/RawJsonSample/Program.cs @@ -0,0 +1,71 @@ +/* SPDX-License-Identifier: Apache-2.0 +* +* The OpenSearch Contributors require contributions made to +* this file be licensed under the Apache-2.0 license or a +* compatible open source license. +*/ + +using System.Diagnostics; +using OpenSearch.Client; +using OpenSearch.Net; +using HttpMethod = OpenSearch.Net.HttpMethod; + +public class Program +{ + public static async Task Main(string[] args) + { + var node = new Uri("http://localhost:9200"); + var config = new ConnectionSettings(node) + .ServerCertificateValidationCallback(CertificateValidations.AllowAll) + .BasicAuthentication("admin", "admin") + .DisableDirectStreaming(); + + var client = new OpenSearchClient(config); + + var info = await client.LowLevel.DoRequestAsync(HttpMethod.GET, "/", CancellationToken.None); + Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!"); + + // Create an index + + const string indexName = "movies"; + + var indexBody = new { settings = new { index = new { number_of_shards = 4 } } }; + + var createIndex = await client.LowLevel.DoRequestAsync(HttpMethod.PUT, $"/{indexName}", CancellationToken.None, PostData.Serializable(indexBody)); + Debug.Assert(createIndex.Success && (bool)createIndex.Body.acknowledged, createIndex.DebugInformation); + + // Add a document to the index + var document = new { title = "Moneyball", director = "Bennett Miller", year = 2011}; + + const string id = "1"; + + var addDocument = await client.LowLevel.DoRequestAsync(HttpMethod.PUT, $"/{indexName}/_doc/{id}", CancellationToken.None, PostData.Serializable(document)); + Debug.Assert(addDocument.Success, addDocument.DebugInformation); + + // Refresh the index + var refresh = await client.LowLevel.DoRequestAsync(HttpMethod.POST, $"/{indexName}/_refresh", CancellationToken.None); + Debug.Assert(refresh.Success, refresh.DebugInformation); + + // Search for a document + const string q = "miller"; + + var query = new + { + size = 5, + 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); + + foreach (var hit in search.Body.hits.hits) Console.WriteLine(hit["_source"]["title"]); + + // Delete the document + var deleteDocument = await client.LowLevel.DoRequestAsync(HttpMethod.DELETE, $"/{indexName}/_doc/{id}", CancellationToken.None); + Debug.Assert(deleteDocument.Success, deleteDocument.DebugInformation); + + // Delete the index + var deleteIndex = await client.LowLevel.DoRequestAsync(HttpMethod.DELETE, $"/{indexName}", CancellationToken.None); + Debug.Assert(deleteIndex.Success && (bool)deleteIndex.Body.acknowledged, deleteIndex.DebugInformation); + } +} diff --git a/samples/Samples/Samples.csproj b/samples/Samples/Samples.csproj new file mode 100644 index 0000000000..684c46b599 --- /dev/null +++ b/samples/Samples/Samples.csproj @@ -0,0 +1,15 @@ + + + + Exe + net6.0 + enable + enable + False + + + + + + + \ No newline at end of file