Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

Added

  • Environment variable EXCLUDED_FROM_QUERYABLES to exclude specific fields from queryables endpoint and filtering. Supports comma-separated list of fully qualified field names (e.g., properties.auth:schemes,properties.storage:schemes) #489
  • Added Redis caching configuration for navigation pagination support, enabling proper prev and next links in paginated responses. #488

Changed

Fixed

Removed

Updated

  • Improved OpenAPI docs for /collections-search GET and POST endpoints. #508

v6.6.0 - 2025-10-21

Added

  • Spatial search support for collections via bbox parameter on /collections endpoint. Collections are now indexed with a bbox_shape field (GeoJSON polygon) derived from their spatial extent for efficient geospatial queries when created or updated. [#481](stac-utils/stac-fastapi-elasticsearch-opensearch!481
  • Introduced SFEOS Tools (sfeos_tools/) - An installable Click-based CLI package for managing SFEOS deployments. Initial command add-bbox-shape adds the bbox_shape field to existing collections for spatial search compatibility. Install with pip install sfeos-tools[elasticsearch] or pip install sfeos-tools[opensearch]. #481
  • Moved SFEOS Tools to its own repository at Healy-Hyperspatial/sfeos-tools. The CLI package is now maintained separately.
  • CloudFerro logo to sponsors and supporters list #485
  • Latest news section to README #485
  • Python 3.14 support #500

Changed

  • Removed ENV_MAX_LIMIT environment variable; maximum limits are now handled by the default global limit environment variable. #482
  • Changed the default and maximum pagination limits for collections/items endpoints. #482
  • Removed the rel=child links to the collections from the landing page, as the listing was incomplete due to pagination. #496
  • Changed to pyproject.toml file from setup.py #505

Fixed

Removed

  • Removed Elasticsearch 7 from CI/CD test matrix. The project now only tests against Elasticsearch 8 and OpenSearch. #497

Updated

  • Updated Elasticsearch version to 8.19.5 in CI/CD test matrix and compose.yml. #497
  • Updated OpenSearch version to 2.19.3 in CI/CD test matrix and compose.yml. #499
  • Updated elasticsearh python library to 8.19.1 in setup.py. #499

v6.5.1 - 2025-09-30

Fixed

  • Issue where token, query param was not being passed to POST collections search logic #483
  • Issue where datetime param was not being passed from POST collections search logic to Elasticsearch #483
  • Collections search tests to ensure both GET /collections and GET/POST /collections-search endpoints are tested #483

v6.5.0 - 2025-09-29

Added

  • Environment variable ENABLE_COLLECTIONS_SEARCH_ROUTE to turn on/off the /collections-search endpoint. #478
  • POST and GET /collections-search endpoint for collections search queries, needed because POST /collections search will not work when the Transactions Extension is enabled. Defaults to False #478
  • GET /collections collection search structured filter extension with support for both cql2-json and cql2-text formats. #475
  • GET /collections collection search query extension. #477
  • GET /collections collections search datetime filtering support. #476

Changed

  • Refactored /collections endpoint implementation to support both GET and POST methods. #478

Fixed

  • support of disabled nested attributes in the properties dictionary. #474

v6.4.0 - 2025-09-24

Added

  • GET /collections collection search free text extension ex. /collections?q=sentinel. #470
  • Added USE_DATETIME environment variable to configure datetime search behavior in SFEOS. #452
  • GET /collections collection search sort extension ex. /collections?sortby=+id. #456
  • GET /collections collection search fields extension ex. /collections?fields=id,title. #465
  • Improved error messages for sorting on unsortable fields in collection search, including guidance on how to make fields sortable. #465
  • Added field alias for temporal to enable easier sorting by temporal extent, alongside extent.temporal.interval. #465
  • Added ENABLE_COLLECTIONS_SEARCH environment variable to make collection search extensions optional (defaults to enabled). #465

Changed

  • Fixed a bug where missing copy() caused default queryables to be incorrectly enriched by results from previous queries. #427
  • Removed non-generic attributes (cloud_cover, cloud_shadow_percentage, nodata_pixel_percentage) not applicable to all collections (e.g., SAR data).#427
  • Updated async_prep_create_item to support OS item loading with multiple indices.#427
  • unified the type of queryables endpoint to application/schema+json. #445
  • updated numReturned & numMatched fields in itemCollection return to numberReturned & numberMatched. #446

v6.3.0 - 2025-09-16

Added

  • STAC_INDEX_ASSETS environment variable to allow asset serialization to be configurable. #433
  • Added the ENV_MAX_LIMIT environment variable to SFEOS, allowing overriding of the MAX_LIMIT, which controls the ?limit parameter for returned items and STAC collections. #434
  • Sort, Query, and Filter extension and functionality to the item collection route. #437
  • Added Fields Extension implementation for the /collections/{collection_id}/items endpoint. #436

Changed

  • Changed assets serialization to prevent mapping explosion while allowing asset information to be indexed. #341
  • Simplified the item_collection function in core.py, moving the request to the get_search function. #437
  • Updated the format_datetime_range function to support milliseconds. #423
  • Blocked the /collections/{collection_id}/bulk_items endpoint when environmental variable ENABLE_DATETIME_INDEX_FILTERING is set to true. #438

Fixed

  • Fixed issue where sortby was not accepting the default sort, where a + or - was not specified before the field value ie. localhost:8081/collections/{collection_id}/items?sortby=id. #437

v6.2.1 - 2025-09-02

Added

  • Added id field as secondary sort to sort config to ensure unique pagination tokens. #421
  • Added default environment variable STAC_ITEM_LIMIT to SFEOS for result limiting of returned items and STAC collections #419

Changed

  • Simplified Patch class and updated patch script creation including adding nest creation for merge patch #420

v6.2.0 - 2025-08-27

Added

  • Added comprehensive index management system with dynamic selection and insertion strategies for improved performance and scalability #405
  • Added ENABLE_DATETIME_INDEX_FILTERING environment variable to enable datetime-based index selection using collection IDs. When enabled, the system creates indexes with UUID-based names and manages them through time-based aliases. Default is false. #405
  • Added DATETIME_INDEX_MAX_SIZE_GB environment variable to set maximum size limit in GB for datetime-based indexes. When an index exceeds this size, a new time-partitioned index will be created. Note: add +20% to target size due to ES/OS compression. Default is 25 GB. Only applies when ENABLE_DATETIME_INDEX_FILTERING is enabled. #405
  • Added index operations system with unified interface for both Elasticsearch and OpenSearch #405:
  • IndexOperations class with common index creation and management methods
  • UUID-based physical index naming: {prefix}_{collection-id}_{uuid4}
  • Alias management: main collection alias, temporal aliases, and closed index aliases
  • Automatic alias updates when indexes reach size limits
  • Added datetime-based index selection strategies with caching support #405:
  • DatetimeBasedIndexSelector for temporal filtering with intelligent caching
  • IndexCacheManager with configurable TTL-based cache expiration (default 1 hour)
  • IndexAliasLoader for alias management and cache refresh
  • UnfilteredIndexSelector as fallback for returning all available indexes
  • Added index insertion strategies with automatic partitioning #405:
  • Simple insertion strategy (SimpleIndexInserter) for traditional single-index-per-collection approach
  • Datetime-based insertion strategy (DatetimeIndexInserter) with time-based partitioning
  • Automatic index size monitoring and splitting when limits exceeded
  • Handling of chronologically early data and bulk operations
  • Added index management utilities #405:
  • IndexSizeManager for size monitoring and overflow handling with compression awareness
  • DatetimeIndexManager for datetime-based index operations and validation
  • Factory patterns (IndexInsertionFactory, IndexSelectorFactory) for strategy creation based on configuration

Changed

  • Added the Datetime-Based Index Management section to the Table of Contents in the readme, updating heading sizes to match the rest of the document #418

v6.1.0 - 2025-07-24

Added

  • Added the ability to set timeout for Opensearch and Elasticsearch clients by setting the environmental variable ES_TIMEOUT #408
  • Added collection-search#filter conformance class to CollectionSearchExtension to enable compatibility with stac-auth-proxy collection filtering #411

Changed

  • Updated collection to index logic to support searching a large amount of indices #412
  • Updated documentation to reflect use of ES environment variables #410
  • Updated documentation to reflect APP_PORT in stac-fastapi-core ApiSettings #410

v6.0.0 - 2025-06-22

Added

Changed

  • Updated stac-fastapi parent libraries to v6.0.0 #291

v5.0.0 - 2025-06-11

Added

  • Created new sfeos_helpers package to improve code organization and maintainability #376
  • Added introduction section - What is stac-fastapi-elasticsearch-opensearch? - to README #384
  • Added support for enum queryables #390

Changed

  • Refactored utility functions into dedicated modules within sfeos_helpers #376:
  • Created database package with specialized modules for index, document, and utility operations
  • Created aggregation package for Elasticsearch/OpenSearch-specific aggregation functionality
  • Moved shared logic from core module to helper functions for better code reuse
  • Separated utility functions from constant mappings for clearer code organization
  • Updated documentation to reflect recent code refactoring #376
  • Improved README documentation with consistent formatting and enhanced sections #381:
  • Added sfeos logo and banner
  • Added a comprehensive Quick Start guide
  • Reorganized sections for better navigation
  • Reformatted content with bullet points for improved readability
  • Added more detailed examples for API interaction
  • Updated mkdocs/ sfeos doucmentation page #386
  • Improved datetime query handling to only check start and end datetime values when datetime is None #396
  • Optimize data_loader.py script #395
  • Refactored test configuration to use shared app config pattern #399
  • Make orjson usage more consistent #402

Fixed

  • Added the ability to authenticate with OpenSearch/ElasticSearch with SSL disabled #388

Removed

  • Removed requests dev dependency #395

v4.2.0 - 2025-05-15

Added

  • Added dynamic queryables mapping for search and aggregations #375
  • Added configurable landing page ID STAC_FASTAPI_LANDING_PAGE_ID #352
  • Added support for S_CONTAINS, S_WITHIN, S_DISJOINT spatial filter operations #371
  • Introduced the DATABASE_REFRESH environment variable to control 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. #370
  • Added the ENABLE_TRANSACTIONS_EXTENSIONS environment variable to enable or disable the Transactions and Bulk Transactions API extensions. When set to false, endpoints provided by TransactionsClient and BulkTransactionsClient are not available. This allows for flexible deployment scenarios and improved API control. #374

Changed

  • Refactored CRUD methods in TransactionsClient to use the validate_refresh helper method for consistent and reusable handling of the refresh parameter. #370

Fixed

  • Fixed an issue where some routes were not passing the refresh parameter from kwargs to the database logic, ensuring consistent behavior across all CRUD operations. #370

v4.1.0 - 2025-05-09

Added

  • Added logging to bulk insertion methods to provide detailed feedback on errors encountered during operations. #364
  • Introduced the RAISE_ON_BULK_ERROR environment variable to control whether bulk insertion methods raise exceptions on errors (true) or log warnings and continue processing (false). #364
  • Added code coverage reporting to the test suite using pytest-cov. #87

Changed

  • Updated dynamic mapping for items to map long values to double versus float. #326
  • Extended Datetime Search to search on start_datetime and end_datetime as well as datetime fields. #182
  • Changed item update operation to use Elasticsearch index API instead of delete and create for better efficiency and atomicity. #75
  • Bulk insertion via BulkTransactionsClient now strictly validates all STAC Items using the Pydantic model before insertion. Any invalid item will immediately raise a ValidationError, ensuring consistent validation with single-item inserts and preventing invalid STAC Items from being stored. This validation is enforced regardless of the RAISE_ON_BULK_ERROR setting. #368

Changed

Fixed

  • Refactored create_item and update_item methods to share unified logic, ensuring consistent conflict detection, validation, and database operations. #368

v4.0.0 - 2025-04-23

Added

  • Added support for dynamically-generated queryables based on Elasticsearch/OpenSearch mappings, with extensible metadata augmentation #351
  • Included default queryables configuration for seamless integration. #351
  • Added support for high-performance direct response mode for both Elasticsearch and Opensearch backends, controlled by the ENABLE_DIRECT_RESPONSE environment variable. When enabled (ENABLE_DIRECT_RESPONSE=true), endpoints return Starlette Response objects directly, bypassing FastAPI's jsonable_encoder and Pydantic serialization for significantly improved performance on large search responses. Note: In this mode, all FastAPI dependencies (including authentication, custom status codes, and validation) are disabled for all routes. Default is false for safety. A warning is logged at startup if enabled. See issue #347 and PR #359.
  • Added robust tests for the ENABLE_DIRECT_RESPONSE environment variable, covering both Elasticsearch and OpenSearch backends. Tests gracefully handle missing backends by attempting to import both configs and skipping if neither is available. #359

Changed

  • Refactored database logic to reduce duplication #351
  • Replaced fastapi-slim with fastapi dependency #351
  • Changed minimum Python version to 3.9 #354
  • Updated stac-fastapi api, types, and extensions libraries to 5.1.1 from 3.0.0 and made various associated changes #354
  • Changed makefile commands from 'docker-compose' to 'docker compose' #354
  • Updated package names in setup.py files to use underscores instead of periods for PEP 625 compliance #358
  • Changed stac_fastapi.opensearch to stac_fastapi_opensearch
  • Changed stac_fastapi.elasticsearch to stac_fastapi_elasticsearch
  • Changed stac_fastapi.core to stac_fastapi_core
  • Updated all related dependencies to use the new naming convention
  • Renamed docker-compose.yml to compose.yml to align with Docker Compose V2 conventions #358
  • Removed deprecated version field from all compose files #358
  • Updated STAC_FASTAPI_VERSION environment variables to 4.0.0 in all compose files #362
  • Bumped version from 4.0.0a2 to 4.0.0 for the PEP 625 compliant release #362
  • Updated dependency requirements to use compatible release specifiers (~=) for more controlled updates while allowing for bug fixes and security patches #358
  • Removed elasticsearch-dsl dependency as it's now part of the elasticsearch package since version 8.18.0 #358
  • Updated test suite to use httpx.ASGITransport(app=...) for FastAPI app testing (removes deprecation warning). #359
  • Updated stac-fastapi parent libraries to 5.2.0. #359
  • Migrated Elasticsearch index template creation from legacy put_template to composable put_index_template API in database_logic.py. This resolves deprecation warnings and ensures compatibility with Elasticsearch 7.x and 8.x. #359
  • Updated all Pydantic models to use ConfigDict instead of class-based Config for Pydantic v2 compatibility. This resolves deprecation warnings and prepares for Pydantic v3. #359
  • Migrated all Pydantic @root_validator validators to @model_validator for Pydantic v2 compatibility. #359
  • Migrated startup event handling from deprecated @app.on_event("startup") to FastAPI's recommended lifespan context manager. This removes deprecation warnings and ensures compatibility with future FastAPI versions. #361
  • Refactored all boolean environment variable parsing in both Elasticsearch and OpenSearch backends to use the shared get_bool_env utility. This ensures robust and consistent handling of environment variables such as ES_USE_SSL, ES_HTTP_COMPRESS, and ES_VERIFY_CERTS across both backends. #359

Fixed

  • Improved performance of mk_actions and filter-links methods #351
  • Fixed inheritance relating to BaseDatabaseSettings and ApiBaseSettings #355
  • Fixed delete_item and delete_collection methods return types #355
  • Fixed inheritance relating to DatabaseLogic and BaseDatabaseLogic, and ApiBaseSettings #355

v3.2.5 - 2025-04-07

Added

  • Option to configure multiple Elasticsearch/OpenSearch hosts and enable http_compress. #349

v3.2.4 - 2025-03-14

Added

  • Support python 3.13 in SFEOS Core, Opensearch and ElasticSearch. #330

v3.2.3 - 2025-02-11

Changed

  • Added note on the use of the default * use in route authentication dependecies. #325
  • Update item index naming and aliasing to allow capitalisation of collection ids #329
  • Bugfixes for the IsNull operator and datetime filtering #330

v3.2.2 - 2024-12-15

Changed

  • Use base64 encoded JSON string of sort keys as pagination token instead of comma-separated string #323

v3.2.1 - 2024-11-14

Added

  • Added dockerfiles/Dockerfile.ci.os and dockerfiles/Dockerfile.ci.es, along with their respective entrypoints #311

Changed

  • Updated the publish.yml workflow to include Docker image publishing to GitHub Container Registry #311
  • Improved the README with detailed descriptions of the new Docker images, providing guidance for images. #311
  • Aggregation ElasticSearch total_count bugfix, moved aggregation text to docs. #314

v3.2.0 - 2024-10-09

Added

  • Added datetime_frequency_interval parameter for datetime_frequency aggregation. #294
  • Added rate limiting functionality with configurable limits using environment variable STAC_FASTAPI_RATE_LIMIT, example: 500/minute. #303
  • Added publish.yml to automatically publish new releases to PyPI #305

Changed

  • Updated CollectionLinks to generate correct self link for collections endpoint. #297
  • Refactored aggregation in database logic. #294
  • Fixed the self link for the /collections/{collection_id}/aggregations endpoint. #295

v3.1.0 - 2024-09-02

Added

  • Added support for FreeTextExtension. #227

Changed

  • Support escaped backslashes in CQL2 LIKE queries, and reject invalid (or incomplete) escape sequences. #286

v3.0.0 - 2024-08-14

Changed

  • Aggregation bug fixes #281
  • Updated stac-fastapi libraries to v3.0.0 #282

[v3.0.0a3] - 2024-07-17

Added

  • Added an implementation of the Aggregation Extension. Enables spatial, frequency distribution, and datetime distribution aggregations. #276
  • Added support for route depndencies configuration through the STAC_FASTAPI_ROUTE_DEPENDENCIES environment variable, directly or via json file. Allows for fastapi's inbuilt OAuth2 flows to be used as dependencies. Custom dependencies can also be written, see Basic Auth for an example. #251
  • Added docker-compose.route_dependencies_file.yml that gives an example of OAuth2 workflow using keycloak as the identity provider. #251
  • Added docker-compose.route_dependencies_env.yml that gives an example using the STAC_FASTAPI_ROUTE_DEPENDENCIES environment variable. #251

Changed

  • Updated to stac-fastapi 3.0.0a4. #275
  • Converted Basic auth to a route dependency and merged with new route depndencies method. #251
  • Updated docker-compose.basic_auth_protected.yml to use STAC_FASTAPI_ROUTE_DEPENDENCIES environment variable. #251

[v3.0.0a2]

Added

  • Queryables landing page and collection links when the Filter Extension is enabled #267

Changed

  • Updated stac-fastapi libraries to v3.0.0a1 #265
  • Updated stac-fastapi libraries to v3.0.0a3 #269
  • Converted Basic auth to a route dependency and merged with new route depndencies method. #251
  • Updated docker-compose.basic_auth_protected.yml to use STAC_FASTAPI_ROUTE_DEPENDENCIES environment variable. #251

Fixed

  • API sort extension tests #264
  • Basic auth permission fix for checking route path instead of absolute path #266
  • Remove deprecated filter_fields property, return all properties as default #269

[v3.0.0a1]

Changed

  • Unskip temporal open window test #254
  • Removed deprecated context extension #255
  • Remove duplicated code from stac_fastapi.types #257

[v3.0.0a0]

Added

  • Symlinks from project-specific readme files to main readme #250
  • Support for Python 3.12 #234

Changed

  • Updated stac-fastapi parent libraries to v3.0.0a0 #234
  • Removed pystac dependency #234

Fixed

  • Fixed issue where paginated search queries would return a next_token on the last page #243

v2.4.1

Added

  • A test to ensure that pagination correctly returns expected links, particularly verifying the absence of a 'next' link on the last page of results #244

Fixed

  • Fixed issue where searches return an empty links array #241

v2.4.0

Added

  • Added option to include Basic Auth #232

Changed

  • Upgrade stac-fastapi libaries to v2.5.5 #237

Fixed

  • Fixed POST /collections/test-collection/items returning an item with an empty links array #236

v2.3.0

Changed

  • Upgraded stac-fastapi libraries to v2.5.3 from v2.4.9 #172

v2.2.0

Added

  • use index templates for Collection and Item indices #208
  • Added API title, version, and description parameters from environment variables STAC_FASTAPI_TITLE, STAC_FASTAPI_VERSION and STAC_FASTAPI_DESCRIPTION, respectively. #207
  • Added a STAC_FASTAPI_ROOT_PATH environment variable to define the root path. Useful when working with an API gateway or load balancer. #221
  • Added mkdocs, pdocs, to generate docs and push to gh pages via workflow. Updated documentation. #223

Changed

  • Updated the pip_docker example to use stac-fastapi.elasticsearch 2.1.0 and the elasticsearch 8.11.0 docker image. #216
  • Updated the Data Loader CLI tool to accept a base_url, a data directory, a custom collection id, and an option to use bulk insert. #218
  • Changed the default ca_certs value to use certifi.where() to find the installed certificate authority. #222

Fixed

  • URL encode next href: #215
  • Do not overwrite links in Item and Collection objects before persisting in database #210

v2.1.0

Added

  • Added explicit mapping for ID in ES_COLLECTIONS_MAPPINGS #198

Changed

  • Removed database logic from core.py all_collections #196
  • Changed OpenSearch config ssl_version to SSLv23 #200

Fixed

v2.0.0

Added

  • Added core library package for common logic #186

Changed

  • Moved Elasticsearch and Opensearch backends into separate packages #186

Fixed

  • Allow additional top-level properties on collections #191

v1.1.0

Added

  • Advanced comparison (LIKE, IN, BETWEEN) operators to the Filter extension #178
  • Collection update endpoint no longer delete all sub items #177
  • OpenSearch 2.11.1 support #188

Changed

  • Elasticsearch drivers from 7.17.9 to 8.11.0 #169
  • Collection update endpoint no longer delete all sub items #177

Fixed

  • Exclude unset fields in search response #166
  • Upgrade stac-fastapi to v2.4.9 #172
  • Set correct default filter-lang for GET /search requests #179

v1.0.0

Added

  • Collection-level Assets to the CollectionSerializer #148
  • Pagination for /collections - GET all collections - route #164
  • Examples folder with example docker setup for running sfes from pip #147
  • GET /search filter extension queries #163
  • Added support for GET /search intersection queries #158

Changed

  • Update elasticsearch version from 8.1.3 to 8.10.4 in cicd, gh actions #164
  • Updated core stac-fastapi libraries to 2.4.8 from 2.4.3 #151
  • Use aliases on Elasticsearch indices, add number suffix in index name. #152

Fixed

  • Corrected the closing of client connections in ES index management functions #132
  • Corrected the automatic converstion of float values to int when building Filter Clauses #135
  • Do not index proj:geometry field as geo_shape #154
  • Remove unsupported characters from Elasticsearch index names #153
  • Fixed GET /search sortby requests #25

v0.3.0

Added

  • Added bbox and datetime parameters and functionality to item_collection #127
  • Added collection_id parameter to create_item function #127
  • Added item_id and collection_id to update_item #127
  • The default Collection objects index can be overridden by the STAC_COLLECTIONS_INDEX environment variable #128
  • The default Item objects index prefix can be overridden by the STAC_ITEMS_INDEX_PREFIX environment variable #128
  • Fields Extension #129
  • Support for Python 3.11 #131

Changed

  • Updated core stac-fastapi libraries to 2.4.3 from 2.3.0 #127

v0.2.0

Added

  • Filter Extension as GET with CQL2-Text and POST with CQL2-JSON, supporting the Basic CQL2 and Basic Spatial Operators conformance classes.
  • Added Elasticsearch local config to support snapshot/restore to local filesystem

Fixed

  • Fixed search intersects query.
  • Corrected the Sort and Query conformance class URIs.

Changed

  • Default to Python 3.10
  • Default to Elasticsearch 8.x
  • Collection objects are now stored in collections index rather than stac_collections index
  • Item objects are no longer stored in stac_items, but in indices per collection named items_{collection_id}
  • When using bulk ingest, items will continue to be ingested if any of them fail. Previously, the call would fail immediately if any items failed.

v0.1.0

Changed

  • Elasticsearch index mappings updated to be more thorough.
  • Endpoints that return items (e.g., /search) now sort the results by 'properties.datetime,id,collection'. Previously, there was no sort order defined.
  • Db_to_stac serializer moved to core.py for consistency as it existed in both core and database_logic previously.
  • Use genexp in execute_search and get_all_collections to return results.
  • Added db_to_stac serializer to item_collection method in core.py.