prompts

Author: cboettig

h3-guide.md

@@ -0,0 +1,36 @@
+# H3 Geospatial Indexing
+
+**Most of these data uses H3 hexagons** (https://h3geo.org) - uniform hexagonal grid covering Earth
+
+## Key Facts
+
+- Each h8 hexagon = **73.7327598 hectares** (≈ 0.737 km²)
+- Always report AREAS, not hex counts
+- **Use** `APPROX_COUNT_DISTINCT(h8)` when counting hexes to compute areas -- this avoids double-counting and is reasonably fast enough.
+
+## Area Conversion
+
+```sql
+SELECT APPROX_COUNT_DISTINCT(h8) * 0.737327598 as area_km2 FROM ...
+```
+
+## Joining Different Resolutions
+
+Some datasets use different H3 resolutions (h8 vs h0-h4). Use `h3_cell_to_parent()` to convert:
+
+```sql
+-- iNaturalist has h4, wetlands has h8 → convert h8 to h4
+JOIN read_parquet('s3://public-inat/range-maps/hex/**') pos 
+    ON h3_cell_to_parent(wetlands.h8, 4) = pos.h4 
+    AND wetlands.h0 = pos.h0  -- Always include h0 for partition pruning!
+```
+
+## Generating Output Files
+
+```sql
+COPY (SELECT ...) TO 's3://public-output/unique-file-name.csv' (FORMAT CSV, HEADER, OVERWRITE_OR_IGNORE);
+```
+
+Then tell the user the *public https* address (note the use of the public, not private endpoint): it should have the format like: `https://s3-west.nrp-nautilus.io/public-output/unique-file-name.csv` (adjust `unique-file-name.csv` part appropriately.)
+
+**Note:** s3://public-output has a 30-day expiration and 1 Gb object size limit. CORS headers will permit files to be placed here and rendered by other tools.

k8s/deployment.yaml

@@ -3,7 +3,7 @@ kind: Deployment
 metadata:
   name: duckdb-mcp
 spec:
-  replicas: 2
+  replicas: 1
   selector:
     matchLabels:
       app: duckdb-mcp
@@ -28,7 +28,7 @@ spec:
             apt-get update && apt-get install -y git && \
             git clone https://github.com/boettiger-lab/mcp-data-server.git /app && \
             cd /app && \
-            uv run --with "mcp" --with "duckdb" --with pandas --with uvicorn server.py
+            uv run --with "mcp" --with "duckdb" --with pandas --with uvicorn --with tabulate server.py
         resources:   
           requests:
             memory: 16Gi

query-optimization.md

@@ -0,0 +1,20 @@
+# Query Optimization Essentials
+
+## 1. Filter Small Tables First
+
+```sql
+-- Good: Filter country → then join to large dataset
+WITH filtered AS (
+  SELECT h8, h0 FROM read_parquet('s3://public-overturemaps/hex/countries.parquet')
+  WHERE country = 'US'
+)
+SELECT ... FROM filtered JOIN read_parquet('s3://public-wetlands/glwd/hex/**') w 
+ON filtered.h8 = w.h8 AND filtered.h0 = w.h0
+```
+
+## 2. ALWAYS Include h0 in Joins
+
+```sql
+-- Enables partition pruning → 5-20x faster
+JOIN table2 ON table1.h8 = table2.h8 AND table1.h0 = table2.h0
+```

server.py

@@ -97,8 +97,43 @@ def query(sql_query: str) -> str:
     except Exception as e:
         return f"SQL Error: {str(e)}"
 
+
+
+@mcp.prompt("geospatial-analyst")
+def analyst_persona() -> str:
+    """
+    Loads the expert persona, H3 math rules, and query optimization guides.
+    Use this at the start of every chat to ensure correct SQL generation.
+    """
+    optim = load_file("query-optimization.md")
+    h3_guide = load_file("h3-guide.md")
+    
+    return f"""
+
+    You are an expert **Geospatial Analyst** specializing in H3-indexed data.
+    
+    YOUR CORE RESPONSIBILITIES:
+    1. Analyze natural language questions about geospatial data.
+    2. Write highly optimized DuckDB SQL queries using the rules below.
+    3. Interpret results with a focus on spatial accuracy.
+    
+    ---
+    
+    {optim}
+    
+    ---
+    
+    {h3_guide}
+
+    ---
+    
+    REMINDER:
+    - Always check `catalog://list` first to see available datasets.
+    - Never assume column names; check the catalog schema.
+    """
+
 # -------------------------------------------------------------------------
-# 5. SERVER ENTRY POINT (Streamable HTTP)
+# 6. SERVER ENTRY POINT (Streamable HTTP)
 # -------------------------------------------------------------------------
 if __name__ == "__main__":
     # Streamable HTTP uses a single endpoint (default: /mcp)