stac-fastapi-elasticsearch 4.1.0__py3-none-any.whl → 5.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- stac_fastapi/elasticsearch/app.py +51 -29
- stac_fastapi/elasticsearch/config.py +28 -5
- stac_fastapi/elasticsearch/database_logic.py +398 -281
- stac_fastapi/elasticsearch/version.py +1 -1
- stac_fastapi_elasticsearch-5.0.0.dist-info/METADATA +575 -0
- stac_fastapi_elasticsearch-5.0.0.dist-info/RECORD +10 -0
- stac_fastapi_elasticsearch-4.1.0.dist-info/METADATA +0 -379
- stac_fastapi_elasticsearch-4.1.0.dist-info/RECORD +0 -10
- {stac_fastapi_elasticsearch-4.1.0.dist-info → stac_fastapi_elasticsearch-5.0.0.dist-info}/WHEEL +0 -0
- {stac_fastapi_elasticsearch-4.1.0.dist-info → stac_fastapi_elasticsearch-5.0.0.dist-info}/entry_points.txt +0 -0
- {stac_fastapi_elasticsearch-4.1.0.dist-info → stac_fastapi_elasticsearch-5.0.0.dist-info}/top_level.txt +0 -0
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""library version."""
|
|
2
|
-
__version__ = "
|
|
2
|
+
__version__ = "5.0.0"
|
|
@@ -0,0 +1,575 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: stac-fastapi-elasticsearch
|
|
3
|
+
Version: 5.0.0
|
|
4
|
+
Summary: An implementation of STAC API based on the FastAPI framework with both Elasticsearch and Opensearch.
|
|
5
|
+
Home-page: https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Intended Audience :: Developers
|
|
8
|
+
Classifier: Intended Audience :: Information Technology
|
|
9
|
+
Classifier: Intended Audience :: Science/Research
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
Requires-Dist: stac-fastapi-core==5.0.0
|
|
19
|
+
Requires-Dist: sfeos-helpers==5.0.0
|
|
20
|
+
Requires-Dist: elasticsearch[async]~=8.18.0
|
|
21
|
+
Requires-Dist: uvicorn~=0.23.0
|
|
22
|
+
Requires-Dist: starlette<0.36.0,>=0.35.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest~=7.0.0; extra == "dev"
|
|
25
|
+
Requires-Dist: pytest-cov~=4.0.0; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-asyncio~=0.21.0; extra == "dev"
|
|
27
|
+
Requires-Dist: pre-commit~=3.0.0; extra == "dev"
|
|
28
|
+
Requires-Dist: ciso8601~=2.3.0; extra == "dev"
|
|
29
|
+
Requires-Dist: httpx<0.28.0,>=0.24.0; extra == "dev"
|
|
30
|
+
Provides-Extra: docs
|
|
31
|
+
Requires-Dist: mkdocs~=1.4.0; extra == "docs"
|
|
32
|
+
Requires-Dist: mkdocs-material~=9.0.0; extra == "docs"
|
|
33
|
+
Requires-Dist: pdocs~=1.2.0; extra == "docs"
|
|
34
|
+
Provides-Extra: server
|
|
35
|
+
Requires-Dist: uvicorn[standard]~=0.23.0; extra == "server"
|
|
36
|
+
|
|
37
|
+
# stac-fastapi-elasticsearch-opensearch
|
|
38
|
+
|
|
39
|
+
<!-- markdownlint-disable MD033 MD041 -->
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
<p align="left">
|
|
43
|
+
<img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/sfeos.png" width=1000>
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
**Jump to:** [Project Introduction](#project-introduction---what-is-sfeos) | [Quick Start](#quick-start) | [Table of Contents](#table-of-contents)
|
|
47
|
+
|
|
48
|
+
[](https://pepy.tech/project/stac-fastapi-core)
|
|
49
|
+
[](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/graphs/contributors)
|
|
50
|
+
[](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/stargazers)
|
|
51
|
+
[](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/network/members)
|
|
52
|
+
[](https://pypi.org/project/stac-fastapi-elasticsearch/)
|
|
53
|
+
[](https://github.com/radiantearth/stac-spec/tree/v1.1.0)
|
|
54
|
+
[](https://github.com/stac-utils/stac-fastapi)
|
|
55
|
+
|
|
56
|
+
## Sponsors & Supporters
|
|
57
|
+
|
|
58
|
+
The following organizations have contributed time and/or funding to support the development of this project:
|
|
59
|
+
|
|
60
|
+
<p align="left">
|
|
61
|
+
<a href="https://healy-hyperspatial.github.io/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/hh-logo-blue.png" alt="Healy Hyperspatial" height="100" hspace="20"></a>
|
|
62
|
+
<a href="https://atomicmaps.io/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/am-logo-black.png" alt="Atomic Maps" height="100" hspace="20"></a>
|
|
63
|
+
<a href="https://remotesensing.vito.be/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/VITO.png" alt="VITO Remote Sensing" height="100" hspace="20"></a>
|
|
64
|
+
</p>
|
|
65
|
+
|
|
66
|
+
## Project Introduction - What is SFEOS?
|
|
67
|
+
|
|
68
|
+
SFEOS (stac-fastapi-elasticsearch-opensearch) is a high-performance, scalable API implementation for serving SpatioTemporal Asset Catalog (STAC) data - an enhanced GeoJSON format designed specifically for geospatial assets like satellite imagery, aerial photography, and other Earth observation data. This project enables organizations to:
|
|
69
|
+
|
|
70
|
+
- **Efficiently catalog and search geospatial data** such as satellite imagery, aerial photography, DEMs, and other geospatial assets using Elasticsearch or OpenSearch as the database backend
|
|
71
|
+
- **Implement standardized STAC APIs** that support complex spatial, temporal, and property-based queries across large collections of geospatial data
|
|
72
|
+
- **Scale to millions of geospatial assets** with fast search performance through optimized spatial indexing and query capabilities
|
|
73
|
+
- **Support OGC-compliant filtering** including spatial operations (intersects, contains, etc.) and temporal queries
|
|
74
|
+
- **Perform geospatial aggregations** to analyze data distribution across space and time
|
|
75
|
+
|
|
76
|
+
This implementation builds on the STAC-FastAPI framework, providing a production-ready solution specifically optimized for Elasticsearch and OpenSearch databases. It's ideal for organizations managing large geospatial data catalogs who need efficient discovery and access capabilities through standardized APIs.
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
## Common Deployment Patterns
|
|
81
|
+
|
|
82
|
+
stac-fastapi-elasticsearch-opensearch can be deployed in several ways depending on your needs:
|
|
83
|
+
|
|
84
|
+
- **Containerized Application**: Run as a Docker container with connections to Elasticsearch/OpenSearch databases
|
|
85
|
+
- **Serverless Function**: Deploy as AWS Lambda or similar serverless function with API Gateway
|
|
86
|
+
- **Traditional Server**: Run on virtual machines or bare metal servers in your infrastructure
|
|
87
|
+
- **Kubernetes**: Deploy as part of a larger microservices architecture with container orchestration
|
|
88
|
+
|
|
89
|
+
The implementation is flexible and can scale from small local deployments to large production environments serving millions of geospatial assets.
|
|
90
|
+
|
|
91
|
+
## Technologies
|
|
92
|
+
|
|
93
|
+
This project is built on the following technologies: STAC, stac-fastapi, FastAPI, Elasticsearch, Python, OpenSearch
|
|
94
|
+
|
|
95
|
+
<p align="left">
|
|
96
|
+
<a href="https://stacspec.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/STAC-01.png" alt="STAC" height="100" hspace="10"></a>
|
|
97
|
+
<a href="https://www.python.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/python.png" alt="Python" height="80" hspace="10"></a>
|
|
98
|
+
<a href="https://fastapi.tiangolo.com/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/fastapi.svg" alt="FastAPI" height="80" hspace="10"></a>
|
|
99
|
+
<a href="https://www.elastic.co/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/elasticsearch.png" alt="Elasticsearch" height="80" hspace="10"></a>
|
|
100
|
+
<a href="https://opensearch.org/"><img src="https://raw.githubusercontent.com/stac-utils/stac-fastapi-elasticsearch-opensearch/refs/heads/main/assets/opensearch.svg" alt="OpenSearch" height="80" hspace="10"></a>
|
|
101
|
+
</p>
|
|
102
|
+
|
|
103
|
+
## Table of Contents
|
|
104
|
+
|
|
105
|
+
- [Documentation & Resources](#documentation--resources)
|
|
106
|
+
- [Package Structure](#package-structure)
|
|
107
|
+
- [Examples](#examples)
|
|
108
|
+
- [Performance](#performance)
|
|
109
|
+
- [Quick Start](#quick-start)
|
|
110
|
+
- [Installation](#installation)
|
|
111
|
+
- [Running Locally](#running-locally)
|
|
112
|
+
- [Configuration reference](#configuration-reference)
|
|
113
|
+
- [Interacting with the API](#interacting-with-the-api)
|
|
114
|
+
- [Configure the API](#configure-the-api)
|
|
115
|
+
- [Collection pagination](#collection-pagination)
|
|
116
|
+
- [Ingesting Sample Data CLI Tool](#ingesting-sample-data-cli-tool)
|
|
117
|
+
- [Elasticsearch Mappings](#elasticsearch-mappings)
|
|
118
|
+
- [Managing Elasticsearch Indices](#managing-elasticsearch-indices)
|
|
119
|
+
- [Snapshots](#snapshots)
|
|
120
|
+
- [Reindexing](#reindexing)
|
|
121
|
+
- [Auth](#auth)
|
|
122
|
+
- [Aggregation](#aggregation)
|
|
123
|
+
- [Rate Limiting](#rate-limiting)
|
|
124
|
+
|
|
125
|
+
## Documentation & Resources
|
|
126
|
+
|
|
127
|
+
- **Online Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
|
|
128
|
+
- **Source Code**: [https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch)
|
|
129
|
+
- **API Examples**: [Postman Documentation](https://documenter.getpostman.com/view/12888943/2s8ZDSdRHA) - Examples of how to use the API endpoints
|
|
130
|
+
- **Community**:
|
|
131
|
+
- [Gitter Chat](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) - For real-time discussions
|
|
132
|
+
- [GitHub Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) - For longer-form questions and answers
|
|
133
|
+
|
|
134
|
+
## Package Structure
|
|
135
|
+
|
|
136
|
+
This project is organized into several packages, each with a specific purpose:
|
|
137
|
+
|
|
138
|
+
- **stac_fastapi_core**: Core functionality that's database-agnostic, including API models, extensions, and shared utilities. This package provides the foundation for building STAC API implementations with any database backend. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example.
|
|
139
|
+
|
|
140
|
+
- **sfeos_helpers**: Shared helper functions and utilities used by both the Elasticsearch and OpenSearch backends. This package includes:
|
|
141
|
+
- `database`: Specialized modules for index, document, and database utility operations
|
|
142
|
+
- `aggregation`: Elasticsearch/OpenSearch-specific aggregation functionality
|
|
143
|
+
- Shared logic and utilities that improve code reuse between backends
|
|
144
|
+
|
|
145
|
+
- **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`.
|
|
146
|
+
-
|
|
147
|
+
- **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`.
|
|
148
|
+
|
|
149
|
+
## Examples
|
|
150
|
+
|
|
151
|
+
The `/examples` directory contains several useful examples and reference implementations:
|
|
152
|
+
|
|
153
|
+
- **pip_docker**: Examples of running stac-fastapi-elasticsearch from PyPI in Docker without needing any code from the repository
|
|
154
|
+
- **auth**: Authentication examples including:
|
|
155
|
+
- Basic authentication
|
|
156
|
+
- OAuth2 with Keycloak
|
|
157
|
+
- Route dependencies configuration
|
|
158
|
+
- **rate_limit**: Example of implementing rate limiting for API requests
|
|
159
|
+
- **postman_collections**: Postman collection files you can import for testing API endpoints
|
|
160
|
+
|
|
161
|
+
These examples provide practical reference implementations for various deployment scenarios and features.
|
|
162
|
+
|
|
163
|
+
## Performance
|
|
164
|
+
|
|
165
|
+
### Direct Response Mode
|
|
166
|
+
|
|
167
|
+
- The `enable_direct_response` option is provided by the stac-fastapi core library (introduced in stac-fastapi 5.2.0) and is available in this project starting from v4.0.0.
|
|
168
|
+
- **Control via environment variable**: Set `ENABLE_DIRECT_RESPONSE=true` to enable this feature.
|
|
169
|
+
- **How it works**: When enabled, endpoints return Starlette Response objects directly, bypassing FastAPI's default serialization for improved performance.
|
|
170
|
+
- **Important limitation**: All FastAPI dependencies (including authentication, custom status codes, and validation) are disabled for all routes when this mode is enabled.
|
|
171
|
+
- **Best use case**: This mode is best suited for public or read-only APIs where authentication and custom logic are not required.
|
|
172
|
+
- **Default setting**: `false` for safety.
|
|
173
|
+
- **More information**: See [issue #347](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347) for background and implementation details.
|
|
174
|
+
|
|
175
|
+
## Quick Start
|
|
176
|
+
|
|
177
|
+
This section helps you get up and running with stac-fastapi-elasticsearch-opensearch quickly.
|
|
178
|
+
|
|
179
|
+
### Installation
|
|
180
|
+
|
|
181
|
+
- **For versions 4.0.0a1 and newer** (PEP 625 compliant naming):
|
|
182
|
+
```bash
|
|
183
|
+
pip install stac-fastapi-elasticsearch # Elasticsearch backend
|
|
184
|
+
pip install stac-fastapi-opensearch # Opensearch backend
|
|
185
|
+
pip install stac-fastapi-core # Core library
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
- **For versions 4.0.0a0 and older**:
|
|
189
|
+
```bash
|
|
190
|
+
pip install stac-fastapi.elasticsearch # Elasticsearch backend
|
|
191
|
+
pip install stac-fastapi.opensearch # Opensearch backend
|
|
192
|
+
pip install stac-fastapi.core # Core library
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
> **Important Note:** Starting with version 4.0.0a1, package names have changed from using periods (e.g., `stac-fastapi.core`) to using hyphens (e.g., `stac-fastapi-core`) to comply with PEP 625. The internal package structure uses underscores, but users should install with hyphens as shown above. Please update your requirements files accordingly.
|
|
196
|
+
|
|
197
|
+
### Running Locally
|
|
198
|
+
|
|
199
|
+
There are two main ways to run the API locally:
|
|
200
|
+
|
|
201
|
+
#### Using Pre-built Docker Images
|
|
202
|
+
|
|
203
|
+
- We provide ready-to-use Docker images through GitHub Container Registry:
|
|
204
|
+
- [ElasticSearch backend](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-es)
|
|
205
|
+
- [OpenSearch backend](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pkgs/container/stac-fastapi-os)
|
|
206
|
+
|
|
207
|
+
- **Pull and run the images**:
|
|
208
|
+
```shell
|
|
209
|
+
# For Elasticsearch backend
|
|
210
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-es:latest
|
|
211
|
+
|
|
212
|
+
# For OpenSearch backend
|
|
213
|
+
docker pull ghcr.io/stac-utils/stac-fastapi-os:latest
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
#### Using Docker Compose
|
|
217
|
+
|
|
218
|
+
- **Prerequisites**: Ensure [Docker Compose](https://docs.docker.com/compose/install/) or [Podman Compose](https://podman-desktop.io/docs/compose) is installed on your machine.
|
|
219
|
+
|
|
220
|
+
- **Start the API**:
|
|
221
|
+
```shell
|
|
222
|
+
docker compose up elasticsearch app-elasticsearch
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- **Configuration**: By default, Docker Compose uses Elasticsearch 8.x and OpenSearch 2.11.1. To use different versions, create a `.env` file:
|
|
226
|
+
```shell
|
|
227
|
+
ELASTICSEARCH_VERSION=8.11.0
|
|
228
|
+
OPENSEARCH_VERSION=2.11.1
|
|
229
|
+
ENABLE_DIRECT_RESPONSE=false
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
- **Compatibility**: The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
## Configuration Reference
|
|
237
|
+
|
|
238
|
+
You can customize additional settings in your `.env` file:
|
|
239
|
+
|
|
240
|
+
| Variable | Description | Default | Required |
|
|
241
|
+
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
|
|
242
|
+
| `ES_HOST` | Hostname for external Elasticsearch/OpenSearch. | `localhost` | Optional |
|
|
243
|
+
| `ES_PORT` | Port for Elasticsearch/OpenSearch. | `9200` (ES) / `9202` (OS)| Optional |
|
|
244
|
+
| `ES_USE_SSL` | Use SSL for connecting to Elasticsearch/OpenSearch. | `false` | Optional |
|
|
245
|
+
| `ES_VERIFY_CERTS` | Verify SSL certificates when connecting. | `false` | Optional |
|
|
246
|
+
| `STAC_FASTAPI_TITLE` | Title of the API in the documentation. | `stac-fastapi-<backend>` | Optional |
|
|
247
|
+
| `STAC_FASTAPI_DESCRIPTION` | Description of the API in the documentation. | N/A | Optional |
|
|
248
|
+
| `STAC_FASTAPI_VERSION` | API version. | `2.1` | Optional |
|
|
249
|
+
| `STAC_FASTAPI_LANDING_PAGE_ID` | Landing page ID | `stac-fastapi` | Optional |
|
|
250
|
+
| `APP_HOST` | Server bind address. | `0.0.0.0` | Optional |
|
|
251
|
+
| `APP_PORT` | Server port. | `8080` | Optional |
|
|
252
|
+
| `ENVIRONMENT` | Runtime environment. | `local` | Optional |
|
|
253
|
+
| `WEB_CONCURRENCY` | Number of worker processes. | `10` | Optional |
|
|
254
|
+
| `RELOAD` | Enable auto-reload for development. | `true` | Optional |
|
|
255
|
+
| `STAC_FASTAPI_RATE_LIMIT` | API rate limit per client. | `200/minute` | Optional |
|
|
256
|
+
| `BACKEND` | Tests-related variable | `elasticsearch` or `opensearch` based on the backend | Optional |
|
|
257
|
+
| `ELASTICSEARCH_VERSION` | Version of Elasticsearch to use. | `8.11.0` | Optional | |
|
|
258
|
+
| `OPENSEARCH_VERSION` | OpenSearch version | `2.11.1` | Optional
|
|
259
|
+
| `ENABLE_DIRECT_RESPONSE` | Enable direct response for maximum performance (disables all FastAPI dependencies, including authentication, custom status codes, and validation) | `false` | Optional
|
|
260
|
+
| `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 |
|
|
261
|
+
| `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 |
|
|
262
|
+
| `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 |
|
|
263
|
+
|
|
264
|
+
> [!NOTE]
|
|
265
|
+
> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, and `ES_VERIFY_CERTS` 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.
|
|
266
|
+
|
|
267
|
+
## Interacting with the API
|
|
268
|
+
|
|
269
|
+
- **Creating a Collection**:
|
|
270
|
+
```shell
|
|
271
|
+
curl -X "POST" "http://localhost:8080/collections" \
|
|
272
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
273
|
+
-d $'{
|
|
274
|
+
"id": "my_collection"
|
|
275
|
+
}'
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
- **Adding an Item to a Collection**:
|
|
279
|
+
```shell
|
|
280
|
+
curl -X "POST" "http://localhost:8080/collections/my_collection/items" \
|
|
281
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
282
|
+
-d @item.json
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
- **Searching for Items**:
|
|
286
|
+
```shell
|
|
287
|
+
curl -X "GET" "http://localhost:8080/search" \
|
|
288
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
289
|
+
-d $'{
|
|
290
|
+
"collections": ["my_collection"],
|
|
291
|
+
"limit": 10
|
|
292
|
+
}'
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
- **Filtering by Bbox**:
|
|
296
|
+
```shell
|
|
297
|
+
curl -X "GET" "http://localhost:8080/search" \
|
|
298
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
299
|
+
-d $'{
|
|
300
|
+
"collections": ["my_collection"],
|
|
301
|
+
"bbox": [-180, -90, 180, 90]
|
|
302
|
+
}'
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
- **Filtering by Datetime**:
|
|
306
|
+
```shell
|
|
307
|
+
curl -X "GET" "http://localhost:8080/search" \
|
|
308
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
309
|
+
-d $'{
|
|
310
|
+
"collections": ["my_collection"],
|
|
311
|
+
"datetime": "2020-01-01T00:00:00Z/2020-12-31T23:59:59Z"
|
|
312
|
+
}'
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
## Configure the API
|
|
316
|
+
|
|
317
|
+
- **API Title and Description**: By default set to `stac-fastapi-<backend>`. Customize these by setting:
|
|
318
|
+
- `STAC_FASTAPI_TITLE`: Changes the API title in the documentation
|
|
319
|
+
- `STAC_FASTAPI_DESCRIPTION`: Changes the API description in the documentation
|
|
320
|
+
|
|
321
|
+
- **Database Indices**: By default, the API reads from and writes to:
|
|
322
|
+
- `collections` index for collections
|
|
323
|
+
- `items_<collection name>` indices for items
|
|
324
|
+
- Customize with `STAC_COLLECTIONS_INDEX` and `STAC_ITEMS_INDEX_PREFIX` environment variables
|
|
325
|
+
|
|
326
|
+
- **Root Path Configuration**: The application root path is the base URL by default.
|
|
327
|
+
- For AWS Lambda with Gateway API: Set `STAC_FASTAPI_ROOT_PATH` to match the Gateway API stage name (e.g., `/v1`)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
## Collection Pagination
|
|
331
|
+
|
|
332
|
+
- **Overview**: The collections route supports pagination through optional query parameters.
|
|
333
|
+
- **Parameters**:
|
|
334
|
+
- `limit`: Controls the number of collections returned per page
|
|
335
|
+
- `token`: Used to retrieve subsequent pages of results
|
|
336
|
+
- **Response Structure**: The `links` field in the response contains a `next` link with the token for the next page of results.
|
|
337
|
+
- **Example Usage**:
|
|
338
|
+
```shell
|
|
339
|
+
curl -X "GET" "http://localhost:8080/collections?limit=1&token=example_token"
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## Ingesting Sample Data CLI Tool
|
|
343
|
+
|
|
344
|
+
- **Overview**: The `data_loader.py` script provides a convenient way to load STAC items into the database.
|
|
345
|
+
|
|
346
|
+
- **Usage**:
|
|
347
|
+
```shell
|
|
348
|
+
python3 data_loader.py --base-url http://localhost:8080
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
- **Options**:
|
|
352
|
+
```
|
|
353
|
+
--base-url TEXT Base URL of the STAC API [required]
|
|
354
|
+
--collection-id TEXT ID of the collection to which items are added
|
|
355
|
+
--use-bulk Use bulk insert method for items
|
|
356
|
+
--data-dir PATH Directory containing collection.json and feature
|
|
357
|
+
collection file
|
|
358
|
+
--help Show this message and exit.
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
- **Example Workflows**:
|
|
362
|
+
- **Loading Sample Data**:
|
|
363
|
+
```shell
|
|
364
|
+
python3 data_loader.py --base-url http://localhost:8080
|
|
365
|
+
```
|
|
366
|
+
- **Loading Data to a Specific Collection**:
|
|
367
|
+
```shell
|
|
368
|
+
python3 data_loader.py --base-url http://localhost:8080 --collection-id my-collection
|
|
369
|
+
```
|
|
370
|
+
- **Using Bulk Insert for Performance**:
|
|
371
|
+
```shell
|
|
372
|
+
python3 data_loader.py --base-url http://localhost:8080 --use-bulk
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
## Elasticsearch Mappings
|
|
376
|
+
|
|
377
|
+
- **Overview**: Mappings apply to search index, not source data. They define how documents and their fields are stored and indexed.
|
|
378
|
+
- **Implementation**:
|
|
379
|
+
- Mappings are stored in index templates that are created on application startup
|
|
380
|
+
- These templates are automatically applied when creating new Collection and Item indices
|
|
381
|
+
- The `sfeos_helpers` package contains shared mapping definitions used by both Elasticsearch and OpenSearch backends
|
|
382
|
+
- **Customization**: Custom mappings can be defined by extending the base mapping templates.
|
|
383
|
+
|
|
384
|
+
## Managing Elasticsearch Indices
|
|
385
|
+
|
|
386
|
+
### Snapshots
|
|
387
|
+
|
|
388
|
+
- **Overview**: Snapshots provide a way to backup and restore your indices.
|
|
389
|
+
|
|
390
|
+
- **Creating a Snapshot Repository**:
|
|
391
|
+
```shell
|
|
392
|
+
curl -X "PUT" "http://localhost:9200/_snapshot/my_fs_backup" \
|
|
393
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
394
|
+
-d $'{
|
|
395
|
+
"type": "fs",
|
|
396
|
+
"settings": {
|
|
397
|
+
"location": "/usr/share/elasticsearch/snapshots/my_fs_backup"
|
|
398
|
+
}
|
|
399
|
+
}'
|
|
400
|
+
```
|
|
401
|
+
- This creates a snapshot repository that stores files in the elasticsearch/snapshots directory in this git repo clone
|
|
402
|
+
- The elasticsearch.yml and compose files create a mapping from that directory to /usr/share/elasticsearch/snapshots within the Elasticsearch container and grant permissions for using it
|
|
403
|
+
|
|
404
|
+
- **Creating a Snapshot**:
|
|
405
|
+
```shell
|
|
406
|
+
curl -X "PUT" "http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2?wait_for_completion=true" \
|
|
407
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
408
|
+
-d $'{
|
|
409
|
+
"metadata": {
|
|
410
|
+
"taken_because": "dump of all items",
|
|
411
|
+
"taken_by": "pvarner"
|
|
412
|
+
},
|
|
413
|
+
"include_global_state": false,
|
|
414
|
+
"ignore_unavailable": false,
|
|
415
|
+
"indices": "items_my-collection"
|
|
416
|
+
}'
|
|
417
|
+
```
|
|
418
|
+
- This creates a snapshot named my_snapshot_2 and waits for the action to be completed before returning
|
|
419
|
+
- This can also be done asynchronously by omitting the wait_for_completion parameter, and queried for status later
|
|
420
|
+
- The indices parameter determines which indices are snapshotted, and can include wildcards
|
|
421
|
+
|
|
422
|
+
- **Viewing Snapshots**:
|
|
423
|
+
```shell
|
|
424
|
+
# View a specific snapshot
|
|
425
|
+
curl http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2
|
|
426
|
+
|
|
427
|
+
# View all snapshots
|
|
428
|
+
curl http://localhost:9200/_snapshot/my_fs_backup/_all
|
|
429
|
+
```
|
|
430
|
+
- These commands allow you to check the status and details of your snapshots
|
|
431
|
+
|
|
432
|
+
- **Restoring a Snapshot**:
|
|
433
|
+
```shell
|
|
434
|
+
curl -X "POST" "http://localhost:9200/_snapshot/my_fs_backup/my_snapshot_2/_restore?wait_for_completion=true" \
|
|
435
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
436
|
+
-d $'{
|
|
437
|
+
"include_aliases": false,
|
|
438
|
+
"include_global_state": false,
|
|
439
|
+
"ignore_unavailable": true,
|
|
440
|
+
"rename_replacement": "items_$1-copy",
|
|
441
|
+
"indices": "items_*",
|
|
442
|
+
"rename_pattern": "items_(.+)"
|
|
443
|
+
}'
|
|
444
|
+
```
|
|
445
|
+
- This specific command will restore any indices that match items_* and rename them so that the new index name will be suffixed with -copy
|
|
446
|
+
- The rename_pattern and rename_replacement parameters allow you to restore indices under new names
|
|
447
|
+
|
|
448
|
+
- **Updating Collection References**:
|
|
449
|
+
```shell
|
|
450
|
+
curl -X "POST" "http://localhost:9200/items_my-collection-copy/_update_by_query" \
|
|
451
|
+
-H 'Content-Type: application/json; charset=utf-8' \
|
|
452
|
+
-d $'{
|
|
453
|
+
"query": {
|
|
454
|
+
"match_all": {}
|
|
455
|
+
},
|
|
456
|
+
"script": {
|
|
457
|
+
"lang": "painless",
|
|
458
|
+
"params": {
|
|
459
|
+
"collection": "my-collection-copy"
|
|
460
|
+
},
|
|
461
|
+
"source": "ctx._source.collection = params.collection"
|
|
462
|
+
}
|
|
463
|
+
}'
|
|
464
|
+
```
|
|
465
|
+
- After restoring, the item documents have been restored in the new index (e.g., my-collection-copy), but the value of the collection field in those documents is still the original value of my-collection
|
|
466
|
+
- This command updates these values to match the new collection name using Elasticsearch's Update By Query feature
|
|
467
|
+
|
|
468
|
+
- **Creating a New Collection**:
|
|
469
|
+
```shell
|
|
470
|
+
curl -X "POST" "http://localhost:8080/collections" \
|
|
471
|
+
-H 'Content-Type: application/json' \
|
|
472
|
+
-d $'{
|
|
473
|
+
"id": "my-collection-copy"
|
|
474
|
+
}'
|
|
475
|
+
```
|
|
476
|
+
- The final step is to create a new collection through the API with the new name for each of the restored indices
|
|
477
|
+
- This gives you a copy of the collection that has a resource URI (/collections/my-collection-copy) and can be correctly queried by collection name
|
|
478
|
+
|
|
479
|
+
### Reindexing
|
|
480
|
+
|
|
481
|
+
- **Overview**: Reindexing allows you to copy documents from one index to another, optionally transforming them in the process.
|
|
482
|
+
|
|
483
|
+
- **Use Cases**:
|
|
484
|
+
- Apply changes to documents
|
|
485
|
+
- Correct dynamically generated mappings
|
|
486
|
+
- Transform data (e.g., lowercase identifiers)
|
|
487
|
+
- The index templates will make sure that manually created indices will also have the correct mappings and settings
|
|
488
|
+
|
|
489
|
+
- **Example: Reindexing with Transformation**:
|
|
490
|
+
```shell
|
|
491
|
+
curl -X "POST" "http://localhost:9200/_reindex" \
|
|
492
|
+
-H 'Content-Type: application/json' \
|
|
493
|
+
-d $'{
|
|
494
|
+
"source": {
|
|
495
|
+
"index": "items_my-collection-lower_my-collection-hex-000001"
|
|
496
|
+
},
|
|
497
|
+
"dest": {
|
|
498
|
+
"index": "items_my-collection-lower_my-collection-hex-000002"
|
|
499
|
+
},
|
|
500
|
+
"script": {
|
|
501
|
+
"source": "ctx._source.id = ctx._source.id.toLowerCase()",
|
|
502
|
+
"lang": "painless"
|
|
503
|
+
}
|
|
504
|
+
}'
|
|
505
|
+
```
|
|
506
|
+
- In this example, we make a copy of an existing Item index but change the Item identifier to be lowercase
|
|
507
|
+
- The script parameter allows you to transform documents during the reindexing process
|
|
508
|
+
|
|
509
|
+
- **Updating Aliases**:
|
|
510
|
+
```shell
|
|
511
|
+
curl -X "POST" "http://localhost:9200/_aliases" \
|
|
512
|
+
-H 'Content-Type: application/json' \
|
|
513
|
+
-d $'{
|
|
514
|
+
"actions": [
|
|
515
|
+
{
|
|
516
|
+
"remove": {
|
|
517
|
+
"index": "*",
|
|
518
|
+
"alias": "items_my-collection"
|
|
519
|
+
}
|
|
520
|
+
},
|
|
521
|
+
{
|
|
522
|
+
"add": {
|
|
523
|
+
"index": "items_my-collection-lower_my-collection-hex-000002",
|
|
524
|
+
"alias": "items_my-collection"
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
]
|
|
528
|
+
}'
|
|
529
|
+
```
|
|
530
|
+
- If you are happy with the data in the newly created index, you can move the alias items_my-collection to the new index
|
|
531
|
+
- This makes the modified Items with lowercase identifiers visible to users accessing my-collection in the STAC API
|
|
532
|
+
- Using aliases allows you to switch between different index versions without changing the API endpoint
|
|
533
|
+
|
|
534
|
+
## Auth
|
|
535
|
+
|
|
536
|
+
- **Overview**: Authentication is an optional feature that can be enabled through Route Dependencies.
|
|
537
|
+
- **Implementation Options**:
|
|
538
|
+
- Basic authentication
|
|
539
|
+
- OAuth2 with Keycloak
|
|
540
|
+
- Custom route dependencies
|
|
541
|
+
- **Configuration**: Authentication can be configured using the `STAC_FASTAPI_ROUTE_DEPENDENCIES` environment variable.
|
|
542
|
+
- **Examples and Documentation**: Detailed examples and implementation guides can be found in the [examples/auth](examples/auth) directory.
|
|
543
|
+
|
|
544
|
+
## Aggregation
|
|
545
|
+
|
|
546
|
+
- **Supported Aggregations**:
|
|
547
|
+
- Spatial aggregations of points and geometries
|
|
548
|
+
- Frequency distribution aggregation of any property including dates
|
|
549
|
+
- Temporal distribution of datetime values
|
|
550
|
+
|
|
551
|
+
- **Endpoint Locations**:
|
|
552
|
+
- Root Catalog level: `/aggregations`
|
|
553
|
+
- Collection level: `/<collection_id>/aggregations`
|
|
554
|
+
|
|
555
|
+
- **Implementation Details**: The `sfeos_helpers.aggregation` package provides specialized functionality for both Elasticsearch and OpenSearch backends.
|
|
556
|
+
|
|
557
|
+
- **Documentation**: Detailed information about supported aggregations can be found in [the aggregation docs](./docs/src/aggregation.md).
|
|
558
|
+
|
|
559
|
+
|
|
560
|
+
## Rate Limiting
|
|
561
|
+
|
|
562
|
+
- **Overview**: Rate limiting is an optional security feature that controls API request frequency on a remote address basis.
|
|
563
|
+
|
|
564
|
+
- **Configuration**: Enabled by setting the `STAC_FASTAPI_RATE_LIMIT` environment variable:
|
|
565
|
+
```
|
|
566
|
+
STAC_FASTAPI_RATE_LIMIT=500/minute
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
- **Functionality**:
|
|
570
|
+
- Limits each client to a specified number of requests per time period (e.g., 500 requests per minute)
|
|
571
|
+
- Helps prevent API abuse and maintains system stability
|
|
572
|
+
- Ensures fair resource allocation among all clients
|
|
573
|
+
|
|
574
|
+
- **Examples**: Implementation examples are available in the [examples/rate_limit](examples/rate_limit) directory.
|
|
575
|
+
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
stac_fastapi/elasticsearch/__init__.py,sha256=w_MZutYLreNV372sCuO46bPb0TngmPs4u8737ueS0wE,31
|
|
2
|
+
stac_fastapi/elasticsearch/app.py,sha256=R_zxNIzbNDZwC6-jJm9AeEpALlRDVH0eA384KVfR2wc,5188
|
|
3
|
+
stac_fastapi/elasticsearch/config.py,sha256=PKSowbXmSryMj0Oq15XJduyPL2c_NlDkewXnR1DFP2o,5181
|
|
4
|
+
stac_fastapi/elasticsearch/database_logic.py,sha256=pRb1ZoZdtOFKfCi9fqvbXL0IOoAQTk7BgHnsdoNWglM,48763
|
|
5
|
+
stac_fastapi/elasticsearch/version.py,sha256=OmdIBuUO48QSNasPq039QZ4jr1YGTWDPPnYtlSe5Hxg,45
|
|
6
|
+
stac_fastapi_elasticsearch-5.0.0.dist-info/METADATA,sha256=fKg_SekBAydJNU9PKG42wfSwhSoJm6HKu-EV8oYkyBI,31931
|
|
7
|
+
stac_fastapi_elasticsearch-5.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
|
|
8
|
+
stac_fastapi_elasticsearch-5.0.0.dist-info/entry_points.txt,sha256=aCKixki0LpUl64UPsPMtiNvfdyq-QsTCxVjJ54VF6Jk,82
|
|
9
|
+
stac_fastapi_elasticsearch-5.0.0.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
|
|
10
|
+
stac_fastapi_elasticsearch-5.0.0.dist-info/RECORD,,
|