docarray
diff --git a/‎docarray/utils/filter.py‎
Lines changed: 32 additions & 5 deletions b/‎docarray/utils/filter.py‎
Lines changed: 32 additions & 5 deletions
diff --git a/‎tests/units/util/test_filter.py‎
Lines changed: 32 additions & 0 deletions b/‎tests/units/util/test_filter.py‎
Lines changed: 32 additions & 0 deletions
@@ -8,7 +8,7 @@
 
 
 def filter(
-    index: AnyDocumentArray,
+    docs: AnyDocumentArray,
     query: Union[str, Dict, List[Dict]],
 ) -> AnyDocumentArray:
     """
@@ -19,9 +19,36 @@ def filter(
 
     .. code-block:: python
 
-        TODO: fill it
+        from docarray import DocumentArray, BaseDocument
+        from docarray.documents import Text, Image
+        from docarray.util.filter import filter
 
-    :param index: the index of Documents to filter in
+
+        class MyDocument(BaseDocument):
+            caption: Text
+            image: Image
+            price: int
+
+
+        docs = DocumentArray[MyDocument](
+            [MyDocument(caption='A tiger in the jungle', image=Image(url='tigerphoto.png'), price=100),
+            MyDocument(caption='A swimming turtle', image=Image(url='turtlepic.png'), price=50),
+            MyDocument(caption='A couple birdwatching with binoculars', image=Image(url='binocularsphoto.png'), price=30)]
+        )
+        query = {
+            '$and': {
+                'image.url': {'$regex': 'photo'},
+                'price': {'$lte': 50},
+            }
+        }
+
+        results = filter(docs, query)
+        assert len(results) == 1
+        assert results[0].price == 30
+        assert results[0].caption == 'A couple birdwatching with binoculars'
+        assert results[0].image.url == 'binocularsphoto.png'
+
+    :param docs: the DocumentArray where to apply the filter
     :param query: the query to filter by
     :return: A DocumentArray containing the Documents
     inside DocumentArray that fullfil the filter conditions
@@ -31,6 +58,6 @@ def filter(
     if query:
         query = query if not isinstance(query, str) else json.loads(query)
         parser = QueryParser(query)
-        return DocumentArray(d for d in index if parser.evaluate(d))
+        return DocumentArray(d for d in docs if parser.evaluate(d))
     else:
-        return index
+        return docs
@@ -232,3 +232,35 @@ def test_logic_filter(docs, dict_api):
         }
     )
     assert len(result) == 3
+
+
+@pytest.mark.parametrize('dict_api', [True, False])
+def test_from_docstring(dict_api):
+    class MyDocument(BaseDocument):
+        caption: Text
+        image: Image
+        price: int
+
+    docs = DocumentArray[MyDocument](
+        [MyDocument(caption='A tiger in the jungle', image=Image(url='tigerphoto.png'), price=100),
+         MyDocument(caption='A swimming turtle', image=Image(url='turtlepic.png'), price=50),
+         MyDocument(caption='A couple birdwatching with binoculars', image=Image(url='binocularsphoto.png'), price=30)]
+    )
+
+    query = {
+        '$and': {
+            'image.url': {'$regex': 'photo'},
+            'price': {'$lte': 50},
+        }
+    }
+
+    if dict_api:
+        method = lambda query: filter(docs, query)
+    else:
+        method = lambda query: filter(docs, json.dumps(query))
+
+    results = method(query)
+    assert len(results) == 1
+    assert results[0].price == 30
+    assert results[0].caption == 'A couple birdwatching with binoculars'
+    assert results[0].image.url == 'binocularsphoto.png'