Major improvements to parquet_cesium visualization

- Added loading states for async operations with visual feedback
- Improved error handling with loadData function using latest-only pattern
- Added explanatory text for Path 1 and Path 2 sample queries
- Fixed race conditions in data fetching with request tokens
- Added loading indicators for geo record and sample queries
- Improved user experience with clear loading/error states
- Added detailed documentation of query chains for both paths

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: rdhyee

tutorials/parquet_cesium.qmd

@@ -31,6 +31,11 @@ Cesium.Ion.defaultAccessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOi
 viewof parquet_path = Inputs.text({label:"Source", value:"https://storage.googleapis.com/opencontext-parquet/oc_isamples_pqg.parquet", width:"100%", submit:true});
 ```
 
+::: callout-warning
+#### Heads up: first interaction may be slow
+The first click or query can take a few seconds while the in‑browser database engine initializes and the remote Parquet file is fetched and indexed. Subsequent interactions are much faster because both the browser and DuckDB cache metadata and column chunks, so later queries reuse what was already loaded.
+:::
+
 ```{ojs}
 //| code-fold: true
 
@@ -42,24 +47,30 @@ db = {
 }
 
 
-async function loadData(query, params=[], waiting_id=null) {
+async function loadData(query, params = [], waiting_id = null, key = "default") {
+    // latest-only guard per key
+    loadData._latest = loadData._latest || new Map();
+    const requestToken = Symbol();
+    loadData._latest.set(key, requestToken);
+
     // Get loading indicator
-    const waiter = document.getElementById(waiting_id);
-    if (waiter) {
-        waiter.hidden = false;
-    }
+    const waiter = waiting_id ? document.getElementById(waiting_id) : null;
+    if (waiter) waiter.hidden = false;
+
     try {
         // Run the (slow) query
-        const _results = await db.query(query, ...params);
+        const _results = await db.query(query, params);
+        // Ignore stale responses
+        if (loadData._latest.get(key) !== requestToken) return null;
         return _results;
     } catch (error) {
-        if (waiter) {
-            waiter.innerHtml = `<pre>${error}</pre>`;
+        if (waiter && loadData._latest.get(key) === requestToken) {
+            waiter.innerHTML = `<pre>${error}</pre>`;
         }
         return null;
     } finally {
-        // Hide the waiter (if there is one)
-        if (waiter) {
+        // Hide the waiter (if there is one) only if latest
+        if (waiter && loadData._latest.get(key) === requestToken) {
             waiter.hidden = true;
         }
     }
@@ -68,7 +79,7 @@ async function loadData(query, params=[], waiting_id=null) {
 locations = {
     // get the content form the parquet file
     const query = `SELECT pid, latitude, longitude FROM nodes WHERE otype='GeospatialCoordLocation'`;
-    const data = await loadData(query, [], "loading_1");
+    const data = await loadData(query, [], "loading_1", "locations");
 
     // Clear the existing PointPrimitiveCollection
     content.points.removeAll();
@@ -189,8 +200,8 @@ async function getGeoRecord(pid) {
         return "unset";
     }
     const q = `SELECT row_id, pid, otype, latitude, longitude FROM nodes WHERE otype='GeospatialCoordLocation' AND pid=?`;
-    const result = await db.queryRow(q, [pid]);
-    return result;
+    const rows = await loadData(q, [pid], "loading_geo", "geo");
+    return rows && rows.length ? rows[0] : null;
 }
 
 async function get_samples_1(pid) {
@@ -215,8 +226,8 @@ async function get_samples_1(pid) {
           AND g.otype = 'GeospatialCoordLocation'
           AND g.pid = ?
     `;
-    const result = await db.query(q, [pid]);
-    return result;
+    const result = await loadData(q, [pid], "loading_s1", "samples_1");
+    return result ?? [];
 }
 
 async function get_samples_2(pid) {
@@ -245,8 +256,8 @@ async function get_samples_2(pid) {
           AND g.otype = 'GeospatialCoordLocation'
           AND g.pid = ?
     `;
-    const result = await db.query(q, [pid]);
-    return result; 
+    const result = await loadData(q, [pid], "loading_s2", "samples_2");
+    return result ?? []; 
 }
 
 async function locationUsedBy(rowid){
@@ -258,7 +269,38 @@ async function locationUsedBy(rowid){
 }
 
 mutable clickedPointId = "unset";
-selectedGeoRecord = await getGeoRecord(clickedPointId);
+// Loading flags to control UI clearing while fetching
+mutable geoLoading = false;
+mutable s1Loading = false;
+mutable s2Loading = false;
+
+// Precompute selection-driven data with loading flags
+selectedGeoRecord = {
+    mutable geoLoading = true;
+    try {
+        return await getGeoRecord(clickedPointId);
+    } finally {
+        mutable geoLoading = false;
+    }
+}
+
+selectedSamples1 = {
+    mutable s1Loading = true;
+    try {
+        return await get_samples_1(clickedPointId);
+    } finally {
+        mutable s1Loading = false;
+    }
+}
+
+selectedSamples2 = {
+    mutable s2Loading = true;
+    try {
+        return await get_samples_2(clickedPointId);
+    } finally {
+        mutable s2Loading = false;
+    }
+}
 
 md`Retrieved ${pointdata.length} locations from ${parquet_path}.`;
 ```
@@ -293,49 +335,22 @@ viewof pointdata = {
 
 The click point ID is "${clickedPointId}".
 
+<div id="loading_geo" hidden>Loading selected location…</div>
+
 ```{ojs}
 //| echo: false
-md`\`\`\`
+geoLoading ? md`(loading…)` : md`\`\`\`
 ${JSON.stringify(selectedGeoRecord, null, 2)}
 \`\`\`
 `
 ```
 
-## Sample Data
-
-First 10 rows of the dataset to understand the data structure:
-
-```{ojs}
-//| code-fold: true
-sampleData = {
-    const query = `SELECT * FROM nodes LIMIT 10`;
-    const data = await loadData(query, [], "loading_sample");
-    return data;
-}
-```
-
-<div id="loading_sample">Loading sample data...</div>
-
-```{ojs}
-//| code-fold: true
-viewof sampleTable = {
-    const data_table = Inputs.table(sampleData, {
-        layout: "auto",
-        width: {
-            pid: 200,
-            otype: 150
-        }
-    });
-    return data_table;
-}
-```
-
 ## getGeoRecord (selected)
 
 ```{ojs}
 //| code-fold: true
 pid = clickedPointId
-testrecord = await getGeoRecord(pid);
+testrecord = selectedGeoRecord;
 ```
 
 ```{ojs}
@@ -348,10 +363,17 @@ ${JSON.stringify(testrecord, null, 2)}
 
 ## Related Sample Path 1 (selected)
 
+<div id="loading_s1" hidden>Loading related samples (path 1)…</div>
+
+Path 1 (direct_event_location): find MaterialSampleRecord items whose producing SamplingEvent has a direct sample_location pointing to the clicked GeospatialCoordLocation (pid).
+
+- Chain: MaterialSampleRecord → produced_by → SamplingEvent → sample_location → GeospatialCoordLocation (clicked pid)
+- This matches the "direct_samples" concept in the Python notebook and is labeled as `location_path = 'direct_event_location'` in the query.
+
 ```{ojs}
 //| echo: false
-samples_1 = await get_samples_1(clickedPointId)
-md`\`\`\`
+samples_1 = selectedSamples1
+s1Loading ? md`(loading…)` : md`\`\`\`
 ${JSON.stringify(samples_1, null, 2)}
 \`\`\`
 `
@@ -360,10 +382,17 @@ ${JSON.stringify(samples_1, null, 2)}
 
 ## Related Sample Path 2 (selected)
 
+<div id="loading_s2" hidden>Loading related samples (path 2)…</div>
+
+Path 2 (via_site_location): find MaterialSampleRecord items whose producing SamplingEvent references a SamplingSite, and that site’s site_location points to the clicked GeospatialCoordLocation (pid).
+
+- Chain: MaterialSampleRecord → produced_by → SamplingEvent → sampling_site → SamplingSite → site_location → GeospatialCoordLocation (clicked pid)
+- This matches the "samples_via_sites" concept in the Python notebook and is labeled as `location_path = 'via_site_location'` in the query.
+
 ```{ojs}
 //| echo: false
-samples_2 = await get_samples_2(clickedPointId)
-md`\`\`\`
+samples_2 = selectedSamples2
+s2Loading ? md`(loading…)` : md`\`\`\`
 ${JSON.stringify(samples_2, null, 2)}
 \`\`\`
 `