stac-fastapi-core 6.1.0__py3-none-any.whl → 6.2.1__py3-none-any.whl

stac_fastapi/core/base_database_logic.py

@@ -48,6 +48,7 @@ class BaseDatabaseLogic(abc.ABC):
         item_id: str,
         operations: List,
         base_url: str,
+        create_nest: bool = False,
         refresh: bool = True,
     ) -> Dict:
         """Patch a item in the database follows RF6902."""
@@ -94,6 +95,7 @@ class BaseDatabaseLogic(abc.ABC):
         collection_id: str,
         operations: List,
         base_url: str,
+        create_nest: bool = False,
         refresh: bool = True,
     ) -> Dict:
         """Patch a collection in the database follows RF6902."""

stac_fastapi/core/core.py

@@ -1,6 +1,7 @@
 """Core client."""
 
 import logging
+import os
 from datetime import datetime as datetime_type
 from datetime import timezone
 from enum import Enum
@@ -234,7 +235,7 @@ class CoreClient(AsyncBaseCoreClient):
         """
         request = kwargs["request"]
         base_url = str(request.base_url)
-        limit = int(request.query_params.get("limit", 10))
+        limit = int(request.query_params.get("limit", os.getenv("STAC_ITEM_LIMIT", 10)))
         token = request.query_params.get("token")
 
         collections, next_token = await self.database.get_all_collections(
@@ -285,7 +286,7 @@ class CoreClient(AsyncBaseCoreClient):
         collection_id: str,
         bbox: Optional[BBox] = None,
         datetime: Optional[str] = None,
-        limit: Optional[int] = 10,
+        limit: Optional[int] = None,
         token: Optional[str] = None,
         **kwargs,
     ) -> stac_types.ItemCollection:
@@ -295,7 +296,7 @@ class CoreClient(AsyncBaseCoreClient):
             collection_id (str): The identifier of the collection to read items from.
             bbox (Optional[BBox]): The bounding box to filter items by.
             datetime (Optional[str]): The datetime range to filter items by.
-            limit (int): The maximum number of items to return. The default value is 10.
+            limit (int): The maximum number of items to return.
             token (str): A token used for pagination.
             request (Request): The incoming request.
 
@@ -324,10 +325,15 @@ class CoreClient(AsyncBaseCoreClient):
             search=search, collection_ids=[collection_id]
         )
 
-        if datetime:
-            search = self.database.apply_datetime_filter(
-                search=search, interval=datetime
+        try:
+            search, datetime_search = self.database.apply_datetime_filter(
+                search=search, datetime=datetime
             )
+        except (ValueError, TypeError) as e:
+            # Handle invalid interval formats if return_date fails
+            msg = f"Invalid interval format: {datetime}, error: {e}"
+            logger.error(msg)
+            raise HTTPException(status_code=400, detail=msg)
 
         if bbox:
             bbox = [float(x) for x in bbox]
@@ -336,12 +342,14 @@ class CoreClient(AsyncBaseCoreClient):
 
             search = self.database.apply_bbox_filter(search=search, bbox=bbox)
 
+        limit = int(request.query_params.get("limit", os.getenv("STAC_ITEM_LIMIT", 10)))
         items, maybe_count, next_token = await self.database.execute_search(
             search=search,
             limit=limit,
             sort=None,
             token=token,
             collection_ids=[collection_id],
+            datetime_search=datetime_search,
         )
 
         items = [
@@ -387,7 +395,7 @@ class CoreClient(AsyncBaseCoreClient):
         ids: Optional[List[str]] = None,
         bbox: Optional[BBox] = None,
         datetime: Optional[str] = None,
-        limit: Optional[int] = 10,
+        limit: Optional[int] = None,
         query: Optional[str] = None,
         token: Optional[str] = None,
         fields: Optional[List[str]] = None,
@@ -420,6 +428,7 @@ class CoreClient(AsyncBaseCoreClient):
         Raises:
             HTTPException: If any error occurs while searching the catalog.
         """
+        limit = int(request.query_params.get("limit", os.getenv("STAC_ITEM_LIMIT", 10)))
         base_args = {
             "collections": collections,
             "ids": ids,
@@ -500,10 +509,15 @@ class CoreClient(AsyncBaseCoreClient):
                 search=search, collection_ids=search_request.collections
             )
 
-        if search_request.datetime:
-            search = self.database.apply_datetime_filter(
-                search=search, interval=search_request.datetime
+        try:
+            search, datetime_search = self.database.apply_datetime_filter(
+                search=search, datetime=search_request.datetime
             )
+        except (ValueError, TypeError) as e:
+            # Handle invalid interval formats if return_date fails
+            msg = f"Invalid interval format: {search_request.datetime}, error: {e}"
+            logger.error(msg)
+            raise HTTPException(status_code=400, detail=msg)
 
         if search_request.bbox:
             bbox = search_request.bbox
@@ -560,6 +574,7 @@ class CoreClient(AsyncBaseCoreClient):
             token=search_request.token,
             sort=sort,
             collection_ids=search_request.collections,
+            datetime_search=datetime_search,
         )
 
         fields = (

stac_fastapi/core/datetime_utils.py

@@ -1,4 +1,5 @@
 """Utility functions to handle datetime parsing."""
+
 from datetime import datetime, timezone
 
 from stac_fastapi.types.rfc3339 import rfc3339_str_to_datetime

stac_fastapi/core/serializers.py

@@ -1,4 +1,5 @@
 """Serializers."""
+
 import abc
 from copy import deepcopy
 from typing import Any, List, Optional

stac_fastapi/core/session.py

@@ -1,4 +1,5 @@
 """database session management."""
+
 import logging
 
 import attr

stac_fastapi/core/version.py

@@ -1,2 +1,2 @@
 """library version."""
-__version__ = "6.1.0"
+__version__ = "6.2.1"

{stac_fastapi_core-6.1.0.dist-info → stac_fastapi_core-6.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
-Name: stac-fastapi-core
-Version: 6.1.0
+Metadata-Version: 2.4
+Name: stac_fastapi_core
+Version: 6.2.1
 Summary: Core library for the Elasticsearch and Opensearch stac-fastapi backends.
 Home-page: https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
 License: MIT
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: fastapi~=0.109.0
 Requires-Dist: attrs>=23.2.0
 Requires-Dist: pydantic<3.0.0,>=2.4.1
-Requires-Dist: stac-pydantic~=3.3.0
+Requires-Dist: stac_pydantic~=3.3.0
 Requires-Dist: stac-fastapi.types==6.0.0
 Requires-Dist: stac-fastapi.api==6.0.0
 Requires-Dist: stac-fastapi.extensions==6.0.0
@@ -28,6 +28,14 @@ Requires-Dist: geojson-pydantic~=1.0.0
 Requires-Dist: pygeofilter~=0.3.1
 Requires-Dist: jsonschema~=4.0.0
 Requires-Dist: slowapi~=0.1.9
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # stac-fastapi-elasticsearch-opensearch
 
@@ -116,6 +124,7 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 - [Auth](#auth)
 - [Aggregation](#aggregation)
 - [Rate Limiting](#rate-limiting)
+- [Datetime-Based Index Management](#datetime-based-index-management)
 
 ## Documentation & Resources
 
@@ -257,10 +266,86 @@ You can customize additional settings in your `.env` file:
 | `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_TRANSACTIONS_EXTENSIONS` | Enables or disables the Transactions and Bulk Transactions API extensions. If set to `false`, the POST `/collections` route and related transaction endpoints (including bulk transaction operations) will be unavailable in the API. This is useful for deployments where mutating the catalog via the API should be prevented. | `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 |
 
 > [!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**:
@@ -569,4 +654,3 @@ You can customize additional settings in your `.env` file:
   - Ensures fair resource allocation among all clients
   
 - **Examples**: Implementation examples are available in the [examples/rate_limit](examples/rate_limit) directory.
-

{stac_fastapi_core-6.1.0.dist-info → stac_fastapi_core-6.2.1.dist-info}/RECORD

@@ -1,15 +1,15 @@
 stac_fastapi/core/__init__.py,sha256=8izV3IWRGdXmDOK1hIPQAanbWs9EI04PJCGgqG1ZGIs,20
-stac_fastapi/core/base_database_logic.py,sha256=AcvS38fWUk44BHD1vJfQENKHx1LDQdvRjMqcSQBFqw4,3189
+stac_fastapi/core/base_database_logic.py,sha256=sGeBUQ622CuId43lwHSsR_dqlIRsN-mctzZb-zVjiIU,3259
 stac_fastapi/core/base_settings.py,sha256=R3_Sx7n5XpGMs3zAwFJD7y008WvGU_uI2xkaabm82Kg,239
 stac_fastapi/core/basic_auth.py,sha256=RhFv3RVSHF6OaqnaaU2DO4ncJ_S5nB1q8UNpnVJJsrk,2155
-stac_fastapi/core/core.py,sha256=Unfg3c7UX_AxH_FdJSKfHzIggWhENUR2PAlf7XKbgew,35974
-stac_fastapi/core/datetime_utils.py,sha256=oueonjfuKdsB8IF_Ow-brK_X1bXs8_GLuVZOZr_L4ws,2527
+stac_fastapi/core/core.py,sha256=-FfM60nfA55-xaFHysd9rm3NyfQ-BrMApZRf0zZoNyY,36823
+stac_fastapi/core/datetime_utils.py,sha256=99vlw-fo0OB_aYfBHXhOkZNxrl2sKr6ZX0oR4PfIQH4,2528
 stac_fastapi/core/rate_limit.py,sha256=Gu8dAaJReGsj1L91U6m2tflU6RahpXDRs2-AYSKoybA,1318
 stac_fastapi/core/route_dependencies.py,sha256=hdtuMkv-zY1vg0YxiCz1aKP0SbBcORqDGEKDGgEazW8,5482
-stac_fastapi/core/serializers.py,sha256=pJjpwA6BOHjCXBCmwVTH7MOmTjY9NXF1-i_E0yB60Zg,6228
-stac_fastapi/core/session.py,sha256=Qr080UU_7qKtIv0qZAuOV7oNUQUzT5Yn00h-m_aoCvY,473
+stac_fastapi/core/serializers.py,sha256=-DdbKYkYxmNyhuGc9UMrtFFlwiQpfxhzlog27qpMIpw,6229
+stac_fastapi/core/session.py,sha256=aXqu4LXfVbAAsChMVXd9gAhczA2bZPne6HqPeklAwMY,474
 stac_fastapi/core/utilities.py,sha256=xXWO5oJCNDi7_C5jPYlHZD0B-DL-FN66eEUBUSW-cXw,7296
-stac_fastapi/core/version.py,sha256=7IrY7mbr0cGVqZsk6wmCeITxZjDgz_mPHUswrziX5ME,45
+stac_fastapi/core/version.py,sha256=TvDysD5xP1CNnI8XDtkkz5sggBM1uuxjhZCv120q3AU,45
 stac_fastapi/core/extensions/__init__.py,sha256=2MCo0UoInkgItIM8id-rbeygzn_qUOvTGfr8jFXZjHQ,167
 stac_fastapi/core/extensions/aggregation.py,sha256=v1hUHqlYuMqfQ554g3cTp16pUyRYucQxPERbHPAFtf8,1878
 stac_fastapi/core/extensions/fields.py,sha256=NCT5XHvfaf297eDPNaIFsIzvJnbbUTpScqF0otdx0NA,1066
@@ -18,7 +18,7 @@ stac_fastapi/core/extensions/query.py,sha256=Xmo8pfZEZKPudZEjjozv3R0wLOP0ayjC9E6
 stac_fastapi/core/models/__init__.py,sha256=g-D1DiGfmC9Bg27DW9JzkN6fAvscv75wyhyiZ6NzvIk,48
 stac_fastapi/core/models/links.py,sha256=3jk4t2wA3RGTq9_BbzFsMKvMbgDBajQy4vKZFSHt7E8,6666
 stac_fastapi/core/models/search.py,sha256=7SgAUyzHGXBXSqB4G6cwq9FMwoAS00momb7jvBkjyow,27
-stac_fastapi_core-6.1.0.dist-info/METADATA,sha256=NrERN6IX0gXP6MeleYzPc0n6BtYiv1eXy_WimCSXJdQ,31948
-stac_fastapi_core-6.1.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-stac_fastapi_core-6.1.0.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
-stac_fastapi_core-6.1.0.dist-info/RECORD,,
+stac_fastapi_core-6.2.1.dist-info/METADATA,sha256=Gih-ceUvVccON3HZKibcibSHlsCr0ju4TzjXj1FPwpY,35049
+stac_fastapi_core-6.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+stac_fastapi_core-6.2.1.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
+stac_fastapi_core-6.2.1.dist-info/RECORD,,

{stac_fastapi_core-6.1.0.dist-info → stac_fastapi_core-6.2.1.dist-info}/WHEEL

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