sfeos-helpers 6.5.1__py3-none-any.whl → 6.6.0__py3-none-any.whl

sfeos_helpers-6.6.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: sfeos_helpers
+Version: 6.6.0
+Summary: Helper library for the Elasticsearch and Opensearch stac-fastapi backends.
+Project-URL: Homepage, https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
+License: MIT
+Keywords: Elasticsearch,FastAPI,Opensearch,STAC,STAC-API,stac-fastapi
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Requires-Dist: stac-fastapi-core==6.6.0
+Description-Content-Type: text/markdown
+
+# sfeos-helpers
+
+Helper utilities for the stac-fastapi project. For full documentation, please see the [main README](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/blob/main/README.md).
+
+## Package Information
+
+- **Package name**: sfeos-helpers
+- **Description**: Helper utilities for the stac-fastapi project.
+- **Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
+- **Source**: [GitHub Repository](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/)
+
+## Installation
+
+This package is a dependency of stac-fastapi-elasticsearch and stac-fastapi-opensearch and is typically installed automatically.
+
+```bash
+pip install stac-fastapi-elasticsearch  # or stac-fastapi-opensearch
+```
+
+## Quick Start
+
+For detailed usage and examples, please refer to the [main documentation](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/).

{sfeos_helpers-6.5.1.dist-info → sfeos_helpers-6.6.0.dist-info}/RECORD

@@ -1,15 +1,18 @@
-stac_fastapi/sfeos_helpers/mappings.py,sha256=u7ZHyUu3NPS_sXaflfQPSP2Yleld3jgqCG0yKcQ64w4,8600
-stac_fastapi/sfeos_helpers/version.py,sha256=FuGC3fKnAmD4Wk95swJ6qCVBs5mZiShrlRKuSH-voyE,45
+stac_fastapi/sfeos_helpers/mappings.py,sha256=IqYd0tQUG-FnWVg6Fp1MU9audntF_-pMGm-BUTGbZMM,8596
+stac_fastapi/sfeos_helpers/version.py,sha256=zPQp-GtLh4R45hT8V_KAWzwZcP4-jyw7Xjms_eNMZBc,45
+stac_fastapi/sfeos_helpers/aggregation/README.md,sha256=SDlvCOpKyaJrlJvx84T2RzCnGALe_PK51zNeo3RP9ac,2122
 stac_fastapi/sfeos_helpers/aggregation/__init__.py,sha256=Mym17lFh90by1GnoQgMyIKAqRNJnvCgVSXDYzjBiPQk,1210
 stac_fastapi/sfeos_helpers/aggregation/client.py,sha256=PPUk0kAZnms46FlLGrR5w8wa52vG-dT6BG37896R5CY,17939
 stac_fastapi/sfeos_helpers/aggregation/format.py,sha256=qUW1jjh2EEjy-V7riliFR77grpi-AgsTmP76z60K5Lo,2011
-stac_fastapi/sfeos_helpers/database/__init__.py,sha256=T0YwePfhG3ukL1oUFCh3FYHA9jZZe36FJRYCQplfb18,2645
+stac_fastapi/sfeos_helpers/database/README.md,sha256=TVYFDD4PqDD57ZsWBv4i4LawaL_DAEIOjM6OQuqwLAU,4049
+stac_fastapi/sfeos_helpers/database/__init__.py,sha256=Kvnz8hpXq_sSz8K5OW3PoPsvh9864Vv1zWhI5hxgd4o,2891
 stac_fastapi/sfeos_helpers/database/datetime.py,sha256=XMyi9Q09cuP_hj97qbGbHFtelq7WQVPdehUfzqNZFV4,4040
 stac_fastapi/sfeos_helpers/database/document.py,sha256=LtjX15gvaOuZC_k2t_oQhys_c-zRTLN5rwX0hNJkHnM,1725
 stac_fastapi/sfeos_helpers/database/index.py,sha256=g7_sKfd5XUwq4IhdKRNiasejk045dKlullsdeDSZTq8,6585
 stac_fastapi/sfeos_helpers/database/mapping.py,sha256=4-MSd4xH5wg7yoC4aPjzYMDSEvP026bw4k2TfffMT5E,1387
-stac_fastapi/sfeos_helpers/database/query.py,sha256=g2iGdfgqpx6o8GoQJBMl3AMmqcbSf792qvKWfWipR5w,4193
-stac_fastapi/sfeos_helpers/database/utils.py,sha256=9zU9hEglZb6f-uxOhd95saSw2id9w5PR36dWtyfXTb0,8757
+stac_fastapi/sfeos_helpers/database/query.py,sha256=bbSYe0cLC7oFbhkHR5WTKCF7Ca9iZI3fdanD90KYN98,9476
+stac_fastapi/sfeos_helpers/database/utils.py,sha256=CLtZgoUT37oklc9MsExXsxDviv4bzK-ZP7oxAOXS32Y,11780
+stac_fastapi/sfeos_helpers/filter/README.md,sha256=HT8h7RN7iYgUb-Tf3kOrS2C7_I7dHBZCw1CV1_XVMr4,1947
 stac_fastapi/sfeos_helpers/filter/__init__.py,sha256=n3zL_MhEGOoxMz1KeijyK_UKiZ0MKPl90zHtYI5RAy8,1557
 stac_fastapi/sfeos_helpers/filter/client.py,sha256=QQ6gnUEMqzS_qG8G5QHcX9x3LNk5JvCp1rRJltMTmM4,4414
 stac_fastapi/sfeos_helpers/filter/cql2.py,sha256=Cg9kRYD9CVkVSyRqOyB5oVXmlyteSn2bw88sqklGpUM,955
@@ -26,7 +29,6 @@ stac_fastapi/sfeos_helpers/search_engine/selection/base.py,sha256=106c4FK50cgMmT
 stac_fastapi/sfeos_helpers/search_engine/selection/cache_manager.py,sha256=5yrgf9JA4mgRNMPDKih6xySF8mD724lEWnXhWud7m2c,4039
 stac_fastapi/sfeos_helpers/search_engine/selection/factory.py,sha256=vbgNVCUW2lviePqzpgsPLxp6IEqcX3GHiahqN2oVObA,1305
 stac_fastapi/sfeos_helpers/search_engine/selection/selectors.py,sha256=q83nfCfNfLUqtkHpORwNHNRU9Pa-heeaDIPO0RlHb-8,4779
-sfeos_helpers-6.5.1.dist-info/METADATA,sha256=yCy4qbL5pERMI0QAwOwK2PKff7u0Cus4BLjRr8xuGHg,41326
-sfeos_helpers-6.5.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-sfeos_helpers-6.5.1.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
-sfeos_helpers-6.5.1.dist-info/RECORD,,
+sfeos_helpers-6.6.0.dist-info/METADATA,sha256=g9JGbrU5C9k4Tem68ICmSHSJbd1gsHRFCvO--USKuWc,1911
+sfeos_helpers-6.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sfeos_helpers-6.6.0.dist-info/RECORD,,

{sfeos_helpers-6.5.1.dist-info → sfeos_helpers-6.6.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

stac_fastapi/sfeos_helpers/aggregation/README.md

@@ -0,0 +1,57 @@
+# STAC FastAPI Aggregation Package
+
+This package contains shared aggregation functionality used by both the Elasticsearch and OpenSearch implementations of STAC FastAPI. It helps reduce code duplication and ensures consistent behavior between the two implementations.
+
+## Package Structure
+
+The aggregation package is organized into three main modules:
+
+- **client.py**: Contains the base aggregation client implementation
+  - `EsAsyncBaseAggregationClient`: The main class that implements the STAC aggregation extension for Elasticsearch/OpenSearch
+  - Methods for handling aggregation requests, validating parameters, and formatting responses
+
+- **format.py**: Contains functions for formatting aggregation responses
+  - `frequency_agg`: Formats frequency distribution aggregation responses
+  - `metric_agg`: Formats metric aggregation responses
+
+- **__init__.py**: Package initialization and exports
+  - Exports the main classes and functions for use by other modules
+
+## Features
+
+The aggregation package provides the following features:
+
+- Support for various aggregation types:
+  - Datetime frequency
+  - Collection frequency
+  - Property frequency
+  - Geospatial grid aggregations (geohash, geohex, geotile)
+  - Metric aggregations (min, max, etc.)
+
+- Parameter validation:
+  - Precision validation for geospatial aggregations
+  - Interval validation for datetime aggregations
+
+- Response formatting:
+  - Consistent response structure
+  - Proper typing and documentation
+
+## Usage
+
+The aggregation package is used by the Elasticsearch and OpenSearch implementations to provide aggregation functionality for STAC API. The main entry point is the `EsAsyncBaseAggregationClient` class, which is instantiated in the respective app.py files.
+
+Example:
+```python
+from stac_fastapi.sfeos_helpers.aggregation import EsAsyncBaseAggregationClient
+
+# Create an instance of the aggregation client
+aggregation_client = EsAsyncBaseAggregationClient(database)
+
+# Register the aggregation extension with the API
+api = StacApi(
+    ...,
+    extensions=[
+        ...,
+        AggregationExtension(client=aggregation_client),
+    ],
+)

stac_fastapi/sfeos_helpers/database/README.md

@@ -0,0 +1,61 @@
+# STAC FastAPI Database Package
+
+This package contains shared database operations used by both the Elasticsearch and OpenSearch
+implementations of STAC FastAPI. It helps reduce code duplication and ensures consistent behavior
+between the two implementations.
+
+## Package Structure
+
+The database package is organized into five main modules:
+
+- **index.py**: Contains functions for managing indices
+  - [create_index_templates_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:15:0-48:33): Creates index templates for Collections and Items
+  - [delete_item_index_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:128:0-153:30): Deletes an item index for a collection
+  - [index_by_collection_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:86:0-100:5): Translates a collection ID into an index name
+  - [index_alias_by_collection_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:103:0-115:5): Translates a collection ID into an index alias
+  - [indices](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:118:0-132:5): Gets a comma-separated string of index names
+
+- **query.py**: Contains functions for building and manipulating queries
+  - [apply_free_text_filter_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:51:0-74:16): Applies a free text filter to a search
+  - [apply_intersects_filter_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:77:0-104:5): Creates a geo_shape filter for intersecting geometry
+  - [populate_sort_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:107:0-125:16): Creates a sort configuration for queries
+
+- **mapping.py**: Contains functions for working with mappings
+  - [get_queryables_mapping_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:156:0-185:27): Retrieves mapping of Queryables for search
+
+- **document.py**: Contains functions for working with documents
+  - [mk_item_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:140:0-150:5): Creates a document ID for an Item
+  - [mk_actions](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:153:0-175:5): Creates bulk actions for indexing items
+
+- **utils.py**: Contains utility functions for database operations
+  - [validate_refresh](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:41:0-78:5): Validates the refresh parameter value
+
+## Usage
+
+Import the necessary components from the database package:
+
+```python
+from stac_fastapi.sfeos_helpers.database import (
+    # Index operations
+    create_index_templates_shared,
+    delete_item_index_shared,
+    index_alias_by_collection_id,
+    index_by_collection_id,
+    indices,
+    
+    # Query operations
+    apply_free_text_filter_shared,
+    apply_intersects_filter_shared,
+    populate_sort_shared,
+    
+    # Mapping operations
+    get_queryables_mapping_shared,
+    
+    # Document operations
+    mk_item_id,
+    mk_actions,
+    
+    # Utility functions
+    validate_refresh,
+)
+```

stac_fastapi/sfeos_helpers/database/__init__.py

@@ -42,11 +42,13 @@ from .index import (
 )
 from .mapping import get_queryables_mapping_shared
 from .query import (
+    apply_collections_bbox_filter_shared,
+    apply_collections_datetime_filter_shared,
     apply_free_text_filter_shared,
     apply_intersects_filter_shared,
     populate_sort_shared,
 )
-from .utils import get_bool_env, validate_refresh
+from .utils import add_bbox_shape_to_collection, get_bool_env, validate_refresh
 
 __all__ = [
     # Index operations
@@ -59,6 +61,8 @@ __all__ = [
     # Query operations
     "apply_free_text_filter_shared",
     "apply_intersects_filter_shared",
+    "apply_collections_bbox_filter_shared",
+    "apply_collections_datetime_filter_shared",
     "populate_sort_shared",
     # Mapping operations
     "get_queryables_mapping_shared",
@@ -68,6 +72,7 @@ __all__ = [
     # Utility functions
     "validate_refresh",
     "get_bool_env",
+    "add_bbox_shape_to_collection",
     # Datetime utilities
     "return_date",
     "extract_date",

stac_fastapi/sfeos_helpers/database/query.py

@@ -3,8 +3,10 @@
 This module provides functions for building and manipulating Elasticsearch/OpenSearch queries.
 """
 
-from typing import Any, Dict, List, Optional
+import logging
+from typing import Any, Dict, List, Optional, Union
 
+from stac_fastapi.core.utilities import bbox2polygon
 from stac_fastapi.sfeos_helpers.mappings import Geometry
 
 ES_MAX_URL_LENGTH = 4096
@@ -66,6 +68,139 @@ def apply_intersects_filter_shared(
     }
 
 
+def apply_collections_datetime_filter_shared(
+    datetime_str: Optional[str],
+) -> Optional[Dict[str, Any]]:
+    """Create a temporal filter for collections based on their extent.
+
+    Args:
+        datetime_str: The datetime parameter. Can be:
+            - A single datetime string (e.g., "2020-01-01T00:00:00Z")
+            - A datetime range with "/" separator (e.g., "2020-01-01T00:00:00Z/2021-01-01T00:00:00Z")
+            - Open-ended ranges using ".." (e.g., "../2021-01-01T00:00:00Z" or "2020-01-01T00:00:00Z/..")
+            - None if no datetime filter is provided
+
+    Returns:
+        Optional[Dict[str, Any]]: A dictionary containing the temporal filter configuration
+            that can be used with Elasticsearch/OpenSearch queries, or None if datetime_str is None.
+            Example return value:
+            {
+                "bool": {
+                    "must": [
+                        {"range": {"extent.temporal.interval": {"lte": "2021-01-01T00:00:00Z"}}},
+                        {"range": {"extent.temporal.interval": {"gte": "2020-01-01T00:00:00Z"}}}
+                    ]
+                }
+            }
+
+    Notes:
+        - This function is specifically for filtering collections by their temporal extent
+        - It queries the extent.temporal.interval field
+        - Open-ended ranges (..) are replaced with concrete dates (1800-01-01 for start, 2999-12-31 for end)
+    """
+    if not datetime_str:
+        return None
+
+    # Parse the datetime string into start and end
+    if "/" in datetime_str:
+        start, end = datetime_str.split("/")
+        # Replace open-ended ranges with concrete dates
+        if start == "..":
+            # For open-ended start, use a very early date
+            start = "1800-01-01T00:00:00Z"
+        if end == "..":
+            # For open-ended end, use a far future date
+            end = "2999-12-31T23:59:59Z"
+    else:
+        # If it's just a single date, use it for both start and end
+        start = end = datetime_str
+
+    return {
+        "bool": {
+            "must": [
+                # Check if any date in the array is less than or equal to the query end date
+                # This will match if the collection's start date is before or equal to the query end date
+                {"range": {"extent.temporal.interval": {"lte": end}}},
+                # Check if any date in the array is greater than or equal to the query start date
+                # This will match if the collection's end date is after or equal to the query start date
+                {"range": {"extent.temporal.interval": {"gte": start}}},
+            ]
+        }
+    }
+
+
+def apply_collections_bbox_filter_shared(
+    bbox: Union[str, List[float], None]
+) -> Optional[Dict[str, Dict]]:
+    """Create a geo_shape filter for collections bbox search.
+
+    This function handles bbox parsing from both GET requests (string format) and POST requests
+    (list format), and constructs a geo_shape query for filtering collections by their bbox_shape field.
+
+    Args:
+        bbox: The bounding box parameter. Can be:
+            - A string of comma-separated coordinates (from GET requests)
+            - A list of floats [minx, miny, maxx, maxy] for 2D bbox
+            - None if no bbox filter is provided
+
+    Returns:
+        Optional[Dict[str, Dict]]: A dictionary containing the geo_shape filter configuration
+            that can be used with Elasticsearch/OpenSearch queries, or None if bbox is invalid.
+            Example return value:
+            {
+                "geo_shape": {
+                    "bbox_shape": {
+                        "shape": {
+                            "type": "Polygon",
+                            "coordinates": [[[minx, miny], [maxx, miny], [maxx, maxy], [minx, maxy], [minx, miny]]]
+                        },
+                        "relation": "intersects"
+                    }
+                }
+            }
+
+    Notes:
+        - This function is specifically for filtering collections by their spatial extent
+        - It queries the bbox_shape field (not the geometry field used for items)
+        - The bbox is expected to be 2D (4 values) after any 3D to 2D conversion in the API layer
+    """
+    logger = logging.getLogger(__name__)
+
+    if not bbox:
+        return None
+
+    # Parse bbox if it's a string (from GET requests)
+    if isinstance(bbox, str):
+        try:
+            bbox = [float(x.strip()) for x in bbox.split(",")]
+        except (ValueError, AttributeError) as e:
+            logger.error(f"Invalid bbox format: {bbox}, error: {e}")
+            return None
+
+    if not bbox or len(bbox) != 4:
+        if bbox:
+            logger.warning(
+                f"bbox has incorrect number of coordinates (length={len(bbox)}), expected 4 (2D bbox)"
+            )
+        return None
+
+    # Convert bbox to a polygon for geo_shape query
+    bbox_polygon = {
+        "type": "Polygon",
+        "coordinates": bbox2polygon(bbox[0], bbox[1], bbox[2], bbox[3]),
+    }
+
+    # Return geo_shape query for bbox_shape field
+    return {
+        "geo_shape": {
+            "bbox_shape": {
+                "shape": bbox_polygon,
+                "relation": "intersects",
+            }
+        }
+    }
+
+
 def populate_sort_shared(sortby: List) -> Optional[Dict[str, Dict[str, str]]]:
     """Create a sort configuration for Elasticsearch/OpenSearch queries.
 

stac_fastapi/sfeos_helpers/database/utils.py

@@ -5,9 +5,9 @@ in Elasticsearch/OpenSearch, such as parameter validation.
 """
 
 import logging
-from typing import Dict, List, Union
+from typing import Any, Dict, List, Union
 
-from stac_fastapi.core.utilities import get_bool_env
+from stac_fastapi.core.utilities import bbox2polygon, get_bool_env
 from stac_fastapi.extensions.core.transaction.request import (
     PatchAddReplaceTest,
     PatchOperation,
@@ -15,6 +15,84 @@ from stac_fastapi.extensions.core.transaction.request import (
 )
 from stac_fastapi.sfeos_helpers.models.patch import ElasticPath, ESCommandSet
 
+logger = logging.getLogger(__name__)
+
+
+def add_bbox_shape_to_collection(collection: Dict[str, Any]) -> bool:
+    """Add bbox_shape field to a collection document for spatial queries.
+
+    This function extracts the bounding box from a collection's spatial extent
+    and converts it to a GeoJSON polygon shape that can be used for geospatial
+    queries in Elasticsearch/OpenSearch.
+
+    Args:
+        collection: Collection document dictionary to modify in-place.
+
+    Returns:
+        bool: True if bbox_shape was added, False if it was skipped (already exists,
+            no spatial extent, or invalid bbox).
+
+    Notes:
+        - Modifies the collection dictionary in-place by adding a 'bbox_shape' field
+        - Handles both 2D [minx, miny, maxx, maxy] and 3D [minx, miny, minz, maxx, maxy, maxz] bboxes
+        - Uses the first bbox if multiple are present in the collection
+        - Logs warnings for collections with invalid or missing bbox data
+    """
+    collection_id = collection.get("id", "unknown")
+
+    # Check if bbox_shape already exists
+    if "bbox_shape" in collection:
+        logger.debug(
+            f"Collection '{collection_id}' already has bbox_shape field, skipping"
+        )
+        return False
+
+    # Check if collection has spatial extent
+    if "extent" not in collection or "spatial" not in collection["extent"]:
+        logger.warning(f"Collection '{collection_id}' has no spatial extent, skipping")
+        return False
+
+    spatial_extent = collection["extent"]["spatial"]
+    if "bbox" not in spatial_extent or not spatial_extent["bbox"]:
+        logger.warning(
+            f"Collection '{collection_id}' has no bbox in spatial extent, skipping"
+        )
+        return False
+
+    # Get the first bbox (collections can have multiple bboxes, but we use the first one)
+    bbox = (
+        spatial_extent["bbox"][0]
+        if isinstance(spatial_extent["bbox"][0], list)
+        else spatial_extent["bbox"]
+    )
+
+    if len(bbox) < 4:
+        logger.warning(
+            f"Collection '{collection_id}': bbox has insufficient coordinates (length={len(bbox)}), expected at least 4"
+        )
+        return False
+
+    # Extract 2D coordinates (bbox can be 2D [minx, miny, maxx, maxy] or 3D [minx, miny, minz, maxx, maxy, maxz])
+    # For 2D polygon, we only need the x,y coordinates and discard altitude (z) values
+    minx, miny = bbox[0], bbox[1]
+    if len(bbox) == 4:
+        # 2D bbox: [minx, miny, maxx, maxy]
+        maxx, maxy = bbox[2], bbox[3]
+    else:
+        # 3D bbox: [minx, miny, minz, maxx, maxy, maxz]
+        # Extract indices 3,4 for maxx,maxy - discarding altitude at indices 2 (minz) and 5 (maxz)
+        maxx, maxy = bbox[3], bbox[4]
+
+    # Convert bbox to GeoJSON polygon
+    bbox_polygon_coords = bbox2polygon(minx, miny, maxx, maxy)
+    collection["bbox_shape"] = {
+        "type": "Polygon",
+        "coordinates": bbox_polygon_coords,
+    }
+
+    logger.debug(f"Collection '{collection_id}': Added bbox_shape field")
+    return True
+
 
 def validate_refresh(value: Union[str, bool]) -> str:
     """

stac_fastapi/sfeos_helpers/filter/README.md

@@ -0,0 +1,27 @@
+# STAC FastAPI Filter Package
+
+This package contains shared filter extension functionality used by both the Elasticsearch and OpenSearch
+implementations of STAC FastAPI. It helps reduce code duplication and ensures consistent behavior
+between the two implementations.
+
+## Package Structure
+
+The filter package is organized into three main modules:
+
+- **cql2.py**: Contains functions for converting CQL2 patterns to Elasticsearch/OpenSearch compatible formats
+  - [cql2_like_to_es](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/filter.py:59:0-75:5): Converts CQL2 "LIKE" characters to Elasticsearch "wildcard" characters
+  - [_replace_like_patterns](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/filter.py:51:0-56:71): Helper function for pattern replacement
+
+- **transform.py**: Contains functions for transforming CQL2 queries to Elasticsearch/OpenSearch query DSL
+  - [to_es_field](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/filter.py:83:0-93:47): Maps field names using queryables mapping
+  - [to_es](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/filter.py:96:0-201:13): Transforms CQL2 query structures to Elasticsearch/OpenSearch query DSL
+
+- **client.py**: Contains the base filter client implementation
+  - [EsAsyncBaseFiltersClient](cci:2://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/filter.py:209:0-293:25): Base class for implementing the STAC filter extension
+
+## Usage
+
+Import the necessary components from the filter package:
+
+```python
+from stac_fastapi.sfeos_helpers.filter import cql2_like_to_es, to_es, EsAsyncBaseFiltersClient

stac_fastapi/sfeos_helpers/mappings.py

@@ -160,7 +160,7 @@ ES_COLLECTIONS_MAPPINGS = {
     "dynamic_templates": ES_MAPPINGS_DYNAMIC_TEMPLATES,
     "properties": {
         "id": {"type": "keyword"},
-        "extent.spatial.bbox": {"type": "long"},
+        "bbox_shape": {"type": "geo_shape"},
         "extent.temporal.interval": {
             "type": "date",
             "format": "strict_date_optional_time||epoch_millis",

stac_fastapi/sfeos_helpers/version.py

@@ -1,2 +1,2 @@
 """library version."""
-__version__ = "6.5.1"
+__version__ = "6.6.0"

sfeos_helpers-6.5.1.dist-info/METADATA

@@ -1,714 +0,0 @@
-Metadata-Version: 2.1
-Name: sfeos-helpers
-Version: 6.5.1
-Summary: Helper library for the Elasticsearch and Opensearch stac-fastapi backends.
-Home-page: https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
-License: MIT
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: Intended Audience :: Science/Research
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: stac-fastapi.core==6.5.1
-
-# stac-fastapi-elasticsearch-opensearch
-
-<!-- markdownlint-disable MD033 MD041 -->
-
-
-<p align="left">
-  <img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/sfeos.png" width=1000>
-</p>
-
-**Jump to:** [Project Introduction](#project-introduction---what-is-sfeos) | [Quick Start](#quick-start) | [Table of Contents](#table-of-contents)
-
-  [![Downloads](https://static.pepy.tech/badge/stac-fastapi-core?color=blue)](https://pepy.tech/project/stac-fastapi-core)
-  [![GitHub contributors](https://img.shields.io/github/contributors/stac-utils/stac-fastapi-elasticsearch-opensearch?color=blue)](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/graphs/contributors)
-  [![GitHub stars](https://img.shields.io/github/stars/stac-utils/stac-fastapi-elasticsearch-opensearch.svg?color=blue)](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/stargazers)
-  [![GitHub forks](https://img.shields.io/github/forks/stac-utils/stac-fastapi-elasticsearch-opensearch.svg?color=blue)](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/network/members)
-   [![PyPI version](https://img.shields.io/pypi/v/stac-fastapi-elasticsearch.svg?color=blue)](https://pypi.org/project/stac-fastapi-elasticsearch/)
-  [![STAC](https://img.shields.io/badge/STAC-1.1.0-blue.svg)](https://github.com/radiantearth/stac-spec/tree/v1.1.0)
-  [![stac-fastapi](https://img.shields.io/badge/stac--fastapi-6.0.0-blue.svg)](https://github.com/stac-utils/stac-fastapi)
-
-## Sponsors & Supporters
-
-The following organizations have contributed time and/or funding to support the development of this project:
-
-<p align="left">
-  <a href="https://healy-hyperspatial.github.io/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/hh-logo-blue.png" alt="Healy Hyperspatial" height="100" hspace="20"></a>
-  <a href="https://atomicmaps.io/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/am-logo-black.png" alt="Atomic Maps" height="100" hspace="20"></a>
-  <a href="https://remotesensing.vito.be/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/VITO.png" alt="VITO Remote Sensing" height="100" hspace="20"></a>
-</p>
-
-## Project Introduction - What is SFEOS?
-
-SFEOS (stac-fastapi-elasticsearch-opensearch) is a high-performance, scalable API implementation for serving SpatioTemporal Asset Catalog (STAC) data - an enhanced GeoJSON format designed specifically for geospatial assets like satellite imagery, aerial photography, and other Earth observation data. This project enables organizations to:
-
-- **Efficiently catalog and search geospatial data** such as satellite imagery, aerial photography, DEMs, and other geospatial assets using Elasticsearch or OpenSearch as the database backend
-- **Implement standardized STAC APIs** that support complex spatial, temporal, and property-based queries across large collections of geospatial data
-- **Scale to millions of geospatial assets** with fast search performance through optimized spatial indexing and query capabilities
-- **Support OGC-compliant filtering** including spatial operations (intersects, contains, etc.) and temporal queries
-- **Perform geospatial aggregations** to analyze data distribution across space and time
-- **Enhanced collection search capabilities** with support for sorting and field selection
-
-This implementation builds on the STAC-FastAPI framework, providing a production-ready solution specifically optimized for Elasticsearch and OpenSearch databases. It's ideal for organizations managing large geospatial data catalogs who need efficient discovery and access capabilities through standardized APIs.
-
-## Common Deployment Patterns
-
-stac-fastapi-elasticsearch-opensearch can be deployed in several ways depending on your needs:
-
-- **Containerized Application**: Run as a Docker container with connections to Elasticsearch/OpenSearch databases
-- **Serverless Function**: Deploy as AWS Lambda or similar serverless function with API Gateway
-- **Traditional Server**: Run on virtual machines or bare metal servers in your infrastructure
-- **Kubernetes**: Deploy as part of a larger microservices architecture with container orchestration
-
-The implementation is flexible and can scale from small local deployments to large production environments serving millions of geospatial assets.
-
-## Technologies
-
-This project is built on the following technologies: STAC, stac-fastapi, FastAPI, Elasticsearch, Python, OpenSearch
-
-<p align="left">
-  <a href="https://stacspec.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/STAC-01.png" alt="STAC" height="100" hspace="10"></a>
-  <a href="https://www.python.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/python.png" alt="Python" height="80" hspace="10"></a>
-  <a href="https://fastapi.tiangolo.com/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/fastapi.svg" alt="FastAPI" height="80" hspace="10"></a>
-  <a href="https://www.elastic.co/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/elasticsearch.png" alt="Elasticsearch" height="80" hspace="10"></a>
-  <a href="https://opensearch.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/opensearch.svg" alt="OpenSearch" height="80" hspace="10"></a>
-</p>
-
-## Table of Contents
-
-- [stac-fastapi-elasticsearch-opensearch](#stac-fastapi-elasticsearch-opensearch)
-  - [Sponsors & Supporters](#sponsors--supporters)
-  - [Project Introduction - What is SFEOS?](#project-introduction---what-is-sfeos)
-  - [Common Deployment Patterns](#common-deployment-patterns)
-  - [Technologies](#technologies)
-  - [Table of Contents](#table-of-contents)
-  - [Collection Search Extensions](#collection-search-extensions)
-  - [Documentation & Resources](#documentation--resources)
-  - [Package Structure](#package-structure)
-  - [Examples](#examples)
-  - [Performance](#performance)
-    - [Direct Response Mode](#direct-response-mode)
-  - [Quick Start](#quick-start)
-    - [Installation](#installation)
-    - [Running Locally](#running-locally)
-      - [Using Pre-built Docker Images](#using-pre-built-docker-images)
-      - [Using Docker Compose](#using-docker-compose)
-  - [Configuration Reference](#configuration-reference)
-  - [Datetime-Based Index Management](#datetime-based-index-management)
-    - [Overview](#overview)
-    - [When to Use](#when-to-use)
-    - [Configuration](#configuration)
-      - [Enabling Datetime-Based Indexing](#enabling-datetime-based-indexing)
-    - [Related Configuration Variables](#related-configuration-variables)
-  - [How Datetime-Based Indexing Works](#how-datetime-based-indexing-works)
-    - [Index and Alias Naming Convention](#index-and-alias-naming-convention)
-    - [Index Size Management](#index-size-management)
-  - [Interacting with the API](#interacting-with-the-api)
-  - [Configure the API](#configure-the-api)
-  - [Collection Pagination](#collection-pagination)
-  - [Ingesting Sample Data CLI Tool](#ingesting-sample-data-cli-tool)
-  - [Elasticsearch Mappings](#elasticsearch-mappings)
-  - [Managing Elasticsearch Indices](#managing-elasticsearch-indices)
-    - [Snapshots](#snapshots)
-    - [Reindexing](#reindexing)
-  - [Auth](#auth)
-  - [Aggregation](#aggregation)
-  - [Rate Limiting](#rate-limiting)
-
-## Documentation & Resources
-
-- **Online Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
-- **Source Code**: [https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch)
-- **API Examples**: [Postman Documentation](https://documenter.getpostman.com/view/12888943/2s8ZDSdRHA) - Examples of how to use the API endpoints
-- **Community**:
-  - [Gitter Chat](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) - For real-time discussions
-  - [GitHub Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) - For longer-form questions and answers
-
-## Collection Search Extensions
-
-SFEOS provides enhanced collection search capabilities through two primary routes:
-- **GET/POST `/collections`**: The standard STAC endpoint with extended query parameters
-- **GET/POST `/collections-search`**: A custom endpoint that supports the same parameters, created to avoid conflicts with the STAC Transactions extension if enabled (which uses POST `/collections` for collection creation)
-
-These endpoints support advanced collection discovery features including:
-
-- **Sorting**: Sort collections by sortable fields using the `sortby` parameter
-  - Example: `/collections?sortby=+id` (ascending sort by ID)
-  - Example: `/collections?sortby=-id` (descending sort by ID)
-  - Example: `/collections?sortby=-temporal` (descending sort by temporal extent)
-
-- **Field Selection**: Request only specific fields to be returned using the `fields` parameter
-  - Example: `/collections?fields=id,title,description`
-  - This helps reduce payload size when only certain fields are needed
-
-- **Free Text Search**: Search across collection text fields using the `q` parameter
-  - Example: `/collections?q=landsat`
-  - Searches across multiple text fields including title, description, and keywords
-  - Supports partial word matching and relevance-based sorting
-
-- **Structured Filtering**: Filter collections using CQL2 expressions
-  - JSON format: `/collections?filter={"op":"=","args":[{"property":"id"},"sentinel-2"]}&filter-lang=cql2-json`
-  - Text format: `/collections?filter=id='sentinel-2'&filter-lang=cql2-text` (note: string values must be quoted)
-  - Advanced text format: `/collections?filter=id LIKE '%sentinel%'&filter-lang=cql2-text` (supports LIKE, BETWEEN, etc.)
-  - Supports both CQL2 JSON and CQL2 text formats with various operators
-  - Enables precise filtering on any collection property
-
-- **Datetime Filtering**: Filter collections by their temporal extent using the `datetime` parameter
-  - Example: `/collections?datetime=2020-01-01T00:00:00Z/2020-12-31T23:59:59Z` (finds collections with temporal extents that overlap this range)
-  - Example: `/collections?datetime=2020-06-15T12:00:00Z` (finds collections whose temporal extent includes this specific time)
-  - Example: `/collections?datetime=2020-01-01T00:00:00Z/..` (finds collections with temporal extents that extend to or beyond January 1, 2020)
-  - Example: `/collections?datetime=../2020-12-31T23:59:59Z` (finds collections with temporal extents that begin on or before December 31, 2020)
-  - Collections are matched if their temporal extent overlaps with the provided datetime parameter
-  - This allows for efficient discovery of collections based on time periods
-
-These extensions make it easier to build user interfaces that display and navigate through collections efficiently.
-
-> **Configuration**: Collection search extensions (sorting, field selection, free text search, structured filtering, and datetime filtering) for the `/collections` endpoint can be disabled by setting the `ENABLE_COLLECTIONS_SEARCH` environment variable to `false`. By default, these extensions are enabled.
-> 
-> **Configuration**: The custom `/collections-search` endpoint can be enabled by setting the `ENABLE_COLLECTIONS_SEARCH_ROUTE` environment variable to `true`. By default, this endpoint is **disabled**.
-
-> **Note**: Sorting is only available on fields that are indexed for sorting in Elasticsearch/OpenSearch. With the default mappings, you can sort on:
-> - `id` (keyword field)
-> - `extent.temporal.interval` (date field)
-> - `temporal` (alias to extent.temporal.interval)
->
-> 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.
->
-> **Important**: Adding keyword fields to make text fields sortable can significantly increase the index size, especially for large text fields. Consider the storage implications when deciding which fields to make sortable.
-
-
-## Package Structure
-
-This project is organized into several packages, each with a specific purpose:
-
-- **stac_fastapi_core**: Core functionality that's database-agnostic, including API models, extensions, and shared utilities. This package provides the foundation for building STAC API implementations with any database backend. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
-
-- **sfeos_helpers**: Shared helper functions and utilities used by both the Elasticsearch and OpenSearch backends. This package includes:
-  - `database`: Specialized modules for index, document, and database utility operations
-  - `aggregation`: Elasticsearch/OpenSearch-specific aggregation functionality
-  - Shared logic and utilities that improve code reuse between backends
-
-- **stac_fastapi_elasticsearch**: Complete implementation of the STAC API using Elasticsearch as the backend database. This package depends on both `stac_fastapi_core` and `sfeos_helpers`.
-
-- **stac_fastapi_opensearch**: Complete implementation of the STAC API using OpenSearch as the backend database. This package depends on both `stac_fastapi_core` and `sfeos_helpers`.
-
-## Examples
-
-The `/examples` directory contains several useful examples and reference implementations:
-
-- **pip_docker**: Examples of running stac-fastapi-elasticsearch from PyPI in Docker without needing any code from the repository
-- **auth**: Authentication examples including:
-  - Basic authentication
-  - OAuth2 with Keycloak
-  - Route dependencies configuration
-- **rate_limit**: Example of implementing rate limiting for API requests
-- **postman_collections**: Postman collection files you can import for testing API endpoints
-
-These examples provide practical reference implementations for various deployment scenarios and features.
-
-## Performance
-
-### Direct Response Mode
-
-- The `enable_direct_response` option is provided by the stac-fastapi core library (introduced in stac-fastapi 5.2.0) and is available in this project starting from v4.0.0.
-- **Control via environment variable**: Set `ENABLE_DIRECT_RESPONSE=true` to enable this feature.
-- **How it works**: When enabled, endpoints return Starlette Response objects directly, bypassing FastAPI's default serialization for improved performance.
-- **Important limitation**: All FastAPI dependencies (including authentication, custom status codes, and validation) are disabled for all routes when this mode is enabled.
-- **Best use case**: This mode is best suited for public or read-only APIs where authentication and custom logic are not required.
-- **Default setting**: `false` for safety.
-- **More information**: See [issue #347](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347) for background and implementation details.
-
-## Quick Start
-
-This section helps you get up and running with stac-fastapi-elasticsearch-opensearch quickly.
-
-### Installation
-
-- **For versions 4.0.0a1 and newer** (PEP 625 compliant naming):
-  ```bash
-  pip install stac-fastapi-elasticsearch  # Elasticsearch backend
-  pip install stac-fastapi-opensearch    # Opensearch backend
-  pip install stac-fastapi-core          # Core library
-  ```
-
-- **For versions 4.0.0a0 and older**:
-  ```bash
-  pip install stac-fastapi.elasticsearch  # Elasticsearch backend
-  pip install stac-fastapi.opensearch    # Opensearch backend
-  pip install stac-fastapi.core          # Core library
-  ```
-
-> **Important Note:** Starting with version 4.0.0a1, package names have changed from using periods (e.g., `stac-fastapi.core`) to using hyphens (e.g., `stac-fastapi-core`) to comply with PEP 625. The internal package structure uses underscores, but users should install with hyphens as shown above. Please update your requirements files accordingly.
-
-### Running Locally
-
-There are two main ways to run the API locally:
-
-#### Using Pre-built Docker Images
-
-- We provide ready-to-use Docker images through GitHub Container Registry:
-  - [ElasticSearch backend](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-es)
-  - [OpenSearch backend](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-os)
-
-- **Pull and run the images**:
-  ```shell
-  # For Elasticsearch backend
-  docker pull ghcr.io/stac-utils/stac-fastapi-es:latest
-
-  # For OpenSearch backend
-  docker pull ghcr.io/stac-utils/stac-fastapi-os:latest
-  ```
-
-#### Using Docker Compose
-
-- **Prerequisites**: Ensure [Docker Compose](https://docs.docker.com/compose/install/) or [Podman Compose](https://podman-desktop.io/docs/compose) is installed on your machine.
-
-- **Start the API**:
-  ```shell
-  docker compose up elasticsearch app-elasticsearch
-  ```
-
-- **Configuration**: By default, Docker Compose uses Elasticsearch 8.x and OpenSearch 2.11.1. To use different versions, create a `.env` file:
-  ```shell
-  ELASTICSEARCH_VERSION=8.11.0
-  OPENSEARCH_VERSION=2.11.1
-  ENABLE_DIRECT_RESPONSE=false
-  ```
-
-- **Compatibility**: The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
-
-
-
-## Configuration Reference
-
-You can customize additional settings in your `.env` file:
-
-| Variable                     | Description                                                                          | Default                  | Required                                                                                     |
-|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
-| `ES_HOST`                    | Hostname for external Elasticsearch/OpenSearch.                                      | `localhost`              | Optional                                                                                    |
-| `ES_PORT`                    | Port for Elasticsearch/OpenSearch.                                                   | `9200` (ES) / `9202` (OS)| Optional                                                                                    |
-| `ES_USE_SSL`                 | Use SSL for connecting to Elasticsearch/OpenSearch.                                  | `true`                   | Optional                                                                                    |
-| `ES_VERIFY_CERTS`            | Verify SSL certificates when connecting.                                             | `true`                   | Optional                                                                                    |
-| `ES_API_KEY`                 | API Key for external Elasticsearch/OpenSearch.                                       | N/A                      | Optional                                                                                    |
-| `ES_TIMEOUT`                 | Client timeout for Elasticsearch/OpenSearch.                                         | DB client default        | Optional                                                                                    |
-| `STAC_FASTAPI_TITLE`         | Title of the API in the documentation.                                               | `stac-fastapi-<backend>` | Optional                                                                                    |
-| `STAC_FASTAPI_DESCRIPTION`   | Description of the API in the documentation.                                         | N/A                      | Optional                                                                                    |
-| `STAC_FASTAPI_VERSION`       | API version.                                                                         | `2.1`                    | Optional                                                                                    |
-| `STAC_FASTAPI_LANDING_PAGE_ID` | Landing page ID                                                                    | `stac-fastapi`           | Optional                                                                                    |
-| `APP_HOST`                   | Server bind address.                                                                 | `0.0.0.0`                | Optional                                                                                    |
-| `APP_PORT`                   | Server port.                                                                         | `8000`                   | Optional                                                                                    |
-| `ENVIRONMENT`                | Runtime environment.                                                                 | `local`                  | Optional                                                                                    |
-| `WEB_CONCURRENCY`            | Number of worker processes.                                                          | `10`                     | Optional                                                                                    |
-| `RELOAD`                     | Enable auto-reload for development.                                                  | `true`                   | Optional                                                                                    |
-| `STAC_FASTAPI_RATE_LIMIT`    | API rate limit per client.                                                           | `200/minute`             | Optional                                                                                    |
-| `BACKEND`                    | Tests-related variable                                                               | `elasticsearch` or `opensearch` based on the backend | Optional                                                        |
-| `ELASTICSEARCH_VERSION`      | Version of Elasticsearch to use.                                                     | `8.11.0`                 | Optional                                                                                    |
-| `OPENSEARCH_VERSION`         | OpenSearch version                                                                   | `2.11.1`                 | Optional                                                                                    |
-| `ENABLE_DIRECT_RESPONSE`     | Enable direct response for maximum performance (disables all FastAPI dependencies, including authentication, custom status codes, and validation) | `false`                  | Optional                       |
-| `RAISE_ON_BULK_ERROR`        | Controls whether bulk insert operations raise exceptions on errors. If set to `true`, the operation will stop and raise an exception when an error occurs. If set to `false`, errors will be logged, and the operation will continue. **Note:** STAC Item and ItemCollection validation errors will always raise, regardless of this flag. | `false` | Optional |
-| `DATABASE_REFRESH`           | Controls whether database operations refresh the index immediately after changes. If set to `true`, changes will be immediately searchable. If set to `false`, changes may not be immediately visible but can improve performance for bulk operations. If set to `wait_for`, changes will wait for the next refresh cycle to become visible. | `false` | Optional |
-| `ENABLE_COLLECTIONS_SEARCH`  | Enable collection search extensions (sort, fields, free text search, structured filtering, and datetime filtering) on the core `/collections` endpoint. | `true`                   | Optional                                                                                    |
-| `ENABLE_COLLECTIONS_SEARCH_ROUTE` | Enable the custom `/collections-search` endpoint (both GET and POST methods). When disabled, the custom endpoint will not be available, but collection search extensions will still be available on the core `/collections` endpoint if `ENABLE_COLLECTIONS_SEARCH` is true. | `false` | Optional |
-| `ENABLE_TRANSACTIONS_EXTENSIONS` | Enables or disables the Transactions and Bulk Transactions API extensions. This is useful for deployments where mutating the catalog via the API should be prevented. If set to `true`, the POST `/collections` route for search will be unavailable in the API. | `true` | Optional |
-| `STAC_ITEM_LIMIT` | Sets the environment variable for result limiting to SFEOS for the number of returned items and STAC collections. | `10` | Optional |
-| `STAC_INDEX_ASSETS` | Controls if Assets are indexed when added to Elasticsearch/Opensearch. This allows asset fields to be included in search queries. | `false` | Optional |
-| `ENV_MAX_LIMIT` | Configures the environment variable in SFEOS to override the default `MAX_LIMIT`, which controls the limit parameter for returned items and STAC collections. | `10,000` | Optional |
-| `USE_DATETIME` | Configures the datetime search behavior in SFEOS. When enabled, searches both datetime field and falls back to start_datetime/end_datetime range for items with null datetime. When disabled, searches only by start_datetime/end_datetime range. | `true` | Optional |
-
-> [!NOTE]
-> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, `ES_VERIFY_CERTS` and `ES_TIMEOUT` apply to both Elasticsearch and OpenSearch backends, so there is no need to rename the key names to `OS_` even if you're using OpenSearch.
-
-## Datetime-Based Index Management
-
-### Overview
-
-SFEOS supports two indexing strategies for managing STAC items:
-
-1. **Simple Indexing** (default) - One index per collection
-2. **Datetime-Based Indexing** - Time-partitioned indexes with automatic management
-
-The datetime-based indexing strategy is particularly useful for large temporal datasets. When a user provides a datetime parameter in a query, the system knows exactly which index to search, providing **multiple times faster searches** and significantly **reducing database load**.
-
-### When to Use
-
-**Recommended for:**
-- Systems with large collections containing millions of items
-- Systems requiring high-performance temporal searching
-
-**Pros:**
-- Multiple times faster queries with datetime filter
-- Reduced database load - only relevant indexes are searched
-
-**Cons:**
-- Slightly longer item indexing time (automatic index management)
-- Greater management complexity
-
-### Configuration
-
-#### Enabling Datetime-Based Indexing
-
-Enable datetime-based indexing by setting the following environment variable:
-
-```bash
-ENABLE_DATETIME_INDEX_FILTERING=true
-```
-
-### Related Configuration Variables
-
-| Variable | Description | Default | Example |
-|----------|-------------|---------|---------|
-| `ENABLE_DATETIME_INDEX_FILTERING` | Enables time-based index partitioning | `false` | `true` |
-| `DATETIME_INDEX_MAX_SIZE_GB` | Maximum size limit for datetime indexes (GB) - note: add +20% to target size due to ES/OS compression | `25` | `50` |
-| `STAC_ITEMS_INDEX_PREFIX` | Prefix for item indexes | `items_` | `stac_items_` |
-
-## How Datetime-Based Indexing Works
-
-### Index and Alias Naming Convention
-
-The system uses a precise naming convention:
-
-**Physical indexes:**
-```
-{ITEMS_INDEX_PREFIX}{collection-id}_{uuid4}
-```
-
-**Aliases:**
-```
-{ITEMS_INDEX_PREFIX}{collection-id}                                  # Main collection alias
-{ITEMS_INDEX_PREFIX}{collection-id}_{start-datetime}                 # Temporal alias
-{ITEMS_INDEX_PREFIX}{collection-id}_{start-datetime}_{end-datetime}  # Closed index alias
-```
-
-**Example:**
-
-*Physical indexes:*
-- `items_sentinel-2-l2a_a1b2c3d4-e5f6-7890-abcd-ef1234567890`
-
-*Aliases:*
-- `items_sentinel-2-l2a` - main collection alias
-- `items_sentinel-2-l2a_2024-01-01` - active alias from January 1, 2024
-- `items_sentinel-2-l2a_2024-01-01_2024-03-15` - closed index alias (reached size limit)
-
-### Index Size Management
-
-**Important - Data Compression:** Elasticsearch and OpenSearch automatically compress data. The configured `DATETIME_INDEX_MAX_SIZE_GB` limit refers to the compressed size on disk. It is recommended to add +20% to the target size to account for compression overhead and metadata.
-
-## Interacting with the API
-
-- **Creating a Collection**:
-  ```shell
-  curl -X "POST" "http://localhost:8080/collections" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "id": "my_collection"
-  }'
-  ```
-
-- **Adding an Item to a Collection**:
-  ```shell
-  curl -X "POST" "http://localhost:8080/collections/my_collection/items" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d @item.json
-  ```
-
-- **Searching for Items**:
-  ```shell
-  curl -X "GET" "http://localhost:8080/search" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "collections": ["my_collection"],
-    "limit": 10
-  }'
-  ```
-
-- **Filtering by Bbox**:
-  ```shell
-  curl -X "GET" "http://localhost:8080/search" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "collections": ["my_collection"],
-    "bbox": [-180, -90, 180, 90]
-  }'
-  ```
-
-- **Filtering by Datetime**:
-  ```shell
-  curl -X "GET" "http://localhost:8080/search" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "collections": ["my_collection"],
-    "datetime": "2020-01-01T00:00:00Z/2020-12-31T23:59:59Z"
-  }'
-  ```
-
-## Configure the API
-
-- **API Title and Description**: By default set to `stac-fastapi-<backend>`. Customize these by setting:
-  - `STAC_FASTAPI_TITLE`: Changes the API title in the documentation
-  - `STAC_FASTAPI_DESCRIPTION`: Changes the API description in the documentation
-
-- **Database Indices**: By default, the API reads from and writes to:
-  - `collections` index for collections
-  - `items_<collection name>` indices for items
-  - Customize with `STAC_COLLECTIONS_INDEX` and `STAC_ITEMS_INDEX_PREFIX` environment variables
-
-- **Root Path Configuration**: The application root path is the base URL by default.
-  - For AWS Lambda with Gateway API: Set `STAC_FASTAPI_ROOT_PATH` to match the Gateway API stage name (e.g., `/v1`)
-
-- **Feature Configuration**: Control which features are enabled:
-  - `ENABLE_COLLECTIONS_SEARCH`: Set to `true` (default) to enable collection search extensions (sort, fields). Set to `false` to disable.
-  - `ENABLE_TRANSACTIONS_EXTENSIONS`: Set to `true` (default) to enable transaction extensions. Set to `false` to disable.
-
-## Collection Pagination
-
-- **Overview**: The collections route supports pagination through optional query parameters.
-- **Parameters**:
-  - `limit`: Controls the number of collections returned per page
-  - `token`: Used to retrieve subsequent pages of results
-- **Response Structure**: The `links` field in the response contains a `next` link with the token for the next page of results.
-- **Example Usage**:
-  ```shell
-  curl -X "GET" "http://localhost:8080/collections?limit=1&token=example_token"
-  ```
-
-## Ingesting Sample Data CLI Tool
-
-- **Overview**: The `data_loader.py` script provides a convenient way to load STAC items into the database.
-
-- **Usage**:
-  ```shell
-  python3 data_loader.py --base-url http://localhost:8080
-  ```
-
-- **Options**:
-  ```
-  --base-url TEXT       Base URL of the STAC API  [required]
-  --collection-id TEXT  ID of the collection to which items are added
-  --use-bulk            Use bulk insert method for items
-  --data-dir PATH       Directory containing collection.json and feature
-                        collection file
-  --help                Show this message and exit.
-  ```
-
-- **Example Workflows**:
-  - **Loading Sample Data**: 
-    ```shell
-    python3 data_loader.py --base-url http://localhost:8080
-    ```
-  - **Loading Data to a Specific Collection**:
-    ```shell
-    python3 data_loader.py --base-url http://localhost:8080 --collection-id my-collection
-    ```
-  - **Using Bulk Insert for Performance**:
-    ```shell
-    python3 data_loader.py --base-url http://localhost:8080 --use-bulk
-    ```
-
-## Elasticsearch Mappings
-
-- **Overview**: Mappings apply to search index, not source data. They define how documents and their fields are stored and indexed.
-- **Implementation**: 
-  - Mappings are stored in index templates that are created on application startup
-  - These templates are automatically applied when creating new Collection and Item indices
-  - The `sfeos_helpers` package contains shared mapping definitions used by both Elasticsearch and OpenSearch backends
-- **Customization**: Custom mappings can be defined by extending the base mapping templates.
-
-## Managing Elasticsearch Indices
-
-### Snapshots
-
-- **Overview**: Snapshots provide a way to backup and restore your indices.
-
-- **Creating a Snapshot Repository**:
-  ```shell
-  curl -X "PUT" "http://localhost:9200/_snapshot/my_fs_backup" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-               "type": "fs",
-               "settings": {
-                   "location": "/usr/share/elasticsearch/snapshots/my_fs_backup"
-               }
-  }'
-  ```
-  - This creates a snapshot repository that stores files in the elasticsearch/snapshots directory in this git repo clone
-  - The elasticsearch.yml and compose files create a mapping from that directory to /usr/share/elasticsearch/snapshots within the Elasticsearch container and grant permissions for using it
-
-- **Creating a Snapshot**:
-  ```shell
-  curl -X "PUT" "http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2?wait_for_completion=true" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "metadata": {
-      "taken_because": "dump of all items",
-      "taken_by": "pvarner"
-    },
-    "include_global_state": false,
-    "ignore_unavailable": false,
-    "indices": "items_my-collection"
-  }'
-  ```
-  - This creates a snapshot named my_snapshot_2 and waits for the action to be completed before returning
-  - This can also be done asynchronously by omitting the wait_for_completion parameter, and queried for status later
-  - The indices parameter determines which indices are snapshotted, and can include wildcards
-
-- **Viewing Snapshots**:
-  ```shell
-  # View a specific snapshot
-  curl http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2
-  
-  # View all snapshots
-  curl http://localhost:9200/_snapshot/my_fs_backup/_all
-  ```
-  - These commands allow you to check the status and details of your snapshots
-
-- **Restoring a Snapshot**:
-  ```shell
-  curl -X "POST" "http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2/_restore?wait_for_completion=true" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-    "include_aliases": false,
-    "include_global_state": false,
-    "ignore_unavailable": true,
-    "rename_replacement": "items_$1-copy",
-    "indices": "items_*",
-    "rename_pattern": "items_(.+)"
-  }'
-  ```
-  - This specific command will restore any indices that match items_* and rename them so that the new index name will be suffixed with -copy
-  - The rename_pattern and rename_replacement parameters allow you to restore indices under new names
-
-- **Updating Collection References**:
-  ```shell
-  curl -X "POST" "http://localhost:9200/items_my-collection-copy/_update_by_query" \
-       -H 'Content-Type: application/json; charset=utf-8' \
-       -d $'{
-      "query": {
-          "match_all": {}
-  },
-    "script": {
-      "lang": "painless",
-      "params": {
-        "collection": "my-collection-copy"
-      },
-      "source": "ctx._source.collection = params.collection"
-    }
-  }'
-  ```
-  - After restoring, the item documents have been restored in the new index (e.g., my-collection-copy), but the value of the collection field in those documents is still the original value of my-collection
-  - This command updates these values to match the new collection name using Elasticsearch's Update By Query feature
-
-- **Creating a New Collection**:
-  ```shell
-  curl -X "POST" "http://localhost:8080/collections" \
-       -H 'Content-Type: application/json' \
-       -d $'{
-    "id": "my-collection-copy"
-  }'
-  ```
-  - The final step is to create a new collection through the API with the new name for each of the restored indices
-  - This gives you a copy of the collection that has a resource URI (/collections/my-collection-copy) and can be correctly queried by collection name
-
-### Reindexing
-
-- **Overview**: Reindexing allows you to copy documents from one index to another, optionally transforming them in the process.
-
-- **Use Cases**:
-  - Apply changes to documents
-  - Correct dynamically generated mappings
-  - Transform data (e.g., lowercase identifiers)
-  - The index templates will make sure that manually created indices will also have the correct mappings and settings
-
-- **Example: Reindexing with Transformation**:
-  ```shell
-  curl -X "POST" "http://localhost:9200/_reindex" \
-    -H 'Content-Type: application/json' \
-    -d $'{
-      "source": {
-        "index": "items_my-collection-lower_my-collection-hex-000001"
-      }, 
-      "dest": {
-        "index": "items_my-collection-lower_my-collection-hex-000002"
-      },
-      "script": {
-        "source": "ctx._source.id = ctx._source.id.toLowerCase()",
-        "lang": "painless"
-      }
-    }'
-  ```
-  - In this example, we make a copy of an existing Item index but change the Item identifier to be lowercase
-  - The script parameter allows you to transform documents during the reindexing process
-
-- **Updating Aliases**:
-  ```shell
-  curl -X "POST" "http://localhost:9200/_aliases" \
-    -H 'Content-Type: application/json' \
-    -d $'{
-      "actions": [
-        {
-          "remove": {
-            "index": "*",
-            "alias": "items_my-collection"
-          }
-        },
-        {
-          "add": {
-            "index": "items_my-collection-lower_my-collection-hex-000002",
-            "alias": "items_my-collection"
-          }
-        }
-      ]
-    }'
-  ```
-  - If you are happy with the data in the newly created index, you can move the alias items_my-collection to the new index
-  - This makes the modified Items with lowercase identifiers visible to users accessing my-collection in the STAC API
-  - Using aliases allows you to switch between different index versions without changing the API endpoint
-
-## Auth
-
-- **Overview**: Authentication is an optional feature that can be enabled through Route Dependencies.
-- **Implementation Options**:
-  - Basic authentication
-  - OAuth2 with Keycloak
-  - Custom route dependencies
-- **Configuration**: Authentication can be configured using the `STAC_FASTAPI_ROUTE_DEPENDENCIES` environment variable.
-- **Examples and Documentation**: Detailed examples and implementation guides can be found in the [examples/auth](examples/auth) directory.
-
-## Aggregation
-
-- **Supported Aggregations**:
-  - Spatial aggregations of points and geometries
-  - Frequency distribution aggregation of any property including dates
-  - Temporal distribution of datetime values
-
-- **Endpoint Locations**:
-  - Root Catalog level: `/aggregations`
-  - Collection level: `/<collection_id>/aggregations`
-
-- **Implementation Details**: The `sfeos_helpers.aggregation` package provides specialized functionality for both Elasticsearch and OpenSearch backends.
-
-- **Documentation**: Detailed information about supported aggregations can be found in [the aggregation docs](./docs/src/aggregation.md).
-
-
-## Rate Limiting
-
-- **Overview**: Rate limiting is an optional security feature that controls API request frequency on a remote address basis.
-
-- **Configuration**: Enabled by setting the `STAC_FASTAPI_RATE_LIMIT` environment variable:
-  ```
-  STAC_FASTAPI_RATE_LIMIT=500/minute
-  ```
-
-- **Functionality**: 
-  - Limits each client to a specified number of requests per time period (e.g., 500 requests per minute)
-  - Helps prevent API abuse and maintains system stability
-  - Ensures fair resource allocation among all clients
-  
-- **Examples**: Implementation examples are available in the [examples/rate_limit](examples/rate_limit) directory.

sfeos_helpers-6.5.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-stac_fastapi