Skip to content

Commit 7a28d15

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

File tree

2 files changed

+525
-14
lines changed

2 files changed

+525
-14
lines changed

‎docs/release-notes/breaking-changes.md

+177-8
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@ 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+
% ## Next version [elasticsearch-net-client-nextversion-breaking-changes]
1112

1213
% ::::{dropdown} Title of breaking change
1314
% Description of the breaking change.
@@ -16,11 +17,179 @@ Breaking changes can impact your Elastic applications, potentially disrupting no
1617
% **Action**<br> Steps for mitigating deprecation impact.
1718
% ::::
1819

19-
% ## 9.0.0 [elasticsearch-nett-client-900-breaking-changes]
20+
## 9.0.0 [elasticsearch-net-client-900-breaking-changes]
2021

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

0 commit comments

Comments
 (0)