Release Notes

The 8.0.0-alpha.1 release includes a (currently limited) core, high-level API surface for working with Elasticsearch from .NET client applications. It is the successor to NEST and forms the basis of the client that developers should use to work with v8.0.0 of Elasticsearch. As described in more detail in the v8.0.0 roadmap, some significant changes are occurring in this major release. We appreciate that some of these changes are breaking and will require work from developments to migrate applications. We will provide subsequent documentation on the migration and upgrade path. The decisions were not taken lightly and have been made to support improved consistency with server APIs, faster endpoint inclusion, improved user experience, robust behaviour and improved performance.

The most significant factor in the changes is that we now code generate the models and much of the client API surface from a common schema. This ensures the accuracy of the models over time and allows us to ship a client aligned to new APIs and request/response models much more quickly. This process has led to requirements to introduce deeper namespacing for types and will result in some properties and types from NEST changing names. Our goal is to limit the impact of such changes where practical.

Breaking Changes

The following is not a complete list of all breaking changes but highlights some of the main considerations for consumers testing the new alpha client. Further detail will be provided in subsequent documentation and future releases.

Assembly and Package Naming

You will have noticed that this library has been renamed from NEST to Elastic.Clients.Elasticsearch. As a result of this change, all types now belong to the root namespace Elastic.Clients.Elasticsearch.

We believe that this naming will be much clearer to new consumers of the library, while also providing an advantage during migration. We expect an upgrade path to include running NEST and Elastic.Clients.Elasticsearch side-by-side. You can find the new client on NuGet.

Core Type Renaming

As already mentioned, some request and response types along with models for their members are now code-generated. Some special treatment has been given to specific areas, but as far as possible we allow the types to be generated based on the common Elasticsearch specification used by all clients.

We have taken the opportunity to also clarify the naming of a few core types, the most obvious being the rename of IElasticClient to IElasticsearchClient, along with the related ElasticsearchClient implementation. The related ConnectionSettings type is now named ElasticsearchClientSettings.

Serialization

Internally, the serializer used for requests, responses and user types (by default) has had a major overhaul. NEST 7.x ships with an internal serializer based on Utf8Json. This was originally chosen for its performance characteristics but has had some drawbacks. The original library is no longer supported and various bugs have been identified and fixed in our internalised version. We have decided to move away from this serializer and standardise on Microsoft’s System.Text.Json library which is also geared towards high-performance (de)serialization and is fully supported by Microsoft. While the library is limited in some areas, we have been able to replace the serializer for client types, as well as user serialization. We will continue to support consumers who wish to provide a separate serializer implementation using another third-party serializer. We intend also to continue to ship a Json.NET based library that can be used for source serialization. Upon installing the v8.0.0 client you may need to attribute your document types and properties with System.Text.Json attributes to control the serialization of your documents, such as renaming or ignoring properties.

Fluent Descriptors

For a long time, NEST has offered two main approaches to work with requests and responses. The object initializer syntax is a more classic approach where you create a new request object and assign properties via the constructor or property setters. We have also supported a fluent syntax through descriptor types, which can make working with complex requests and queries terser. Often the choice between these is somewhat subjective and mixing approaches is also very valid.

We will continue to include both patterns in the v8 client. Internally, we have separated the concepts such that we no longer provide a common interface for request types that the object and descriptor implement. Instead, the concepts are decoupled. This has some advantages and can enable future improvements. The main user-facing change is that some interop between these concepts is not fully completed in alpha.1. Additionally, because these components are now code-generated, request descriptors are renamed and include “Request” in the name. For example, the ClusterHealthRequest object is paired with a ClusterHealthRequestDescriptor type (previously named ClusterHealthDescriptor). We have been able to simplify the APIs for working with the fluent syntax such that they no longer expect a Func<TDescriptor, TInterface> to configure them. Instead, we have a simplified Action interface.

Transport and Low-level Client

The transport layer of the client has been transplanted to a new library and package called Elastic.Transport. This contains the concepts for working with clusters of servers (nodes) as well as performing the work t create and send HTTP requests. This library will evolve to form a common transport layer designed for future .NET client libraries targeting Elastic products.

Elastic.Clients.Elasticsearch depends on Elastic.Transport and its transport APIs. As a result, some types have moved into the Elastic.Transport assembly and namespace.

For the time being, the client offers a pure high-level API surface as found in NEST versions previously. We currently do not expose a low-level client concept. Functionality performed via the low-level client can be achieved with a direct dependency on Elastic.Transport in the interim.

Attribute Mappings

Historically, NEST has supported several mechanisms to infer and control mapping and source serialization behaviour of user types. One approach we have removed for 8.0.0 is legacy attribute mappings. These are no longer supported as they cannot be consumed with the Microsoft serializer and were quite brittle to maintain and use due to the limitations of attributes.

Supported Endpoints

Alpha 1 of the v8.0.0 client is limited to core APIs around CRUD functionality. We intend to ship all APIs in final releases. Due to the effort of code-generating these accurately and testing them, we have excluded untested/incomplete APIs from this first alpha. We will re-introduce more of these in each subsequent release. Please let us know if you depend on missing APIs and we will work to prioritize those that we can to align with the community needs.

Includes endpoints in this release:

• Bulk
• ClosePointInTime
• Count
• Create
• Delete
• Exists
• Get
• Index
• OpenPointInTime
• Ping
• Search
• Source
• Update
• Cluster.AllocationExplain
• Cluster.Health
• Cluster.PendingTasks
• Cluster.State
• IndexManagement.Delete
• IndexManagement.Exists
• IndexManagement.Refresh

Supported Aggregations

Alpha 1 ships with an incomplete set of supported aggregation types for the same reasons as discussed for endpoints. More aggregations will be added to subsequent alpha releases.

Included aggregations:

• DateHistogram
• Terms
• Average
• Boxplot
• Cardinality
• Extended stats
• Max
• Median absolute deviation
• Min
• Stats
• String stats
• Value count
• Weighted average

Feedback

We welcome feedback on the changes to the client, in particular, if something is missing or broken that you require, please let us know. We plan to release further alphas with more aggregations and endpoints and can prioritise those endpoints needed most commonly by the community.