[OSDEV-1581] Add Geohex grid aggregation support to the production locations endpoint

doc/release/RELEASE-NOTES.md

@@ -19,7 +19,7 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 * *Describe schema changes here.*
 
 ### Code/API changes
-* *Describe code/API changes here.*
+* [OSDEV-1581](https://opensupplyhub.atlassian.net/browse/OSDEV-1581) - Added support for Geohex grid aggregation to the GET `/api/v1/production-locations/` endpoint. To receive the Geohex grid aggregation list in the response, it is necessary to pass the `aggregation` parameter with a value of `geohex_grid` and optionally specify `geohex_grid_precision` with an integer between 0 and 15. If `geohex_grid_precision` is not defined, the default value of 5 will be used.
 
 ### Architecture/Environment changes
 * *Describe architecture/environment changes here.*

src/django/api/serializers/v1/production_locations_serializer.py

@@ -25,6 +25,8 @@
 class ProductionLocationsSerializer(Serializer):
     # These params are checking considering serialize_params output
     size = IntegerField(required=False)
+    address = CharField(required=False)
+    description = CharField(required=False)
     number_of_workers_min = IntegerField(required=False)
     number_of_workers_max = IntegerField(required=False)
     percent_female_workers_min = FloatField(required=False)
@@ -45,6 +47,15 @@ class ProductionLocationsSerializer(Serializer):
         choices=['asc', 'desc'],
         required=False
     )
+    aggregation = ChoiceField(
+        choices=['geohex_grid'],
+        required=False,
+    )
+    geohex_grid_precision = IntegerField(
+        min_value=0,
+        max_value=15,
+        required=False,
+    )
 
     def validate(self, data):
         validators = [

src/django/api/services/opensearch/search.py

@@ -46,11 +46,26 @@ def __prepare_opensearch_response(self, response):
             else:
                 logger.warning(f"Missing '_source' in hit: {hit}")
 
-        return {
+        response_data = {
             "count": total_hits,
-            "data": data
+            "data": data,
         }
 
+        geohex_buckets = (
+            response.get("aggregations", {})
+            .get("grouped", {})
+            .get("buckets", [])
+        )
+
+        if geohex_buckets:
+            response_data.update({
+                "aggregations": {
+                    "geohex_grid": geohex_buckets
+                }
+            })
+
+        return response_data
+
     @staticmethod
     def __remove_null_values(obj):
         if isinstance(obj, dict):

src/django/api/tests/test_moderation_events_query_builder.py

@@ -1,4 +1,3 @@
-import unittest
 from django.test import TestCase
 from api.views.v1.opensearch_query_builder. \
     moderation_events_query_builder import ModerationEventsQueryBuilder
@@ -88,6 +87,21 @@ def test_add_sort(self):
         expected = {'created_at': {'order': 'asc'}}
         self.assertIn(expected, self.builder.query_body['sort'])
 
+    def test_add_sort_with_default_order(self):
+        self.builder.add_sort('created_at')
+        expected = {'created_at': {'order': 'desc'}}
+        self.assertIn(expected, self.builder.query_body['sort'])
+
+    def test_add_sort_name(self):
+        self.builder.add_sort('name', 'asc')
+        expected = {'cleaned_data.name': {'order': 'asc'}}
+        self.assertIn(expected, self.builder.query_body['sort'])
+
+    def test_add_sort_address(self):
+        self.builder.add_sort('address', 'asc')
+        expected = {'cleaned_data.address': {'order': 'asc'}}
+        self.assertIn(expected, self.builder.query_body['sort'])
+
     def test_add_sort_country(self):
         self.builder.add_sort('country', 'asc')
         expected = {'cleaned_data.country.name': {'order': 'asc'}}
@@ -121,7 +135,3 @@ def test_get_final_query_body(self):
             'sort': []
         }
         self.assertEqual(final_query, expected)
-
-
-if __name__ == '__main__':
-    unittest.main()

src/django/api/tests/test_opensearch_response_formatter.py

@@ -188,6 +188,47 @@ def test_prepare_opensearch_response_rename_lon_field(self, mock_logger):
         self.assertEqual(result, expected_result)
         mock_logger.warning.assert_not_called()
 
+    @patch('api.services.opensearch.search.logger')
+    def test_prepare_opensearch_response_with_aggregation_data(
+        self,
+        mock_logger
+    ):
+        response = {
+            "hits": {
+                "total": {"value": 10},
+                "hits": [
+                    {"_source": {"field1": "value1"}},
+                    {"_source": {"field2": "value2"}}
+                ]
+            },
+            "aggregations": {
+                "grouped": {
+                    "buckets": [
+                        {"key": "value1"},
+                        {"key": "value2"}
+                    ]
+                }
+            }
+        }
+        expected_result = {
+            "count": 10,
+            "data": [
+                {"field1": "value1"},
+                {"field2": "value2"}
+            ],
+            "aggregations": {
+                "geohex_grid": [
+                    {"key": "value1"},
+                    {"key": "value2"}
+                ]
+            }
+        }
+
+        result = self.service. \
+            _OpenSearchService__prepare_opensearch_response(response)
+        self.assertEqual(result, expected_result)
+        mock_logger.warning.assert_not_called()
+
 
 if __name__ == '__main__':
     unittest.main()

src/django/api/tests/test_production_locations_query_builder.py

@@ -1,5 +1,5 @@
-import unittest
 from django.test import TestCase
+from unittest.mock import patch
 from api.views.v1.opensearch_query_builder. \
     production_locations_query_builder import ProductionLocationsQueryBuilder
 
@@ -26,20 +26,6 @@ def test_add_match(self):
             self.builder.query_body['query']['bool']['must']
             )
 
-    def test_add_multi_match(self):
-        self.builder.add_multi_match('test query')
-        expected = {
-            'multi_match': {
-                'query': 'test query',
-                'fields': ['name^2', 'address', 'description', 'local_name'],
-                'fuzziness': 2
-            }
-        }
-        self.assertIn(
-            expected,
-            self.builder.query_body['query']['bool']['must']
-            )
-
     def test_add_terms_for_standard_field(self):
         self.builder.add_terms('country', ['US', 'CA'])
         expected = {'terms': {'country.alpha_2': ['US', 'CA']}}
@@ -181,6 +167,11 @@ def test_add_sort(self):
         expected = {'name.keyword': {'order': 'desc'}}
         self.assertIn(expected, self.builder.query_body['sort'])
 
+    def test_add_sort_with_default_order(self):
+        self.builder.add_sort('name')
+        expected = {'name.keyword': {'order': 'asc'}}
+        self.assertIn(expected, self.builder.query_body['sort'])
+
     def test_add_search_after(self):
         search_after_value = 'test_value'
         search_after_id = 'test_id'
@@ -214,6 +205,89 @@ def test_get_final_query_body(self):
         }
         self.assertEqual(final_query, expected)
 
+    def test_add_multi_match(self):
+        self.builder._ProductionLocationsQueryBuilder__add_multi_match(
+            'test query'
+        )
+        expected = {
+            'multi_match': {
+                'query': 'test query',
+                'fields': ['name^2', 'address', 'description', 'local_name'],
+                'fuzziness': 2,
+            }
+        }
+        self.assertIn(
+            expected, self.builder.query_body['query']['bool']['must']
+        )
+
+    def test_add_aggregations_with_precision(self):
+        aggregation = 'geohex_grid'
+        geohex_grid_precision = 5
+        self.builder._ProductionLocationsQueryBuilder__add_aggregations(
+            aggregation,
+            geohex_grid_precision
+        )
+        expected = {
+            'grouped': {
+                'geohex_grid': {
+                    'field': 'coordinates',
+                    'precision': geohex_grid_precision
+                }
+            }
+        }
+        self.assertIn('aggregations', self.builder.query_body)
+        self.assertEqual(expected, self.builder.query_body['aggregations'])
+
+    def test_add_aggregations_without_precision(self):
+        aggregation = 'geohex_grid'
+        self.builder._ProductionLocationsQueryBuilder__add_aggregations(
+            aggregation
+        )
+        expected = {
+            'grouped': {
+                'geohex_grid': {'field': 'coordinates'}
+            }
+        }
+        self.assertIn('aggregations', self.builder.query_body)
+        self.assertEqual(expected, self.builder.query_body['aggregations'])
+
+    @patch.object(
+        ProductionLocationsQueryBuilder,
+        '_ProductionLocationsQueryBuilder__add_aggregations'
+    )
+    def test_add_specific_queries_with_aggregation(
+        self, mock_add_aggregations
+    ):
+        query_params = {
+            'aggregation': 'geohex_grid',
+        }
+        self.builder.add_specific_queries(query_params)
+
+        mock_add_aggregations.assert_called_once_with('geohex_grid', None)
+
+    @patch.object(
+        ProductionLocationsQueryBuilder,
+        '_ProductionLocationsQueryBuilder__add_aggregations'
+    )
+    def test_add_specific_queries_wit_aggregation_and_precision(
+        self, mock_add_aggregations
+    ):
+        query_params = {
+            'aggregation': 'geohex_grid',
+            'geohex_grid_precision': 4,
+        }
+        self.builder.add_specific_queries(query_params)
+
+        mock_add_aggregations.assert_called_once_with('geohex_grid', 4)
+
+    @patch.object(
+        ProductionLocationsQueryBuilder,
+        '_ProductionLocationsQueryBuilder__add_multi_match'
+    )
+    def test_add_specific_queries_with_query(self, mock_add_multi_match):
+        query_params = {
+            'query': 'search term',
+        }
+        self.builder.add_specific_queries(query_params)
 
-if __name__ == '__main__':
-    unittest.main()
+        mock_add_multi_match.assert_called_once_with('search term')