docs: add USE_DATETIME env var to README, update CHANGELOG

Author: Yuri Zmytrakov

CHANGELOG.md

@@ -8,10 +8,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+- Added `USE_DATETIME` environment variable behavior to set datetime filtering logic. [#443](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/443)
+
 ### Added
 
 - 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](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/434)
-- Updated the `format_datetime_range` function to support milliseconds. [#423](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/423)
 
 ### Changed
 

README.md

@@ -229,6 +229,7 @@ You can customize additional settings in your `.env` file:
 | `ENABLE_TRANSACTIONS_EXTENSIONS` | Enables or disables the Transactions and Bulk Transactions API extensions. If set to `false`, the POST `/collections` route and related transaction endpoints (including bulk transaction operations) will be unavailable in the API. This is useful for deployments where mutating the catalog via the API should be prevented. | `true` | Optional |
 | `STAC_ITEM_LIMIT` | Sets the environment variable for result limiting to SFEOS for the number of returned items and STAC collections. | `10` | Optional |
 | `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 environment variable to control datetime filtering behavior. When `true`, searches by datetime field, and if datetime is `null` then by start/end datetime fields. When `false`, always searches only by start/end datetime fields. | 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.

stac_fastapi/opensearch/stac_fastapi/opensearch/database_logic.py

@@ -316,7 +316,10 @@ def apply_datetime_filter(
                         "bool",
                         filter=[
                             Q("exists", field="properties.datetime"),
-                            Q("term", **{"properties__datetime": datetime_search["eq"]}),
+                            Q(
+                                "term",
+                                **{"properties__datetime": datetime_search["eq"]},
+                            ),
                         ],
                     ),
                     Q(
@@ -327,7 +330,9 @@ def apply_datetime_filter(
                             Q("exists", field="properties.end_datetime"),
                             Q(
                                 "range",
-                                properties__start_datetime={"lte": datetime_search["eq"]},
+                                properties__start_datetime={
+                                    "lte": datetime_search["eq"]
+                                },
                             ),
                             Q(
                                 "range",
@@ -362,11 +367,15 @@ def apply_datetime_filter(
                             Q("exists", field="properties.end_datetime"),
                             Q(
                                 "range",
-                                properties__start_datetime={"lte": datetime_search["lte"]},
+                                properties__start_datetime={
+                                    "lte": datetime_search["lte"]
+                                },
                             ),
                             Q(
                                 "range",
-                                properties__end_datetime={"gte": datetime_search["gte"]},
+                                properties__end_datetime={
+                                    "gte": datetime_search["gte"]
+                                },
                             ),
                         ],
                     ),