add improved error message

Author: jonhealy1

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Added `USE_DATETIME` environment variable to configure datetime search behavior in SFEOS. [#452](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/452)
 - GET `/collections` collection search sort extension ex. `/collections?sortby=+id`. [#456](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/456)
 - GET `/collections` collection search fields extension ex. `/collections?fields=id,title`. [#465](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/465)
+- Improved error messages for sorting on unsortable fields in collection search, including guidance on how to make fields sortable. [#465](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/465)
 
 ### Changed
 

README.md

@@ -131,7 +131,7 @@ These extensions make it easier to build user interfaces that display and naviga
 > - `id` (keyword field)
 > - `extent.temporal.interval` (date field)
 >
-> Text fields like `title` and `description` are not sortable by default as they use text analysis for better search capabilities. Attempting to sort on these fields will result in a `BadRequestError` with a message about fielddata being disabled.
+> Text fields like `title` and `description` are not sortable by default as they use text analysis for better search capabilities. Attempting to sort on these fields will result in a user-friendly error message explaining which fields are sortable and how to make additional fields sortable by updating the mappings.
 
 ## Package Structure
 

stac_fastapi/elasticsearch/stac_fastapi/elasticsearch/database_logic.py

@@ -186,18 +186,35 @@ async def get_all_collections(
 
         Returns:
             A tuple of (collections, next pagination token if any).
+
+        Raises:
+            HTTPException: If sorting is requested on a field that is not sortable.
         """
+        # Define sortable fields based on the ES_COLLECTIONS_MAPPINGS
+        sortable_fields = ["id", "extent.temporal.interval"]
+
+        # Format the sort parameter
         formatted_sort = []
         if sort:
             for item in sort:
                 field = item.get("field")
                 direction = item.get("direction", "asc")
                 if field:
+                    # Validate that the field is sortable
+                    if field not in sortable_fields:
+                        raise HTTPException(
+                            status_code=400,
+                            detail=f"Field '{field}' is not sortable. Sortable fields are: {', '.join(sortable_fields)}. "
+                            + "Text fields are not sortable by default in Elasticsearch. "
+                            + "To make a field sortable, update the mapping to use 'keyword' type or add a '.keyword' subfield. "
+                            + "See the ES_COLLECTIONS_MAPPINGS in mappings.py for details.",
+                        )
                     formatted_sort.append({field: {"order": direction}})
             # Always include id as a secondary sort to ensure consistent pagination
             if not any("id" in item for item in formatted_sort):
                 formatted_sort.append({"id": {"order": "asc"}})
         else:
+            # Use a collections-specific default sort that doesn't rely on properties.datetime
             formatted_sort = [{"id": {"order": "asc"}}]
 
         body = {

stac_fastapi/opensearch/stac_fastapi/opensearch/database_logic.py

@@ -170,18 +170,35 @@ async def get_all_collections(
 
         Returns:
             A tuple of (collections, next pagination token if any).
+
+        Raises:
+            HTTPException: If sorting is requested on a field that is not sortable.
         """
+        # Define sortable fields based on the ES_COLLECTIONS_MAPPINGS
+        sortable_fields = ["id", "extent.temporal.interval"]
+
+        # Format the sort parameter
         formatted_sort = []
         if sort:
             for item in sort:
                 field = item.get("field")
                 direction = item.get("direction", "asc")
                 if field:
+                    # Validate that the field is sortable
+                    if field not in sortable_fields:
+                        raise HTTPException(
+                            status_code=400,
+                            detail=f"Field '{field}' is not sortable. Sortable fields are: {', '.join(sortable_fields)}. "
+                            + "Text fields are not sortable by default in OpenSearch. "
+                            + "To make a field sortable, update the mapping to use 'keyword' type or add a '.keyword' subfield. "
+                            + "See the ES_COLLECTIONS_MAPPINGS in mappings.py for details.",
+                        )
                     formatted_sort.append({field: {"order": direction}})
             # Always include id as a secondary sort to ensure consistent pagination
             if not any("id" in item for item in formatted_sort):
                 formatted_sort.append({"id": {"order": "asc"}})
         else:
+            # Use a collections-specific default sort that doesn't rely on properties.datetime
             formatted_sort = [{"id": {"order": "asc"}}]
 
         body = {