Skip to content

Commit 7af0a9f

Browse files
floberndflobernd
committed
Add release notes
1 parent 3900766 commit 7af0a9f

File tree

2 files changed

+508
-13
lines changed

2 files changed

+508
-13
lines changed

Diff for: ‎docs/release-notes/breaking-changes.md

+159-8
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,12 @@ mapped_pages:
55
---
66

77
# Elasticsearch .NET Client breaking changes [elasticsearch-net-client-breaking-changes]
8+
89
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](docs-content://deploy-manage/upgrade.md).
910

10-
% ## Next version [elasticsearch-nett-client-nextversion-breaking-changes]
11+
The 💥 icon indicates changes that are most likely breaking for users, whereas the ⚠️ icon indicates breaking changes that will not affect most users (e.g., changes in fluent descriptors that do not affect the lambda expression syntax).
12+
13+
% ## Next version [elasticsearch-net-client-nextversion-breaking-changes]
1114

1215
% ::::{dropdown} Title of breaking change
1316
% Description of the breaking change.
@@ -16,11 +19,159 @@ Breaking changes can impact your Elastic applications, potentially disrupting no
1619
% **Action**<br> Steps for mitigating deprecation impact.
1720
% ::::
1821

19-
% ## 9.0.0 [elasticsearch-nett-client-900-breaking-changes]
22+
## 9.0.0 [elasticsearch-net-client-900-breaking-changes]
2023

21-
% ::::{dropdown} Title of breaking change
22-
% Description of the breaking change.
23-
% For more information, check [PR #](PR link).
24-
% **Impact**<br> Impact of the breaking change.
25-
% **Action**<br> Steps for mitigating deprecation impact.
26-
% ::::
24+
### 1. 💥 Container types
25+
26+
Container types now use regular properties for their variants instead of static factory methods ([read more](index.md#900-elasticsearch-net-client-900-release-notes)).
27+
28+
This change primarily affects the `Query` and `Aggregation` types.
29+
30+
```csharp
31+
// 8.x
32+
new SearchRequest
33+
{
34+
Query = Query.MatchAll(
35+
new MatchAllQuery
36+
{
37+
}
38+
)
39+
};
40+
41+
// 9.0
42+
new SearchRequest
43+
{
44+
Query = new Query
45+
{
46+
MatchAll = new MatchAllQuery
47+
{
48+
}
49+
}
50+
};
51+
```
52+
53+
### 2. 💥 Removal of certain generic request descriptors
54+
55+
Removed the generic version of some request descriptors for which the corresponding requests do not contain inferrable properties.
56+
57+
These descriptors were generated unintentionally.
58+
59+
When migrating, the generic type parameter must be removed from the type, e.g., `AsyncSearchStatusRequestDescriptor<TDocument>` should become just `AsyncSearchStatusRequestDescriptor`.
60+
61+
List of affected descriptors:
62+
63+
- `AsyncQueryDeleteRequestDescriptor<TDocument>`
64+
- `AsyncQueryGetRequestDescriptor<TDocument>`
65+
- `AsyncSearchStatusRequestDescriptor<TDocument>`
66+
- `DatabaseConfigurationDescriptor<TDocument>`
67+
- `DatabaseConfigurationFullDescriptor<TDocument>`
68+
- `DeleteAsyncRequestDescriptor<TDocument>`
69+
- `DeleteAsyncSearchRequestDescriptor<TDocument>`
70+
- `DeleteDataFrameAnalyticsRequestDescriptor<TDocument>`
71+
- `DeleteGeoipDatabaseRequestDescriptor<TDocument>`
72+
- `DeleteIpLocationDatabaseRequestDescriptor<TDocument>`
73+
- `DeleteJobRequestDescriptor<TDocument>`
74+
- `DeletePipelineRequestDescriptor<TDocument>`
75+
- `DeleteScriptRequestDescriptor<TDocument>`
76+
- `DeleteSynonymRequestDescriptor<TDocument>`
77+
- `EqlDeleteRequestDescriptor<TDocument>`
78+
- `EqlGetRequestDescriptor<TDocument>`
79+
- `GetAsyncRequestDescriptor<TDocument>`
80+
- `GetAsyncSearchRequestDescriptor<TDocument>`
81+
- `GetAsyncStatusRequestDescriptor<TDocument>`
82+
- `GetDataFrameAnalyticsRequestDescriptor<TDocument>`
83+
- `GetDataFrameAnalyticsStatsRequestDescriptor<TDocument>`
84+
- `GetEqlStatusRequestDescriptor<TDocument>`
85+
- `GetGeoipDatabaseRequestDescriptor<TDocument>`
86+
- `GetIpLocationDatabaseRequestDescriptor<TDocument>`
87+
- `GetJobsRequestDescriptor<TDocument>`
88+
- `GetPipelineRequestDescriptor<TDocument>`
89+
- `GetRollupCapsRequestDescriptor<TDocument>`
90+
- `GetRollupIndexCapsRequestDescriptor<TDocument>`
91+
- `GetScriptRequestDescriptor<TDocument>`
92+
- `GetSynonymRequestDescriptor<TDocument>`
93+
- `IndexModifyDataStreamActionDescriptor<TDocument>`
94+
- `PreprocessorDescriptor<TDocument>`
95+
- `PutGeoipDatabaseRequestDescriptor<TDocument>`
96+
- `PutIpLocationDatabaseRequestDescriptor<TDocument>`
97+
- `PutScriptRequestDescriptor<TDocument>`
98+
- `PutSynonymRequestDescriptor<TDocument>`
99+
- `QueryVectorBuilderDescriptor<TDocument>`
100+
- `RankDescriptor<TDocument>`
101+
- `RenderSearchTemplateRequestDescriptor<TDocument>`
102+
- `SmoothingModelDescriptor<TDocument>`
103+
- `StartDataFrameAnalyticsRequestDescriptor<TDocument>`
104+
- `StartJobRequestDescriptor<TDocument>`
105+
- `StopDataFrameAnalyticsRequestDescriptor<TDocument>`
106+
- `StopJobRequestDescriptor<TDocument>`
107+
- `TokenizationConfigDescriptor<TDocument>`
108+
- `UpdateDataFrameAnalyticsRequestDescriptor<TDocument>`
109+
110+
### 3. 💥 Removal of certain descriptor constructors and related request APIs
111+
112+
Removed `(TDocument, IndexName)` descriptor constructors and related request APIs for all requests with `IndexName` and `Id` path parameters.
113+
114+
For example:
115+
116+
```csharp
117+
// 8.x
118+
public IndexRequestDescriptor(TDocument document, IndexName index, Id? id) { }
119+
public IndexRequestDescriptor(TDocument document, IndexName index) { }
120+
public IndexRequestDescriptor(TDocument document, Id? id) { }
121+
public IndexRequestDescriptor(TDocument document) { }
122+
123+
// 9.0
124+
public IndexRequestDescriptor(TDocument document, IndexName index, Id? id) { }
125+
public IndexRequestDescriptor(TDocument document, Id? id) { }
126+
public IndexRequestDescriptor(TDocument document) { }
127+
```
128+
129+
These overloads caused invocation ambiguities since both, `IndexName` and `Id` implement implicit conversion operators from `string`.
130+
131+
Alternative with same semantics:
132+
133+
```csharp
134+
// Descriptor constructor.
135+
new IndexRequestDescriptor(document, "my_index", Id.From(document));
136+
137+
// Request API method.
138+
await client.IndexAsync(document, "my_index", Id.From(document), ...);
139+
```
140+
141+
### 4. 💥 Date / Time / Duration values
142+
143+
In places where previously `long` or `double` was used to represent a date/time/duration value, `DateTimeOffset` or `TimeSpan` is now used instead.
144+
145+
### 5. 💥 `ExtendedBounds`
146+
147+
Removed `ExtendedBoundsDate`/`ExtendedBoundsDateDescriptor`, `ExtendedBoundsFloat`/`ExtendedBoundsFloatDescriptor`.
148+
149+
Replaced by `ExtendedBounds<T>`, `ExtendedBoundsOfFieldDateMathDescriptor`, and `ExtendedBoundsOfDoubleDescriptor`.
150+
151+
### 6. ⚠️ `Field.Format`
152+
153+
Removed `Field.Format` property and corresponding constructor and inferrer overloads.
154+
155+
This property has not been used for some time (replaced by the `FieldAndFormat` type).
156+
157+
### 7. ⚠️ `Field`/`Fields` semantics
158+
159+
`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`.
160+
161+
This makes implicit conversions to `Field` more user-friendly without requiring the null-forgiveness operator (`!`) ([read more](index#5-field-name-inference)).
162+
163+
### 8. ⚠️ `FieldValue`
164+
165+
Removed `FieldValue.IsLazyDocument`, `FieldValue.IsComposite`, and the corresponding members in the `FieldValue.ValueKind` enum.
166+
167+
These values have not been used for some time.
168+
169+
### 9. ⚠️ `FieldSort`
170+
171+
Removed static `FieldSort.Empty` member.
172+
173+
Sorting got reworked which makes this member obsolete ([read more](index#8-sorting)).
174+
175+
### 10. ⚠️ Descriptor types `class` -> `struct`
176+
177+
All descriptor types are now implemented as `struct` instead of `class`.

0 commit comments

Comments
 (0)