|
1 | 1 | Query |
2 | 2 | ===== |
3 | 3 |
|
| 4 | +.. _query_builder: |
| 5 | + |
4 | 6 | Query Builder |
5 | 7 | ------------- |
6 | 8 |
|
| 9 | +A query can be created for every ``ApiComponent`` (such as ``MailBox``). The ``Query`` can be used to handle the filtering, sorting, selecting, expanding and search very easily. |
| 10 | + |
| 11 | +For example: |
| 12 | + |
| 13 | +.. code-block:: python |
| 14 | +
|
| 15 | + from O365.utils import QueryBuilder |
| 16 | + builder = QueryBuilder(protocol=account.protocol) |
| 17 | +
|
| 18 | + query = builder.chain_or(builder.contains('subject', 'george best'), builder.startswith('subject', 'quotes') |
| 19 | +
|
| 20 | + # 'created_date_time' will automatically be converted to the protocol casing. |
| 21 | + # For example when using MS Graph this will become 'createdDateTime'. |
| 22 | +
|
| 23 | + query = query & builder.greater('created_date_time', datetime(2018, 3, 21)) |
| 24 | +
|
| 25 | + print(query) |
| 26 | +
|
| 27 | + # contains(subject, 'george best') or startswith(subject, 'quotes') and createdDateTime gt '2018-03-21T00:00:00Z' |
| 28 | + # note you can pass naive datetimes and those will be converted to you local timezone and then send to the api as UTC in iso8601 format |
| 29 | +
|
| 30 | + # To use Query objetcs just pass it to the query parameter: |
| 31 | + filtered_messages = mailbox.get_messages(query=query) |
| 32 | +
|
| 33 | +You can also specify specific data to be retrieved with "select": |
| 34 | +
|
| 35 | +.. code-block:: python |
| 36 | +
|
| 37 | + # select only some properties for the retrieved messages: |
| 38 | + query = builder.select('subject', 'to_recipients', 'created_date_time) |
| 39 | +
|
| 40 | + messages_with_selected_properties = mailbox.get_messages(query=query) |
| 41 | +
|
| 42 | +You can also search content. As said in the graph docs: |
| 43 | +
|
| 44 | + You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request. |
| 45 | + |
| 46 | + If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body. |
| 47 | +
|
| 48 | + .. code-block:: python |
| 49 | +
|
| 50 | + # searching is the easy part ;) |
| 51 | + query = builder.search('george best is da boss') |
| 52 | + messages = mailbox.get_messages(query=query) |
7 | 53 |
|
0 commit comments