sfeos-helpers 6.9.0__py3-none-any.whl → 6.10.1__py3-none-any.whl

stac_fastapi/sfeos_helpers/database/utils.py

@@ -5,7 +5,7 @@ in Elasticsearch/OpenSearch, such as parameter validation.
 """
 
 import logging
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
 
 from stac_fastapi.core.utilities import bbox2polygon, get_bool_env
 from stac_fastapi.extensions.core.transaction.request import (
@@ -14,10 +14,73 @@ from stac_fastapi.extensions.core.transaction.request import (
     PatchRemove,
 )
 from stac_fastapi.sfeos_helpers.models.patch import ElasticPath, ESCommandSet
+from stac_fastapi.types.errors import ConflictError
 
 logger = logging.getLogger(__name__)
 
 
+class ItemAlreadyExistsError(ConflictError):
+    """Error raised when attempting to create an item that already exists.
+
+    Attributes:
+        item_id: The ID of the item that already exists.
+        collection_id: The ID of the collection containing the item.
+    """
+
+    def __init__(self, item_id: str, collection_id: str):
+        """Initialize the error with item and collection IDs."""
+        self.item_id = item_id
+        self.collection_id = collection_id
+        message = f"Item {item_id} in collection {collection_id} already exists"
+        super().__init__(message)
+
+
+async def check_item_exists_in_alias(client: Any, alias: str, doc_id: str) -> bool:
+    """Check if an item exists across all indexes for an alias.
+
+    Args:
+        client: The async Elasticsearch/OpenSearch client.
+        alias: The index alias to search against.
+        doc_id: The document ID to check for existence.
+
+    Returns:
+        bool: True if the item exists in any index under the alias, False otherwise.
+    """
+    resp = await client.search(
+        index=alias,
+        body={
+            "query": {"ids": {"values": [doc_id]}},
+            "_source": False,
+        },
+        size=0,
+        terminate_after=1,
+    )
+    return bool(resp["hits"]["total"]["value"])
+
+
+def check_item_exists_in_alias_sync(client: Any, alias: str, doc_id: str) -> bool:
+    """Check if an item exists across all indexes for an alias (sync).
+
+    Args:
+        client: The sync Elasticsearch/OpenSearch client.
+        alias: The index alias to search against.
+        doc_id: The document ID to check for existence.
+
+    Returns:
+        bool: True if the item exists in any index under the alias, False otherwise.
+    """
+    resp = client.search(
+        index=alias,
+        body={
+            "query": {"ids": {"values": [doc_id]}},
+            "_source": False,
+        },
+        size=0,
+        terminate_after=1,
+    )
+    return bool(resp["hits"]["total"]["value"])
+
+
 def add_bbox_shape_to_collection(collection: Dict[str, Any]) -> bool:
     """Add bbox_shape field to a collection document for spatial queries.
 
@@ -354,10 +417,42 @@ def operations_to_script(operations: List, create_nest: bool = False) -> Dict:
                 commands=commands, operation=operation, path=path, params=params
             )
 
-        source = "".join(commands)
+    source = "".join(commands)
 
     return {
         "source": source,
         "lang": "painless",
         "params": params,
     }
+
+
+def add_hidden_filter(
+    query: Optional[Dict[str, Any]] = None, hide_item_path: Optional[str] = None
+) -> Dict[str, Any]:
+    """Add hidden filter to a query to exclude hidden items.
+
+    Args:
+        query: Optional Elasticsearch query to combine with hidden filter
+        hide_item_path: Path to the hidden field (e.g., "properties._private.hidden")
+                       If None or empty, return original query (no filtering)
+
+    Returns:
+        Query with hidden filter applied
+    """
+    if not hide_item_path:
+        return query or {"match_all": {}}
+
+    hidden_filter = {
+        "bool": {
+            "should": [
+                {"term": {hide_item_path: False}},
+                {"bool": {"must_not": {"exists": {"field": hide_item_path}}}},
+            ],
+            "minimum_should_match": 1,
+        }
+    }
+
+    if query:
+        return {"bool": {"must": [query, hidden_filter]}}
+    else:
+        return hidden_filter

stac_fastapi/sfeos_helpers/mappings.py

@@ -268,8 +268,8 @@ _BASE_ITEMS_MAPPINGS = {
             "properties": {
                 # Common https://github.com/radiantearth/stac-spec/blob/master/item-spec/common-metadata.md
                 "datetime": {"type": "date_nanos"},
-                "start_datetime": {"type": "date"},
-                "end_datetime": {"type": "date"},
+                "start_datetime": {"type": "date_nanos"},
+                "end_datetime": {"type": "date_nanos"},
                 "created": {"type": "date"},
                 "updated": {"type": "date"},
                 # Satellite Extension https://github.com/stac-extensions/sat

stac_fastapi/sfeos_helpers/search_engine/base.py

@@ -49,3 +49,33 @@ class BaseIndexInserter(ABC):
             str: Created index name.
         """
         pass
+
+    @staticmethod
+    @abstractmethod
+    def should_create_collection_index() -> bool:
+        """Whether this strategy requires collection index creation.
+
+        Returns:
+            bool: True if strategy creates collection indexes, False otherwise.
+        """
+        pass
+
+    async def refresh_cache(self) -> None:
+        """Refresh internal cache if applicable.
+
+        Default implementation does nothing. Subclasses that maintain
+        internal caches should override this method.
+        """
+        pass
+
+    def validate_datetime_field_update(self, field_path: str) -> None:
+        """Validate if a datetime field can be updated.
+
+        For datetime-based indexing, certain datetime fields cannot be modified
+        because they determine the index where the item is stored.
+
+        Args:
+            field_path (str): The path of the field being updated (e.g., "properties.datetime").
+
+        """
+        pass

stac_fastapi/sfeos_helpers/search_engine/index_operations.py

@@ -1,8 +1,9 @@
 """Search engine adapters for different implementations."""
 
 import uuid
-from typing import Any, Dict
+from typing import Any, Dict, List, Literal
 
+from stac_fastapi.core.utilities import get_bool_env
 from stac_fastapi.sfeos_helpers.database import (
     index_alias_by_collection_id,
     index_by_collection_id,
@@ -18,6 +19,16 @@ from stac_fastapi.sfeos_helpers.mappings import (
 class IndexOperations:
     """Base class for search engine adapters with common implementations."""
 
+    @property
+    def use_datetime(self) -> bool:
+        """Get USE_DATETIME setting dynamically."""
+        return get_bool_env("USE_DATETIME", default=True)
+
+    @property
+    def primary_datetime_name(self) -> str:
+        """Get primary datetime field name based on current USE_DATETIME setting."""
+        return "datetime" if self.use_datetime else "start_datetime"
+
     async def create_simple_index(self, client: Any, collection_id: str) -> str:
         """Create a simple index for the given collection.
 
@@ -45,26 +56,51 @@ class IndexOperations:
         return index_name
 
     async def create_datetime_index(
-        self, client: Any, collection_id: str, start_date: str
+        self,
+        client: Any,
+        collection_id: str,
+        start_datetime: str | None,
+        datetime: str | None,
+        end_datetime: str | None,
     ) -> str:
         """Create a datetime-based index for the given collection.
 
         Args:
             client: Search engine client instance.
             collection_id (str): Collection identifier.
-            start_date (str): Start date for the alias.
+            start_datetime (str | None): Start datetime for the index alias.
+            datetime (str | None): Datetime for the datetime alias.
+            end_datetime (str | None): End datetime for the index alias.
 
         Returns:
-            str: Created index alias name.
+            str: Created datetime alias name.
         """
         index_name = self.create_index_name(collection_id)
-        alias_name = self.create_alias_name(collection_id, start_date)
         collection_alias = index_alias_by_collection_id(collection_id)
+
+        aliases: Dict[str, Any] = {
+            collection_alias: {},
+        }
+
+        if start_datetime:
+            alias_start_date = self.create_alias_name(
+                collection_id, "start_datetime", start_datetime
+            )
+            alias_end_date = self.create_alias_name(
+                collection_id, "end_datetime", end_datetime
+            )
+            aliases[alias_start_date] = {}
+            aliases[alias_end_date] = {}
+            created_alias = alias_start_date
+        else:
+            created_alias = self.create_alias_name(collection_id, "datetime", datetime)
+            aliases[created_alias] = {}
+
         await client.indices.create(
             index=index_name,
-            body=self._create_index_body({collection_alias: {}, alias_name: {}}),
+            body=self._create_index_body(aliases),
         )
-        return alias_name
+        return created_alias
 
     @staticmethod
     async def update_index_alias(client: Any, end_date: str, old_alias: str) -> str:
@@ -90,23 +126,33 @@ class IndexOperations:
         return new_alias
 
     @staticmethod
-    async def change_alias_name(client: Any, old_alias: str, new_alias: str) -> None:
-        """Change alias name from old to new.
+    async def change_alias_name(
+        client: Any,
+        old_start_datetime_alias: str,
+        aliases_to_change: List[str],
+        aliases_to_create: List[str],
+    ) -> None:
+        """Change alias names by removing old aliases and adding new ones.
 
         Args:
             client: Search engine client instance.
-            old_alias (str): Current alias name.
-            new_alias (str): New alias name.
+            old_start_datetime_alias (str): Current start_datetime alias name to identify the index.
+            aliases_to_change (List[str]): List of old alias names to remove.
+            aliases_to_create (List[str]): List of new alias names to add.
 
         Returns:
             None
         """
-        aliases_info = await client.indices.get_alias(name=old_alias)
-        actions = []
+        aliases_info = await client.indices.get_alias(name=old_start_datetime_alias)
+        index_name = list(aliases_info.keys())[0]
 
-        for index_name in aliases_info.keys():
+        actions = []
+        for old_alias in aliases_to_change:
             actions.append({"remove": {"index": index_name, "alias": old_alias}})
+
+        for new_alias in aliases_to_create:
             actions.append({"add": {"index": index_name, "alias": new_alias}})
+
         await client.indices.update_aliases(body={"actions": actions})
 
     @staticmethod
@@ -123,18 +169,23 @@ class IndexOperations:
         return f"{ITEMS_INDEX_PREFIX}{cleaned.lower()}_{uuid.uuid4()}"
 
     @staticmethod
-    def create_alias_name(collection_id: str, start_date: str) -> str:
-        """Create index name from collection ID and uuid4.
+    def create_alias_name(
+        collection_id: str,
+        name: Literal["start_datetime", "datetime", "end_datetime"],
+        start_date: str,
+    ) -> str:
+        """Create alias name from collection ID and date.
 
         Args:
             collection_id (str): Collection identifier.
-            start_date (str): Start date for the alias.
+            name (Literal["start_datetime", "datetime", "end_datetime"]): Type of alias to create.
+            start_date (str): Date value for the alias.
 
         Returns:
-            str: Alias name with initial date.
+            str: Formatted alias name with prefix, type, collection ID, and date.
         """
         cleaned = collection_id.translate(_ES_INDEX_NAME_UNSUPPORTED_CHARS_TABLE)
-        return f"{ITEMS_INDEX_PREFIX}{cleaned.lower()}_{start_date}"
+        return f"{ITEMS_INDEX_PREFIX}{name}_{cleaned.lower()}_{start_date}"
 
     @staticmethod
     def _create_index_body(aliases: Dict[str, Dict]) -> Dict[str, Any]:
@@ -152,21 +203,25 @@ class IndexOperations:
             "settings": ES_ITEMS_SETTINGS,
         }
 
-    @staticmethod
-    async def find_latest_item_in_index(client: Any, index_name: str) -> dict[str, Any]:
-        """Find the latest item date in the specified index.
+    async def find_latest_item_in_index(
+        self, client: Any, index_name: str
+    ) -> dict[str, Any]:
+        """Find the latest item in the specified index.
 
         Args:
             client: Search engine client instance.
             index_name (str): Name of the index to query.
 
         Returns:
-            datetime: Date of the latest item in the index.
+            dict[str, Any]: Latest item document from the index with metadata.
         """
         query = {
             "size": 1,
-            "sort": [{"properties.datetime": {"order": "desc"}}],
-            "_source": ["properties.datetime"],
+            "sort": [{f"properties.{self.primary_datetime_name}": {"order": "desc"}}],
+            "_source": [
+                "properties.start_datetime",
+                "properties.datetime",
+            ],
         }
 
         response = await client.search(index=index_name, body=query)