add numberMatched and numberReturned for /collections

Author: vincentsarago

CHANGES.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [4.0.1] - 2025-02-06
+
+### Added
+
+- add `numberReturned` and `numberMatched` in `/collections` response
+
 ## [4.0.0] - 2025-02-03
 
 ### Changed
@@ -366,7 +372,8 @@ As a part of this release, this repository was extracted from the main
 
 - First PyPi release!
 
-[Unreleased]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/4.0.0..main>
+[Unreleased]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/4.0.1..main>
+[4.0.1]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/4.0.0..4.0.1>
 [4.0.0]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/3.0.1..4.0.0>
 [3.0.1]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/3.0.0..3.0.1>
 [3.0.0]: <https://github.com/stac-utils/stac-fastapi-pgstac/compare/2.5.0..3.0.0>

docker-compose.nginx.yml

@@ -10,4 +10,4 @@ services:
     command: [ "nginx-debug", "-g", "daemon off;" ]
   app:
     environment:
-      - UVICORN_ROOT_PATH=/api/v1/pgstac
+      - ROOT_PATH=/api/v1/pgstac

stac_fastapi/pgstac/core.py

@@ -114,10 +114,19 @@ async def all_collections(  # noqa: C901
                 )
                 collections_result = {"collections": cols, "links": []}
 
-        linked_collections: List[Collection] = []
-        collections = collections_result["collections"]
-        if collections is not None and len(collections) > 0:
-            for c in collections:
+        collections = Collections(
+            collections=[],
+            links=[],
+            numberReturned=collections_result.get(
+                "numberReturned", len(collections_result["collections"])
+            ),
+        )
+        if collections_result.get("numberMatched", None) is not None:
+            collections["numberMatched"] = collections_result.get("numberMatched")
+
+        cols = collections_result["collections"]
+        if cols is not None and len(cols) > 0:
+            for c in cols:
                 coll = Collection(**c)
                 coll["links"] = await CollectionLinks(
                     collection_id=coll["id"], request=request
@@ -137,18 +146,15 @@ async def all_collections(  # noqa: C901
                         }
                     )
 
-                linked_collections.append(coll)
+                collections["collections"].append(coll)
 
-        links = await CollectionSearchPagingLinks(
+        collections["links"] = await CollectionSearchPagingLinks(
             request=request,
             next=next_link,
             prev=prev_link,
         ).get_links()
 
-        return Collections(
-            collections=linked_collections or [],
-            links=links,
-        )
+        return collections
 
     async def get_collection(
         self, collection_id: str, request: Request, **kwargs

tests/resources/test_collection.py

@@ -116,6 +116,7 @@ async def test_nocollections(
 ):
     resp = await app_client.get("/collections")
     assert resp.status_code == 200
+    assert resp.json()["numberReturned"] == 0
 
 
 async def test_returns_valid_collection(app_client, load_test_data):
@@ -168,6 +169,9 @@ async def test_returns_valid_links_in_collections(app_client, load_test_data):
     resp = await app_client.get("/collections")
     assert resp.status_code == 200
     resp_json = resp.json()
+    assert resp.json()["numberReturned"]
+    assert resp.json()["numberMatched"]
+
     collections = resp_json["collections"]
     # Find collection in list by ID
     single_coll = next(coll for coll in collections if coll["id"] == in_json["id"])
@@ -317,6 +321,8 @@ async def test_collection_search_freetext(
         "/collections",
         params={"q": "temperature"},
     )
+    assert resp.json()["numberReturned"] == 1
+    assert resp.json()["numberMatched"] == 1
     assert len(resp.json()["collections"]) == 1
     assert resp.json()["collections"][0]["id"] == load_test2_collection.id
 
@@ -341,13 +347,17 @@ async def test_all_collections_with_pagination(app_client, load_test_data):
         assert resp.status_code == 201
 
     resp = await app_client.get("/collections")
+    assert resp.json()["numberReturned"] == 10
+    assert resp.json()["numberMatched"] == 12
     cols = resp.json()["collections"]
     assert len(cols) == 10
     links = resp.json()["links"]
     assert len(links) == 3
     assert {"root", "self", "next"} == {link["rel"] for link in links}
 
     resp = await app_client.get("/collections", params={"limit": 12})
+    assert resp.json()["numberReturned"] == 12
+    assert resp.json()["numberMatched"] == 12
     cols = resp.json()["collections"]
     assert len(cols) == 12
     links = resp.json()["links"]
@@ -369,6 +379,8 @@ async def test_all_collections_without_pagination(app_client_no_ext, load_test_d
         assert resp.status_code == 201
 
     resp = await app_client_no_ext.get("/collections")
+    assert resp.json()["numberReturned"] == 12
+    assert "numberMatched" not in resp.json()
     cols = resp.json()["collections"]
     assert len(cols) == 12
     links = resp.json()["links"]
@@ -382,6 +394,8 @@ async def test_get_collections_search_pagination(
     app_client, load_test_collection, load_test2_collection
 ):
     resp = await app_client.get("/collections")
+    assert resp.json()["numberReturned"] == 2
+    assert resp.json()["numberMatched"] == 2
     cols = resp.json()["collections"]
     assert len(cols) == 2
     links = resp.json()["links"]