stac-fastapi-core 6.5.1__py3-none-any.whl → 6.6.0__py3-none-any.whl

stac_fastapi/core/base_database_logic.py

@@ -3,6 +3,8 @@
 import abc
 from typing import Any, Dict, Iterable, List, Optional, Tuple
 
+from stac_pydantic.shared import BBox
+
 
 class BaseDatabaseLogic(abc.ABC):
     """
@@ -19,7 +21,12 @@ class BaseDatabaseLogic(abc.ABC):
         limit: int,
         request: Any = None,
         sort: Optional[List[Dict[str, Any]]] = None,
-    ) -> Tuple[List[Dict[str, Any]], Optional[str]]:
+        bbox: Optional[BBox] = None,
+        q: Optional[List[str]] = None,
+        filter: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Dict[str, Any]]] = None,
+        datetime: Optional[str] = None,
+    ) -> Tuple[List[Dict[str, Any]], Optional[str], Optional[int]]:
         """Retrieve a list of collections from the database, supporting pagination.
 
         Args:
@@ -27,9 +34,14 @@ class BaseDatabaseLogic(abc.ABC):
             limit (int): The number of results to return.
             request (Any, optional): The FastAPI request object. Defaults to None.
             sort (Optional[List[Dict[str, Any]]], optional): Optional sort parameter. Defaults to None.
+            bbox (Optional[BBox], optional): Bounding box to filter collections by spatial extent. Defaults to None.
+            q (Optional[List[str]], optional): Free text search terms. Defaults to None.
+            filter (Optional[Dict[str, Any]], optional): Structured query in CQL2 format. Defaults to None.
+            query (Optional[Dict[str, Dict[str, Any]]], optional): Query extension parameters. Defaults to None.
+            datetime (Optional[str], optional): Temporal filter. Defaults to None.
 
         Returns:
-            A tuple of (collections, next pagination token if any).
+            A tuple of (collections, next pagination token if any, optional count).
         """
         pass
 

stac_fastapi/core/core.py

@@ -201,17 +201,6 @@ class CoreClient(AsyncBaseCoreClient):
                 ]
             )
 
-        collections = await self.all_collections(request=kwargs["request"])
-        for collection in collections["collections"]:
-            landing_page["links"].append(
-                {
-                    "rel": Relations.child.value,
-                    "type": MimeTypes.json.value,
-                    "title": collection.get("title") or collection.get("id"),
-                    "href": urljoin(base_url, f"collections/{collection['id']}"),
-                }
-            )
-
         # Add OpenAPI URL
         landing_page["links"].append(
             {
@@ -241,6 +230,7 @@ class CoreClient(AsyncBaseCoreClient):
     async def all_collections(
         self,
         limit: Optional[int] = None,
+        bbox: Optional[BBox] = None,
         datetime: Optional[str] = None,
         fields: Optional[List[str]] = None,
         sortby: Optional[Union[str, List[str]]] = None,
@@ -255,14 +245,17 @@ class CoreClient(AsyncBaseCoreClient):
         """Read all collections from the database.
 
         Args:
-            datetime (Optional[str]): Filter collections by datetime range.
             limit (Optional[int]): Maximum number of collections to return.
+            bbox (Optional[BBox]): Bounding box to filter collections by spatial extent.
+            datetime (Optional[str]): Filter collections by datetime range.
             fields (Optional[List[str]]): Fields to include or exclude from the results.
-            sortby (Optional[str]): Sorting options for the results.
+            sortby (Optional[Union[str, List[str]]]): Sorting options for the results.
             filter_expr (Optional[str]): Structured filter expression in CQL2 JSON or CQL2-text format.
-            query (Optional[str]): Legacy query parameter (deprecated).
             filter_lang (Optional[str]): Must be 'cql2-json' or 'cql2-text' if specified, other values will result in an error.
             q (Optional[Union[str, List[str]]]): Free text search terms.
+            query (Optional[str]): Legacy query parameter (deprecated).
+            request (Request): FastAPI Request object.
+            token (Optional[str]): Pagination token for retrieving the next page of results.
             **kwargs: Keyword arguments from the request.
 
         Returns:
@@ -270,34 +263,31 @@ class CoreClient(AsyncBaseCoreClient):
         """
         base_url = str(request.base_url)
 
-        # Get the global limit from environment variable
-        global_limit = None
-        env_limit = os.getenv("STAC_ITEM_LIMIT")
-        if env_limit:
-            try:
-                global_limit = int(env_limit)
-            except ValueError:
-                # Handle invalid integer in environment variable
-                pass
-
-        # Apply global limit if it exists
-        if global_limit is not None:
-            # If a limit was provided, use the smaller of the two
-            if limit is not None:
-                limit = min(limit, global_limit)
-            else:
-                limit = global_limit
+        global_max_limit = (
+            int(os.getenv("STAC_GLOBAL_COLLECTION_MAX_LIMIT"))
+            if os.getenv("STAC_GLOBAL_COLLECTION_MAX_LIMIT")
+            else None
+        )
+        query_limit = request.query_params.get("limit")
+        default_limit = int(os.getenv("STAC_DEFAULT_COLLECTION_LIMIT", 300))
+
+        body_limit = None
+        try:
+            if request.method == "POST" and request.body():
+                body_data = await request.json()
+                body_limit = body_data.get("limit")
+        except Exception:
+            pass
+
+        if body_limit is not None:
+            limit = int(body_limit)
+        elif query_limit:
+            limit = int(query_limit)
         else:
-            # No global limit, use provided limit or default
-            if limit is None:
-                query_limit = request.query_params.get("limit")
-                if query_limit:
-                    try:
-                        limit = int(query_limit)
-                    except ValueError:
-                        limit = 10
-                else:
-                    limit = 10
+            limit = default_limit
+
+        if global_max_limit is not None:
+            limit = min(limit, global_max_limit)
 
         # Get token from query params only if not already provided (for GET requests)
         if token is None:
@@ -401,6 +391,7 @@ class CoreClient(AsyncBaseCoreClient):
             limit=limit,
             request=request,
             sort=sort,
+            bbox=bbox,
             q=q_list,
             filter=parsed_filter,
             query=parsed_query,
@@ -502,6 +493,7 @@ class CoreClient(AsyncBaseCoreClient):
         # Pass all parameters from search_request to all_collections
         return await self.all_collections(
             limit=search_request.limit if hasattr(search_request, "limit") else None,
+            bbox=search_request.bbox if hasattr(search_request, "bbox") else None,
             datetime=search_request.datetime
             if hasattr(search_request, "datetime")
             else None,
@@ -569,7 +561,7 @@ class CoreClient(AsyncBaseCoreClient):
             request (Request): FastAPI Request object.
             bbox (Optional[BBox]): Optional bounding box filter.
             datetime (Optional[str]): Optional datetime or interval filter.
-            limit (Optional[int]): Optional page size. Defaults to env ``STAC_ITEM_LIMIT`` when unset.
+            limit (Optional[int]): Optional page size. Defaults to env `STAC_DEFAULT_ITEM_LIMIT` when unset.
             sortby (Optional[str]): Optional sort specification. Accepts repeated values
                 like ``sortby=-properties.datetime`` or ``sortby=+id``. Bare fields (e.g. ``sortby=id``)
                 imply ascending order.
@@ -660,15 +652,12 @@ class CoreClient(AsyncBaseCoreClient):
             q (Optional[List[str]]): Free text query to filter the results.
             intersects (Optional[str]): GeoJSON geometry to search in.
             kwargs: Additional parameters to be passed to the API.
-
         Returns:
             ItemCollection: Collection of `Item` objects representing the search results.
 
         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,
@@ -743,6 +732,34 @@ class CoreClient(AsyncBaseCoreClient):
         Raises:
             HTTPException: If there is an error with the cql2_json filter.
         """
+        global_max_limit = (
+            int(os.getenv("STAC_GLOBAL_ITEM_MAX_LIMIT"))
+            if os.getenv("STAC_GLOBAL_ITEM_MAX_LIMIT")
+            else None
+        )
+        query_limit = request.query_params.get("limit")
+        default_limit = int(os.getenv("STAC_DEFAULT_ITEM_LIMIT", 10))
+
+        body_limit = None
+        try:
+            if request.method == "POST" and request.body():
+                body_data = await request.json()
+                body_limit = body_data.get("limit")
+        except Exception:
+            pass
+
+        if body_limit is not None:
+            limit = int(body_limit)
+        elif query_limit:
+            limit = int(query_limit)
+        else:
+            limit = default_limit
+
+        if global_max_limit:
+            limit = min(limit, global_max_limit)
+
+        search_request.limit = limit
+
         base_url = str(request.base_url)
 
         search = self.database.make_search()
@@ -819,7 +836,6 @@ class CoreClient(AsyncBaseCoreClient):
         if hasattr(search_request, "sortby") and getattr(search_request, "sortby"):
             sort = self.database.populate_sort(getattr(search_request, "sortby"))
 
-        limit = 10
         if search_request.limit:
             limit = search_request.limit
 

stac_fastapi/core/serializers.py

@@ -1,6 +1,7 @@
 """Serializers."""
 
 import abc
+import logging
 from copy import deepcopy
 from typing import Any, List, Optional
 
@@ -13,6 +14,8 @@ from stac_fastapi.core.utilities import get_bool_env
 from stac_fastapi.types import stac as stac_types
 from stac_fastapi.types.links import ItemLinks, resolve_links
 
+logger = logging.getLogger(__name__)
+
 
 @attr.s
 class Serializer(abc.ABC):
@@ -168,6 +171,9 @@ class CollectionSerializer(Serializer):
         # Avoid modifying the input dict in-place ... doing so breaks some tests
         collection = deepcopy(collection)
 
+        # Remove internal bbox_shape field (not part of STAC spec)
+        collection.pop("bbox_shape", None)
+
         # Set defaults
         collection_id = collection.get("id")
         collection.setdefault("type", "Collection")

stac_fastapi/core/utilities.py

@@ -10,15 +10,7 @@ from typing import Any, Dict, List, Optional, Set, Union
 
 from stac_fastapi.types.stac import Item
 
-
-def get_max_limit():
-    """
-    Retrieve a MAX_LIMIT value from an environment variable.
-
-    Returns:
-        int: The int value parsed from the environment variable.
-    """
-    return int(os.getenv("ENV_MAX_LIMIT", 10000))
+MAX_LIMIT = 10000
 
 
 def get_bool_env(name: str, default: Union[bool, str] = False) -> bool:

stac_fastapi/core/version.py

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

stac_fastapi_core-6.6.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: stac_fastapi_core
+Version: 6.6.0
+Summary: Core 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: attrs>=23.2.0
+Requires-Dist: fastapi~=0.109.0
+Requires-Dist: geojson-pydantic~=1.0.0
+Requires-Dist: jsonschema~=4.0.0
+Requires-Dist: orjson~=3.11.0
+Requires-Dist: overrides~=7.4.0
+Requires-Dist: pydantic<3.0.0,>=2.4.1
+Requires-Dist: pygeofilter~=0.3.1
+Requires-Dist: slowapi~=0.1.9
+Requires-Dist: stac-fastapi-api==6.0.0
+Requires-Dist: stac-fastapi-extensions==6.0.0
+Requires-Dist: stac-fastapi-types==6.0.0
+Requires-Dist: stac-pydantic~=3.3.0
+Description-Content-Type: text/markdown
+
+# stac-fastapi-core
+
+Core functionality for stac-fastapi. 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**: stac-fastapi-core
+- **Description**: Core functionality for STAC API implementations.
+- **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
+
+```bash
+pip install stac-fastapi-core
+```
+
+## Quick Start
+
+For detailed usage and examples, please refer to the [main documentation](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/).

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

@@ -1,15 +1,15 @@
 stac_fastapi/core/__init__.py,sha256=8izV3IWRGdXmDOK1hIPQAanbWs9EI04PJCGgqG1ZGIs,20
-stac_fastapi/core/base_database_logic.py,sha256=nhj0CZNur_SRs4GtXTER-Zjq8JPub5zINiCKbCjw0Bs,3814
+stac_fastapi/core/base_database_logic.py,sha256=3_XJ_j06ogQHE-Tcjkv5Vye_zNDn9OEU9lNYU03am1k,4618
 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=D_TUtcPnLKWDLnY-oPw5jsmqoA2ghLqPPs6H56c4myc,48369
+stac_fastapi/core/core.py,sha256=f1-TJSH7Hl5MYTtdgjBUGUvFi7gFLex3MxU4ubYBqhI,48838
 stac_fastapi/core/datetime_utils.py,sha256=TrTgbU7AKNC-ic4a3HptfE5XAc9tHR7uJasZyhOuwnc,2633
 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=HU7sVSMa6w_F_qs_gdAeIFZ18GW-6t8ZHFmgI4-1uNw,7455
+stac_fastapi/core/serializers.py,sha256=ZW5hPgq-mftk6zxJeZGur-1Qxn7YGc3fJYFLsd-SYwM,7619
 stac_fastapi/core/session.py,sha256=aXqu4LXfVbAAsChMVXd9gAhczA2bZPne6HqPeklAwMY,474
-stac_fastapi/core/utilities.py,sha256=WbspaJey_Cs-7TrBKasdqq7yjB7vjKiU01KyJM0m8_E,7506
-stac_fastapi/core/version.py,sha256=FuGC3fKnAmD4Wk95swJ6qCVBs5mZiShrlRKuSH-voyE,45
+stac_fastapi/core/utilities.py,sha256=xXWO5oJCNDi7_C5jPYlHZD0B-DL-FN66eEUBUSW-cXw,7296
+stac_fastapi/core/version.py,sha256=zPQp-GtLh4R45hT8V_KAWzwZcP4-jyw7Xjms_eNMZBc,45
 stac_fastapi/core/extensions/__init__.py,sha256=zSIAqou8jnakWPbkh4Ddcx1-oazZVBOs7U2PAakAdU0,291
 stac_fastapi/core/extensions/aggregation.py,sha256=v1hUHqlYuMqfQ554g3cTp16pUyRYucQxPERbHPAFtf8,1878
 stac_fastapi/core/extensions/collections_search.py,sha256=q7eRBykEqNRCiTfkmM_TobqKkxA3n1zQ7dYo37juE6s,6503
@@ -19,7 +19,6 @@ 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=0dWSEMt3aa7NCISlHwo11zLBeIV1LwXG3JGjrXC3dZI,6672
 stac_fastapi/core/models/search.py,sha256=7SgAUyzHGXBXSqB4G6cwq9FMwoAS00momb7jvBkjyow,27
-stac_fastapi_core-6.5.1.dist-info/METADATA,sha256=PIBVPUY1dqhKMj_JDMOUYuyLoSa8mDoLuUpfI_sjKcU,41746
-stac_fastapi_core-6.5.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-stac_fastapi_core-6.5.1.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
-stac_fastapi_core-6.5.1.dist-info/RECORD,,
+stac_fastapi_core-6.6.0.dist-info/METADATA,sha256=h54wZw2qk4ZgGH7kFlwIFmxR3wgEHwoXJ3p69w-iOFs,2163
+stac_fastapi_core-6.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+stac_fastapi_core-6.6.0.dist-info/RECORD,,

{stac_fastapi_core-6.5.1.dist-info → stac_fastapi_core-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_core-6.5.1.dist-info/METADATA

@@ -1,726 +0,0 @@
-Metadata-Version: 2.1
-Name: stac-fastapi-core
-Version: 6.5.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
-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: 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-fastapi.types==6.0.0
-Requires-Dist: stac-fastapi.api==6.0.0
-Requires-Dist: stac-fastapi.extensions==6.0.0
-Requires-Dist: orjson~=3.9.0
-Requires-Dist: overrides~=7.4.0
-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
-
-# 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.

stac_fastapi_core-6.5.1.dist-info/top_level.txt

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