UPGRADING.md

• Upgrading OpenSearch.Net & OpenSearch.Client
  • 1.x.y to 2.0.0
    • OpenSearch.Net
      • General
      • Bulk Action
      • DeleteByQuery Action
      • ReindexOnServer Action
      • Search Action
      • UpdateByQuery Action
      • Cat.Help Action
      • Cat.Indices Action
      • Cat.Master Action
      • Cat.Plugins Action
      • Cat.Recovery Action
      • Cluster.ExistsComponentTemplate Action
      • Cluster.Health Action
      • Cluster.PostVotingConfigExclusions Action
      • Cluster.Reroute Action
      • Features Namespace
      • Indices.AddBlock Action
      • Indices.Analyze Action
      • Indices.ClearCache Action
      • Indices.DeleteTemplateV2 Action
      • Indices.ExistsTemplate Action
      • Indices.GetTemplateV2 Action
      • Indices.PutTemplateV2 Action
      • Indices.ShardStores Action
      • Indices.Stats Action
      • Nodes.HotThreads Action
      • Nodes.Stats Action
      • Snapshot.CleanupRepository Action
      • Tasks.List Action
    • OpenSearch.Client
      • General
      • Bulk Action
      • UpdateByQuery Action
      • Cat.Help Action
      • Cat.Indices Action
      • Cat.Master Action
      • Cat.Plugins Action
      • Cluster.GetComponentTemplate Action
      • Cluster.Health Action
      • Cluster.PostVotingConfigExclusions Action
      • Cluster.Reroute Action
      • Cluster.Stats Action
      • Indices.GetComposableTemplate Action
      • Nodes.HotThreads Action
      • Nodes.Stats Action
      • Tasks.List Action

Upgrading OpenSearch.Net & OpenSearch.Client

1.x.y to 2.0.0

OpenSearch.Net

General

• Support for .NET Framework v4.6.1 has been removed, if you have a .NET Framework based project it is recommended to upgrade the project to target .NET Framework v4.7.2 or higher.
• The MasterTimeSpanout & ClusterManagerTimeSpanout parameters on all actions have been corrected to MasterTimeout and ClusterManagerTimeout respectively.
• The MasterTimeout parameters on all actions have been marked [Obsolete], please migrate to using ClusterManagerTimeout if your OpenSearch cluster is at least version 2.0.0 as MasterTimeout may be removed in future major versions.
• The ExpandWildcards enum is now attributed with [Flags] to allow combining of multiple values e.g. ExpandWildcards.Open | ExpandWildcards.Closed to match open and closed indexes but not hidden.
• The Bytes enum has been renamed to ByteUnit.
• All instances of the Routing parameter now accept an array of strings instead of a single string to better represent the underlying API that accepts comma-separated lists.
• The SortOrder enum has been moved from the OpenSearch.Client namespace to the OpenSearch.Net namespace.
• The TimeUnit enum has been moved from the OpenSearch.Client namespace to the OpenSearch.Net namespace. The Millisecond, Second, Minute, Hour and Day variants names have been pluralized to Milliseconds, Seconds, Minutes, Hours and Days respectively.

Bulk Action

• The TypeQueryString parameter has been renamed to simply Type.

DeleteByQuery Action

• The Slices parameter now accepts a string instead of a long as the API can also accept the string "auto".

ReindexOnServer Action

• The Slices parameter now accepts a string instead of a long as the API can also accept the string "auto".

Search Action

• The MinCompatibleShardNode parameter has been removed as it was never supported by OpenSearch.

UpdateByQuery Action

• The Slices parameter now accepts a string instead of a long as the API can also accept the string "auto".
• The VersionType parameter has been removed as it was never supported by OpenSearch.

Cat.Help Action

• The Help and SortByColumns parameters have been removed as they are unsupported by OpenSearch.

Cat.Indices Action

• The Health parameter now accepts a new HealthStatus enum instead of the Health enum. The values are identical and are now unified with other parts of the API that utilize the same enum.

Cat.Master Action

• The action has been marked [Obsolete], please migrate to using Cat.ClusterManager if your OpenSearch cluster is at least version 2.0.0 as Cat.Master may be removed in future major versions.

Cat.Plugins Action

• The IncludeBootstrap parameter has been removed as it was never supported by OpenSearch.

Cat.Recovery Action

• The IndexQueryString parameter has been renamed to simply Index.

Cluster.ExistsComponentTemplate Action

• This action has been removed in favour of the correctly named Cluster.ComponentTemplateExists action.

Cluster.Health Action

• The Level parameter now accepts a new ClusterHealthLevel enum instead of the Level enum. The values are the same except for the addition of the AwarenessAttributes value.
• The WaitForStatus parameter now accepts a new HealthStatus enum instead of the WaitForStatus enum. The values are identical and are now unified with other parts of the API that utilize the same enum.

Cluster.PostVotingConfigExclusions Action

• The NodeIds & NodeNames parameters now accept an array of strings instead of a single string to better represent the underlying API that accepts comma-separated lists.

Cluster.Reroute Action

• The Metric parameter has been changed from a string to an ClusterRerouteMetric enum.

Features Namespace

• The entire Features API namespace has been removed, there is no migration path as it was never supported by OpenSearch.

Indices.AddBlock Action

• The block parameter has been changed from a string to an IndexApiBlock enum.

Indices.Analyze Action

• The IndexQueryString parameter has been renamed to simply Index.

Indices.ClearCache Action

• The IndexQueryString parameter has been renamed to simply Index.

Indices.DeleteTemplateV2 Action

• This action has been removed in favour of the more descriptively named and typed Indices.DeleteComposableTemplate action.

Indices.ExistsTemplate Action

• This action has been removed due to confusing naming as it in the prior naming scheme it should have been TemplateExistsV2 because it should be used with composable index templates, however it could be confused with the legacy TemplateExists action. Please migrate to the correct action depending on your use case:
  • Indices.TemplateExists for legacy index templates, i.e. the /_template/{name} API.
  • Indices.ComposableTemplateExists for newer composable index templates, i.e. the /_index_template/{name} API.

Indices.GetTemplateV2 Action

• This action has been removed in favour of the more descriptively named and typed Indices.GetComposableTemplate action.

Indices.PutTemplateV2 Action

• This action has been removed in favour of the more descriptively named and typed Indices.PutComposableTemplate action.

Indices.ShardStores Action

• The Status parameter now takes an IndicesShardStoresStatus flag enum instead of a string array.

Indices.Stats Action

• The metric parameter has been changed from a string to an IndicesStatsMetric enum.

Nodes.HotThreads Action

• The ThreadType parameter has been renamed to just Type to match the query parameter it represents. Its corresponding ThreadType enum has been renamed to NodesSampleType.

Nodes.Stats Action

• The Groups parameter's type has been corrected from bool to string[] to match the API which expects a comma-separated list of groups.

Snapshot.CleanupRepository Action

• The PostData body parameter has been removed as the API does not expect a body to be sent.

Tasks.List Action

• The GroupBy parameter's GroupBy enum has been renamed to TasksGroupBy.

OpenSearch.Client

General

• The MasterTimeout parameters on all actions have been marked [Obsolete], please migrate to using ClusterManagerTimeout if your OpenSearch cluster is at least version 2.0.0 as MasterTimeout may be removed in future major versions.
• The ExpandWildcards enum is now attributed with [Flags] to allow combining of multiple values e.g. ExpandWildcards.Open | ExpandWildcards.Closed to match open and closed indexes but not hidden.
• The namespaced APIs exposed in IOpenSearchClient have each gained a corresponding interface and the types of the properties on IOpenSearchClient and OpenSearchClient have been changed from the concrete implementations to the matching interfaces. For example, IOpenSearchClient.Cluster was ClusterNamespace and now is IClusterNamespace.
• The Bytes enum has been renamed to ByteUnit.

Bulk Action

• The TypeQueryString parameter has been renamed to simply Type.

UpdateByQuery Action

• The VersionType parameter has been removed as it was never supported by OpenSearch.

Cat.Help Action

• The Help and SortByColumns parameters have been removed as they are unsupported by OpenSearch.

Cat.Indices Action

• The Health parameter now accepts a new HealthStatus enum instead of the Health enum. The values are identical and are now unified with other parts of the API that utilize the same enum.

Cat.Master Action

• The Cat.Master action has been marked [Obsolete], please migrate to using Cat.ClusterManager if your OpenSearch cluster is at least version 2.0.0 as Cat.Master may be removed in future major versions.

Cat.Plugins Action

• The IncludeBootstrap parameter of the Cat.Plugins action has been removed as it was never supported by OpenSearch.

Cluster.GetComponentTemplate Action

• The variant of this action accepting a template name has been corrected to only accept a single value rather than multiple as it was previously erroneously documented as accepting a comma-separated list. Attempting to use multiple names results in a server error.

Cluster.Health Action

• The Level parameter now accepts a new ClusterHealthLevel enum instead of the Level enum. The values are the same except for the addition of the AwarenessAttributes value.
• The WaitForStatus parameter now accepts a new HealthStatus enum instead of the WaitForStatus enum. The values are identical and are now unified with other parts of the API that utilize the same enum.
• The Status, Indices[<index>].Status, and Indices[<index>].Shards[<shard>].Status properties in the response object now return the HealthStatus enum instead of the Health enum. The values are identical and are now unified with other parts of the API that utilize the same enum.

Cluster.PostVotingConfigExclusions Action

• The NodeIds & NodeNames parameters now accept an array of strings instead of a single string to better represent the underlying API that accepts comma-separated lists.

Cluster.Reroute Action

• The Metric parameter has been changed from a string to an ClusterRerouteMetric enum.

Cluster.Stats Action

• The Nodes.OperatingSystem.PrettyNames property in the response object's item type has been renamed from ClusterOperatingSystemPrettyNane to ClusterOperatingSystemPrettyName to correct a spelling mistake.

Indices.GetComposableTemplate Action

• The variant of this action accepting a template name has been corrected to only accept a single value rather than multiple as it was previously erroneously documented as accepting a comma-separated list. Attempting to use multiple names results in a server error.

Nodes.HotThreads Action

• The ThreadType parameter has been renamed to just Type to match the query parameter it represents. Its corresponding ThreadType enum has been renamed to NodesSampleType.

Nodes.Stats Action

• The Groups parameter's type has been corrected from bool to string[] to match the cluster which expects a comma-separated list of groups.

Tasks.List Action

• The GroupBy parameter's GroupBy enum has been renamed to TasksGroupBy. The enum otherwise remains unchanged.