docs: address rustac quickstart review

- add an obstore cell listing the partition files
- show glob narrowing (part-*_2017-*.parquet) to skip partitions, ~3x faster
- call them partition files, not part files
- clarify the SAS-token sentence; expand the acronym
- note the search scans every partition with no index
- trim the closing recap

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aboydnw

quickstarts/rustac.ipynb

@@ -34,7 +34,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install --quiet 'rustac[arrow]' pystac-client planetary-computer geopandas pyarrow"
+    "%pip install --quiet 'rustac[arrow]' pystac-client planetary-computer geopandas pyarrow obstore"
    ]
   },
   {
@@ -43,7 +43,7 @@
    "source": [
     "## Find the GeoParquet snapshot",
     "",
-    "Every Planetary Computer collection carries a collection-level `geoparquet-items` asset that points at its STAC-items snapshot. The href resolves to a directory of monthly `part-NNNN` Parquet files on the `pcstacitems` storage account.",
+    "Every Planetary Computer collection carries a collection-level `geoparquet-items` asset that points at its STAC-items snapshot. The href resolves to a directory of monthly `part-NNNN` partition files on the `pcstacitems` storage account.",
     "",
     "**Expected result:** `abfs://items/sentinel-2-l2a.parquet`."
    ]
@@ -61,13 +61,47 @@
     "asset.href"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## List the partition files",
+    "",
+    "The snapshot is a set of monthly `part-NNNN` partition files. List them with [obstore](https://developmentseed.org/obstore/), which signs Planetary Computer blobs through its own credential provider. Each filename embeds the partition's date range, which the query section below uses to skip partitions.",
+    "",
+    "**Expected result:** about 136 partition files, the first covering July 2015."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider\n",
+    "from obstore.store import AzureStore\n",
+    "\n",
+    "store = AzureStore(\n",
+    "    credential_provider=PlanetaryComputerCredentialProvider(\n",
+    "        \"https://pcstacitems.blob.core.windows.net/items\"\n",
+    "    )\n",
+    ")\n",
+    "partitions = [\n",
+    "    meta[\"path\"]\n",
+    "    for stream in store.list(prefix=\"sentinel-2-l2a.parquet\")\n",
+    "    for meta in stream\n",
+    "    if \"/part-\" in meta[\"path\"]\n",
+    "]\n",
+    "len(partitions), partitions[0]"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Authenticate the DuckDB engine",
     "",
-    "The account name looks public, but reads still need a SAS token. The high-level `rustac.search()` coroutine cannot pass Azure credentials, so use `rustac.DuckdbClient` instead and configure its connection once: fetch a container SAS from the Planetary Computer token API, register an Azure secret, and switch the Azure transport to curl.",
+    "Reading from the account needs a Shared Access Signature (SAS) token. The high-level `rustac.search()` coroutine cannot pass Azure credentials, so use `rustac.DuckdbClient` instead and configure its connection once: fetch a container SAS from the Planetary Computer token API, register an Azure secret, and switch the Azure transport to curl.",
     "",
     "The `azure_transport_option_type = 'curl'` line is not optional. Without it, DuckDB's default Azure transport fails with an opaque SSL CA-certificate error. The SAS expires after about an hour, so long-running jobs re-fetch it.",
     "",
@@ -102,9 +136,9 @@
    "source": [
     "## Query the snapshot",
     "",
-    "Point `search()` at the snapshot glob and pass the filters you want pushed into the read, so only matching rows cross the network. The glob (`/*.parquet`) spans the monthly part files.",
+    "Point `search()` at the snapshot glob and pass the filters you want pushed into the read, so only matching rows cross the network. The glob (`/*.parquet`) spans the monthly partition files.",
     "",
-    "`DuckdbClient.search` is synchronous (no `await`); the bundled engine scans the part files for you, which takes a little time on the first call.",
+    "`DuckdbClient.search` is synchronous (no `await`); this is a search over every partition file (about 136), with no index, so expect it to take a minute or two on the first call.",
     "",
     "**Expected result:** a handful of Portland scenes (5)."
    ]
@@ -153,6 +187,32 @@
     "len(items)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Narrow the glob to skip partitions",
+    "",
+    "Because each partition filename embeds its date range (`part-NNNN_<start>_<end>.parquet`), you can point the glob at only the partitions a query needs instead of scanning every partition. For a 2017 query, match the 2017 partitions:",
+    "",
+    "**Expected result:** the same scenes as the full-glob search, but noticeably faster (the read touches only the 2017 partitions)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items = client.search(\n",
+    "    \"az://items/sentinel-2-l2a.parquet/part-*_2017-*.parquet\",\n",
+    "    collections=[\"sentinel-2-l2a\"],\n",
+    "    bbox=[-122.7, 45.5, -122.6, 45.6],\n",
+    "    datetime=\"2017-07-01/2017-08-01\",\n",
+    ")\n",
+    "len(items)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -235,7 +295,7 @@
    "source": [
     "## You're done",
     "",
-    "If every cell above ran, you pushed a spatial, temporal, and cloud-cover filter into a remote GeoParquet snapshot, read back only the matching Sentinel-2 scenes, wrote them to Parquet, and bridged them into GeoPandas: STAC-GeoParquet \u2192 filtered Arrow table \u2192 GeoDataFrame, with no full download.",
+    "If every cell above ran, you used a spatial, temporal, and cloud-cover filter to read matching Sentinel-2 scenes, wrote them to Parquet, and bridged them into GeoPandas: STAC-GeoParquet \u2192 filtered Arrow table \u2192 GeoDataFrame, with no full download.",
     "",
     "Swap in your own bbox, datetime window, or collection and the same pattern applies. For small or current-data queries, the live STAC API through `pystac-client` is the better tool. To ask analytical questions or join the catalog against other datasets, see the [DuckDB tutorial](../overview/duckdb.md), which uses the same authentication. For the imagery behind the metadata, hand a signed asset href to the [async-geotiff tutorial](../overview/async-geotiff.md)."
    ]