add default filter lookup option; more on correcting the docs regarding the separators change

Author: barseghyanartur

CHANGELOG.rst

@@ -28,12 +28,17 @@ yyyy-mm-dd (not released yet)
     Do not keep things as they were in your own fork, since new search backends
     will use the `|` and `:` symbols differently.
 
+**Shortcuts**
+
+.. code-block:: text
+
+
+
+
 - `SEPARATOR_LOOKUP_VALUE` has been removed. Use
   `SEPARATOR_LOOKUP_COMPLEX_VALUE` and
   `SEPARATOR_LOOKUP_COMPLEX_MULTIPLE_VALUE` instead.
-  # TODO: Name a couple of usage examples.
 - `SEPARATOR_LOOKUP_NAME` has been added.
-  # TODO: Name a couple of usage examples.
 - The method `split_lookup_complex_value` has been removed. Use
   `split_lookup_complex_value` instead.
 

advanced_usage_examples.rst

@@ -517,11 +517,11 @@ Search in all fields (``title``, ``description`` and ``summary``) for word
 **Search a single term on specific field**
 
 In order to search in specific field (``title``) for term "education", add
-the field name separated with ``|`` to the search term.
+the field name separated with ``:`` to the search term.
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?search=title|education
+    http://127.0.0.1:8080/search/books/?search=title:education
 
 **Search for multiple terms**
 
@@ -536,11 +536,11 @@ multiple ``search`` query params.
 
 In order to search for multiple terms "education", "technology" in specific
 fields add multiple ``search`` query params and field names separated with
-``|`` to each of the search terms.
+``:`` to each of the search terms.
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?search=title|education&search=summary|technology
+    http://127.0.0.1:8080/search/books/?search=title:education&search=summary:technology
 
 **Search with boosting**
 
@@ -590,7 +590,7 @@ Filter documents by field (``states``) "published" and "in_progress".
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?state__in=published|in_progress
+    http://127.0.0.1:8080/search/books/?state__in=published__in_progress
 
 **Filter document by a single field**
 
@@ -607,7 +607,7 @@ with use of functional ``in`` query filter.
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?tags__in=education|economy
+    http://127.0.0.1:8080/search/books/?tags__in=education__economy
 
 You can achieve the same effect by specifying multiple fields (``tags``)
 "education" and "economy". Note, that in this case multiple filter terms are
@@ -644,15 +644,15 @@ Order documents by field ``price`` (ascending).
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=price
+    http://127.0.0.1:8080/search/books/?search=title:lorem&ordering=price
 
 **Order documents by field (descending)**
 
 Order documents by field ``price`` (descending).
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=-price
+    http://127.0.0.1:8080/search/books/?search=title:lorem&ordering=-price
 
 **Order documents by multiple fields**
 
@@ -662,15 +662,15 @@ the example below, documents would be ordered first by field
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=-publication_date&ordering=price
+    http://127.0.0.1:8080/search/books/?search=title:lorem&ordering=-publication_date&ordering=price
 
 Ids filter
 ----------
 Filters documents that only have the provided ids.
 
 .. code-block:: text
 
-    http://127.0.0.1:8000/api/articles/?ids=68|64|58
+    http://127.0.0.1:8000/api/articles/?ids=68__64__58
 
 Or, alternatively:
 
@@ -881,7 +881,7 @@ Filter documents by field (``states``) "published" and "in_progress".
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/books/?state_pf__in=published|in_progress
+    http://127.0.0.1:8080/search/books/?state_pf__in=published__in_progress
 
 Geo-spatial features
 --------------------
@@ -900,23 +900,23 @@ Filter documents by radius of 100000km from the given location.
 
 .. code-block:: text
 
-    http://localhost:8000/search/publishers/?location__geo_distance=100000km|12.04|-63.93
+    http://localhost:8000/search/publishers/?location__geo_distance=100000km__12.04__-63.93
 
 **Geo-polygon filtering**
 
 Filter documents that are located in the given polygon.
 
 .. code-block:: text
 
-    http://localhost:8000/search/publishers/?location__geo_polygon=40,-70|30,-80|20,-90
+    http://localhost:8000/search/publishers/?location__geo_polygon=40,-70__30,-80__20,-90
 
 **Geo-bounding-box filtering**
 
 Filter documents that are located in the given bounding box.
 
 .. code-block:: text
 
-    http://localhost:8000/search/publishers/?location__geo_bounding_box=44.87,40.07|43.87,41.11
+    http://localhost:8000/search/publishers/?location__geo_bounding_box=44.87,40.07__43.87,41.11
 
 Ordering
 ~~~~~~~~
@@ -925,7 +925,7 @@ Ordering
 
 .. code-block:: text
 
-    http://localhost:8000/search/publishers/?ordering=location|48.85|2.30|km|plane
+    http://localhost:8000/search/publishers/?ordering=location__48.85__2.30__km__plane
 
 Suggestions
 -----------

examples/simple/search_indexes/urls.py

@@ -7,6 +7,7 @@
     BookOrderingByScoreDocumentViewSet,
     BookFunctionalSuggesterDocumentViewSet,
     BookMoreLikeThisDocumentViewSet,
+    BookDefaultFilterLookupDocumentViewSet,
     CityDocumentViewSet,
     PublisherDocumentViewSet,
 )
@@ -51,6 +52,12 @@
     base_name='bookdocument_more_like_this'
 )
 
+books_default_filter_lookup = router.register(
+    r'books-default-filter-lookup',
+    BookDefaultFilterLookupDocumentViewSet,
+    base_name='bookdocument_default_filter_lookup'
+)
+
 cities = router.register(
     r'cities',
     CityDocumentViewSet,

examples/simple/search_indexes/viewsets/__init__.py

@@ -5,6 +5,7 @@
     BookOrderingByScoreDocumentViewSet,
     BookFunctionalSuggesterDocumentViewSet,
     BookMoreLikeThisDocumentViewSet,
+    BookDefaultFilterLookupDocumentViewSet,
 )
 from .city import CityDocumentViewSet
 from .publisher import PublisherDocumentViewSet
@@ -15,6 +16,7 @@
     'BookDocumentViewSet',
     'BookFunctionalSuggesterDocumentViewSet',
     'BookMoreLikeThisDocumentViewSet',
+    'BookDefaultFilterLookupDocumentViewSet',
     'BookOrderingByScoreDocumentViewSet',
     'CityDocumentViewSet',
     'PublisherDocumentViewSet',

examples/simple/search_indexes/viewsets/book.py

@@ -3,6 +3,7 @@
     FUNCTIONAL_SUGGESTER_COMPLETION_PREFIX,
     LOOKUP_FILTER_PREFIX,
     LOOKUP_FILTER_RANGE,
+    LOOKUP_FILTER_TERM,
     LOOKUP_FILTER_TERMS,
     LOOKUP_FILTER_WILDCARD,
     LOOKUP_QUERY_EXCLUDE,
@@ -45,6 +46,7 @@
     'BookOrderingByScoreDocumentViewSet',
     'BookFunctionalSuggesterDocumentViewSet',
     'BookMoreLikeThisDocumentViewSet',
+    'BookDefaultFilterLookupDocumentViewSet',
 )
 
 
@@ -295,6 +297,33 @@ class BookOrderingByScoreDocumentViewSet(BookDocumentViewSet):
     ordering = ('_score', 'id', 'title', 'price',)
 
 
+class BookDefaultFilterLookupDocumentViewSet(BookDocumentViewSet):
+    """Same as parent, but with default filter lookups & no default facets."""
+
+    filter_fields = {
+        'authors': {
+            'field': 'authors.raw',
+            'lookups': [
+                LOOKUP_FILTER_TERM,
+                LOOKUP_FILTER_TERMS,
+                LOOKUP_FILTER_PREFIX,
+                LOOKUP_FILTER_WILDCARD,
+                LOOKUP_QUERY_IN,
+                LOOKUP_QUERY_EXCLUDE,
+            ],
+            'default_lookup': LOOKUP_FILTER_TERM,
+        },
+    }
+
+    faceted_search_fields = {
+        'state': 'state.raw',
+        'publisher': {
+            'field': 'publisher.raw',
+            'enabled': False,
+        },
+    }
+
+
 class BookMoreLikeThisDocumentViewSet(BaseDocumentViewSet,
                                       MoreLikeThisMixin):
     """Same as BookDocumentViewSet, with more-like-this and no facets."""

filtering_usage_examples.rst

@@ -33,11 +33,11 @@ Search a single term on specific field
 --------------------------------------
 
 In order to search in specific field (``name``) for term "reilly", add
-the field name separated with ``|`` to the search term.
+the field name separated with ``:`` to the search term.
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/publisher/?search=name|reilly
+    http://127.0.0.1:8080/search/publisher/?search=name:reilly
 
 Search for multiple terms
 -------------------------
@@ -54,11 +54,11 @@ Search for multiple terms in specific fields
 
 In order to search for multiple terms "reilly", "bloomsbury" in specific
 fields add multiple ``search`` query params and field names separated with
-``|`` to each of the search terms.
+``:`` to each of the search terms.
 
 .. code-block:: text
 
-    http://127.0.0.1:8080/search/publisher/?search=name|reilly&search=city|london
+    http://127.0.0.1:8080/search/publisher/?search=name:reilly&search=city:london
 
 Filtering
 =========
@@ -98,7 +98,7 @@ specified.
 .. code-block:: text
 
     http://localhost:8000/api/articles/?id=1&id=2&id=3
-    http://localhost:8000/api/articles/?id__terms=1;2;3
+    http://localhost:8000/api/articles/?id__terms=1__2__3
 
 range
 ^^^^^
@@ -109,15 +109,15 @@ strings) in the range specified.
 
 .. code-block:: text
 
-    http://localhost:8000/api/users/?age__range=16;67
+    http://localhost:8000/api/users/?age__range=16__67
 
 .. code-block:: text
 
 **From, to, boost**
 
 .. code-block:: text
 
-    http://localhost:8000/api/users/?age__range=16;67;2.0
+    http://localhost:8000/api/users/?age__range=16__67__2.0
 
 exists
 ^^^^^^
@@ -152,7 +152,7 @@ Find documents with the specified type and IDs.
 
 .. code-block:: text
 
-    http://localhost:8000/api/articles/?ids=68;64;58
+    http://localhost:8000/api/articles/?ids=68__64__58
     http://localhost:8000/api/articles/?ids=68&ids=64&ids=58
 
 Functional
@@ -182,7 +182,7 @@ In a given list.
 
 .. code-block:: text
 
-    http://localhost:8000/api/articles/?id__in=1;2;3
+    http://localhost:8000/api/articles/?id__in=1__2__3
 
 gt
 ^^
@@ -254,6 +254,7 @@ lookup parameters.
 .. code-block:: text
 
     http://localhost:8000/api/articles/?tags__exclude=children
+    http://localhost:8000/api/articles/?tags__exclude=children__python
 
 Usage examples
 ==============