stac-fastapi-elasticsearch 4.2.0__py3-none-any.whl → 5.0.0__py3-none-any.whl

stac_fastapi/elasticsearch/app.py

@@ -11,14 +11,12 @@ from stac_fastapi.api.models import create_get_request_model, create_post_reques
 from stac_fastapi.core.core import (
     BulkTransactionsClient,
     CoreClient,
-    EsAsyncBaseFiltersClient,
     TransactionsClient,
 )
 from stac_fastapi.core.extensions import QueryExtension
 from stac_fastapi.core.extensions.aggregation import (
     EsAggregationExtensionGetRequest,
     EsAggregationExtensionPostRequest,
-    EsAsyncAggregationClient,
 )
 from stac_fastapi.core.extensions.fields import FieldsExtension
 from stac_fastapi.core.rate_limit import setup_rate_limit
@@ -39,7 +37,10 @@ from stac_fastapi.extensions.core import (
     TokenPaginationExtension,
     TransactionExtension,
 )
+from stac_fastapi.extensions.core.filter import FilterConformanceClasses
 from stac_fastapi.extensions.third_party import BulkTransactionExtension
+from stac_fastapi.sfeos_helpers.aggregation import EsAsyncBaseAggregationClient
+from stac_fastapi.sfeos_helpers.filter import EsAsyncBaseFiltersClient
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
@@ -56,11 +57,11 @@ filter_extension = FilterExtension(
     client=EsAsyncBaseFiltersClient(database=database_logic)
 )
 filter_extension.conformance_classes.append(
-    "http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators"
+    FilterConformanceClasses.ADVANCED_COMPARISON_OPERATORS
 )
 
 aggregation_extension = AggregationExtension(
-    client=EsAsyncAggregationClient(
+    client=EsAsyncBaseAggregationClient(
         database=database_logic, session=session, settings=settings
     )
 )
@@ -103,22 +104,24 @@ database_logic.extensions = [type(ext).__name__ for ext in extensions]
 
 post_request_model = create_post_request_model(search_extensions)
 
-api = StacApi(
-    title=os.getenv("STAC_FASTAPI_TITLE", "stac-fastapi-elasticsearch"),
-    description=os.getenv("STAC_FASTAPI_DESCRIPTION", "stac-fastapi-elasticsearch"),
-    api_version=os.getenv("STAC_FASTAPI_VERSION", "4.2.0"),
-    settings=settings,
-    extensions=extensions,
-    client=CoreClient(
+app_config = {
+    "title": os.getenv("STAC_FASTAPI_TITLE", "stac-fastapi-elasticsearch"),
+    "description": os.getenv("STAC_FASTAPI_DESCRIPTION", "stac-fastapi-elasticsearch"),
+    "api_version": os.getenv("STAC_FASTAPI_VERSION", "5.0.0"),
+    "settings": settings,
+    "extensions": extensions,
+    "client": CoreClient(
         database=database_logic,
         session=session,
         post_request_model=post_request_model,
         landing_page_id=os.getenv("STAC_FASTAPI_LANDING_PAGE_ID", "stac-fastapi"),
     ),
-    search_get_request_model=create_get_request_model(search_extensions),
-    search_post_request_model=post_request_model,
-    route_dependencies=get_route_dependencies(),
-)
+    "search_get_request_model": create_get_request_model(search_extensions),
+    "search_post_request_model": post_request_model,
+    "route_dependencies": get_route_dependencies(),
+}
+
+api = StacApi(**app_config)
 
 
 @asynccontextmanager

stac_fastapi/elasticsearch/config.py

@@ -10,7 +10,8 @@ from elasticsearch._async.client import AsyncElasticsearch
 
 from elasticsearch import Elasticsearch  # type: ignore[attr-defined]
 from stac_fastapi.core.base_settings import ApiBaseSettings
-from stac_fastapi.core.utilities import get_bool_env, validate_refresh
+from stac_fastapi.core.utilities import get_bool_env
+from stac_fastapi.sfeos_helpers.database import validate_refresh
 from stac_fastapi.types.config import ApiSettings
 
 
@@ -51,6 +52,10 @@ def _es_config() -> Dict[str, Any]:
     if http_compress:
         config["http_compress"] = True
 
+    # Handle authentication
+    if (u := os.getenv("ES_USER")) and (p := os.getenv("ES_PASS")):
+        config["http_auth"] = (u, p)
+
     # Explicitly exclude SSL settings when not using SSL
     if not use_ssl:
         return config
@@ -63,10 +68,6 @@ def _es_config() -> Dict[str, Any]:
     if config["verify_certs"]:
         config["ca_certs"] = os.getenv("CURL_CA_BUNDLE", certifi.where())
 
-    # Handle authentication
-    if (u := os.getenv("ES_USER")) and (p := os.getenv("ES_PASS")):
-        config["http_auth"] = (u, p)
-
     return config
 
 

stac_fastapi/elasticsearch/database_logic.py

@@ -1,42 +1,51 @@
 """Database logic."""
 
 import asyncio
-import json
 import logging
 from base64 import urlsafe_b64decode, urlsafe_b64encode
 from copy import deepcopy
-from typing import Any, Dict, Iterable, List, Optional, Tuple, Type
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Type, Union
 
 import attr
 import elasticsearch.helpers as helpers
+import orjson
 from elasticsearch.dsl import Q, Search
 from elasticsearch.exceptions import NotFoundError as ESNotFoundError
 from starlette.requests import Request
 
 from stac_fastapi.core.base_database_logic import BaseDatabaseLogic
-from stac_fastapi.core.database_logic import (
-    COLLECTIONS_INDEX,
-    DEFAULT_SORT,
-    ES_COLLECTIONS_MAPPINGS,
-    ES_ITEMS_MAPPINGS,
-    ES_ITEMS_SETTINGS,
-    ITEM_INDICES,
-    ITEMS_INDEX_PREFIX,
-    Geometry,
+from stac_fastapi.core.serializers import CollectionSerializer, ItemSerializer
+from stac_fastapi.core.utilities import MAX_LIMIT, bbox2polygon
+from stac_fastapi.elasticsearch.config import AsyncElasticsearchSettings
+from stac_fastapi.elasticsearch.config import (
+    ElasticsearchSettings as SyncElasticsearchSettings,
+)
+from stac_fastapi.sfeos_helpers import filter
+from stac_fastapi.sfeos_helpers.database import (
+    apply_free_text_filter_shared,
+    apply_intersects_filter_shared,
+    create_index_templates_shared,
+    delete_item_index_shared,
+    get_queryables_mapping_shared,
     index_alias_by_collection_id,
     index_by_collection_id,
     indices,
     mk_actions,
     mk_item_id,
+    populate_sort_shared,
+    return_date,
+    validate_refresh,
 )
-from stac_fastapi.core.extensions import filter
-from stac_fastapi.core.serializers import CollectionSerializer, ItemSerializer
-from stac_fastapi.core.utilities import MAX_LIMIT, bbox2polygon, validate_refresh
-from stac_fastapi.elasticsearch.config import AsyncElasticsearchSettings
-from stac_fastapi.elasticsearch.config import (
-    ElasticsearchSettings as SyncElasticsearchSettings,
+from stac_fastapi.sfeos_helpers.mappings import (
+    AGGREGATION_MAPPING,
+    COLLECTIONS_INDEX,
+    DEFAULT_SORT,
+    ITEM_INDICES,
+    ITEMS_INDEX_PREFIX,
+    Geometry,
 )
 from stac_fastapi.types.errors import ConflictError, NotFoundError
+from stac_fastapi.types.rfc3339 import DateTimeType
 from stac_fastapi.types.stac import Collection, Item
 
 logger = logging.getLogger(__name__)
@@ -50,22 +59,7 @@ async def create_index_templates() -> None:
         None
 
     """
-    client = AsyncElasticsearchSettings().create_client
-    await client.indices.put_index_template(
-        name=f"template_{COLLECTIONS_INDEX}",
-        body={
-            "index_patterns": [f"{COLLECTIONS_INDEX}*"],
-            "template": {"mappings": ES_COLLECTIONS_MAPPINGS},
-        },
-    )
-    await client.indices.put_index_template(
-        name=f"template_{ITEMS_INDEX_PREFIX}",
-        body={
-            "index_patterns": [f"{ITEMS_INDEX_PREFIX}*"],
-            "template": {"settings": ES_ITEMS_SETTINGS, "mappings": ES_ITEMS_MAPPINGS},
-        },
-    )
-    await client.close()
+    await create_index_templates_shared(settings=AsyncElasticsearchSettings())
 
 
 async def create_collection_index() -> None:
@@ -110,18 +104,13 @@ async def delete_item_index(collection_id: str):
 
     Args:
         collection_id (str): The ID of the collection whose items index will be deleted.
-    """
-    client = AsyncElasticsearchSettings().create_client
 
-    name = index_alias_by_collection_id(collection_id)
-    resolved = await client.indices.resolve_index(name=name)
-    if "aliases" in resolved and resolved["aliases"]:
-        [alias] = resolved["aliases"]
-        await client.indices.delete_alias(index=alias["indices"], name=alias["name"])
-        await client.indices.delete(index=alias["indices"])
-    else:
-        await client.indices.delete(index=name)
-    await client.close()
+    Notes:
+        This function delegates to the shared implementation in delete_item_index_shared.
+    """
+    await delete_item_index_shared(
+        settings=AsyncElasticsearchSettings(), collection_id=collection_id
+    )
 
 
 @attr.s
@@ -150,76 +139,7 @@ class DatabaseLogic(BaseDatabaseLogic):
 
     extensions: List[str] = attr.ib(default=attr.Factory(list))
 
-    aggregation_mapping: Dict[str, Dict[str, Any]] = {
-        "total_count": {"value_count": {"field": "id"}},
-        "collection_frequency": {"terms": {"field": "collection", "size": 100}},
-        "platform_frequency": {"terms": {"field": "properties.platform", "size": 100}},
-        "cloud_cover_frequency": {
-            "range": {
-                "field": "properties.eo:cloud_cover",
-                "ranges": [
-                    {"to": 5},
-                    {"from": 5, "to": 15},
-                    {"from": 15, "to": 40},
-                    {"from": 40},
-                ],
-            }
-        },
-        "datetime_frequency": {
-            "date_histogram": {
-                "field": "properties.datetime",
-                "calendar_interval": "month",
-            }
-        },
-        "datetime_min": {"min": {"field": "properties.datetime"}},
-        "datetime_max": {"max": {"field": "properties.datetime"}},
-        "grid_code_frequency": {
-            "terms": {
-                "field": "properties.grid:code",
-                "missing": "none",
-                "size": 10000,
-            }
-        },
-        "sun_elevation_frequency": {
-            "histogram": {"field": "properties.view:sun_elevation", "interval": 5}
-        },
-        "sun_azimuth_frequency": {
-            "histogram": {"field": "properties.view:sun_azimuth", "interval": 5}
-        },
-        "off_nadir_frequency": {
-            "histogram": {"field": "properties.view:off_nadir", "interval": 5}
-        },
-        "centroid_geohash_grid_frequency": {
-            "geohash_grid": {
-                "field": "properties.proj:centroid",
-                "precision": 1,
-            }
-        },
-        "centroid_geohex_grid_frequency": {
-            "geohex_grid": {
-                "field": "properties.proj:centroid",
-                "precision": 0,
-            }
-        },
-        "centroid_geotile_grid_frequency": {
-            "geotile_grid": {
-                "field": "properties.proj:centroid",
-                "precision": 0,
-            }
-        },
-        "geometry_geohash_grid_frequency": {
-            "geohash_grid": {
-                "field": "geometry",
-                "precision": 1,
-            }
-        },
-        "geometry_geotile_grid_frequency": {
-            "geotile_grid": {
-                "field": "geometry",
-                "precision": 0,
-            }
-        },
-    }
+    aggregation_mapping: Dict[str, Dict[str, Any]] = AGGREGATION_MAPPING
 
     """CORE LOGIC"""
 
@@ -300,23 +220,12 @@ class DatabaseLogic(BaseDatabaseLogic):
         Returns:
             dict: A dictionary containing the Queryables mappings.
         """
-        queryables_mapping = {}
-
         mappings = await self.client.indices.get_mapping(
             index=f"{ITEMS_INDEX_PREFIX}{collection_id}",
         )
-
-        for mapping in mappings.values():
-            fields = mapping["mappings"].get("properties", {})
-            properties = fields.pop("properties", {}).get("properties", {}).keys()
-
-            for field_key in fields:
-                queryables_mapping[field_key] = field_key
-
-            for property_key in properties:
-                queryables_mapping[property_key] = f"properties.{property_key}"
-
-        return queryables_mapping
+        return await get_queryables_mapping_shared(
+            collection_id=collection_id, mappings=mappings
+        )
 
     @staticmethod
     def make_search():
@@ -334,120 +243,99 @@ class DatabaseLogic(BaseDatabaseLogic):
         return search.filter("terms", collection=collection_ids)
 
     @staticmethod
-    def apply_datetime_filter(search: Search, datetime_search: dict):
+    def apply_datetime_filter(
+        search: Search, interval: Optional[Union[DateTimeType, str]]
+    ) -> Search:
         """Apply a filter to search on datetime, start_datetime, and end_datetime fields.
 
         Args:
-            search (Search): The search object to filter.
-            datetime_search (dict): The datetime filter criteria.
+            search: The search object to filter.
+            interval: Optional datetime interval to filter by. Can be:
+                - A single datetime string (e.g., "2023-01-01T12:00:00")
+                - A datetime range string (e.g., "2023-01-01/2023-12-31")
+                - A datetime object
+                - A tuple of (start_datetime, end_datetime)
 
         Returns:
-            Search: The filtered search object.
+            The filtered search object.
         """
+        if not interval:
+            return search
+
         should = []
+        try:
+            datetime_search = return_date(interval)
+        except (ValueError, TypeError) as e:
+            # Handle invalid interval formats if return_date fails
+            logger.error(f"Invalid interval format: {interval}, error: {e}")
+            return search
 
-        # If the request is a single datetime return
-        # items with datetimes equal to the requested datetime OR
-        # the requested datetime is between their start and end datetimes
         if "eq" in datetime_search:
-            should.extend(
-                [
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "term",
-                                properties__datetime=datetime_search["eq"],
-                            ),
-                        ],
-                    ),
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "range",
-                                properties__start_datetime={
-                                    "lte": datetime_search["eq"],
-                                },
-                            ),
-                            Q(
-                                "range",
-                                properties__end_datetime={
-                                    "gte": datetime_search["eq"],
-                                },
-                            ),
-                        ],
-                    ),
-                ]
-            )
-
-        # If the request is a date range return
-        # items with datetimes within the requested date range OR
-        # their startdatetime ithin the requested date range OR
-        # their enddatetime ithin the requested date range OR
-        # the requested daterange within their start and end datetimes
+            # For exact matches, include:
+            # 1. Items with matching exact datetime
+            # 2. Items with datetime:null where the time falls within their range
+            should = [
+                Q(
+                    "bool",
+                    filter=[
+                        Q("exists", field="properties.datetime"),
+                        Q("term", **{"properties__datetime": datetime_search["eq"]}),
+                    ],
+                ),
+                Q(
+                    "bool",
+                    must_not=[Q("exists", field="properties.datetime")],
+                    filter=[
+                        Q("exists", field="properties.start_datetime"),
+                        Q("exists", field="properties.end_datetime"),
+                        Q(
+                            "range",
+                            properties__start_datetime={"lte": datetime_search["eq"]},
+                        ),
+                        Q(
+                            "range",
+                            properties__end_datetime={"gte": datetime_search["eq"]},
+                        ),
+                    ],
+                ),
+            ]
         else:
-            should.extend(
-                [
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "range",
-                                properties__datetime={
-                                    "gte": datetime_search["gte"],
-                                    "lte": datetime_search["lte"],
-                                },
-                            ),
-                        ],
-                    ),
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "range",
-                                properties__start_datetime={
-                                    "gte": datetime_search["gte"],
-                                    "lte": datetime_search["lte"],
-                                },
-                            ),
-                        ],
-                    ),
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "range",
-                                properties__end_datetime={
-                                    "gte": datetime_search["gte"],
-                                    "lte": datetime_search["lte"],
-                                },
-                            ),
-                        ],
-                    ),
-                    Q(
-                        "bool",
-                        filter=[
-                            Q(
-                                "range",
-                                properties__start_datetime={
-                                    "lte": datetime_search["gte"]
-                                },
-                            ),
-                            Q(
-                                "range",
-                                properties__end_datetime={
-                                    "gte": datetime_search["lte"]
-                                },
-                            ),
-                        ],
-                    ),
-                ]
-            )
-
-        search = search.query(Q("bool", filter=[Q("bool", should=should)]))
-
-        return search
+            # For date ranges, include:
+            # 1. Items with datetime in the range
+            # 2. Items with datetime:null that overlap the search range
+            should = [
+                Q(
+                    "bool",
+                    filter=[
+                        Q("exists", field="properties.datetime"),
+                        Q(
+                            "range",
+                            properties__datetime={
+                                "gte": datetime_search["gte"],
+                                "lte": datetime_search["lte"],
+                            },
+                        ),
+                    ],
+                ),
+                Q(
+                    "bool",
+                    must_not=[Q("exists", field="properties.datetime")],
+                    filter=[
+                        Q("exists", field="properties.start_datetime"),
+                        Q("exists", field="properties.end_datetime"),
+                        Q(
+                            "range",
+                            properties__start_datetime={"lte": datetime_search["lte"]},
+                        ),
+                        Q(
+                            "range",
+                            properties__end_datetime={"gte": datetime_search["gte"]},
+                        ),
+                    ],
+                ),
+            ]
+
+        return search.query(Q("bool", should=should, minimum_should_match=1))
 
     @staticmethod
     def apply_bbox_filter(search: Search, bbox: List):
@@ -497,21 +385,8 @@ class DatabaseLogic(BaseDatabaseLogic):
         Notes:
             A geo_shape filter is added to the search object, set to intersect with the specified geometry.
         """
-        return search.filter(
-            Q(
-                {
-                    "geo_shape": {
-                        "geometry": {
-                            "shape": {
-                                "type": intersects.type.lower(),
-                                "coordinates": intersects.coordinates,
-                            },
-                            "relation": "intersects",
-                        }
-                    }
-                }
-            )
-        )
+        filter = apply_intersects_filter_shared(intersects=intersects)
+        return search.filter(Q(filter))
 
     @staticmethod
     def apply_stacql_filter(search: Search, op: str, field: str, value: float):
@@ -537,14 +412,21 @@ class DatabaseLogic(BaseDatabaseLogic):
 
     @staticmethod
     def apply_free_text_filter(search: Search, free_text_queries: Optional[List[str]]):
-        """Database logic to perform query for search endpoint."""
-        if free_text_queries is not None:
-            free_text_query_string = '" OR properties.\\*:"'.join(free_text_queries)
-            search = search.query(
-                "query_string", query=f'properties.\\*:"{free_text_query_string}"'
-            )
+        """Create a free text query for Elasticsearch queries.
 
-        return search
+        This method delegates to the shared implementation in apply_free_text_filter_shared.
+
+        Args:
+            search (Search): The search object to apply the query to.
+            free_text_queries (Optional[List[str]]): A list of text strings to search for in the properties.
+
+        Returns:
+            Search: The search object with the free text query applied, or the original search
+                object if no free_text_queries were provided.
+        """
+        return apply_free_text_filter_shared(
+            search=search, free_text_queries=free_text_queries
+        )
 
     async def apply_cql2_filter(
         self, search: Search, _filter: Optional[Dict[str, Any]]
@@ -575,11 +457,18 @@ class DatabaseLogic(BaseDatabaseLogic):
 
     @staticmethod
     def populate_sort(sortby: List) -> Optional[Dict[str, Dict[str, str]]]:
-        """Database logic to sort search instance."""
-        if sortby:
-            return {s.field: {"order": s.direction} for s in sortby}
-        else:
-            return None
+        """Create a sort configuration for Elasticsearch queries.
+
+        This method delegates to the shared implementation in populate_sort_shared.
+
+        Args:
+            sortby (List): A list of sort specifications, each containing a field and direction.
+
+        Returns:
+            Optional[Dict[str, Dict[str, str]]]: A dictionary mapping field names to sort direction
+                configurations, or None if no sort was specified.
+        """
+        return populate_sort_shared(sortby=sortby)
 
     async def execute_search(
         self,
@@ -614,7 +503,7 @@ class DatabaseLogic(BaseDatabaseLogic):
         search_after = None
 
         if token:
-            search_after = json.loads(urlsafe_b64decode(token).decode())
+            search_after = orjson.loads(urlsafe_b64decode(token))
 
         query = search.query.to_dict() if search.query else None
 
@@ -654,7 +543,7 @@ class DatabaseLogic(BaseDatabaseLogic):
         next_token = None
         if len(hits) > limit and limit < max_result_window:
             if hits and (sort_array := hits[limit - 1].get("sort")):
-                next_token = urlsafe_b64encode(json.dumps(sort_array).encode()).decode()
+                next_token = urlsafe_b64encode(orjson.dumps(sort_array)).decode()
 
         matched = (
             es_response["hits"]["total"]["value"]
@@ -982,6 +871,37 @@ class DatabaseLogic(BaseDatabaseLogic):
         except ESNotFoundError:
             raise NotFoundError(f"Mapping for index {index_name} not found")
 
+    async def get_items_unique_values(
+        self, collection_id: str, field_names: Iterable[str], *, limit: int = 100
+    ) -> Dict[str, List[str]]:
+        """Get the unique values for the given fields in the collection."""
+        limit_plus_one = limit + 1
+        index_name = index_alias_by_collection_id(collection_id)
+
+        query = await self.client.search(
+            index=index_name,
+            body={
+                "size": 0,
+                "aggs": {
+                    field: {"terms": {"field": field, "size": limit_plus_one}}
+                    for field in field_names
+                },
+            },
+        )
+
+        result: Dict[str, List[str]] = {}
+        for field, agg in query["aggregations"].items():
+            if len(agg["buckets"]) > limit:
+                logger.warning(
+                    "Skipping enum field %s: exceeds limit of %d unique values. "
+                    "Consider excluding this field from enumeration or increase the limit.",
+                    field,
+                    limit,
+                )
+                continue
+            result[field] = [bucket["key"] for bucket in agg["buckets"]]
+        return result
+
     async def create_collection(self, collection: Collection, **kwargs: Any):
         """Create a single collection in the database.
 

stac_fastapi/elasticsearch/version.py

@@ -1,2 +1,2 @@
 """library version."""
-__version__ = "4.2.0"
+__version__ = "5.0.0"