Add metadata query functionality (#574)

sujaygarlanka · web-flow · commit 228c6a92e1de · 2021-02-05T16:05:57.000-05:00
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -3,6 +3,13 @@
 Release History
 ---------------
 
+Next Release
+++++++++
+
+**New Features and Enhancements:**
+
+- Add metadata query functionality (`#574 <https://github.com/box/box-python-sdk/pull/574>`_)
+
 2.11.0 (2021-01-11)
 ++++++++
 
diff --git a/boxsdk/object/search.py b/boxsdk/object/search.py
@@ -6,6 +6,7 @@
 
 from .base_endpoint import BaseEndpoint
 from ..pagination.limit_offset_based_object_collection import LimitOffsetBasedObjectCollection
+from ..pagination.marker_based_object_collection import MarkerBasedObjectCollection
 from ..util.api_call_decorator import api_call
 from ..util.text_enum import TextEnum
 
@@ -310,3 +311,75 @@ def query(
             additional_params=additional_params,
             return_full_pages=False,
         )
+
+    @api_call
+    def metadata_query(self, from_template, ancestor_folder_id, query=None, query_params=None, use_index=None, order_by=None,
+                       marker=None, limit=None, fields=None):
+        # pylint: disable=arguments-differ
+        """Query Box items by their metadata.
+
+        :param from_template:
+            The template used in the query. Must be in the form scope.templateKey.
+        :type from_template:
+            `unicode`
+        :param ancestor_folder_id:
+            The folder_id to which to restrain the query
+        :type ancestor_folder_id:
+            `unicode`
+        :param query:
+            The logical expression of the query
+        :type query:
+            `unicode` or None
+        :param query_params:
+            Required if query present. The arguments for the query.
+        :type query_params:
+            `dict` or None
+        :param use_index:
+            The name of the index to use
+        :type use_index:
+            `unicode` or None
+        :param order_by:
+            The field_key(s) to order on and the corresponding direction(s)
+        :type order_by:
+            `list` of `dict`
+        :param marker:
+            The marker to use for requesting the next page
+        :type marker:
+            `unicode` or None
+        :param limit:
+            Max results to return for a single request (0-100 inclusive)
+        :type limit:
+            `int`
+        :param fields:
+            List of fields to request
+        :type fields:
+            `Iterable` of `unicode` or None
+        :returns:
+            An iterator of the item search results
+        :rtype:
+            :class:`BoxObjectCollection`
+        """
+        url = super(Search, self).get_url('metadata_queries/execute_read')
+        data = {
+            'from': from_template,
+            'ancestor_folder_id': ancestor_folder_id
+        }
+        if query is not None:
+            data['query'] = query
+        if query_params is not None:
+            data['query_params'] = query_params
+        if use_index is not None:
+            data['use_index'] = use_index
+        if order_by is not None:
+            data['order_by'] = order_by
+
+        return MarkerBasedObjectCollection(
+            session=self._session,
+            url=url,
+            limit=limit,
+            marker=marker,
+            fields=fields,
+            additional_params=data,
+            return_full_pages=False,
+            use_post=True
+        )
diff --git a/boxsdk/pagination/box_object_collection.py b/boxsdk/pagination/box_object_collection.py
@@ -2,6 +2,7 @@
 
 from __future__ import unicode_literals
 
+import json
 import sys
 from abc import ABCMeta, abstractmethod
 
@@ -42,6 +43,7 @@ def __init__(
             fields=None,
             additional_params=None,
             return_full_pages=False,
+            use_post=False
     ):
         """
         :param session:
@@ -71,6 +73,11 @@ def __init__(
             call to next(). If False, the iterator will return a single Box object on each next() call.
         :type return_full_pages:
             `bool`
+        :param use_post:
+            If True, then the returned iterator will make POST requests with all the data in the body on each
+            call to next(). If False, the iterator will make GET requets with all the data as query params on each call to next().
+        :type use_post:
+            `bool`
         """
         super(BoxObjectCollection, self).__init__()
         self._session = session
@@ -81,6 +88,7 @@ def __init__(
         self._return_full_pages = return_full_pages
         self._has_retrieved_all_items = False
         self._all_items = None
+        self._use_post = use_post
 
     def next(self):
         """
@@ -135,12 +143,17 @@ def _load_next_page(self):
         params = {}
         if self._limit is not None:
             params['limit'] = self._limit
-        if self._fields:
-            params['fields'] = ','.join(self._fields)
         if self._additional_params:
             params.update(self._additional_params)
         params.update(self._next_page_pointer_params())
-        box_response = self._session.get(self._url, params=params)
+        if self._use_post:
+            if self._fields:
+                params['fields'] = self._fields
+            box_response = self._session.post(self._url, data=json.dumps(params), headers={b'Content-Type': b'application/json'})
+        else:
+            if self._fields:
+                params['fields'] = ','.join(self._fields)
+            box_response = self._session.get(self._url, params=params)
         return box_response.json()
 
     @abstractmethod
diff --git a/boxsdk/pagination/marker_based_object_collection.py b/boxsdk/pagination/marker_based_object_collection.py
@@ -23,6 +23,7 @@ def __init__(
             return_full_pages=False,
             marker=None,
             supports_limit_offset_paging=False,
+            use_post=False
     ):
         """
         :param marker:
@@ -34,6 +35,11 @@ def __init__(
             the endpoints that support both require an special extra request parameter.
         :type supports_limit_offset_paging:
             `bool`
+        :param use_post:
+            If True, then the returned iterator will make POST requests with all the data in the body on each
+            call to next(). If False, the iterator will make GET requets with all the data as query params on each call to next().
+        :type use_post:
+            `bool`
         """
         super(MarkerBasedObjectCollection, self).__init__(
             session,
@@ -42,6 +48,7 @@ def __init__(
             fields=fields,
             additional_params=additional_params,
             return_full_pages=return_full_pages,
+            use_post=use_post
         )
         self._marker = marker
         self._supports_limit_offset_paging = supports_limit_offset_paging
diff --git a/docs/usage/search.md b/docs/usage/search.md
@@ -1,8 +1,11 @@
 Search
 ======
 
-The search endpoint provides a powerful way of finding items that are accessible by a single user or an entire 
-enterprise. Leverage the parameters listed below to generate targeted advanced searches.
+Search provides a powerful way of finding items that are accessible by a single user or an entire 
+enterprise.
+
+- [Search for Content](#search-for-content)
+- [Metadata Query](#metadata-query)
 
 Search for Content
 ------------------
@@ -46,3 +49,39 @@ client.search().query(None, limit=100, offset=0, metadata_filters=metadata_searc
 [metadata_search_filters]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilters
 [add_value_based_filter]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilter.add_value_based_filter
 [add_filter]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilters.add_filter
+
+Metadata Query
+--------------
+To search using SQL-like syntax to return items that match specific metadata, call `search.metadata_query(from_template, ancestor_folder_id, query=None, query_params=None, use_index=None, order_by=None, marker=None, limit=None, fields=None)` 
+
+By default, this method returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the fields parameter.
+
+```python
+from_template = 'enterprise_12345.someTemplate'
+ancestor_folder_id = '5555'
+query = 'amount >= :arg'
+query_params = {'arg': 100}
+use_index = 'amountAsc'
+order_by = [
+    {
+        'field_key': 'amount',
+        'direction': 'asc'
+    }
+]
+fields = ['type', 'id', 'name', 'metadata.enterprise_67890.catalogImages.$parent']
+limit = 2
+marker = 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKs'
+items = client.search().metadata_query(
+        from_template,
+        ancestor_folder_id,
+        query,
+        query_params,
+        use_index,
+        order_by,
+        marker,
+        limit,
+        fields
+    )
+for item in items:
+    print('The item ID is {0} and the item name is {1}'.format(item.id, item.name))
+```
diff --git a/test/unit/object/test_search.py b/test/unit/object/test_search.py
@@ -6,6 +6,7 @@
 
 import pytest
 
+from boxsdk.config import API
 from boxsdk.object.file import File
 from boxsdk.object.user import User
 from boxsdk.object.search import MetadataSearchFilters, MetadataSearchFilter, SearchScope, TrashContent
@@ -78,6 +79,48 @@ def search_response():
     }
 
 
+@pytest.fixture
+def metadata_query_response():
+    return {
+        'entries': [
+            {
+                'type': 'file',
+                'id': '1244738582',
+                'name': 'Very Important.docx',
+                'metadata': {
+                    'enterprise_67890': {
+                        'catalogImages': {
+                            '$parent': 'file_50347290',
+                            '$version': 2,
+                            '$template': 'catalogImages',
+                            '$scope': 'enterprise_67890',
+                            'photographer': 'Bob Dylan'
+                        }
+                    }
+                }
+            },
+            {
+                'type': 'folder',
+                'id': '124242482',
+                'name': 'Also Important.docx',
+                'metadata': {
+                    'enterprise_67890': {
+                        'catalogImages': {
+                            '$parent': 'file_50427291',
+                            '$version': 2,
+                            '$template': 'catalogImages',
+                            '$scope': 'enterprise_67890',
+                            'photographer': 'Bob Dylan'
+                        }
+                    }
+                }
+            }
+        ],
+        'limit': 2,
+        'next_marker': ''
+    }
+
+
 class Matcher(object):
     def __init__(self, compare, some_obj):
         self.compare = compare
@@ -257,6 +300,61 @@ def test_query_with_owner_users(
     )
 
 
+def test_metadata_query(
+        mock_box_session,
+        make_mock_box_request,
+        test_search,
+        metadata_query_response
+):
+    # pylint:disable=redefined-outer-name
+    expected_url = '{0}/metadata_queries/execute_read'.format(API.BASE_API_URL)
+    from_template = 'enterprise_12345.someTemplate'
+    ancestor_folder_id = '5555'
+    query = 'amount >= :arg'
+    query_params = {'arg': 100}
+    use_index = 'amountAsc'
+    order_by = [
+        {
+            'field_key': 'amount',
+            'direction': 'asc'
+        }
+    ]
+    fields = ['type', 'id', 'name', 'metadata.enterprise_67890.catalogImages.$parent']
+    limit = 2
+    marker = 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKs'
+    expected_data = {
+        'limit': limit,
+        'from': from_template,
+        'ancestor_folder_id': ancestor_folder_id,
+        'query': query,
+        'query_params': query_params,
+        'use_index': use_index,
+        'order_by': order_by,
+        'marker': marker,
+        'fields': fields
+    }
+    expected_headers = {b'Content-Type': b'application/json'}
+    mock_box_session.post.return_value, _ = make_mock_box_request(response=metadata_query_response)
+    items = test_search.metadata_query(
+        from_template,
+        ancestor_folder_id,
+        query,
+        query_params,
+        use_index,
+        order_by,
+        marker,
+        limit,
+        fields
+    )
+    item1 = items.next()
+    item2 = items.next()
+    mock_box_session.post.assert_called_once_with(expected_url, data=json.dumps(expected_data), headers=expected_headers)
+    assert item1['type'] == 'file'
+    assert item1['metadata']['enterprise_67890']['catalogImages']['$parent'] == 'file_50347290'
+    assert item2['type'] == 'folder'
+    assert item2['metadata']['enterprise_67890']['catalogImages']['$parent'] == 'file_50427291'
+
+
 def test_range_filter_without_gt_and_lt_will_fail_validation():
     metadata_filter = MetadataSearchFilter(template_key='mytemplate', scope='enterprise')
     with pytest.raises(ValueError):
