Elasticsearch .NET Client breaking changes
Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch .NET Client breaking changes and take the necessary steps to mitigate any issues. To learn how to upgrade, check Upgrade.
- 1. Container types
- 2. Removal of certain generic request descriptors
- 3. Removal of certain descriptor constructors and related request APIs
- 4. Date / Time / Duration values
- 5.
ExtendedBounds - 6.
Field.Format - 7.
Field/Fieldssemantics - 8.
FieldValue - 9.
FieldSort - 10. Descriptor types
class->struct
Impact: High.
Container types now use regular properties for their variants instead of static factory methods (read more).
This change primarily affects the Query and Aggregation types.
// 8.x
new SearchRequest
{
Query = Query.MatchAll(
new MatchAllQuery
{
}
)
};
// 9.0
new SearchRequest
{
Query = new Query
{
MatchAll = new MatchAllQuery
{
}
}
};
Previously required methods like e.g. TryGet<TVariant>(out) have been removed.
The new recommended way of inspecting container types is to use simple pattern matching:
var query = new Query();
if (query.Nested is { } nested)
{
// We have a nested query.
}
Impact: High.
Removed the generic version of some request descriptors for which the corresponding requests do not contain inferrable properties.
These descriptors were generated unintentionally.
When migrating, the generic type parameter must be removed from the type, e.g., AsyncSearchStatusRequestDescriptor<TDocument> should become just AsyncSearchStatusRequestDescriptor.
List of affected descriptors:
AsyncQueryDeleteRequestDescriptor<TDocument>AsyncQueryGetRequestDescriptor<TDocument>AsyncSearchStatusRequestDescriptor<TDocument>DatabaseConfigurationDescriptor<TDocument>DatabaseConfigurationFullDescriptor<TDocument>DeleteAsyncRequestDescriptor<TDocument>DeleteAsyncSearchRequestDescriptor<TDocument>DeleteDataFrameAnalyticsRequestDescriptor<TDocument>DeleteGeoipDatabaseRequestDescriptor<TDocument>DeleteIpLocationDatabaseRequestDescriptor<TDocument>DeleteJobRequestDescriptor<TDocument>DeletePipelineRequestDescriptor<TDocument>DeleteScriptRequestDescriptor<TDocument>DeleteSynonymRequestDescriptor<TDocument>EqlDeleteRequestDescriptor<TDocument>EqlGetRequestDescriptor<TDocument>GetAsyncRequestDescriptor<TDocument>GetAsyncSearchRequestDescriptor<TDocument>GetAsyncStatusRequestDescriptor<TDocument>GetDataFrameAnalyticsRequestDescriptor<TDocument>GetDataFrameAnalyticsStatsRequestDescriptor<TDocument>GetEqlStatusRequestDescriptor<TDocument>GetGeoipDatabaseRequestDescriptor<TDocument>GetIpLocationDatabaseRequestDescriptor<TDocument>GetJobsRequestDescriptor<TDocument>GetPipelineRequestDescriptor<TDocument>GetRollupCapsRequestDescriptor<TDocument>GetRollupIndexCapsRequestDescriptor<TDocument>GetScriptRequestDescriptor<TDocument>GetSynonymRequestDescriptor<TDocument>IndexModifyDataStreamActionDescriptor<TDocument>PreprocessorDescriptor<TDocument>PutGeoipDatabaseRequestDescriptor<TDocument>PutIpLocationDatabaseRequestDescriptor<TDocument>PutScriptRequestDescriptor<TDocument>PutSynonymRequestDescriptor<TDocument>QueryVectorBuilderDescriptor<TDocument>RankDescriptor<TDocument>RenderSearchTemplateRequestDescriptor<TDocument>SmoothingModelDescriptor<TDocument>StartDataFrameAnalyticsRequestDescriptor<TDocument>StartJobRequestDescriptor<TDocument>StopDataFrameAnalyticsRequestDescriptor<TDocument>StopJobRequestDescriptor<TDocument>TokenizationConfigDescriptor<TDocument>UpdateDataFrameAnalyticsRequestDescriptor<TDocument>
Impact: High.
Removed (TDocument, IndexName) descriptor constructors and related request APIs for all requests with IndexName and Id path parameters.
For example:
// 8.x
public IndexRequestDescriptor(TDocument document, IndexName index, Id? id) { }
public IndexRequestDescriptor(TDocument document, IndexName index) { }
public IndexRequestDescriptor(TDocument document, Id? id) { }
public IndexRequestDescriptor(TDocument document) { }
// 9.0
public IndexRequestDescriptor(TDocument document, IndexName index, Id? id) { }
public IndexRequestDescriptor(TDocument document, Id? id) { }
public IndexRequestDescriptor(TDocument document) { }
These overloads caused invocation ambiguities since both, IndexName and Id implement implicit conversion operators from string.
Alternative with same semantics:
// Descriptor constructor.
new IndexRequestDescriptor(document, "my_index", Id.From(document));
// Request API method.
await client.IndexAsync(document, "my_index", Id.From(document), ...);
Impact: High.
In places where previously long or double was used to represent a date/time/duration value, DateTimeOffset or TimeSpan is now used instead.
Impact: High.
Removed ExtendedBoundsDate/ExtendedBoundsDateDescriptor, ExtendedBoundsFloat/ExtendedBoundsFloatDescriptor.
Replaced by ExtendedBounds<T>, ExtendedBoundsOfFieldDateMathDescriptor, and ExtendedBoundsOfDoubleDescriptor.
Impact: Low.
Removed Field.Format property and corresponding constructor and inferrer overloads.
This property has not been used for some time (replaced by the FieldAndFormat type).
Impact: Low.
Field/Fields static factory methods and conversion operators no longer return nullable references but throw exceptions instead (Field) if the input string/Expression/PropertyInfo argument is null.
This makes implicit conversions to Field more user-friendly without requiring the null-forgiveness operator (!) (read more).
Impact: Low.
Removed FieldValue.IsLazyDocument, FieldValue.IsComposite, and the corresponding members in the FieldValue.ValueKind enum.
These values have not been used for some time.
Impact: High.
Removed FieldSort parameterless constructor.
Please use the new constructor instead:
public FieldSort(Elastic.Clients.Elasticsearch.Field field)
Impact: Low.
Removed static FieldSort.Empty member.
Sorting got reworked which makes this member obsolete (read more).
Impact: Low.
All descriptor types are now implemented as struct instead of class.