Skip to content

Commit c98576b

Browse files
YuriZmytrakovYuriZmytrakov
authored
Merge branch 'main' into CAT-1382-2
2 parents 9cf57b6 + 0517b4b commit c98576b

File tree

17 files changed

+1035
-131
lines changed

17 files changed

+1035
-131
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
99

1010
### Added
1111

12+
- 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](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/481)
13+
- 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](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/481)
1214
- CloudFerro logo to sponsors and supporters list [#485](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/485)
1315
- Latest news section to README [#485](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/485)
1416
- Added Redis caching configuration for navigation pagination support, enabling proper `prev` and `next` links in paginated responses. [#488](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/488)
@@ -17,15 +19,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
1719

1820
### Fixed
1921

20-
[v6.5.1] - 2025-09-30
22+
## [v6.5.1] - 2025-09-30
2123

2224
### Fixed
2325

2426
- Issue where token, query param was not being passed to POST collections search logic [#483](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/483)
2527
- Issue where datetime param was not being passed from POST collections search logic to Elasticsearch [#483](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/483)
2628
- Collections search tests to ensure both GET /collections and GET/POST /collections-search endpoints are tested [#483](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/483)
2729

28-
[v6.5.0] - 2025-09-29
30+
## [v6.5.0] - 2025-09-29
2931

3032
### Added
3133

‎README.md‎

Lines changed: 74 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ The following organizations have contributed time and/or funding to support the
3232

3333
<div style="max-height: 200px; overflow-y: auto; padding: 10px; border: 1px solid #eaecef; border-radius: 6px; margin-bottom: 16px;">
3434

35-
- 10/04/2025: The [CloudFerro](https://cloudferro.com/) logo has been added to the sponsors and supporters list above. Their sponsorship of the ongoing collections search extension work has been invaluable. This is in addition to the many other important changes and updates their developers have added to the project.
35+
- **10/12/2025:** Collections search **bbox** functionality added! The collections search extension now supports bbox queries. Collections will need to be updated via the API or with the new **[SFEOS-tools](#sfeos-tools-cli)** CLI package to support geospatial discoverability. Thanks again to **CloudFerro** for their sponsorship of this work!
36+
- **10/04/2025:** The **[CloudFerro](https://cloudferro.com/)** logo has been added to the sponsors and supporters list above. Their sponsorship of the ongoing collections search extension work has been invaluable. This is in addition to the many other important changes and updates their developers have added to the project.
3637

3738
</div>
3839

@@ -105,6 +106,7 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
105106
- [Interacting with the API](#interacting-with-the-api)
106107
- [Configure the API](#configure-the-api)
107108
- [Collection Pagination](#collection-pagination)
109+
- [SFEOS Tools CLI](#sfeos-tools-cli)
108110
- [Ingesting Sample Data CLI Tool](#ingesting-sample-data-cli-tool)
109111
- [Elasticsearch Mappings](#elasticsearch-mappings)
110112
- [Managing Elasticsearch Indices](#managing-elasticsearch-indices)
@@ -160,9 +162,21 @@ These endpoints support advanced collection discovery features including:
160162
- Collections are matched if their temporal extent overlaps with the provided datetime parameter
161163
- This allows for efficient discovery of collections based on time periods
162164

165+
- **Spatial Filtering**: Filter collections by their spatial extent using the `bbox` parameter
166+
- Example: `/collections?bbox=-10,35,40,70` (finds collections whose spatial extent intersects with this bounding box)
167+
- Example: `/collections?bbox=-180,-90,180,90` (finds all collections with global coverage)
168+
- Supports both 2D bounding boxes `[minx, miny, maxx, maxy]` and 3D bounding boxes `[minx, miny, minz, maxx, maxy, maxz]` (altitude values are ignored for spatial queries)
169+
- Collections are matched if their spatial extent (stored in the `extent.spatial.bbox` field) intersects with the provided bbox parameter
170+
- **Implementation Note**: When collections are created or updated, a `bbox_shape` field is automatically generated from the collection's spatial extent and indexed as a GeoJSON polygon for efficient geospatial queries
171+
- **Migrating Legacy Collections**: Collections created before this feature was added will not be discoverable via bbox search until they have the `bbox_shape` field added. You can either:
172+
- Update each collection via the API (PUT `/collections/{collection_id}` with the existing collection data)
173+
- Run the migration tool (see [SFEOS Tools CLI](#sfeos-tools-cli) for installation and connection options):
174+
- `sfeos-tools add-bbox-shape --backend elasticsearch --no-ssl`
175+
- `sfeos-tools add-bbox-shape --backend opensearch --host db.example.com --no-ssl`
176+
163177
These extensions make it easier to build user interfaces that display and navigate through collections efficiently.
164178

165-
> **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.
179+
> **Configuration**: Collection search extensions (sorting, field selection, free text search, structured filtering, datetime filtering, and spatial filtering) for the `/collections` endpoint can be disabled by setting the `ENABLE_COLLECTIONS_SEARCH` environment variable to `false`. By default, these extensions are enabled.
166180
>
167181
> **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**.
168182
@@ -495,6 +509,64 @@ The system uses a precise naming convention:
495509
curl -X "GET" "http://localhost:8080/collections?limit=1&token=example_token"
496510
```
497511

512+
## SFEOS Tools CLI
513+
514+
- **Overview**: SFEOS Tools is an installable CLI package for managing and maintaining SFEOS deployments.
515+
516+
- **Installation**:
517+
```shell
518+
# For Elasticsearch (from PyPI)
519+
pip install sfeos-tools[elasticsearch]
520+
521+
# For OpenSearch (from PyPI)
522+
pip install sfeos-tools[opensearch]
523+
524+
# For local development
525+
pip install -e sfeos_tools[elasticsearch]
526+
# or
527+
pip install -e sfeos_tools[opensearch]
528+
```
529+
530+
- **Available Commands**:
531+
- `add-bbox-shape`: Add bbox_shape field to existing collections for spatial search support
532+
533+
- **Basic Usage**:
534+
```shell
535+
sfeos-tools add-bbox-shape --backend elasticsearch
536+
sfeos-tools add-bbox-shape --backend opensearch
537+
```
538+
539+
- **Connection Options**: Configure database connection via CLI flags or environment variables:
540+
- `--host`: Database host (default: `localhost` or `ES_HOST` env var)
541+
- `--port`: Database port (default: `9200` or `ES_PORT` env var)
542+
- `--use-ssl` / `--no-ssl`: Use SSL connection (default: `true` or `ES_USE_SSL` env var)
543+
- `--user`: Database username (default: `ES_USER` env var)
544+
- `--password`: Database password (default: `ES_PASS` env var)
545+
546+
- **Examples**:
547+
```shell
548+
# Local Docker Compose (no SSL)
549+
sfeos-tools add-bbox-shape --backend elasticsearch --no-ssl
550+
551+
# Remote server with SSL
552+
sfeos-tools add-bbox-shape \
553+
--backend elasticsearch \
554+
--host db.example.com \
555+
--port 9200 \
556+
--user admin \
557+
--password secret
558+
559+
# Cloud deployment with environment variables
560+
ES_HOST=my-es-cluster.cloud.com ES_PORT=9243 ES_USER=elastic ES_PASS=changeme \
561+
sfeos-tools add-bbox-shape --backend elasticsearch
562+
563+
# Using --help for more information
564+
sfeos-tools --help
565+
sfeos-tools add-bbox-shape --help
566+
```
567+
568+
For more details, see the [SFEOS Tools README](./sfeos_tools/README.md).
569+
498570
## Ingesting Sample Data CLI Tool
499571

500572
- **Overview**: The `data_loader.py` script provides a convenient way to load STAC items into the database.

‎sfeos_tools/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Jonathan Healy and CloudFerro S.A.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎sfeos_tools/README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# SFEOS Tools
2+
3+
CLI tools for managing [stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch) deployments.
4+
5+
## Installation
6+
7+
### For Elasticsearch
8+
9+
```bash
10+
pip install sfeos-tools[elasticsearch]
11+
```
12+
13+
Or for local development:
14+
```bash
15+
pip install -e sfeos_tools[elasticsearch]
16+
```
17+
18+
### For OpenSearch
19+
20+
```bash
21+
pip install sfeos-tools[opensearch]
22+
```
23+
24+
Or for local development:
25+
```bash
26+
pip install -e sfeos_tools[opensearch]
27+
```
28+
29+
### For Development (both backends)
30+
31+
```bash
32+
pip install sfeos-tools[dev]
33+
```
34+
35+
Or for local development:
36+
```bash
37+
pip install -e sfeos_tools[dev]
38+
```
39+
40+
## Usage
41+
42+
After installation, the `sfeos-tools` command will be available:
43+
44+
```bash
45+
# View available commands
46+
sfeos-tools --help
47+
48+
# View version
49+
sfeos-tools --version
50+
51+
# Get help for a specific command
52+
sfeos-tools add-bbox-shape --help
53+
```
54+
55+
## Commands
56+
57+
### add-bbox-shape
58+
59+
Add `bbox_shape` field to existing collections for spatial search support.
60+
61+
**Basic usage:**
62+
63+
```bash
64+
# Elasticsearch
65+
sfeos-tools add-bbox-shape --backend elasticsearch
66+
67+
# OpenSearch
68+
sfeos-tools add-bbox-shape --backend opensearch
69+
```
70+
71+
**Connection options:**
72+
73+
```bash
74+
# Local Docker Compose (no SSL)
75+
sfeos-tools add-bbox-shape --backend elasticsearch --no-ssl
76+
77+
# Remote server with SSL
78+
sfeos-tools add-bbox-shape \
79+
--backend elasticsearch \
80+
--host db.example.com \
81+
--port 9200 \
82+
--user admin \
83+
--password secret
84+
85+
# Using environment variables
86+
ES_HOST=my-cluster.cloud.com ES_PORT=9243 ES_USER=elastic ES_PASS=changeme \
87+
sfeos-tools add-bbox-shape --backend elasticsearch
88+
```
89+
90+
**Available options:**
91+
92+
- `--backend`: Database backend (elasticsearch or opensearch) - **required**
93+
- `--host`: Database host (default: localhost or ES_HOST env var)
94+
- `--port`: Database port (default: 9200 or ES_PORT env var)
95+
- `--use-ssl / --no-ssl`: Use SSL connection (default: true or ES_USE_SSL env var)
96+
- `--user`: Database username (default: ES_USER env var)
97+
- `--password`: Database password (default: ES_PASS env var)
98+
99+
## Development
100+
101+
To develop sfeos-tools locally:
102+
103+
```bash
104+
# Install in editable mode with dev dependencies
105+
pip install -e ./sfeos_tools[dev]
106+
107+
# Run the CLI
108+
sfeos-tools --help
109+
```
110+
111+
## License
112+
113+
MIT License - see the main repository for details.

‎sfeos_tools/setup.py‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
"""Setup for SFEOS Tools."""
2+
3+
from setuptools import find_packages, setup
4+
5+
with open("README.md", "r", encoding="utf-8") as f:
6+
long_description = f.read()
7+
8+
setup(
9+
name="sfeos-tools",
10+
version="0.1.0",
11+
description="CLI tools for managing stac-fastapi-elasticsearch-opensearch deployments",
12+
long_description=long_description,
13+
long_description_content_type="text/markdown",
14+
author="Jonathan Healy, CloudFerro S.A.",
15+
license="MIT",
16+
url="https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch",
17+
packages=find_packages(),
18+
python_requires=">=3.8",
19+
install_requires=[
20+
"click>=8.0.0",
21+
],
22+
extras_require={
23+
"elasticsearch": [
24+
"stac_fastapi_core",
25+
"sfeos_helpers",
26+
"stac_fastapi_elasticsearch",
27+
],
28+
"opensearch": [
29+
"stac_fastapi_core",
30+
"sfeos_helpers",
31+
"stac_fastapi_opensearch",
32+
],
33+
"dev": [
34+
"stac_fastapi_core",
35+
"sfeos_helpers",
36+
"stac_fastapi_elasticsearch",
37+
"stac_fastapi_opensearch",
38+
],
39+
},
40+
entry_points={
41+
"console_scripts": [
42+
"sfeos-tools=sfeos_tools.cli:cli",
43+
],
44+
},
45+
classifiers=[
46+
"Development Status :: 4 - Beta",
47+
"Intended Audience :: Developers",
48+
"License :: OSI Approved :: MIT License",
49+
"Programming Language :: Python :: 3",
50+
"Programming Language :: Python :: 3.8",
51+
"Programming Language :: Python :: 3.9",
52+
"Programming Language :: Python :: 3.10",
53+
"Programming Language :: Python :: 3.11",
54+
"Programming Language :: Python :: 3.12",
55+
],
56+
)

‎sfeos_tools/sfeos_tools/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""SFEOS Tools - Utilities for managing stac-fastapi-elasticsearch-opensearch deployments."""
2+
3+
__version__ = "0.1.0"

0 commit comments

Comments
 (0)