Delete documents by filter

[brunoocasali]

⚠️ This issue is generated, it means the examples and the namings do not necessarily correspond to the language of this repository.
Also, if you are a maintainer, feel free to add any clarification and instruction about this issue.

Sorry if this is already partially/completely implemented, feel free to let me know about the state of this issue in the repo.

Related to meilisearch/integration-guides#261

---

This issue is divided in two sections, first you need to make the implementation, second you must update the code-samples (no one likes a outdated docs, right?).

New implementation

Related to:

• issue: Delete and get documents by filter meilisearch#3477
• spec: Get and delete documents by filter specifications#236

It allows the user to use a filter expression to remove documents.

Since there is already a method called deleteDocuments(uids) in the SDKs, and this method is calling the route POST /indexes/:index_uid/documents/delete-batch, the requirements to implement the new way is to create a conditional internally to check the presence of the new parameter filters and then call the new method POST /indexes/:index_uid/documents/delete.
When the developer uses the old ids argument, it should keep calling the old implementation.

This will avoid any silent failures the users may find.

For example, in the Ruby SDK:

# Public: Delete documents from an index
#
# documents_ids - An array with document ids (deprecated, optional)
# filter - A hash containing a filter that should match documents. Available ONLY with Meilisearch v1.2 and newer (optional)
# 
# Returns a Task object.
def delete_documents(documents_ids = nil, filter: nil)
  if documents_ids
    http_post "/indexes/#{@uid}/documents/delete-batch", documents_ids
  else
    http_post "/indexes/#{@uid}/documents/delete", { filter: filter }
  end
end

Extra: Add inline documentation for the method, explaining the availability of the filter syntax only for Meilisearch v1.2 and newer.

Extra: Mark the document_ids parameter as deprecated. eg. @Deprecated('migration') on Java/Dart, Obsolete on C#, etc. Add a library if necessary.

Extra: Add a try/catch to detect the error and give the user a hint about the possibility of a version mismatch between the SDK version and the instance version. Check this PR for an example in JavaScript: meilisearch/meilisearch-js#1492

Extra: General recommendations:

• For languages where method overloading is available, use the overloading.
• For languages where a builder is available, use the builder pattern.

Code samples:

Inside of this file: .code-samples.meilisearch.yml:

1. Rename this key: delete_documents_1: to delete_documents_by_batch_1:
2. Create a new entry with this key delete_documents_by_filter_1: containing a call to the deleteDocuments method
   using the new behavior from the index movies using the filter param with this string "genres = action OR genres = adventure".

Use this as a reference if the previous description was not helpful:

  POST http://localhost:7700/indexes/movies/documents/delete
  with data: { "filter": "genres = action OR genres = adventure" }

Todo:

• Implement the deleteDocuments new behavior keeping the old behavior when possible.
• Update the code-samples according to this issue.