[bug]: onfusing error message in deleteBy operation & unclear migration path from v3 to v4

[lappemic]

Description

First, thank you for maintaining the Python client! I ran into some issues while trying to use the delete_by operation that I think could be improved to help other developers.

Current Behavior

When trying to delete records using delete_by, I get a Pydantic validation error that's quite cryptic:

pydantic_core._pydantic_core.ValidationError: 1 validation error for DeletedAtResponse
deletedAt
  Field required [type=missing, input_value={'updatedAt': '2024-11-15...'taskID': 1518117274002}, input_type=dict]

The error occurs with this simple code:

from algoliasearch.search_client import SearchClient

client = SearchClient.create('APP_ID', 'API_KEY')
index = client.init_index('INDEX_NAME')

index.delete_by({
    'filters': 'basics.company:Tesla'
})

Expected Behavior

1. Either the operation should work as documented, or
2. The error message could be more helpful in explaining what's wrong and how to fix it

Issues

1. Documentation seems to mix v3 and v4 API styles which is confusing for users
2. The error message doesn't clearly indicate if this is a client version mismatch, API incompatibility, or incorrect usage
3. The Pydantic validation error suggests an internal API response mapping issue, which shouldn't be exposed to users

Questions

1. Is there a recommended way to perform batch deletions by query in v4?
2. Is there a migration guide from v3 to v4 that covers common operations?

Environment

• Python version: 3.10
• algoliasearch version: 4.6.5
• OS: macOS

Let me know if you need any additional information.

Client

Search

Version

4.6.5

Relevant log output

Traceback (most recent call last):
  File "/Users/mi/repos/renewable-energy-jobs-scraper/delete-tesla-jobs.py", line 17, in <module>
    response = client.delete_by(
  File "/Users/mi/repos/renewable-energy-jobs-scraper/.venv/lib/python3.10/site-packages/algoliasearch/search/client.py", line 6922, in delete_by
    resp = self.delete_by_with_http_info(
  File "/Users/mi/repos/renewable-energy-jobs-scraper/.venv/lib/python3.10/site-packages/algoliasearch/search/client.py", line 6888, in delete_by_with_http_info
    return self._transporter.request(
  File "/Users/mi/repos/renewable-energy-jobs-scraper/.venv/lib/python3.10/site-packages/algoliasearch/http/transporter_sync.py", line 113, in request
    raise RequestException(content, response.status_code)
algoliasearch.http.exceptions.RequestException: Expecting a string (near 1:13)

[shortcuts]

Hey, thanks for opening the issue :)

Documentation seems to mix v3 and v4 API styles which is confusing for users

It seems like you are indeed using the v4 client with the v3 syntax/code snippets. We did some docs improvements last week (mostly around the search), that allows you to get more up to date results (cf screenshot) which should bring you to this page that contains the correct v4 snippet.

The error message doesn't clearly indicate if this is a client version mismatch, API incompatibility, or incorrect usage

Totally agree that this is pretty hard to comprehend, I'll see if I can improve it

When trying to delete records using delete_by, I get a Pydantic validation error that's quite cryptic:

This is actually an error on the API client side, it should expect an updated_at field and not deleted_at, which should be fixed by algolia/api-clients-automation#4107