docs: talk about collections (#14)

* docs: talk about collections

* deps: update rustac

Author: gadomski

README.md

@@ -6,7 +6,7 @@
 
 A [stac-fastapi](https://github.com/stac-utils/stac-fastapi) with a [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet/blob/main/spec/stac-geoparquet-spec.md) backend.
 
-**stac-fastapi-geoparquet** can serve a full-featured STAC API from a **stac-geoparquet** file located (e.g.) in blob storage — no database required.
+**stac-fastapi-geoparquet** can serve a full-featured STAC API from one or more **stac-geoparquet** files located (e.g.) in blob storage — no database required.
 
 > [!WARNING]
 > 👷 This project is under active development and may change and break at any time.
@@ -24,7 +24,32 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
 ```
 
-To explore the API, you can use [stac browser](https://radiantearth.github.io/stac-browser/#/external/http:/127.0.0.1:8000/?.language=en).
+This will start the server on <http://127.0.0.1:8000>.
+The collection will be auto-generated from the items in the **stac-geoparquet** file.
+
+### Using collections
+
+Instead of providing the href to a single file, you can provide the href to a file containing a JSON list of collections.
+Any [collection assets](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#assets) with a [application/vnd.apache.parquet](https://github.com/opengeospatial/geoparquet/blob/main/format-specs/geoparquet.md#media-type) `type` field will be added to the server as sources of items.
+For an example, see [data/collections.json](./data/collections.json).
+
+To start a server with one or more collections:
+
+```shell
+$ STAC_FASTAPI_COLLECTIONS_HREF=data/collections.json uvicorn stac_fastapi.geoparquet.main:app
+INFO:     Started server process [47920]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+To auto-generate the collections file, we provide a [script](./scripts/generate-collections):
+
+```shell
+scripts/generate-collections s3://my-bucket/a.parquet s3://my-bucket/b.parquet
+```
+
+This will update `./data/collections.json`.
 
 ## Development
 

pyproject.toml

@@ -3,13 +3,13 @@ name = "stac-fastapi-geoparquet"
 version = "0.0.1"
 description = "A stac-fastapi implementation with a stac-geoparquet backend"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "attr>=0.3.2",
     "fastapi>=0.115.8",
     "geojson-pydantic>=1.2.0",
     "pydantic>=2.10.4",
-    "rustac==0.7.0b2",
+    "rustac==0.7.0b3",
     "stac-fastapi-api>=5.0.2",
     "stac-fastapi-extensions>=5.0.2",
     "stac-fastapi-types>=5.0.2",

src/stac_fastapi/geoparquet/api.py

@@ -5,7 +5,7 @@
 
 import pystac.utils
 from fastapi import FastAPI, HTTPException
-from rustac import DuckdbClient
+from rustac import Collection, DuckdbClient
 
 import stac_fastapi.api.models
 from stac_fastapi.api.app import StacApi
@@ -47,6 +47,36 @@ class State(TypedDict):
     """A mapping of collection id to geoparquet href."""
 
 
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[State]:
+    client = app.extra["duckdb_client"]
+    settings: Settings = app.extra["settings"]
+    collections = app.extra["collections"]
+    collection_dict = dict()
+    hrefs = defaultdict(list)
+    for collection in collections:
+        if collection["id"] in collection_dict:
+            raise HTTPException(
+                500, f"two collections with the same id: {collection.id}"
+            )
+        else:
+            collection_dict[collection["id"]] = collection
+        for key, asset in collection["assets"].items():
+            if asset.get("type") == GEOPARQUET_MEDIA_TYPE:
+                hrefs[collection["id"]].append(
+                    pystac.utils.make_absolute_href(
+                        asset["href"],
+                        settings.stac_fastapi_collections_href,
+                        start_is_dir=False,
+                    )
+                )
+    yield {
+        "client": client,
+        "collections": collection_dict,
+        "hrefs": hrefs,
+    }
+
+
 def create(
     settings: Settings | None = None,
     duckdb_client: DuckdbClient | None = None,
@@ -60,37 +90,19 @@ def create(
             stac_fastapi_description="A stac-fastapi server backend by stac-geoparquet",
         )
 
-    with open(settings.stac_fastapi_collections_href, "rb") as f:
-        collections = json.load(f)
-
-    @asynccontextmanager
-    async def lifespan(app: FastAPI) -> AsyncIterator[State]:
-        client = app.extra["duckdb_client"]
-        settings: Settings = app.extra["settings"]
-        collections = app.extra["collections"]
-        collection_dict = dict()
-        hrefs = defaultdict(list)
-        for collection in collections:
-            if collection["id"] in collection_dict:
-                raise HTTPException(
-                    500, f"two collections with the same id: {collection.id}"
-                )
-            else:
-                collection_dict[collection["id"]] = collection
-            for key, asset in collection["assets"].items():
-                if asset["type"] == GEOPARQUET_MEDIA_TYPE:
-                    hrefs[collection["id"]].append(
-                        pystac.utils.make_absolute_href(
-                            asset["href"],
-                            settings.stac_fastapi_collections_href,
-                            start_is_dir=False,
-                        )
-                    )
-        yield {
-            "client": client,
-            "collections": collection_dict,
-            "hrefs": hrefs,
-        }
+    if settings.stac_fastapi_collections_href:
+        with open(settings.stac_fastapi_collections_href, "rb") as f:
+            collections = json.load(f)
+    else:
+        collections = []
+
+    if settings.stac_fastapi_geoparquet_href:
+        collections.extend(
+            collections_from_geoparquet_href(
+                settings.stac_fastapi_geoparquet_href,
+                duckdb_client,
+            )
+        )
 
     api = StacApi(
         settings=settings,
@@ -108,3 +120,13 @@ async def lifespan(app: FastAPI) -> AsyncIterator[State]:
         search_post_request_model=PostSearchRequestModel,
     )
     return api
+
+
+def collections_from_geoparquet_href(
+    href: str, duckdb_client: DuckdbClient
+) -> list[Collection]:
+    collections = duckdb_client.get_collections(href)
+    for collection in collections:
+        collection["links"] = []
+        collection["assets"] = {"data": {"href": href, "type": GEOPARQUET_MEDIA_TYPE}}
+    return collections

src/stac_fastapi/geoparquet/settings.py

@@ -4,7 +4,12 @@
 class Settings(ApiSettings):  # type: ignore
     """stac-fastapi-geoparquet settings"""
 
-    stac_fastapi_collections_href: str
-    """A file containing JSON list of collections.
+    stac_fastapi_collections_href: str | None = None
+    """The href of a file containing JSON list of collections.
 
     Any parquet assets on the collection will be loaded into the server."""
+
+    stac_fastapi_geoparquet_href: str | None = None
+    """The href of a stac-geoparquet file.
+
+    The items in the file will be used to auto-generate one or more collections."""

tests/conftest.py

@@ -8,6 +8,7 @@
 from stac_fastapi.geoparquet import Settings
 
 COLLECTIONS_PATH = Path(__file__).parents[1] / "data" / "collections.json"
+NAIP_PATH = Path(__file__).parents[1] / "data" / "naip.parquet"
 
 
 @pytest.fixture

tests/test_api.py

@@ -7,7 +7,7 @@
 import stac_fastapi.geoparquet.api
 from stac_fastapi.geoparquet import Settings
 
-from .conftest import COLLECTIONS_PATH
+from .conftest import COLLECTIONS_PATH, NAIP_PATH
 
 
 @pytest.fixture
@@ -24,3 +24,11 @@ def test_create(extension_directory: Path) -> None:
     with TestClient(api.app) as client:
         response = client.get("/search")
         assert response.status_code == 200
+
+
+def test_create_from_parquet_file() -> None:
+    settings = Settings(stac_fastapi_geoparquet_href=str(NAIP_PATH))
+    api = stac_fastapi.geoparquet.api.create(settings=settings)
+    with TestClient(api.app) as client:
+        response = client.get("/search")
+        assert response.status_code == 200