stac-fastapi-core 6.5.1__py3-none-any.whl → 6.7.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

@@ -24,9 +24,10 @@ from stac_fastapi.core.base_database_logic import BaseDatabaseLogic
 from stac_fastapi.core.base_settings import ApiBaseSettings
 from stac_fastapi.core.datetime_utils import format_datetime_range
 from stac_fastapi.core.models.links import PagingLinks
+from stac_fastapi.core.redis_utils import redis_pagination_links
 from stac_fastapi.core.serializers import CollectionSerializer, ItemSerializer
 from stac_fastapi.core.session import Session
-from stac_fastapi.core.utilities import filter_fields
+from stac_fastapi.core.utilities import filter_fields, get_bool_env
 from stac_fastapi.extensions.core.transaction import AsyncBaseTransactionsClient
 from stac_fastapi.extensions.core.transaction.request import (
     PartialCollection,
@@ -201,17 +202,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 +231,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,49 +246,50 @@ 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:
             A Collections object containing all the collections in the database and links to various resources.
         """
         base_url = str(request.base_url)
+        redis_enable = get_bool_env("REDIS_ENABLE", default=False)
 
-        # 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 +393,7 @@ class CoreClient(AsyncBaseCoreClient):
             limit=limit,
             request=request,
             sort=sort,
+            bbox=bbox,
             q=q_list,
             filter=parsed_filter,
             query=parsed_query,
@@ -426,6 +419,14 @@ class CoreClient(AsyncBaseCoreClient):
             },
         ]
 
+        if redis_enable:
+            await redis_pagination_links(
+                current_url=str(request.url),
+                token=token,
+                next_token=next_token,
+                links=links,
+            )
+
         if next_token:
             next_link = PagingLinks(next=next_token, request=request).link_next()
             links.append(next_link)
@@ -502,6 +503,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 +571,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 +662,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,9 +742,37 @@ class CoreClient(AsyncBaseCoreClient):
         Raises:
             HTTPException: If there is an error with the cql2_json filter.
         """
-        base_url = str(request.base_url)
+        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()
+        redis_enable = get_bool_env("REDIS_ENABLE", default=False)
 
         if search_request.ids:
             search = self.database.apply_ids_filter(
@@ -819,7 +846,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
 
@@ -850,6 +876,34 @@ class CoreClient(AsyncBaseCoreClient):
         ]
         links = await PagingLinks(request=request, next=next_token).get_links()
 
+        collection_links = []
+        # Add "collection" and "parent" rels only for /collections/{collection_id}/items
+        if search_request.collections and "/items" in str(request.url):
+            for collection_id in search_request.collections:
+                collection_links.extend(
+                    [
+                        {
+                            "rel": "collection",
+                            "type": "application/json",
+                            "href": urljoin(base_url, f"collections/{collection_id}"),
+                        },
+                        {
+                            "rel": "parent",
+                            "type": "application/json",
+                            "href": urljoin(base_url, f"collections/{collection_id}"),
+                        },
+                    ]
+                )
+        links.extend(collection_links)
+
+        if redis_enable:
+            await redis_pagination_links(
+                current_url=str(request.url),
+                token=token_param,
+                next_token=next_token,
+                links=links,
+            )
+
         return stac_types.ItemCollection(
             type="FeatureCollection",
             features=items,

stac_fastapi/core/extensions/collections_search.py

@@ -1,8 +1,8 @@
 """Collections search extension."""
 
-from typing import List, Optional, Type, Union
+from typing import Any, Dict, List, Optional, Type, Union
 
-from fastapi import APIRouter, FastAPI, Request
+from fastapi import APIRouter, Body, FastAPI, Query, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 from stac_pydantic.api.search import ExtendedSearch
@@ -22,6 +22,168 @@ class CollectionsSearchRequest(ExtendedSearch):
     query: Optional[
         str
     ] = None  # Legacy query extension (deprecated but still supported)
+    filter_expr: Optional[str] = None
+    filter_lang: Optional[str] = None
+
+
+def build_get_collections_search_doc(original_endpoint):
+    """Return a documented GET endpoint wrapper for /collections-search."""
+
+    async def documented_endpoint(
+        request: Request,
+        q: Optional[Union[str, List[str]]] = Query(
+            None,
+            description="Free text search query",
+        ),
+        query: Optional[str] = Query(
+            None,
+            description="Additional filtering expressed as a string (legacy support)",
+            example="platform=landsat AND collection_category=level2",
+        ),
+        limit: int = Query(
+            10,
+            ge=1,
+            description=(
+                "The maximum number of collections to return (page size). Defaults to 10."
+            ),
+        ),
+        token: Optional[str] = Query(
+            None,
+            description="Pagination token for the next page of results",
+        ),
+        bbox: Optional[str] = Query(
+            None,
+            description=(
+                "Bounding box for spatial filtering in format 'minx,miny,maxx,maxy' "
+                "or 'minx,miny,minz,maxx,maxy,maxz'"
+            ),
+        ),
+        datetime: Optional[str] = Query(
+            None,
+            description=(
+                "Temporal filter in ISO 8601 format (e.g., "
+                "'2020-01-01T00:00:00Z/2021-01-01T00:00:00Z')"
+            ),
+        ),
+        sortby: Optional[str] = Query(
+            None,
+            description=(
+                "Sorting criteria in the format 'field' or '-field' for descending order"
+            ),
+        ),
+        fields: Optional[List[str]] = Query(
+            None,
+            description=(
+                "Comma-separated list of fields to include or exclude (use -field to exclude)"
+            ),
+            alias="fields[]",
+        ),
+        filter: Optional[str] = Query(
+            None,
+            description=(
+                "Structured filter expression in CQL2 JSON or CQL2-text format"
+            ),
+            example='{"op": "=", "args": [{"property": "properties.category"}, "level2"]}',
+        ),
+        filter_lang: Optional[str] = Query(
+            None,
+            description=(
+                "Filter language. Must be 'cql2-json' or 'cql2-text' if specified"
+            ),
+            example="cql2-json",
+        ),
+    ):
+        # Delegate to original endpoint with parameters
+        # Since FastAPI extracts parameters from the URL when they're defined as function parameters,
+        # we need to create a request wrapper that provides our modified query_params
+
+        # Create a mutable copy of query_params
+        if hasattr(request, "_query_params"):
+            query_params = dict(request._query_params)
+        else:
+            query_params = dict(request.query_params)
+
+        # Add q parameter back to query_params if it was provided
+        # Convert to list format to match /collections behavior
+        if q is not None:
+            if isinstance(q, str):
+                # Single string should become a list with one element
+                query_params["q"] = [q]
+            elif isinstance(q, list):
+                # Already a list, use as-is
+                query_params["q"] = q
+
+        # Add filter parameters back to query_params if they were provided
+        if filter is not None:
+            query_params["filter"] = filter
+        if filter_lang is not None:
+            query_params["filter-lang"] = filter_lang
+
+        # Create a request wrapper that provides our modified query_params
+        class RequestWrapper:
+            def __init__(self, original_request, modified_query_params):
+                self._original = original_request
+                self._query_params = modified_query_params
+
+            @property
+            def query_params(self):
+                return self._query_params
+
+            def __getattr__(self, name):
+                # Delegate all other attributes to the original request
+                return getattr(self._original, name)
+
+        wrapped_request = RequestWrapper(request, query_params)
+        return await original_endpoint(wrapped_request)
+
+    documented_endpoint.__name__ = original_endpoint.__name__
+    return documented_endpoint
+
+
+def build_post_collections_search_doc(original_post_endpoint):
+    """Return a documented POST endpoint wrapper for /collections-search."""
+
+    async def documented_post_endpoint(
+        request: Request,
+        body: Dict[str, Any] = Body(
+            ...,
+            description=(
+                "Search parameters for collections.\n\n"
+                "- `q`: Free text search query (string or list of strings)\n"
+                "- `query`: Additional filtering expressed as a string (legacy support)\n"
+                "- `filter`: Structured filter expression in CQL2 JSON or CQL2-text format\n"
+                "- `filter_lang`: Filter language. Must be 'cql2-json' or 'cql2-text' if specified\n"
+                "- `limit`: Maximum number of results to return (default: 10)\n"
+                "- `token`: Pagination token for the next page of results\n"
+                "- `bbox`: Bounding box [minx, miny, maxx, maxy] or [minx, miny, minz, maxx, maxy, maxz]\n"
+                "- `datetime`: Temporal filter in ISO 8601 (e.g., '2020-01-01T00:00:00Z/2021-01-01T12:31:12Z')\n"
+                "- `sortby`: List of sort criteria objects with 'field' and 'direction' (asc/desc)\n"
+                "- `fields`: Object with 'include' and 'exclude' arrays for field selection"
+            ),
+            example={
+                "q": "landsat",
+                "query": "platform=landsat AND collection_category=level2",
+                "filter": {
+                    "op": "=",
+                    "args": [{"property": "properties.category"}, "level2"],
+                },
+                "filter_lang": "cql2-json",
+                "limit": 10,
+                "token": "next-page-token",
+                "bbox": [-180, -90, 180, 90],
+                "datetime": "2020-01-01T00:00:00Z/2021-01-01T12:31:12Z",
+                "sortby": [{"field": "id", "direction": "asc"}],
+                "fields": {
+                    "include": ["id", "title", "description"],
+                    "exclude": ["properties"],
+                },
+            },
+        ),
+    ) -> Union[Collections, Response]:
+        return await original_post_endpoint(request, body)
+
+    documented_post_endpoint.__name__ = original_post_endpoint.__name__
+    return documented_post_endpoint
 
 
 class CollectionsSearchEndpointExtension(ApiExtension):
@@ -54,7 +216,6 @@ class CollectionsSearchEndpointExtension(ApiExtension):
         self.POST = POST
         self.conformance_classes = conformance_classes or []
         self.router = APIRouter()
-        self.create_endpoints()
 
     def register(self, app: FastAPI) -> None:
         """Register the extension with a FastAPI application.
@@ -65,32 +226,53 @@ class CollectionsSearchEndpointExtension(ApiExtension):
         Returns:
             None
         """
-        app.include_router(self.router)
+        # Remove any existing routes to avoid duplicates
+        self.router.routes = []
 
-    def create_endpoints(self) -> None:
-        """Create endpoints for the extension."""
+        # Recreate endpoints with proper OpenAPI documentation
         if self.GET:
+            original_endpoint = self.collections_search_get_endpoint
+            documented_endpoint = build_get_collections_search_doc(original_endpoint)
+
             self.router.add_api_route(
-                name="Get Collections Search",
                 path="/collections-search",
+                endpoint=documented_endpoint,
                 response_model=None,
                 response_class=JSONResponse,
                 methods=["GET"],
-                endpoint=self.collections_search_get_endpoint,
+                summary="Search collections",
+                description=(
+                    "Search for collections using query parameters. "
+                    "Supports filtering, sorting, and field selection."
+                ),
+                response_description="A list of collections matching the search criteria",
+                tags=["Collections Search Extension"],
                 **(self.settings if isinstance(self.settings, dict) else {}),
             )
 
         if self.POST:
+            original_post_endpoint = self.collections_search_post_endpoint
+            documented_post_endpoint = build_post_collections_search_doc(
+                original_post_endpoint
+            )
+
             self.router.add_api_route(
-                name="Post Collections Search",
                 path="/collections-search",
+                endpoint=documented_post_endpoint,
                 response_model=None,
                 response_class=JSONResponse,
                 methods=["POST"],
-                endpoint=self.collections_search_post_endpoint,
+                summary="Search collections",
+                description=(
+                    "Search for collections using a JSON request body. "
+                    "Supports filtering, sorting, field selection, and pagination."
+                ),
+                tags=["Collections Search Extension"],
                 **(self.settings if isinstance(self.settings, dict) else {}),
             )
 
+        app.include_router(self.router)
+
     async def collections_search_get_endpoint(
         self, request: Request
     ) -> Union[Collections, Response]:
@@ -124,6 +306,14 @@ class CollectionsSearchEndpointExtension(ApiExtension):
             sortby = sortby_str.split(",")
             params["sortby"] = sortby
 
+        # Handle filter parameter mapping (fixed for collections-search)
+        if "filter" in params:
+            params["filter_expr"] = params.pop("filter")
+
+        # Handle filter-lang parameter mapping (fixed for collections-search)
+        if "filter-lang" in params:
+            params["filter_lang"] = params.pop("filter-lang")
+
         collections = await self.client.all_collections(request=request, **params)
         return collections