diff --git a/docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc b/docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc index 3822a86eda2..85ad0d04156 100644 --- a/docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc +++ b/docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc @@ -29,9 +29,10 @@ this is https://blogs.msdn.microsoft.com/adarshk/2005/01/02/understanding-system So, what is a connection pool in NEST responsible for? It is responsible for managing the nodes in an Elasticsearch cluster to which a connection can be made and there is one instance of an `IConnectionPool` associated with an -instance of `ConnectionSettings`. Since a <>, the lifetime of a single connection pool instance will also be bound to the lifetime -of the application. +instance of `ConnectionSettings`. Since a single client and connection settings +instance is recommended for the life of the application, the lifetime of a +single connection pool instance will also be bound to the lifetime of the +application. There are five types of connection pool diff --git a/docs/client-concepts/connection/configuration-options.asciidoc b/docs/client-concepts/connection/configuration-options.asciidoc index 952d1008bd6..0302d223a46 100644 --- a/docs/client-concepts/connection/configuration-options.asciidoc +++ b/docs/client-concepts/connection/configuration-options.asciidoc @@ -15,10 +15,10 @@ please modify the original csharp file found at the link and submit the PR with [[configuration-options]] === Configuration options -Connecting to Elasticsearch with <> and <> is easy, but +Connecting to Elasticsearch with <> is easy, but it's entirely possible that you'd like to change the default connection behaviour. There are a number of configuration options available -on `ConnectionConfiguration` for the low level client and `ConnectionSettings` for the high level client that can be used to control -how the clients interact with Elasticsearch. +on `ConnectionSettings` that can be used to control how the client interact with +Elasticsearch. ==== Options on ConnectionConfiguration diff --git a/docs/client-concepts/high-level/getting-started.asciidoc b/docs/client-concepts/high-level/getting-started.asciidoc index 1766dd06c9e..541e8386af5 100644 --- a/docs/client-concepts/high-level/getting-started.asciidoc +++ b/docs/client-concepts/high-level/getting-started.asciidoc @@ -18,10 +18,6 @@ please modify the original csharp file found at the link and submit the PR with NEST is a high level Elasticsearch .NET client that still maps very closely to the original Elasticsearch API. All requests and responses are exposed through types, making it ideal for getting up and running quickly. -Under the covers, NEST uses the <> to dispatch requests and -responses, using and extending many of the types within Elasticsearch.Net. The low level client itself is still -exposed on the high level client through the `.LowLevel` property. - [float] === Connecting @@ -45,8 +41,7 @@ var client = new ElasticClient(settings); ---- In this example, a default index was also specified to use if no other index is supplied for the request or can be inferred for the -POCO generic type parameter in the request. There are many other <> on `ConnectionSettings`, which it inherits -from `ConnectionConfiguration`, the type used to pass additional configuration options to the low level client in <>. +POCO generic type parameter in the request. There are many other <> on `ConnectionSettings`. TIP: Specifying a default index is _optional_ but NEST may throw an exception if no index can be inferred for a given request. To understand more around how an index can be specified for a request, see <>. diff --git a/docs/client-concepts/low-level/class.png b/docs/client-concepts/low-level/class.png deleted file mode 100644 index bbc981cfe7a..00000000000 Binary files a/docs/client-concepts/low-level/class.png and /dev/null differ diff --git a/docs/client-concepts/low-level/getting-started.asciidoc b/docs/client-concepts/low-level/getting-started.asciidoc deleted file mode 100644 index c01bcdcaaea..00000000000 --- a/docs/client-concepts/low-level/getting-started.asciidoc +++ /dev/null @@ -1,279 +0,0 @@ -:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master - -:github: https://github.com/elastic/elasticsearch-net - -:nuget: https://www.nuget.org/packages - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/ClientConcepts/LowLevel/GettingStarted.doc.cs. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[elasticsearch-net-getting-started]] -== Getting started - -Elasticsearch.Net is a low level Elasticsearch .NET client that has no dependencies on other libraries -and is unopinionated about how you build your requests and responses. - -[float] -=== Connecting - -To connect to Elasticsearch running locally at `http://localhost:9200` is as simple as -instantiating a new instance of the client - -[source,csharp] ----- -var lowlevelClient = new ElasticLowLevelClient(); ----- - -Often you may need to pass additional configuration options to the client such as the address of Elasticsearch if it's running on -a remote machine. This is where `ConnectionConfiguration` comes in; an instance can be instantiated to provide -the client with different configuration values. - -[source,csharp] ----- -var settings = new ConnectionConfiguration(new Uri("http://example.com:9200")) - .RequestTimeout(TimeSpan.FromMinutes(2)); - -var lowlevelClient = new ElasticLowLevelClient(settings); ----- - -In this example, a default request timeout was also specified that will be applied to all requests, to determine after how long the client should cancel a request. -There are many other <> on `ConnectionConfiguration` to control things such as - -* Basic Authentication header to send with all requests - -* whether the client should connect through a proxy - -* whether HTTP compression support should be enabled on the client - -[float] -==== Connection pools - -`ConnectionConfiguration` is not restricted to being passed a single address for Elasticsearch. There are several different -types of <> available, each with different characteristics that can be used to -configure the client. The following example uses a <> seeded with the addresses -of three Elasticsearch nodes in the cluster, and the client will use this type of pool to maintain a list of available nodes within the -cluster to which it can send requests in a round-robin fashion. - -[source,csharp] ----- -var uris = new[] -{ - new Uri("http://localhost:9200"), - new Uri("http://localhost:9201"), - new Uri("http://localhost:9202"), -}; - -var connectionPool = new SniffingConnectionPool(uris); -var settings = new ConnectionConfiguration(connectionPool); - -var lowlevelClient = new ElasticLowLevelClient(settings); ----- - -[float] -=== Indexing - -Once a client had been configured to connect to Elasticsearch, we need to get some data into the cluster to work with. -Imagine we have the following http://en.wikipedia.org/wiki/Plain_Old_CLR_Object[Plain Old CLR Object (POCO)] - -[source,csharp] ----- -public class Person -{ - public string FirstName { get; set; } - public string LastName { get; set; } -} ----- - -Indexing a single instance of this POCO, either synchronously or asynchronously, is as simple as - -[source,csharp] ----- -var person = new Person -{ - FirstName = "Martijn", - LastName = "Laarman" -}; - -var ndexResponse = lowlevelClient.Index("people", "1", PostData.Serializable(person)); <1> -byte[] responseBytes = ndexResponse.Body; - -var asyncIndexResponse = await lowlevelClient.IndexAsync("people", "1", PostData.Serializable(person)); <2> -string responseString = asyncIndexResponse.Body; ----- -<1> synchronous method that returns an `IndexResponse` -<2> asynchronous method that returns a `Task` that can be awaited - -NOTE: All available methods within Elasticsearch.Net are exposed as both synchronous and asynchronous versions, -with the latter using the idiomatic *Async suffix for the method name. - -Both index requests will index the document to the endpoint `/people/person/1`. - -An https://msdn.microsoft.com/en-us/library/bb397696.aspx[anonymous type] can also be used to represent the document to index - -[source,csharp] ----- -var person = new -{ - FirstName = "Martijn", - LastName = "Laarman" -}; - -var ndexResponse = await lowlevelClient.IndexAsync("people", "1", PostData.Serializable(person)); -byte[] responseStream = ndexResponse.Body; ----- - -For API's that take a body you can send the body as an (anonymous) object, byte[], string, stream. Additionally for API's that -take multilined json you can also send a list of objects or a list of bytes to help you format this. These are all encapsulated -by `PostData` and you can use the static methods on that class to send the body in whatever form you have it. -Check out the documentation on <> to see all of these permutations in action. - -The generic type parameter on the method specifies the type of the response body. In the last example, we return the response as a -string from Elasticsearch, forgoing any deserialization. - -[float] -==== Bulk indexing - -If you need to index many documents, Elasticsearch has a {ref_current}/docs-bulk.html[Bulk API] that can be used to perform many operations in one request - -[source,csharp] ----- -var people = new object[] -{ - new { index = new { _index = "people", _type = "person", _id = "1" }}, - new { FirstName = "Martijn", LastName = "Laarman" }, - new { index = new { _index = "people", _type = "person", _id = "2" }}, - new { FirstName = "Greg", LastName = "Marzouka" }, - new { index = new { _index = "people", _type = "person", _id = "3" }}, - new { FirstName = "Russ", LastName = "Cam" }, -}; - -var ndexResponse = lowlevelClient.Bulk(PostData.MultiJson(people)); -string responseStream = ndexResponse.Body; ----- - -The client will serialize each item seperately and join items up using the `\n` character as required by the Bulk API. Refer to the -Elasticsearch Bulk API documentation for further details and supported operations. - -[float] -=== Searching - -Now that we have indexed some documents we can begin to search for them. - -The Elasticsearch Query DSL can be expressed using an anonymous type within the request - -[source,csharp] ----- -var searchResponse = lowlevelClient.Search("people", PostData.Serializable(new -{ - from = 0, - size = 10, - query = new - { - match = new - { - firstName = new - { - query = "Martijn" - } - } - } -})); - -var successful = searchResponse.Success; -var responseJson = searchResponse.Body; ----- - -`responseJson` now holds a JSON string for the response. The search endpoint for this query is -`/people/person/_search` and it's possible to search over multiple indices and types by changing the arguments -supplied in the request for `index` and `type`, respectively. - -Strings can also be used to express the request - -[source,csharp] ----- -var searchResponse = lowlevelClient.Search("people", @" -{ - ""from"": 0, - ""size"": 10, - ""query"": { - ""match"": { - ""firstName"": { - ""query"": ""Martijn"" - } - } - } -}"); - -var responseBytes = searchResponse.Body; ----- - -As you can see, using strings is a little more cumbersome than using anonymous types because of the need to escape -double quotes, but it can be useful at times nonetheless. `responseBytes` will contain -the bytes of the response from Elasticsearch. - -[NOTE] --- -Elasticsearch.Net does not provide typed objects to represent responses; if you need this, you should consider -using <>, that does map all requests and responses to types. You can work with -strong types with Elasticsearch.Net but it will be up to you as the developer to configure Elasticsearch.Net so that -it understands how to deserialize your types, most likely by providing your own <> implementation -to `ConnectionConfiguration`. - --- - -[float] -=== Handling Errors - -By default, Elasticsearch.Net is configured not to throw exceptions if a HTTP response status code is returned that is not in -the 200-300 range, nor an expected response status code allowed for a given request e.g. checking if an index exists -can return a 404. - -The response from low level client calls provides a number of properties that can be used to determine if a call -is successful - -[source,csharp] ----- -var searchResponse = lowlevelClient.Search("people", PostData.Serializable(new { match_all = new {} })); - -var success = searchResponse.Success; <1> -var successOrKnownError = searchResponse.SuccessOrKnownError; <2> -var exception = searchResponse.OriginalException; <3> ----- -<1> Response is in the 200 range, or an expected response for the given request -<2> Response is successful, or has a response code between 400-599 that indicates the request cannot be retried. -<3> If the response is unsuccessful, will hold the original exception. - -Using these details, it is possible to make decisions around what should be done in your application. - -The default behaviour of not throwing exceptions can be changed by setting `.ThrowExceptions()` on `ConnectionConfiguration` - -[source,csharp] ----- -var settings = new ConnectionConfiguration(new Uri("http://example.com:9200")) - .ThrowExceptions(); - -var lowlevelClient = new ElasticLowLevelClient(settings); ----- - -And if more fine grained control is required, custom exceptions can be thrown using `.OnRequestCompleted()` on -`ConnectionConfiguration` - -[source,csharp] ----- -var settings = new ConnectionConfiguration(new Uri("http://example.com:9200")) - .OnRequestCompleted(apiCallDetails => - { - if (apiCallDetails.HttpStatusCode == 418) - { - throw new TimeForACoffeeException(); - } - }); - -var lowlevelClient = new ElasticLowLevelClient(settings); ----- - diff --git a/docs/client-concepts/low-level/lifetimes.asciidoc b/docs/client-concepts/low-level/lifetimes.asciidoc deleted file mode 100644 index 23a8f3a63a9..00000000000 --- a/docs/client-concepts/low-level/lifetimes.asciidoc +++ /dev/null @@ -1,102 +0,0 @@ -:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master - -:github: https://github.com/elastic/elasticsearch-net - -:nuget: https://www.nuget.org/packages - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/ClientConcepts/LowLevel/Lifetimes.doc.cs. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[lifetimes]] -== Lifetimes - -If you are using an IOC/Dependency Injection container, it's always useful to know the best practices around -the lifetime of your objects. - -In general, we advise folks to register an `ElasticClient` instance as a singleton; the client is thread safe, -so sharing an instance across threads is fine. - -The actual moving part that benefits from being a singleton is `ConnectionSettings` because -**caches are __per__ `ConnectionSettings`**. - -In some applications ,it could make perfect sense to have multiple `ElasticClient` instances registered with different -connection settings such as when your application connects to two different Elasticsearch clusters. - -IMPORTANT: Due to the semantic versioning of Elasticsearch.Net and NEST and their alignment to versions of Elasticsearch, all instances of `ElasticClient` and -Elasticsearch clusters that are connected to must be on the **same major version** - -Let's demonstrate which components are disposed by creating our own derived `ConnectionSettings`, `IConnectionPool` and `IConnection` types - -[source,csharp] ----- -private class AConnectionSettings : ConnectionSettings -{ - public AConnectionSettings(IConnectionPool pool, IConnection connection) - : base(pool, connection) - { } - - public bool IsDisposed { get; private set; } - - protected override void DisposeManagedResources() - { - this.IsDisposed = true; - base.DisposeManagedResources(); - } -} - -private class AConnectionPool : SingleNodeConnectionPool -{ - public AConnectionPool(Uri uri, IDateTimeProvider dateTimeProvider = null) : base(uri, dateTimeProvider) { } - - public bool IsDisposed { get; private set; } - - protected override void DisposeManagedResources() - { - this.IsDisposed = true; - base.DisposeManagedResources(); - } -} - -private class AConnection : InMemoryConnection -{ - public bool IsDisposed { get; private set; } - - protected override void DisposeManagedResources() - { - this.IsDisposed = true; - base.DisposeManagedResources(); - } -} ----- - -`ConnectionSettings`, `IConnectionPool` and `IConnection` all explicitly implement `IDisposable` - -[source,csharp] ----- -var connection = new AConnection(); -var connectionPool = new AConnectionPool(new Uri("http://localhost:9200")); -var settings = new AConnectionSettings(connectionPool, connection); -settings.IsDisposed.Should().BeFalse(); -connectionPool.IsDisposed.Should().BeFalse(); -connection.IsDisposed.Should().BeFalse(); ----- - -Disposing an instance of `ConnectionSettings` will also dispose the `IConnectionPool` and `IConnection` it uses - -[source,csharp] ----- -var connection = new AConnection(); -var connectionPool = new AConnectionPool(new Uri("http://localhost:9200")); -var settings = new AConnectionSettings(connectionPool, connection); -using (settings) { } <1> -settings.IsDisposed.Should().BeTrue(); -connectionPool.IsDisposed.Should().BeTrue(); -connection.IsDisposed.Should().BeTrue(); ----- -<1> force the settings to be disposed - diff --git a/docs/client-concepts/low-level/low-level-response-types.asciidoc b/docs/client-concepts/low-level/low-level-response-types.asciidoc deleted file mode 100644 index 7056d444f6e..00000000000 --- a/docs/client-concepts/low-level/low-level-response-types.asciidoc +++ /dev/null @@ -1,108 +0,0 @@ -:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master - -:github: https://github.com/elastic/elasticsearch-net - -:nuget: https://www.nuget.org/packages - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/ClientConcepts/LowLevel/LowLevelResponseTypes.doc.cs. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[low-level-response-types]] -=== Low Level Client Response Types - -[source,csharp] ----- -return @"{ - ""boolean"" : true, - ""string"" : ""v"", - ""number"" : 29, - ""array"" : [1, 2, 3, 4], - ""object"" : { - ""first"" : ""value1"", - ""second"" : ""value2"", - ""nested"" : { ""x"" : ""value3"" } - }, - ""array_of_objects"" : [ - { - ""first"" : ""value11"", - ""second"" : ""value12"", - ""nested"" : { ""x"" : ""value4"", ""z"" : [{""id"": 1}] } - }, - { - ""first"" : ""value21"", - ""second"" : ""value22"", - ""nested"" : { ""x"" : ""value5"", ""z"" : [{""id"": 3}, {""id"": 2}] }, - ""complex.nested"" : { ""x"" : ""value6"" } - } - ] -}"; ----- - -[float] -=== DynamicResponse - -[source,csharp] ----- -var response = Client.LowLevel.Search(PostData.Empty); -AssertOnResponse(response); - -// this uses System.Text.Json -var responseLowLevel = LowLevelClient.Search(PostData.Empty); -AssertOnResponse(responseLowLevel); - -response.Get("object.first") - .Should() - .NotBeEmpty() - .And.Be("value1"); - -response.Get("object._arbitrary_key_") - .Should() - .NotBeEmpty() - .And.Be("first"); - -response.Get("array.1").Should().Be(2); -response.Get("array.1").Should().Be(2); -response.Get("number").Should().Be(29); -response.Get("number").Should().Be(29); -response.Get("number_does_not_exist").Should().Be(null); -response.Get("number").Should().Be(29); - -response.Get("array_of_objects.1.second") - .Should() - .NotBeEmpty() - .And.Be("value22"); - -response.Get("array_of_objects.1.complex\\.nested.x") - .Should() - .NotBeEmpty() - .And.Be("value6"); ----- - -You can project into arrays using the dot notation - -[source,csharp] ----- -response.Get("array_of_objects.first") - .Should() - .NotBeEmpty() - .And.HaveCount(2) - .And.BeEquivalentTo(new[] { "value11", "value21" }); ----- - -You can even peek into array of arrays - -[source,csharp] ----- -var nestedZs = response.Get("array_of_objects.nested.z.id") - //.SelectMany(d=>d.Get("id")) - .Should() - .NotBeEmpty() - .And.HaveCount(2) - .And.BeEquivalentTo(new[] { new[] { 1 }, new[] { 3, 2 } }); ----- - diff --git a/docs/client-concepts/low-level/pipeline.png b/docs/client-concepts/low-level/pipeline.png deleted file mode 100644 index b15d2f0f8b6..00000000000 Binary files a/docs/client-concepts/low-level/pipeline.png and /dev/null differ diff --git a/docs/client-concepts/low-level/post-data.asciidoc b/docs/client-concepts/low-level/post-data.asciidoc deleted file mode 100644 index 42cffef23c7..00000000000 --- a/docs/client-concepts/low-level/post-data.asciidoc +++ /dev/null @@ -1,190 +0,0 @@ -:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master - -:github: https://github.com/elastic/elasticsearch-net - -:nuget: https://www.nuget.org/packages - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/ClientConcepts/LowLevel/PostData.doc.cs. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[post-data]] -=== Post data - -The low level client allows you to post a `string` or `byte[]` array directly. On top of this, -if you pass a collection of `string` or `object` they will be serialized using Elasticsearch's special bulk/multi format. - -[float] -=== Implicit Conversion - -Even though the argument for PostData on the low level client takes a `PostData`, -You can rely on implicit conversion to abstract the notion of PostData for the most common two use cases: - -* A `string` - -* A `byte[]` array - -Let's demonstrate each with some assertive examples - -[source,csharp] ----- -PostData fromString = @string; -PostData fromByteArray = bytes; - -fromByteArray.WrittenBytes.Should().BeSameAs(bytes); <1> ----- -<1> `WrittenBytes` will always be set if it originated from `byte[]` - -The `Type` property is representative of the original type from which post data is constructed - -[source,csharp] ----- -fromString.Type.Should().Be(PostType.LiteralString); -fromByteArray.Type.Should().Be(PostType.ByteArray); ----- - -and passing a `PostData` instance to a method that accepts `PostData` -as an argument does not wrap it again - -[source,csharp] ----- -fromString = MethodThatAcceptsPostData(fromString); -fromByteArray = MethodThatAcceptsPostData(fromByteArray); - -fromString.Type.Should().Be(PostType.LiteralString); -fromByteArray.Type.Should().Be(PostType.ByteArray); ----- - -[float] -=== Other types of PostData - -You can also pass the following objects directly to the low level client. - -* A Serializable `object` - -* A collection of `object` as multi line json - -* A collection of `string` as multi line json - -Let's demonstrate how to use the static helper on `PostData` for these: - -[source,csharp] ----- -PostData fromObject = PostData.Serializable(@object); -PostData fromListOfString = PostData.MultiJson(collectionOfStrings); -PostData fromListOfObject = PostData.MultiJson(collectionOfObjects); ----- - -The `Type` property is representative of the original type from which post data is constructed - -[source,csharp] ----- -fromListOfString.Type.Should().Be(PostType.EnumerableOfString); -fromListOfObject.Type.Should().Be(PostType.EnumerableOfObject); -fromObject.Type.Should().Be(PostType.Serializable); ----- - -and passing a `PostData` instance to a method that accepts `PostData` as an argument does not wrap it again - -[source,csharp] ----- -fromListOfString = MethodThatAcceptsPostData(fromListOfString); -fromListOfObject = MethodThatAcceptsPostData(fromListOfObject); -fromObject = MethodThatAcceptsPostData(fromObject); - -fromListOfString.Type.Should().Be(PostType.EnumerableOfString); -fromListOfObject.Type.Should().Be(PostType.EnumerableOfObject); -fromObject.Type.Should().Be(PostType.Serializable); ----- - -Each of the implicitly converted types behaves _slightly_ differently. - -For `string`, the UTF-8 bytes are sent in the request and the `WrittenBytes` property is assigned -the bytes - -[source,csharp] ----- -await Post(() => @string, writes: Utf8Bytes(@string), writtenBytesIsSet: true, settings: settings); ----- - -Similarly, for `byte[]`, the bytes are sent verbatim and the `WrittenBytes` property is assigned -the bytes - -[source,csharp] ----- -await Post(() => bytes, writes: bytes, writtenBytesIsSet: true, settings: settings); ----- - -On platforms that support `ReadOnlyMemory` you can use `PostData.ReadOnlyMemory` to pass this directly - -[source,csharp] ----- -await Post(() => PostData.ReadOnlyMemory(bytes.AsMemory()), writes: bytes, writtenBytesIsSet: false, settings: settings); ----- - -When passing a collection of `string`, the client assumes that it's a collection of valid serialized json, -so joins each with newline feeds, ensuring there is a trailing linefeed. As with `string` and `byte[]`, -the `WrittenBytes` property is assigned the UTF-8 bytes of the collection of strings if `DisableDirectStreaming` is set on `ConnectionConfiguration` - -[source,csharp] ----- -await Post(() => PostData.MultiJson(collectionOfStrings), writes: utf8BytesOfListOfStrings, writtenBytesIsSet: false, settings: settings); ----- - -When passing a collection of `object`, the client assumes that it's a collection of objects -that needs to be serialized individually to json and joined with newline feeds. As with the collection of strings, the client ensures that -there is a trailing linefeed. - -[source,csharp] ----- -await Post(() => PostData.MultiJson(collectionOfObjects), writes: utf8BytesOfCollectionOfObjects, writtenBytesIsSet: false, settings: settings); ----- - -In all other cases, Post data is serialized as is and `WrittenBytes` is not assigned - -[source,csharp] ----- -await Post(() => PostData.Serializable(@object), writes: utf8ObjectBytes, writtenBytesIsSet: false, settings: settings); ----- - -If you want even more control over how your data is written to the stream consider `PostData.StreamHandler` -which allows you to inject your own writer routines - -[source,csharp] ----- -var streamHandler = PostData.StreamHandler(bytes, - (b, s) => s.Write(b.AsSpan()), - async (b, s, ctx) => await s.WriteAsync(b.AsMemory(), ctx) -); -await Post(() => streamHandler, writes: bytes, writtenBytesIsSet: false, settings: settings); ----- - -==== Forcing WrittenBytes to be set - -If you want to maintain a copy of the request that went out, you can set `DisableDirectStreaming` on `ConnectionConfiguration`. -In doing so, the serialized bytes are first written to a private `MemoryStream` so that the client can get hold of the serialized bytes - -[source,csharp] ----- -settings = new TransportConfiguration().DisableDirectStreaming(); - -await Post(() => PostData.MultiJson(collectionOfObjects), writes: utf8BytesOfCollectionOfObjects, writtenBytesIsSet: true, settings: settings); - -await Post(() => PostData.MultiJson(collectionOfStrings), writes: utf8BytesOfListOfStrings, writtenBytesIsSet: true, settings: settings); - -await Post(() => PostData.ReadOnlyMemory(bytes.AsMemory()), writes: bytes, writtenBytesIsSet: true, settings: settings); - -await Post(() => streamHandler, writes: bytes, writtenBytesIsSet: true, settings: settings); ----- - -This behavior can also be observed when serializing a simple object using `DisableDirectStreaming` enabled - -[source,csharp] ----- -await Post(() => PostData.Serializable(@object), writes: utf8ObjectBytes, writtenBytesIsSet: true, settings: settings); ----- - diff --git a/docs/conventions.asciidoc b/docs/conventions.asciidoc index b75792ecbba..3a7a57e9e4e 100644 --- a/docs/conventions.asciidoc +++ b/docs/conventions.asciidoc @@ -29,8 +29,6 @@ please modify the original csharp file found at the link and submit the PR with -- Conventions that apply to both Elasticsearch.Net and NEST -* <> - * <> * <> @@ -45,8 +43,6 @@ Conventions that apply to both Elasticsearch.Net and NEST -- -include::client-concepts/low-level/lifetimes.asciidoc[] - [[thrown-exceptions]] == Exceptions diff --git a/docs/high-level.asciidoc b/docs/high-level.asciidoc index 916b04ab1d9..b05fc2144cc 100644 --- a/docs/high-level.asciidoc +++ b/docs/high-level.asciidoc @@ -14,10 +14,6 @@ please modify the original csharp file found at the link and submit the PR with The high level client, `ElasticClient`, provides a strongly typed query DSL that maps one-to-one with the {es} query DSL. -NEST internally uses and still exposes the low level client, -`ElasticLowLevelClient`, from <> via -the `.LowLevel` property on `ElasticClient`. - There are a number of conventions that NEST uses for inference of * <> diff --git a/docs/index.asciidoc b/docs/index.asciidoc index e22fa8065bf..c48d68433ee 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -21,8 +21,6 @@ include::breaking-changes.asciidoc[] include::conventions.asciidoc[] -include::low-level.asciidoc[] - include::high-level.asciidoc[] include::troubleshooting.asciidoc[] @@ -32,4 +30,3 @@ include::search.asciidoc[] include::query-dsl.asciidoc[] include::aggregations.asciidoc[] - diff --git a/docs/installation.asciidoc b/docs/installation.asciidoc deleted file mode 100644 index c2c7d07a641..00000000000 --- a/docs/installation.asciidoc +++ /dev/null @@ -1,56 +0,0 @@ -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/installation.asciidoc. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[installation-old]] -== Installation - -This page is about about how to install the `Elasticsearch.Net` and the `NEST` -clients. - -[[es-net]] -[discrete] -=== Installing the Elasticsearch.Net client - -The low level client, `ElasticLowLevelClient`, is a low level, dependency free -client that has no opinions about how you build and represent your requests and -responses. - -It can be installed from the Package Manager Console inside Visual Studio by -using the following command: - -[source,shell] ----- -Install-Package Elasticsearch.Net ----- - -Or by searching for -https://www.nuget.org/packages/Elasticsearch.Net[Elasticsearch.Net] in the -Package Manager GUI. - -[[es-nest]] -[discrete] -=== Installing the NEST client - -The high level `ElasticClient`, provides a strongly typed query DSL that maps -one-to-one with the {es} query DSL. - -It can be installed from the Package Manager Console inside Visual Studio by -using the following command: - -[source,shell] ----- -Install-Package NEST ----- - -Or by searching for https://www.nuget.org/packages/NEST[NEST] in the Package -Manager GUI. - -NEST internally uses and still exposes the low level client, -`ElasticLowLevelClient`, from <> via the -`.LowLevel` property on `ElasticClient`. - diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc deleted file mode 100644 index 7a347ae3539..00000000000 --- a/docs/introduction.asciidoc +++ /dev/null @@ -1,60 +0,0 @@ -:github: https://github.com/elastic/elasticsearch-net - -:stackoverflow: http://stackoverflow.com - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/introduction.asciidoc. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -[[introduction-old]] -== Introduction - -This is the documentation page for `Elasticsearch.Net` and `NEST`, the two -official .NET clients for {es}. - -[discrete] -=== Why two clients? - -`Elasticsearch.Net` is a low level, dependency free client that has no opinions -about how you build and represent your requests and responses. It has abstracted -enough so that **all** the {es} API endpoints are represented as methods but not -too much to get in the way of how you want to build your json/request/response -objects. It also comes with built in, configurable/overridable cluster failover -retry mechanisms. {es} is _elastic_ so why not your client? - -`NEST` is a high level client that maps all requests and responses as types, and -comes with a strongly typed query DSL that maps 1 to 1 with the {es} query DSL. -It takes advantage of specific .NET features to provide higher level -abstractions such as <>. Internally, NEST -uses and still exposes the low level `Elasticsearch.Net` client, providing -access to the power of NEST and allowing users to drop down to the low level -client when wishing to. - -Please read the getting started guide for both -<> and <>. - -[discrete] -=== {es} Version Compatibility - -Language clients are forward compatible; meaning that clients support communicating with greater or equal minor versions of {es}. -{es} language clients are only backwards compatible with default distributions and without guarantees made. - -[discrete] -=== Questions, bugs, comments, feature requests - -Bug reports and feature requests are more than welcome on the -{github}/issues[github issues pages]! We try to at least reply within the same -day. - -For more general questions and comments, we monitor questions tagged with -{stackoverflow}/questions/tagged/nest[`nest`] and -{stackoverflow}/questions/tagged/elasticsearch-net[`elasticsearch-net`] on -Stackoverflow, as well as discussions opened on our Discourse site, -https://discuss.elastic.co/c/elasticsearch[discuss.elastic.co]. By mentioning -`NEST` or `Elasticsearch.Net` in the title helps folks quickly identify what -the question is about. - diff --git a/docs/low-level.asciidoc b/docs/low-level.asciidoc deleted file mode 100644 index 7047a48d2f6..00000000000 --- a/docs/low-level.asciidoc +++ /dev/null @@ -1,26 +0,0 @@ -[[elasticsearch-net]] -= Elasticsearch.Net - Low level client - -//// -IMPORTANT NOTE -============== -This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/low-level.asciidoc. -If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, -please modify the original csharp file found at the link and submit the PR with that change. Thanks! -//// - -The low level client, `ElasticLowLevelClient`, is a low level, dependency free -client that has no opinions about how you build and represent your requests and -responses. - -include::client-concepts/low-level/getting-started.asciidoc[] - -[[elasticsearch-net-conventions]] -== Conventions - -The low level client has only a few conventions - -* <> - -include::client-concepts/low-level/post-data.asciidoc[] -