Releases: elastic/elasticsearch-net
8.0.0-alpha.1
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.
7.16.0
6.8.10
7.15.2
Bug Fixes
- #6038 Support
wildcardfield inWildcardQuery(issue: #6033) - #6042 Support deprecated range query properties
View the full list of issues and PRs
7.15.1
Enhancements
- #6025 Add experimental config to disable TLS1.3
- #6027 Support params on SQL query & translate APIs (issue: #6022)
View the full list of issues and PRs
7.15.0
Features & Enhancements
- #5989 Support PIT, Fields and RuntimeFields on AsyncSearch (issue: #5988)
- #5997 Add missing properties to AsyncSearch response (issue: #5988)
Bug Fixes
API
- The
indexparameter is now required for the Open Point in Time API.
View the full list of issues and PRs
7.14.1
Bug Fixes
- #5940 Fix bug with case-sensitive header comparisons (.NET Framework)
View the full list of issues and PRs
7.14.0
Features & Enhancements
- #5728 Pre-flight product check - Checks that the client is connected to an Elasticsearch cluster. If the client isn't connected to a supported Elasticsearch cluster an
UnsupportedProductExceptionwill be thrown. - #5731 NameValueCollection.ToQueryString performance optimisation (issue: #4952)
- #5740 Change default IMemoryStreamFactory
- #5780 Add support for dense vector fields (issue: #3836)
- #5755 Add readonly property to FS repository settings (issue: #5753)
- #5789 Support simple_pattern and simple_pattern_split tokenizers (issue: #5716)
- #5792 Add running state to data feed stats (issue: #5776)
- #5793 Add IO stats to node stats model (issue: #5776)
- #5801 Add match_only_text field (issue: #5776)
- #5802 Add keep_values gap policy (issue: #5776)
- #5803 Add cancelled property to TaskInfo (issue: #5776)
- #5812 Support _meta on ILM policy (issue: #5776)
- #5823 Add support for the migrate to data tiers API
- #5831 Support snapshot repository analysis API
- #5832 Support index pattern exclusion in CCR AutoFollow (issue: #5776)
- #5856 Support get async SQL search status API
- #5858 Support delete async SQL search API
- #5861 Support get async SQL search API
- #5869 Support async SQL searches
Performance
- #5865 Reduce allocations on some transport paths
Bug Fixes
- #5743 Fix weekly schedule deserialisation (issue: #5725)
- #5761 Fix discrepancies in Watcher API models which fail (de)serialization (issue: #5725)
- #5888 Fix hourly watcher scheduler serialisation (issue: #5761)
- #5898 Fix null-ref exception when track total hits is disabled (issue: #5892)
Deprecations
View the full list of issues and PRs
7.14.0-beta.1
Features & Enhancements
- #5728 Pre-flight product check
- #5731 NameValueCollection.ToQueryString performance optimisation (issue: #4952)
- #5740 Change default IMemoryStreamFactory
- #5780 Add support for dense vector fields (issue: #3836)
- #5755 Add readonly property to FS repository settings (issue: #5753)
- #5789 Support simple_pattern and simple_pattern_split tokenizers (issue: #5716)
- #5792 Add running state to data feed stats (issue: #5776)
- #5793 Add IO stats to node stats model (issue: #5776)
- #5801 Add match_only_text field (issue: #5776)
- #5802 Add keep_values gap policy (issue: #5776)
- #5803 Add cancelled property to TaskInfo (issue: #5776)
- #5812 Support _meta on ILM policy (issue: #5776)
- #5823 Add support for the migrate to data tiers API
- #5831 Support snapshot repository analysis API
- #5832 Support index pattern exclusion in CCR AutoFollow (issue: #5776)
- #5856 Support get async SQL search status API
- #5858 Support delete async SQL search API
- #5861 Support get async SQL search API
- #5869 Support async SQL searches
Performance
- #5865 Reduce allocations on some transport paths
Bug Fixes
- #5743 Fix weekly schedule deserialisation (issue: #5725)
- #5761 Fix discrepancies in Watcher API models which fail (de)serialization (issue: #5725)
- #5888 Fix hourly watcher scheduler serialisation (issue: #5761)
- #5898 Fix null-ref exception when track total hits is disabled (issue: #5892)