Deprecation warnings in 7.15.0 pre-releases

If you’re seeing this you likely received a deprecation warning from a 7.15.0 pre-release. Thanks for trying out in-development software

The v8.0.0 roadmap includes a list of breaking changes that will be implemented to make the Python Elasticsearch client easier to use and more discoverable. To make the upgrade from the 7.x client to the 8.0.0 client as smooth as possible for developers we’re deprecating options and usages that will be removed in either 8.0 or 9.0.

This also means that you’ll get an early preview for the great things to come in the 8.0.0 client starting in 7.x, which we’re pretty excited about!

Which APIs are effected?

All APIs will emit deprecation warnings for positional argument use in 7.15.0.

The following APIs will start emitting deprecation warnings regarding the body parameters. This list may change leading up to the 7.15.0 release.

• search
• index
• create
• update
• scroll
• clear_scroll
• search_mvt
• indices.create

The following APIs will start emitting deprecation warnings regarding doc_type parameters.

• nodes.hot_threads
• license.post_start_trial

What is being deprecated?

Starting in 7.15.0 the following features will be deprecated and are scheduled for removal in 9.0.0:

Positional arguments for APIs are deprecated

Using keyword arguments has always been recommended when using the client but now starting in 7.15.0 using any positional arguments will emit a deprecation warning.

# ✅ Supported usage:
es.search(index="index", ...)

# ❌ Deprecated usage:
es.search("index", ...)

The body parameter for APIs are deprecated

For JSON requests each field within the top-level JSON object will become it’s own parameter of the API with full type hinting

# ✅ New usage:
es.search(query={...})

# ❌ Deprecated usage:
es.search(body={"query": {...}})

For non-JSON requests or requests where the JSON body is itself an addressable object (like a document) each API will have the parameter renamed to a more semantic name:

# ✅ New usage:
es.index(document={...})

# ❌ Deprecated usage:
es.index(body={...})

The doc_type parameter for non-Index APIs

Using doc_type for APIs that aren’t related to indices or search is deprecated. Instead you should use the type parameter. See https://github.com/elastic/elasticsearch-py/pull/1713 for more context for this change.

For APIs that are related to indices or search the doc_type parameter isn’t deprecated client-side, however mapping types are deprecated in Elasticsearch and will be removed in 8.0.

# ✅ New usage:
es.nodes.hot_threads(type="cpu")

# ❌ Deprecated usage:
es.nodes.hot_threads(doc_type="cpu")

[sethmlarson]

@joshdevins The case of “make a JSON body an API request” is likely to be applicable elsewhere too (ingest.put_pipeline, transform.put_transform, search?) A raw JSON HTTP body is a transport-layer concept compared to “this is the index’s settings” and “this is the index’s mapping” being API-layer concepts.

The goal of moving away from params and body is for the client to become more than “named URLs”: being able to catch issues with your request before it’s sent to Elasticsearch (required parameters, parameter types, using API structures and enums) which means encoding Elasticsearch API information into function signatures.

I know usage of body is pervasive so I’m keeping the option to use body and params for almost all APIs in 8.x (search_template uses the params keyword) and when using these options the individual values will be picked out and expanded so they go through the same processing as if you’d passed the parameters directly:

client.indices.create(index="...", body={"settings": ..., "mappings": ...})
# in 8.0 will effectively be the same as:
client.indices.create(index="...", settings=..., mappings=...)

The downside of above is a DeprecationWarning will be issued for using body=....

If you have a JSON body and the API encodes parameters into the body you can also do:

client.indices.create(index="...", **raw_json)

This is effectively what the rewriting of body does for you, except here you’re doing it yourself and avoiding a DeprecationWarning. By doing this you’re basically blessing the JSON that you have as describing a request to Elasticsearch rather than a raw JSON body (since you can add other parameters to the JSON too like wait_for_active_shards, etc).

What are your thoughts on this?

[sethmlarson]

Going to close and lock this issue as 8.0 is now released. Any issues should be opened separately.