Add filter parameter on get_documents for Meilisearch v1.2 (#473)

Author: bidoubiwa

src/documents.rs

@@ -185,6 +185,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 +201,7 @@ impl<'a> DocumentsQuery<'a> {
             offset: None,
             limit: None,
             fields: None,
+            filter: None,
         }
     }
 
@@ -264,6 +272,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
@@ -304,8 +317,7 @@ impl<'a> DocumentsQuery<'a> {
 #[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};
 
@@ -407,6 +419,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(),

src/indexes.rs

@@ -1,7 +1,7 @@
 use crate::{
     client::Client,
     documents::{DocumentQuery, DocumentsQuery, DocumentsResults},
-    errors::Error,
+    errors::{Error, MeilisearchCommunicationError, MeilisearchError, MEILISEARCH_VERSION_HINT},
     request::*,
     search::*,
     task_info::TaskInfo,
@@ -466,6 +466,39 @@ impl Index {
         &self,
         documents_query: &DocumentsQuery<'_>,
     ) -> Result<DocumentsResults<T>, Error> {
+        if documents_query.filter.is_some() {
+            let url = format!("{}/indexes/{}/documents/fetch", self.client.host, self.uid);
+            return request::<(), &DocumentsQuery, DocumentsResults<T>>(
+                &url,
+                self.client.get_api_key(),
+                Method::Post {
+                    body: documents_query,
+                    query: (),
+                },
+                200,
+            )
+            .await
+            .map_err(|err| match err {
+                Error::MeilisearchCommunication(error) => {
+                    Error::MeilisearchCommunication(MeilisearchCommunicationError {
+                        status_code: error.status_code,
+                        url: error.url,
+                        message: Some(format!("{}.", MEILISEARCH_VERSION_HINT)),
+                    })
+                }
+                Error::Meilisearch(error) => Error::Meilisearch(MeilisearchError {
+                    error_code: error.error_code,
+                    error_link: error.error_link,
+                    error_type: error.error_type,
+                    error_message: format!(
+                        "{}\n{}.",
+                        error.error_message, MEILISEARCH_VERSION_HINT
+                    ),
+                }),
+                _ => err,
+            });
+        }
+
         let url = format!("{}/indexes/{}/documents", self.client.host, self.uid);
         request::<&DocumentsQuery, (), DocumentsResults<T>>(
             &url,

src/request.rs

@@ -1,4 +1,4 @@
-use crate::errors::{Error, MeilisearchError};
+use crate::errors::{Error, MeilisearchCommunicationError, MeilisearchError};
 use log::{error, trace, warn};
 use serde::{de::DeserializeOwned, Serialize};
 use serde_json::{from_str, to_string};
@@ -116,7 +116,7 @@ pub(crate) async fn request<
         body = "null".to_string();
     }
 
-    parse_response(status, expected_status_code, body)
+    parse_response(status, expected_status_code, body, url.to_string())
 }
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -214,7 +214,7 @@ pub(crate) async fn stream_request<
         body = "null".to_string();
     }
 
-    parse_response(status, expected_status_code, body)
+    parse_response(status, expected_status_code, body, url.to_string())
 }
 
 #[cfg(target_arch = "wasm32")]
@@ -318,9 +318,14 @@ pub(crate) async fn request<
 
     if let Some(t) = text.as_string() {
         if t.is_empty() {
-            parse_response(status, expected_status_code, String::from("null"))
+            parse_response(
+                status,
+                expected_status_code,
+                String::from("null"),
+                url.to_string(),
+            )
         } else {
-            parse_response(status, expected_status_code, t)
+            parse_response(status, expected_status_code, t, url.to_string())
         }
     } else {
         error!("Invalid response");
@@ -332,6 +337,7 @@ fn parse_response<Output: DeserializeOwned>(
     status_code: u16,
     expected_status_code: u16,
     body: String,
+    url: String,
 ) -> Result<Output, Error> {
     if status_code == expected_status_code {
         match from_str::<Output>(&body) {
@@ -345,16 +351,26 @@ fn parse_response<Output: DeserializeOwned>(
             }
         };
     }
-    // TODO: create issue where it is clear what the HTTP error is
-    // ParseError(Error("invalid type: null, expected struct MeilisearchError", line: 1, column: 4))
 
     warn!(
         "Expected response code {}, got {}",
         expected_status_code, status_code
     );
+
     match from_str::<MeilisearchError>(&body) {
         Ok(e) => Err(Error::from(e)),
-        Err(e) => Err(Error::ParseError(e)),
+        Err(e) => {
+            if status_code >= 400 {
+                return Err(Error::MeilisearchCommunication(
+                    MeilisearchCommunicationError {
+                        status_code,
+                        message: None,
+                        url,
+                    },
+                ));
+            }
+            Err(Error::ParseError(e))
+        }
     }
 }