Merge #467

467: Changes related to the next Meilisearch release (v1.2.0) r=bidoubiwa a=meili-bot

Related to this issue: meilisearch/integration-guides#261

This PR:
- gathers the changes related to the next Meilisearch release (v1.2.0) so that this package is ready when the official release is out.
- should pass the tests against the [latest pre-release of Meilisearch](https://github.com/meilisearch/meilisearch/releases).
- might eventually contain test failures until the Meilisearch v1.2.0 is out.

⚠️ This PR should NOT be merged until the next release of Meilisearch (v1.2.0) is out.

_This PR is auto-generated for the [pre-release week](https://github.com/meilisearch/integration-guides/blob/main/resources/pre-release-week.md) purpose._


Co-authored-by: meili-bot <[email protected]>
Co-authored-by: Charlotte Vermandel <[email protected]>

Author: 3 people

src/documents.rs

@@ -1,3 +1,4 @@
+use crate::task_info::TaskInfo;
 use async_trait::async_trait;
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
 
@@ -185,6 +186,13 @@ pub struct DocumentsQuery<'a> {
     /// The fields that should appear in the documents. By default all of the fields are present.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub fields: Option<Vec<&'a str>>,
+
+    /// Filters to apply.
+    ///
+    /// Available since v1.2 of Meilisearch
+    /// Read the [dedicated guide](https://docs.meilisearch.com/reference/features/filtering.html) to learn the syntax.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub filter: Option<&'a str>,
 }
 
 impl<'a> DocumentsQuery<'a> {
@@ -194,6 +202,7 @@ impl<'a> DocumentsQuery<'a> {
             offset: None,
             limit: None,
             fields: None,
+            filter: None,
         }
     }
 
@@ -264,6 +273,11 @@ impl<'a> DocumentsQuery<'a> {
         self
     }
 
+    pub fn with_filter<'b>(&'b mut self, filter: &'a str) -> &'b mut DocumentsQuery<'a> {
+        self.filter = Some(filter);
+        self
+    }
+
     /// Execute the get documents query.
     ///
     /// # Example
@@ -301,11 +315,39 @@ impl<'a> DocumentsQuery<'a> {
     }
 }
 
+#[derive(Debug, Clone, Serialize)]
+pub struct DocumentDeletionQuery<'a> {
+    #[serde(skip_serializing)]
+    pub index: &'a Index,
+
+    /// Filters to apply.
+    ///
+    /// Read the [dedicated guide](https://docs.meilisearch.com/reference/features/filtering.html) to learn the syntax.
+    pub filter: Option<&'a str>,
+}
+
+impl<'a> DocumentDeletionQuery<'a> {
+    pub fn new(index: &Index) -> DocumentDeletionQuery {
+        DocumentDeletionQuery {
+            index,
+            filter: None,
+        }
+    }
+
+    pub fn with_filter<'b>(&'b mut self, filter: &'a str) -> &'b mut DocumentDeletionQuery<'a> {
+        self.filter = Some(filter);
+        self
+    }
+
+    pub async fn execute<T: DeserializeOwned + 'static>(&self) -> Result<TaskInfo, Error> {
+        self.index.delete_documents_with(self).await
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{client::*, indexes::*};
-    use ::meilisearch_sdk::documents::IndexConfig;
+    use crate::{client::*, errors::*, indexes::*};
     use meilisearch_test_macro::meilisearch_test;
     use serde::{Deserialize, Serialize};
 
@@ -371,7 +413,6 @@ mod tests {
     #[meilisearch_test]
     async fn test_get_documents_with_execute(client: Client, index: Index) -> Result<(), Error> {
         setup_test_index(&client, &index).await?;
-        // let documents = index.get_documents(None, None, None).await.unwrap();
         let documents = DocumentsQuery::new(&index)
             .with_limit(1)
             .with_offset(1)
@@ -387,6 +428,66 @@ mod tests {
         Ok(())
     }
 
+    #[meilisearch_test]
+    async fn test_delete_documents_with(client: Client, index: Index) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+        index
+            .set_filterable_attributes(["id"])
+            .await?
+            .wait_for_completion(&client, None, None)
+            .await?;
+
+        let mut query = DocumentDeletionQuery::new(&index);
+        query.with_filter("id = 1");
+        index
+            .delete_documents_with(&query)
+            .await?
+            .wait_for_completion(&client, None, None)
+            .await?;
+        let document_result = index.get_document::<MyObject>("1").await;
+
+        match document_result {
+            Ok(_) => panic!("The test was expecting no documents to be returned but got one."),
+            Err(e) => match e {
+                Error::Meilisearch(err) => {
+                    assert_eq!(err.error_code, ErrorCode::DocumentNotFound);
+                }
+                _ => panic!("The error was expected to be a Meilisearch error, but it was not."),
+            },
+        }
+
+        Ok(())
+    }
+
+    #[meilisearch_test]
+    async fn test_delete_documents_with_filter_not_filterable(
+        client: Client,
+        index: Index,
+    ) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+
+        let mut query = DocumentDeletionQuery::new(&index);
+        query.with_filter("id = 1");
+        let error = index
+            .delete_documents_with(&query)
+            .await?
+            .wait_for_completion(&client, None, None)
+            .await?;
+
+        let error = error.unwrap_failure();
+
+        assert!(matches!(
+            error,
+            MeilisearchError {
+                error_code: ErrorCode::InvalidDocumentFilter,
+                error_type: ErrorType::InvalidRequest,
+                ..
+            }
+        ));
+
+        Ok(())
+    }
+
     #[meilisearch_test]
     async fn test_get_documents_with_only_one_param(
         client: Client,
@@ -407,6 +508,116 @@ mod tests {
         Ok(())
     }
 
+    #[meilisearch_test]
+    async fn test_get_documents_with_filter(client: Client, index: Index) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+
+        index
+            .set_filterable_attributes(["id"])
+            .await
+            .unwrap()
+            .wait_for_completion(&client, None, None)
+            .await
+            .unwrap();
+
+        let documents = DocumentsQuery::new(&index)
+            .with_filter("id = 1")
+            .execute::<MyObject>()
+            .await?;
+
+        assert_eq!(documents.results.len(), 1);
+
+        Ok(())
+    }
+
+    #[meilisearch_test]
+    async fn test_get_documents_with_error_hint() -> Result<(), Error> {
+        let url = option_env!("MEILISEARCH_URL").unwrap_or("http://localhost:7700");
+        let client = Client::new(format!("{}/hello", url), Some("masterKey"));
+        let index = client.index("test_get_documents_with_filter_wrong_ms_version");
+
+        let documents = DocumentsQuery::new(&index)
+            .with_filter("id = 1")
+            .execute::<MyObject>()
+            .await;
+
+        let error = documents.unwrap_err();
+
+        let message = Some("Hint: It might not be working because you're not up to date with the Meilisearch version that updated the get_documents_with method.".to_string());
+        let url = "http://localhost:7700/hello/indexes/test_get_documents_with_filter_wrong_ms_version/documents/fetch".to_string();
+        let status_code = 404;
+        let displayed_error = "MeilisearchCommunicationError: The server responded with a 404. Hint: It might not be working because you're not up to date with the Meilisearch version that updated the get_documents_with method.\nurl: http://localhost:7700/hello/indexes/test_get_documents_with_filter_wrong_ms_version/documents/fetch";
+
+        match &error {
+            Error::MeilisearchCommunication(error) => {
+                assert_eq!(error.status_code, status_code);
+                assert_eq!(error.message, message);
+                assert_eq!(error.url, url);
+            }
+            _ => panic!("The error was expected to be a MeilisearchCommunicationError error, but it was not."),
+        };
+        assert_eq!(format!("{}", error), displayed_error);
+
+        Ok(())
+    }
+
+    #[meilisearch_test]
+    async fn test_get_documents_with_error_hint_meilisearch_api_error(
+        index: Index,
+        client: Client,
+    ) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+
+        let error = DocumentsQuery::new(&index)
+            .with_filter("id = 1")
+            .execute::<MyObject>()
+            .await
+            .unwrap_err();
+
+        let message = "Attribute `id` is not filterable. This index does not have configured filterable attributes.
+1:3 id = 1
+Hint: It might not be working because you're not up to date with the Meilisearch version that updated the get_documents_with method.".to_string();
+        let displayed_error = "Meilisearch invalid_request: invalid_document_filter: Attribute `id` is not filterable. This index does not have configured filterable attributes.
+1:3 id = 1
+Hint: It might not be working because you're not up to date with the Meilisearch version that updated the get_documents_with method.. https://docs.meilisearch.com/errors#invalid_document_filter";
+
+        match &error {
+            Error::Meilisearch(error) => {
+                assert_eq!(error.error_message, message);
+            }
+            _ => panic!("The error was expected to be a MeilisearchCommunicationError error, but it was not."),
+        };
+        assert_eq!(format!("{}", error), displayed_error);
+
+        Ok(())
+    }
+
+    #[meilisearch_test]
+    async fn test_get_documents_with_invalid_filter(
+        client: Client,
+        index: Index,
+    ) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+
+        // Does not work because `id` is not filterable
+        let error = DocumentsQuery::new(&index)
+            .with_filter("id = 1")
+            .execute::<MyObject>()
+            .await
+            .unwrap_err();
+
+        assert!(matches!(
+            error,
+            Error::Meilisearch(MeilisearchError {
+                error_code: ErrorCode::InvalidDocumentFilter,
+                error_type: ErrorType::InvalidRequest,
+                ..
+            })
+        ));
+
+        Ok(())
+    }
+
     #[meilisearch_test]
     async fn test_settings_generated_by_macro(client: Client, index: Index) -> Result<(), Error> {
         setup_test_index(&client, &index).await?;

src/errors.rs

@@ -11,6 +11,8 @@ pub enum Error {
     /// Also check out: <https://github.com/meilisearch/Meilisearch/blob/main/meilisearch-error/src/lib.rs>
     #[error(transparent)]
     Meilisearch(#[from] MeilisearchError),
+    #[error(transparent)]
+    MeilisearchCommunication(#[from] MeilisearchCommunicationError),
     /// There is no Meilisearch server listening on the [specified host]
     /// (../client/struct.Client.html#method.new).
     #[error("The Meilisearch server can't be reached.")]
@@ -65,6 +67,30 @@ pub enum Error {
     InvalidUuid4Version,
 }
 
+#[derive(Debug, Clone, Deserialize, Error)]
+#[serde(rename_all = "camelCase")]
+
+pub struct MeilisearchCommunicationError {
+    pub status_code: u16,
+    pub message: Option<String>,
+    pub url: String,
+}
+
+impl std::fmt::Display for MeilisearchCommunicationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "MeilisearchCommunicationError: The server responded with a {}.",
+            self.status_code
+        )?;
+        if let Some(message) = &self.message {
+            write!(f, " {}", message)?;
+        }
+        write!(f, "\nurl: {}", self.url)?;
+        Ok(())
+    }
+}
+
 #[derive(Debug, Clone, Deserialize, Error)]
 #[serde(rename_all = "camelCase")]
 #[error("Meilisearch {}: {}: {}. {}", .error_type, .error_code, .error_message, .error_link)]
@@ -162,6 +188,8 @@ pub enum ErrorCode {
     InvalidIndexOffset,
     InvalidIndexLimit,
     InvalidIndexPrimaryKey,
+    InvalidDocumentFilter,
+    MissingDocumentFilter,
     InvalidDocumentFields,
     InvalidDocumentLimit,
     InvalidDocumentOffset,
@@ -234,6 +262,8 @@ pub enum ErrorCode {
     Unknown,
 }
 
+pub const MEILISEARCH_VERSION_HINT: &str = "Hint: It might not be working because you're not up to date with the Meilisearch version that updated the get_documents_with method";
+
 impl std::fmt::Display for ErrorCode {
     fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::result::Result<(), std::fmt::Error> {
         write!(
@@ -311,6 +341,28 @@ mod test {
 
         assert_eq!(error.to_string(), ("Meilisearch internal: index_creation_failed: The cool error message.. https://the best link eveer"));
 
+        let error: MeilisearchCommunicationError = MeilisearchCommunicationError {
+            status_code: 404,
+            message: Some("Hint: something.".to_string()),
+            url: "http://localhost:7700/something".to_string(),
+        };
+
+        assert_eq!(
+            error.to_string(),
+            ("MeilisearchCommunicationError: The server responded with a 404. Hint: something.\nurl: http://localhost:7700/something")
+        );
+
+        let error: MeilisearchCommunicationError = MeilisearchCommunicationError {
+            status_code: 404,
+            message: None,
+            url: "http://localhost:7700/something".to_string(),
+        };
+
+        assert_eq!(
+            error.to_string(),
+            ("MeilisearchCommunicationError: The server responded with a 404.\nurl: http://localhost:7700/something")
+        );
+
         let error = Error::UnreachableServer;
         assert_eq!(
             error.to_string(),