stac-fastapi-core 6.4.0__tar.gz → 6.5.1__tar.gz

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: stac_fastapi_core
-Version: 6.4.0
+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
@@ -84,13 +84,13 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 ## Table of Contents
 
 - [stac-fastapi-elasticsearch-opensearch](#stac-fastapi-elasticsearch-opensearch)
-  - [Sponsors \& Supporters](#sponsors--supporters)
+  - [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)
+  - [Documentation & Resources](#documentation--resources)
   - [Package Structure](#package-structure)
   - [Examples](#examples)
   - [Performance](#performance)
@@ -133,7 +133,11 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 
 ## Collection Search Extensions
 
-SFEOS implements extended capabilities for the `/collections` endpoint, allowing for more powerful collection discovery:
+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)
@@ -149,9 +153,26 @@ SFEOS implements extended capabilities for the `/collections` endpoint, allowing
   - 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 can be disabled by setting the `ENABLE_COLLECTIONS_SEARCH` environment variable to `false`. By default, these extensions are enabled.
+> **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)
@@ -162,6 +183,7 @@ These extensions make it easier to build user interfaces that display and naviga
 >
 > **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:
@@ -174,7 +196,7 @@ This project is organized into several packages, each with a specific purpose:
   - 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
@@ -292,12 +314,13 @@ You can customize additional settings in your `.env` file:
 | `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).                                 | `true`                   | 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 |
+| `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 |
+| `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.
@@ -443,7 +466,6 @@ The system uses a precise naming convention:
   - `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.

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/README.md

@@ -66,13 +66,13 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 ## Table of Contents
 
 - [stac-fastapi-elasticsearch-opensearch](#stac-fastapi-elasticsearch-opensearch)
-  - [Sponsors \& Supporters](#sponsors--supporters)
+  - [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)
+  - [Documentation & Resources](#documentation--resources)
   - [Package Structure](#package-structure)
   - [Examples](#examples)
   - [Performance](#performance)
@@ -115,7 +115,11 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 
 ## Collection Search Extensions
 
-SFEOS implements extended capabilities for the `/collections` endpoint, allowing for more powerful collection discovery:
+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)
@@ -131,9 +135,26 @@ SFEOS implements extended capabilities for the `/collections` endpoint, allowing
   - 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 can be disabled by setting the `ENABLE_COLLECTIONS_SEARCH` environment variable to `false`. By default, these extensions are enabled.
+> **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)
@@ -144,6 +165,7 @@ These extensions make it easier to build user interfaces that display and naviga
 >
 > **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:
@@ -156,7 +178,7 @@ This project is organized into several packages, each with a specific purpose:
   - 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
@@ -274,12 +296,13 @@ You can customize additional settings in your `.env` file:
 | `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).                                 | `true`                   | 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 |
+| `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 |
+| `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.
@@ -425,7 +448,6 @@ The system uses a precise naming convention:
   - `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.

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/stac_fastapi/core/core.py

@@ -136,6 +136,20 @@ class CoreClient(AsyncBaseCoreClient):
                     "href": urljoin(base_url, "search"),
                     "method": "POST",
                 },
+                {
+                    "rel": "collections-search",
+                    "type": "application/json",
+                    "title": "Collections Search",
+                    "href": urljoin(base_url, "collections-search"),
+                    "method": "GET",
+                },
+                {
+                    "rel": "collections-search",
+                    "type": "application/json",
+                    "title": "Collections Search",
+                    "href": urljoin(base_url, "collections-search"),
+                    "method": "POST",
+                },
             ],
             stac_extensions=extension_schemas,
         )
@@ -226,35 +240,78 @@ class CoreClient(AsyncBaseCoreClient):
 
     async def all_collections(
         self,
+        limit: Optional[int] = None,
+        datetime: Optional[str] = None,
         fields: Optional[List[str]] = None,
-        sortby: Optional[str] = None,
+        sortby: Optional[Union[str, List[str]]] = None,
+        filter_expr: Optional[str] = None,
+        filter_lang: Optional[str] = None,
         q: Optional[Union[str, List[str]]] = None,
+        query: Optional[str] = None,
+        request: Request = None,
+        token: Optional[str] = None,
         **kwargs,
     ) -> stac_types.Collections:
         """Read all collections from the database.
 
         Args:
+            datetime (Optional[str]): Filter collections by datetime range.
+            limit (Optional[int]): Maximum number of collections to return.
             fields (Optional[List[str]]): Fields to include or exclude from the results.
             sortby (Optional[str]): Sorting options for the results.
-            q (Optional[List[str]]): Free text search terms.
+            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.
             **kwargs: Keyword arguments from the request.
 
         Returns:
             A Collections object containing all the collections in the database and links to various resources.
         """
-        request = kwargs["request"]
         base_url = str(request.base_url)
-        limit = int(request.query_params.get("limit", os.getenv("STAC_ITEM_LIMIT", 10)))
-        token = request.query_params.get("token")
+
+        # 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
+        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
+
+        # Get token from query params only if not already provided (for GET requests)
+        if token is None:
+            token = request.query_params.get("token")
 
         # Process fields parameter for filtering collection properties
         includes, excludes = set(), set()
-        if fields and self.extension_is_enabled("FieldsExtension"):
+        if fields:
             for field in fields:
                 if field[0] == "-":
                     excludes.add(field[1:])
                 else:
-                    includes.add(field[1:] if field[0] in "+ " else field)
+                    include_field = field[1:] if field[0] in "+ " else field
+                    includes.add(include_field)
 
         sort = None
         if sortby:
@@ -276,12 +333,82 @@ class CoreClient(AsyncBaseCoreClient):
         if q is not None:
             q_list = [q] if isinstance(q, str) else q
 
-        collections, next_token = await self.database.get_all_collections(
-            token=token, limit=limit, request=request, sort=sort, q=q_list
+        # Parse the query parameter if provided
+        parsed_query = None
+        if query is not None:
+            try:
+                parsed_query = orjson.loads(query)
+            except Exception as e:
+                raise HTTPException(
+                    status_code=400, detail=f"Invalid query parameter: {e}"
+                )
+
+        # Parse the filter parameter if provided
+        parsed_filter = None
+        if filter_expr is not None:
+            try:
+                # Only raise an error for explicitly unsupported filter languages
+                if filter_lang is not None and filter_lang not in [
+                    "cql2-json",
+                    "cql2-text",
+                ]:
+                    # Raise an error for unsupported filter languages
+                    raise HTTPException(
+                        status_code=400,
+                        detail=f"Only 'cql2-json' and 'cql2-text' filter languages are supported for collections. Got '{filter_lang}'.",
+                    )
+
+                # Handle different filter formats
+                try:
+                    if filter_lang == "cql2-text" or filter_lang is None:
+                        # For cql2-text or when no filter_lang is specified, try both formats
+                        try:
+                            # First try to parse as JSON
+                            parsed_filter = orjson.loads(unquote_plus(filter_expr))
+                        except Exception:
+                            # If that fails, use pygeofilter to convert CQL2-text to CQL2-JSON
+                            try:
+                                # Parse CQL2-text and convert to CQL2-JSON
+                                text_filter = unquote_plus(filter_expr)
+                                parsed_ast = parse_cql2_text(text_filter)
+                                parsed_filter = to_cql2(parsed_ast)
+                            except Exception as e:
+                                # If parsing fails, provide a helpful error message
+                                raise HTTPException(
+                                    status_code=400,
+                                    detail=f"Invalid CQL2-text filter: {e}. Please check your syntax.",
+                                )
+                    else:
+                        # For explicit cql2-json, parse as JSON
+                        parsed_filter = orjson.loads(unquote_plus(filter_expr))
+                except Exception as e:
+                    # Catch any other parsing errors
+                    raise HTTPException(
+                        status_code=400, detail=f"Error parsing filter: {e}"
+                    )
+
+            except Exception as e:
+                raise HTTPException(
+                    status_code=400, detail=f"Invalid filter parameter: {e}"
+                )
+
+        parsed_datetime = None
+        if datetime:
+            parsed_datetime = format_datetime_range(date_str=datetime)
+
+        collections, next_token, maybe_count = await self.database.get_all_collections(
+            token=token,
+            limit=limit,
+            request=request,
+            sort=sort,
+            q=q_list,
+            filter=parsed_filter,
+            query=parsed_query,
+            datetime=parsed_datetime,
         )
 
         # Apply field filtering if fields parameter was provided
-        if fields and self.extension_is_enabled("FieldsExtension"):
+        if fields:
             filtered_collections = [
                 filter_fields(collection, includes, excludes)
                 for collection in collections
@@ -303,7 +430,95 @@ class CoreClient(AsyncBaseCoreClient):
             next_link = PagingLinks(next=next_token, request=request).link_next()
             links.append(next_link)
 
-        return stac_types.Collections(collections=filtered_collections, links=links)
+        return stac_types.Collections(
+            collections=filtered_collections,
+            links=links,
+            numberMatched=maybe_count,
+            numberReturned=len(filtered_collections),
+        )
+
+    async def post_all_collections(
+        self, search_request: BaseSearchPostRequest, request: Request, **kwargs
+    ) -> stac_types.Collections:
+        """Search collections with POST request.
+
+        Args:
+            search_request (BaseSearchPostRequest): The search request.
+            request (Request): The request.
+
+        Returns:
+            A Collections object containing all the collections in the database and links to various resources.
+        """
+        request.postbody = search_request.model_dump(exclude_unset=True)
+
+        fields = None
+
+        # Check for field attribute (ExtendedSearch format)
+        if hasattr(search_request, "field") and search_request.field:
+            fields = []
+
+            # Handle include fields
+            if (
+                hasattr(search_request.field, "includes")
+                and search_request.field.includes
+            ):
+                for field in search_request.field.includes:
+                    fields.append(f"+{field}")
+
+            # Handle exclude fields
+            if (
+                hasattr(search_request.field, "excludes")
+                and search_request.field.excludes
+            ):
+                for field in search_request.field.excludes:
+                    fields.append(f"-{field}")
+
+        # Convert sortby parameter from POST format to all_collections format
+        sortby = None
+        # Check for sortby attribute
+        if hasattr(search_request, "sortby") and search_request.sortby:
+            # Create a list of sort strings in the format expected by all_collections
+            sortby = []
+            for sort_item in search_request.sortby:
+                # Handle different types of sort items
+                if hasattr(sort_item, "field") and hasattr(sort_item, "direction"):
+                    # This is a Pydantic model with field and direction attributes
+                    field = sort_item.field
+                    direction = sort_item.direction
+                elif isinstance(sort_item, dict):
+                    # This is a dictionary with field and direction keys
+                    field = sort_item.get("field")
+                    direction = sort_item.get("direction", "asc")
+                else:
+                    # Skip this item if we can't extract field and direction
+                    continue
+
+                if field:
+                    # Create a sort string in the format expected by all_collections
+                    # e.g., "-id" for descending sort on id field
+                    prefix = "-" if direction.lower() == "desc" else ""
+                    sortby.append(f"{prefix}{field}")
+
+        # 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,
+            datetime=search_request.datetime
+            if hasattr(search_request, "datetime")
+            else None,
+            token=search_request.token if hasattr(search_request, "token") else None,
+            fields=fields,
+            sortby=sortby,
+            filter_expr=search_request.filter
+            if hasattr(search_request, "filter")
+            else None,
+            filter_lang=search_request.filter_lang
+            if hasattr(search_request, "filter_lang")
+            else None,
+            query=search_request.query if hasattr(search_request, "query") else None,
+            q=search_request.q if hasattr(search_request, "q") else None,
+            request=request,
+            **kwargs,
+        )
 
     async def get_collection(
         self, collection_id: str, **kwargs
@@ -621,11 +836,7 @@ class CoreClient(AsyncBaseCoreClient):
             datetime_search=datetime_search,
         )
 
-        fields = (
-            getattr(search_request, "fields", None)
-            if self.extension_is_enabled("FieldsExtension")
-            else None
-        )
+        fields = getattr(search_request, "fields", None)
         include: Set[str] = fields.include if fields and fields.include else set()
         exclude: Set[str] = fields.exclude if fields and fields.exclude else set()
 

stac_fastapi_core-6.5.1/stac_fastapi/core/extensions/__init__.py

@@ -0,0 +1,11 @@
+"""elasticsearch extensions modifications."""
+
+from .collections_search import CollectionsSearchEndpointExtension
+from .query import Operator, QueryableTypes, QueryExtension
+
+__all__ = [
+    "Operator",
+    "QueryableTypes",
+    "QueryExtension",
+    "CollectionsSearchEndpointExtension",
+]

stac_fastapi_core-6.5.1/stac_fastapi/core/extensions/collections_search.py

@@ -0,0 +1,194 @@
+"""Collections search extension."""
+
+from typing import List, Optional, Type, Union
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+from stac_pydantic.api.search import ExtendedSearch
+from starlette.responses import Response
+
+from stac_fastapi.api.models import APIRequest
+from stac_fastapi.types.core import BaseCoreClient
+from stac_fastapi.types.extension import ApiExtension
+from stac_fastapi.types.stac import Collections
+
+
+class CollectionsSearchRequest(ExtendedSearch):
+    """Extended search model for collections with free text search support."""
+
+    q: Optional[Union[str, List[str]]] = None
+    token: Optional[str] = None
+    query: Optional[
+        str
+    ] = None  # Legacy query extension (deprecated but still supported)
+
+
+class CollectionsSearchEndpointExtension(ApiExtension):
+    """Collections search endpoint extension.
+
+    This extension adds a dedicated /collections-search endpoint for collection search operations.
+    """
+
+    def __init__(
+        self,
+        client: Optional[BaseCoreClient] = None,
+        settings: dict = None,
+        GET: Optional[Type[Union[BaseModel, APIRequest]]] = None,
+        POST: Optional[Type[Union[BaseModel, APIRequest]]] = None,
+        conformance_classes: Optional[List[str]] = None,
+    ):
+        """Initialize the extension.
+
+        Args:
+            client: Optional BaseCoreClient instance to use for this extension.
+            settings: Dictionary of settings to pass to the extension.
+            GET: Optional GET request model.
+            POST: Optional POST request model.
+            conformance_classes: Optional list of conformance classes to add to the API.
+        """
+        super().__init__()
+        self.client = client
+        self.settings = settings or {}
+        self.GET = GET
+        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.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        app.include_router(self.router)
+
+    def create_endpoints(self) -> None:
+        """Create endpoints for the extension."""
+        if self.GET:
+            self.router.add_api_route(
+                name="Get Collections Search",
+                path="/collections-search",
+                response_model=None,
+                response_class=JSONResponse,
+                methods=["GET"],
+                endpoint=self.collections_search_get_endpoint,
+                **(self.settings if isinstance(self.settings, dict) else {}),
+            )
+
+        if self.POST:
+            self.router.add_api_route(
+                name="Post Collections Search",
+                path="/collections-search",
+                response_model=None,
+                response_class=JSONResponse,
+                methods=["POST"],
+                endpoint=self.collections_search_post_endpoint,
+                **(self.settings if isinstance(self.settings, dict) else {}),
+            )
+
+    async def collections_search_get_endpoint(
+        self, request: Request
+    ) -> Union[Collections, Response]:
+        """GET /collections-search endpoint.
+
+        Args:
+            request: Request object.
+
+        Returns:
+            Collections: Collections object.
+        """
+        # Extract query parameters from the request
+        params = dict(request.query_params)
+
+        # Convert query parameters to appropriate types
+        if "limit" in params:
+            try:
+                params["limit"] = int(params["limit"])
+            except ValueError:
+                pass
+
+        # Handle fields parameter
+        if "fields" in params:
+            fields_str = params.pop("fields")
+            fields = fields_str.split(",")
+            params["fields"] = fields
+
+        # Handle sortby parameter
+        if "sortby" in params:
+            sortby_str = params.pop("sortby")
+            sortby = sortby_str.split(",")
+            params["sortby"] = sortby
+
+        collections = await self.client.all_collections(request=request, **params)
+        return collections
+
+    async def collections_search_post_endpoint(
+        self, request: Request, body: dict
+    ) -> Union[Collections, Response]:
+        """POST /collections-search endpoint.
+
+        Args:
+            request: Request object.
+            body: Search request body.
+
+        Returns:
+            Collections: Collections object.
+        """
+        # Convert the dict to an ExtendedSearch model
+        search_request = CollectionsSearchRequest.model_validate(body)
+
+        # Check if fields are present in the body
+        if "fields" in body:
+            # Extract fields from body and add them to search_request
+            if hasattr(search_request, "field"):
+                from stac_pydantic.api.extensions.fields import FieldsExtension
+
+                fields_data = body["fields"]
+                search_request.field = FieldsExtension(
+                    includes=fields_data.get("include"),
+                    excludes=fields_data.get("exclude"),
+                )
+
+        # Set the postbody on the request for pagination links
+        request.postbody = body
+
+        collections = await self.client.post_all_collections(
+            search_request=search_request, request=request
+        )
+
+        return collections
+
+    @classmethod
+    def from_extensions(
+        cls, extensions: List[ApiExtension]
+    ) -> "CollectionsSearchEndpointExtension":
+        """Create a CollectionsSearchEndpointExtension from a list of extensions.
+
+        Args:
+            extensions: List of extensions to include in the CollectionsSearchEndpointExtension.
+
+        Returns:
+            CollectionsSearchEndpointExtension: A new CollectionsSearchEndpointExtension instance.
+        """
+        from stac_fastapi.api.models import (
+            create_get_request_model,
+            create_post_request_model,
+        )
+
+        get_model = create_get_request_model(extensions)
+        post_model = create_post_request_model(extensions)
+
+        return cls(
+            GET=get_model,
+            POST=post_model,
+            conformance_classes=[
+                ext.conformance_classes
+                for ext in extensions
+                if hasattr(ext, "conformance_classes")
+            ],
+        )

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/stac_fastapi/core/version.py

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

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/stac_fastapi_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: stac-fastapi-core
-Version: 6.4.0
+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
@@ -84,13 +84,13 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 ## Table of Contents
 
 - [stac-fastapi-elasticsearch-opensearch](#stac-fastapi-elasticsearch-opensearch)
-  - [Sponsors \& Supporters](#sponsors--supporters)
+  - [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)
+  - [Documentation & Resources](#documentation--resources)
   - [Package Structure](#package-structure)
   - [Examples](#examples)
   - [Performance](#performance)
@@ -133,7 +133,11 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
 
 ## Collection Search Extensions
 
-SFEOS implements extended capabilities for the `/collections` endpoint, allowing for more powerful collection discovery:
+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)
@@ -149,9 +153,26 @@ SFEOS implements extended capabilities for the `/collections` endpoint, allowing
   - 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 can be disabled by setting the `ENABLE_COLLECTIONS_SEARCH` environment variable to `false`. By default, these extensions are enabled.
+> **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)
@@ -162,6 +183,7 @@ These extensions make it easier to build user interfaces that display and naviga
 >
 > **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:
@@ -174,7 +196,7 @@ This project is organized into several packages, each with a specific purpose:
   - 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
@@ -292,12 +314,13 @@ You can customize additional settings in your `.env` file:
 | `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).                                 | `true`                   | 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 |
+| `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 |
+| `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.
@@ -443,7 +466,6 @@ The system uses a precise naming convention:
   - `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.

{stac_fastapi_core-6.4.0 → stac_fastapi_core-6.5.1}/stac_fastapi_core.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ stac_fastapi/core/utilities.py
 stac_fastapi/core/version.py
 stac_fastapi/core/extensions/__init__.py
 stac_fastapi/core/extensions/aggregation.py
+stac_fastapi/core/extensions/collections_search.py
 stac_fastapi/core/extensions/fields.py
 stac_fastapi/core/extensions/filter.py
 stac_fastapi/core/extensions/query.py

stac_fastapi_core-6.4.0/stac_fastapi/core/extensions/__init__.py

@@ -1,5 +0,0 @@
-"""elasticsearch extensions modifications."""
-
-from .query import Operator, QueryableTypes, QueryExtension
-
-__all__ = ["Operator", "QueryableTypes", "QueryExtension"]