prepare 0.4

Author: barseghyanartur

CHANGELOG.rst

@@ -17,16 +17,16 @@ are used for versioning (schema follows below):
 
 0.4
 ---
-2017-mm-dd (not yet released)
+2017-09-26
 
 - ``GeoSpatialFilteringFilterBackend`` filtering backend, supporting
-  ``geo_distance``, ``geo_distance_range``, ``geo_distance_gt``,
-  ``geo_distance_gte``, ``geo_distance_lt`` and ``geo_distance_lte``
-  geo-spatial queries.
-- ``GeoSpatialOrderingFilterBackend`` ordering backend, supporting ?.
+  ``geo_distance`` and ``geo_polygon`` geo-spatial queries.
+- ``GeoSpatialOrderingFilterBackend`` ordering backend, supporting
+  ordering of results for ``geo_distance`` filter.
 - ``OrderingFilterBackend`` is no longer provides defaults when no ordering is
   given. In order to take care of the defaults include the
-  ``DefaultOrderingFilterBackend`` in the list of ``filter_backends``.
+  ``DefaultOrderingFilterBackend`` in the list of ``filter_backends`` (after
+  all other ordering backends).
 
 0.3.12
 ------

ROADMAP.rst

@@ -2,15 +2,16 @@ Roadmap
 =======
 Road-map/upcoming releases.
 
-0.4
+0.5
 ---
 yyyy-mm-dd (future)
 
-- All filters (mentioned in the ``constants`` module) implemented.
-- Awesome documentation.
+- Improved geo-spatial search/filtering/ordering support.
 
-0.5
+0.6
 ---
 yyyy-mm-dd (future)
 
-- Add support for geo spatial search/filtering/ordering.
+- All filters (mentioned in the ``constants`` module) implemented.
+- Aggregations (also for geo-spatial backends).
+- Awesome documentation.

advanced_usage_examples.rst

@@ -732,6 +732,23 @@ Filter documents by radius of 100000km from the given location.
 
     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
+
+Ordering
+~~~~~~~~
+
+**Geo-distance ordering**
+
+.. code-block:: text
+
+    http://localhost:8000/search/publishers/?ordering=location|48.85|2.30|km|plane
+
 Suggestions
 -----------
 

docs/advanced_usage_examples.rst

@@ -65,6 +65,16 @@ Sample models
         state_province = models.CharField(max_length=30)
         country = models.CharField(max_length=50)
         website = models.URLField()
+        latitude = models.DecimalField(null=True,
+                                   blank=True,
+                                   decimal_places=15,
+                                   max_digits=19,
+                                   default=0)
+        longitude = models.DecimalField(null=True,
+                                        blank=True,
+                                        decimal_places=15,
+                                        max_digits=19,
+                                        default=0)
 
         class Meta(object):
             """Meta options."""
@@ -74,6 +84,17 @@ Sample models
         def __str__(self):
             return self.name
 
+        @property
+        def location_field_indexing(self):
+            """Location for indexing.
+
+            Used in Elasticsearch indexing/tests of `geo_distance` native filter.
+            """
+            return {
+                'lat': self.latitude,
+                'lon': self.longitude,
+            }
+
 
     @python_2_unicode_compatible
     class Author(models.Model):
@@ -379,6 +400,7 @@ Sample view
     from django_elasticsearch_dsl_drf.filter_backends import (
         FilteringFilterBackend,
         OrderingFilterBackend,
+        DefaultOrderingFilterBackend,
         SearchFilterBackend,
     )
     from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
@@ -397,6 +419,7 @@ Sample view
         filter_backends = [
             FilteringFilterBackend,
             OrderingFilterBackend,
+            DefaultOrderingFilterBackend,
             SearchFilterBackend,
         ]
         # Define search fields
@@ -600,6 +623,20 @@ the example below, documents would be ordered first by field
 
     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
+
+Or, alternatively:
+
+.. code-block:: text
+
+    http://127.0.0.1:8000/api/articles/?ids=68&ids=64&ids=58
+
 Faceted search
 --------------
 
@@ -695,6 +732,23 @@ Filter documents by radius of 100000km from the given location.
 
     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
+
+Ordering
+~~~~~~~~
+
+**Geo-distance ordering**
+
+.. code-block:: text
+
+    http://localhost:8000/search/publishers/?ordering=location|48.85|2.30|km|plane
+
 Suggestions
 -----------
 
@@ -787,6 +841,9 @@ To make use of suggestions, you should properly indexed your documents using
 
         website = fields.StringField()
 
+        # Location
+        location = fields.GeoPointField(attr='location_field_indexing')
+
         class Meta(object):
             """Meta options."""
 
@@ -795,6 +852,50 @@ To make use of suggestions, you should properly indexed your documents using
 After that the ``name.suggest``, ``city.suggest``, ``state_province.suggest``
 and ``country.suggest`` fields would be available for suggestions feature.
 
+
+Serializer definition
+---------------------
+
+This is how publisher serializer would look like.
+
+*search_indexes/serializers.py*
+
+.. code-block:: python
+
+    import json
+
+    from django_elasticsearch_dsl_drf.serializers import DocumentSerializer
+
+    class PublisherDocumentSerializer(DocumentSerializer):
+        """Serializer for Publisher document."""
+
+        location = serializers.SerializerMethodField()
+
+        class Meta(object):
+            """Meta options."""
+
+            # Note, that since we're using a dynamic serializer,
+            # we only have to declare fields that we want to be shown. If
+            # somehow, dynamic serializer doesn't work for you, either extend
+            # or declare your serializer explicitly.
+            fields = (
+                'id',
+                'name',
+                'info',
+                'address',
+                'city',
+                'state_province',
+                'country',
+                'website',
+            )
+
+        def get_location(self, obj):
+        """Represent location value."""
+        try:
+            return obj.location.to_dict()
+        except:
+            return {}
+
 ViewSet definition
 ~~~~~~~~~~~~~~~~~~
 
@@ -863,6 +964,15 @@ the following way:
             },
         }
 
+        # Geo-spatial filtering fields
+        geo_spatial_filter_fields = {
+            'location': {
+                'lookups': [
+                    LOOKUP_FILTER_GEO_DISTANCE,
+                ],
+            },
+        }
+
 In the example below, we show suggestion results (auto-completion) for
 ``country`` field.
 

docs/basic_usage_examples.rst

@@ -40,6 +40,16 @@ books/models.py:
         state_province = models.CharField(max_length=30)
         country = models.CharField(max_length=50)
         website = models.URLField()
+        latitude = models.DecimalField(null=True,
+                                   blank=True,
+                                   decimal_places=15,
+                                   max_digits=19,
+                                   default=0)
+        longitude = models.DecimalField(null=True,
+                                        blank=True,
+                                        decimal_places=15,
+                                        max_digits=19,
+                                        default=0)
 
         class Meta(object):
             """Meta options."""
@@ -49,6 +59,17 @@ books/models.py:
         def __str__(self):
             return self.name
 
+        @property
+        def location_field_indexing(self):
+            """Location for indexing.
+
+            Used in Elasticsearch indexing/tests of `geo_distance` native filter.
+            """
+            return {
+                'lat': self.latitude,
+                'lon': self.longitude,
+            }
+
 Sample document
 ---------------
 
@@ -108,6 +129,9 @@ search_indexes/documents/publisher.py:
         )
         website = fields.StringField()
 
+        # Location
+        location = fields.GeoPointField(attr='location_field_indexing')
+
         class Meta(object):
             """Meta options."""
 
@@ -128,6 +152,8 @@ search_indexes/serializers.py:
     class PublisherDocumentSerializer(DocumentSerializer):
         """Serializer for Publisher document."""
 
+        location = serializers.SerializerMethodField()
+
         class Meta(object):
             """Meta options."""
 
@@ -146,13 +172,23 @@ search_indexes/serializers.py:
                 'website',
             )
 
+        def get_location(self, obj):
+        """Represent location value."""
+        try:
+            return obj.location.to_dict()
+        except:
+            return {}
+
 Sample view
 -----------
 
 search_indexes/views.py:
 
 .. code-block:: python
 
+    from django_elasticsearch_dsl_drf.constants import (
+        LOOKUP_FILTER_GEO_DISTANCE,
+    )
     from django_elasticsearch_dsl_drf.filter_backends import (
         FilteringFilterBackend,
         OrderingFilterBackend,
@@ -173,6 +209,7 @@ search_indexes/views.py:
         filter_backends = [
             FilteringFilterBackend,
             OrderingFilterBackend,
+            DefaultOrderingFilterBackend,
             SearchFilterBackend,
         ]
         # Define search fields
@@ -201,6 +238,14 @@ search_indexes/views.py:
         }
         # Specify default ordering
         ordering = ('id', 'name',)
+        # Define geo-spatial filtering fields
+        geo_spatial_filter_fields = {
+            'location': {
+                'lookups': [
+                    LOOKUP_FILTER_GEO_DISTANCE,
+                ],
+            },
+        }
 
 Usage example
 -------------
@@ -321,6 +366,15 @@ Filter documents by a part word part in single field (``city``) "ondon".
 
     http://127.0.0.1:8080/search/publisher/?city__wildcard=*ondon
 
+
+**Geo-distance filtering**
+
+Filter documents by radius of 100000km from the given location.
+
+.. code-block:: text
+
+    http://127.0.0.1:8000/search/publishers/?location__geo_distance=100000km|12.04|-63.93
+
 Ordering
 ^^^^^^^^
 

docs/changelog.rst

@@ -15,6 +15,19 @@ are used for versioning (schema follows below):
   0.3.4 to 0.4).
 - All backwards incompatible changes are mentioned in this document.
 
+0.4
+---
+2017-09-26
+
+- ``GeoSpatialFilteringFilterBackend`` filtering backend, supporting
+  ``geo_distance`` and ``geo_polygon`` geo-spatial queries.
+- ``GeoSpatialOrderingFilterBackend`` ordering backend, supporting
+  ordering of results for ``geo_distance`` filter.
+- ``OrderingFilterBackend`` is no longer provides defaults when no ordering is
+  given. In order to take care of the defaults include the
+  ``DefaultOrderingFilterBackend`` in the list of ``filter_backends`` (after
+  all other ordering backends).
+
 0.3.12
 ------
 2017-09-21

docs/index.rst

@@ -44,11 +44,13 @@ Main features and highlights
   ``isnull``, ``range``, ``in``, ``term`` and ``terms``
   is implemented.
 - :doc:`Geo-spatial filtering filter backend <advanced_usage_examples>` (the
+  following filters implemented: ``geo_distance``, ``geo_polygon``).
+- :doc:`Geo-spatial ordering filter backend <advanced_usage_examples>` (the
   following filters implemented: ``geo_distance``).
 - :doc:`Faceted search filter backend <advanced_usage_examples>`.
 - :doc:`Suggester filter backend <advanced_usage_examples>`.
 - :doc:`Pagination (Page number and limit/offset pagination) <advanced_usage_examples>`.
-- Ids filter backend.
+- :doc:`Ids filter backend <advanced_usage_examples>`.
 
 Installation
 ============