Releases: elastic/elasticsearch-net
6.8.11
b62f824
stevejgordon
Steve Gordon
8.0.0-alpha.5
aa3100e
stevejgordon
Steve Gordon
New features
Breaking changes
- #6244 Simplify namespaces and responses types
- #6252 Rename
IndexManagementclient property toIndices
View the full list of issues and PRs
7.17.1
8b2b5be
stevejgordon
Steve Gordon
8.0.0-alpha.4
19f5dd5
stevejgordon
Steve Gordon
New Features
- #6174 Generate additional aggregations
- #6177 Add Task APIs
- #6200 Add graph explore API
- #6203 Add enrich APIs
- #6206 Add ILM APIs
- #6209 Add node APIs
- #6214 Add Searchable Snapshots APIs
- #6217 Add SLM APIs
- #6220 Add ingest APIs
- #6223 Add various indices APIs
- #6226 Add various global APIs
- #6229 Add additional global APIs
- #6232 Add CCR APIs
View the full list of issues and PRs
8.0.0-alpha.3
New APIs
- #6165 Add support for SQL search APIs
Breaking Changes
- #6161 After careful consideration, we have decided to remove the
IElasticsearchClientinterface which offer little value as it may break consumers when new API methods are added. Instead, we recommend using theElasticsearchClientdirectly.
8.0.0-alpha.2
New APIs
- #6138 Add support for EQL APIs
Misc
- #6157 Code generation now includes generic and non-generic descriptor variants where applicable. This provides more options when consuming the fluent API, allowing consumers to drop into a generic descriptor only when necessary. New client methods will be exposed in future releases to take advantage of and expose these new APIs.
7.17.0
Features & Enhancements
- #6070 Add
IgnoreUnmappedtoGeoDistanceQuery,GeoBoundingBoxQueryandGeoPolygon(issue: #6066) - #6094 Add shard_stats to primary index stats (issue: #6079)
- #6101 Support index template v2 APIs in NEST
Bug Fixes
- #6085 Support version on ingest pipelines (issue: #6082)
- #6088 Add missing fields for
IpProperty(issue: #6067) - #6090 Support deserialisation of simple scripts (issue: #5684)
- #6091 Add missing
TermVectorOption(issue: #6078) - #6095 Update boxplot to handle non-numeric values (issue: #6050)
- #6098 Move explain to body in search template API (issue: #5040)
Breaking Changes
To align with naming elsewhere during the implementation of NEST APIs for index template v2, some of the low-level client types and methods have been renamed:
- ExistsIndexTemplateRequestParameters => IndexTemplateV2ExistsRequestParameters
- ExistsTemplateForAll => TemplateV2ExistsForAll
- ExistsTemplateForAllAsync => TemplateV2ExistsForAllAsync
View the full list of issues and PRs
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.