From ec8642a9f65ae766fde3daae6537db7fa8c906cb Mon Sep 17 00:00:00 2001
From: Marty Pradere <martyp@labkey.com>
Date: Wed, 22 Jul 2026 09:59:14 -0700
Subject: [PATCH 1/6] Add site setting to configure server-side script
 execution timeout (#7862)

## Rationale

The Rhino sandbox terminates any server-side JavaScript (such as trigger
scripts) after a hard-coded 60 seconds of wall-clock time, which
includes database and other Java operations invoked by the script.
Long-running but legitimate operations, such as bulk imports that fire
per-row triggers, can exceed this budget with no recourse. This change
makes the timeout a configurable site setting so admins can raise it, or
disable it entirely, without a code change.

## Related Pull Requests

None.

## Changes

- New `scriptExecutionTimeout` site setting (default 60 seconds, 0
disables) exposed on the Site Settings admin page and as a
`SiteSettings.scriptExecutionTimeout` startup property.
- The Rhino sandbox resolves the timeout once per script execution
instead of using the hard-coded constant, so setting changes take effect
immediately for new script runs; the elapsed-time comparison is promoted
to `long` to avoid overflow with large values.
- The Site Settings form binds the new field as a nullable `Integer`, so
a POST that omits the parameter leaves the stored setting unchanged
rather than silently disabling the timeout.
- Added `RhinoService.TestCase.timeoutTest` (BVT) covering both a short
timeout aborting a runaway script and 0 disabling the watchdog.
---
 api/src/org/labkey/api/settings/AppProps.java |  5 ++
 .../org/labkey/api/settings/AppPropsImpl.java |  6 +++
 .../api/settings/SiteSettingsProperties.java  |  8 +++
 .../api/settings/WriteableAppProps.java       |  7 +++
 .../labkey/core/admin/AdminController.java    | 22 ++++++++
 .../org/labkey/core/admin/customizeSite.jsp   |  5 ++
 .../org/labkey/core/script/RhinoService.java  | 50 +++++++++++++++++--
 7 files changed, 100 insertions(+), 3 deletions(-)

diff --git a/api/src/org/labkey/api/settings/AppProps.java b/api/src/org/labkey/api/settings/AppProps.java
index 3ae76372530..27480cc7b45 100644
--- a/api/src/org/labkey/api/settings/AppProps.java
+++ b/api/src/org/labkey/api/settings/AppProps.java
@@ -173,6 +173,11 @@ static WriteableAppProps getWriteableInstance()
     /** Timeout in seconds for read-only HTTP requests, after which resources like DB connections and spawned processes will be killed. Set to 0 to disable. */
     int getReadOnlyHttpRequestTimeout();
 
+    int DEFAULT_SCRIPT_EXECUTION_TIMEOUT = 60;
+
+    /** Timeout in seconds for server-side JavaScript (e.g. trigger scripts), measured in wall-clock time including database and other Java operations invoked by the script. Set to 0 to disable. */
+    int getScriptExecutionTimeout();
+
     int getMaxBLOBSize();
 
     ExceptionReportingLevel getExceptionReportingLevel();
diff --git a/api/src/org/labkey/api/settings/AppPropsImpl.java b/api/src/org/labkey/api/settings/AppPropsImpl.java
index 60b22b957fe..ac90bf67310 100644
--- a/api/src/org/labkey/api/settings/AppPropsImpl.java
+++ b/api/src/org/labkey/api/settings/AppPropsImpl.java
@@ -321,6 +321,12 @@ public int getReadOnlyHttpRequestTimeout()
         return lookupIntValue(readOnlyHttpRequestTimeout, 0);
     }
 
+    @Override
+    public int getScriptExecutionTimeout()
+    {
+        return lookupIntValue(scriptExecutionTimeout, DEFAULT_SCRIPT_EXECUTION_TIMEOUT);
+    }
+
     @Override
     public int getMaxBLOBSize()
     {
diff --git a/api/src/org/labkey/api/settings/SiteSettingsProperties.java b/api/src/org/labkey/api/settings/SiteSettingsProperties.java
index 961ecb54868..8cbc673f4aa 100644
--- a/api/src/org/labkey/api/settings/SiteSettingsProperties.java
+++ b/api/src/org/labkey/api/settings/SiteSettingsProperties.java
@@ -90,6 +90,14 @@ public void setValue(WriteableAppProps writeable, String value)
             writeable.setReadOnlyHttpRequestTimeout(Integer.parseInt(value));
         }
     },
+    scriptExecutionTimeout("Timeout in seconds for server-side JavaScript such as trigger scripts. Measured in wall-clock time, including database and other Java operations invoked by the script. Set to 0 to disable.")
+    {
+        @Override
+        public void setValue(WriteableAppProps writeable, String value)
+        {
+            writeable.setScriptExecutionTimeout(Integer.parseInt(value));
+        }
+    },
     maxBLOBSize("Maximum file size, in bytes, to allow in database BLOBs")
     {
         @Override
diff --git a/api/src/org/labkey/api/settings/WriteableAppProps.java b/api/src/org/labkey/api/settings/WriteableAppProps.java
index e3691f745b0..92df26b757b 100644
--- a/api/src/org/labkey/api/settings/WriteableAppProps.java
+++ b/api/src/org/labkey/api/settings/WriteableAppProps.java
@@ -94,6 +94,13 @@ public void setReadOnlyHttpRequestTimeout(int timeout)
         storeIntValue(readOnlyHttpRequestTimeout, timeout);
     }
 
+    public void setScriptExecutionTimeout(int timeout)
+    {
+        if (timeout < 0)
+            throw new IllegalArgumentException("scriptExecutionTimeout must be >= 0");
+        storeIntValue(scriptExecutionTimeout, timeout);
+    }
+
     public void setMaxBLOBSize(int maxSize)
     {
         if (maxSize < 0)
diff --git a/core/src/org/labkey/core/admin/AdminController.java b/core/src/org/labkey/core/admin/AdminController.java
index 64d0cdcc26e..97175dc35ba 100644
--- a/core/src/org/labkey/core/admin/AdminController.java
+++ b/core/src/org/labkey/core/admin/AdminController.java
@@ -1381,6 +1381,14 @@ public void validateCommand(SiteSettingsForm form, Errors errors)
             {
                 errors.reject(ERROR_MSG, "Memory logging frequency must be non-negative");
             }
+            if (form.getScriptExecutionTimeout() == null)
+            {
+                errors.reject(ERROR_MSG, "Script execution timeout is required; set to 0 to disable the timeout");
+            }
+            else if (form.getScriptExecutionTimeout() < 0)
+            {
+                errors.reject(ERROR_MSG, "Script execution timeout must be non-negative");
+            }
         }
 
         @Override
@@ -1415,6 +1423,7 @@ public boolean handlePost(SiteSettingsForm form, BindException errors) throws Ex
             props.setSSLPort(form.getSslPort());
             props.setMemoryUsageDumpInterval(form.getMemoryUsageDumpInterval());
             props.setReadOnlyHttpRequestTimeout(form.getReadOnlyHttpRequestTimeout());
+            props.setScriptExecutionTimeout(form.getScriptExecutionTimeout());
             props.setMaxBLOBSize(form.getMaxBLOBSize());
             props.setSelfReportExceptions(form.isSelfReportExceptions());
 
@@ -2384,6 +2393,7 @@ public static class SiteSettingsForm
         private int _sslPort;
         private int _memoryUsageDumpInterval;
         private int _readOnlyHttpRequestTimeout;
+        private Integer _scriptExecutionTimeout;
         private int _maxBLOBSize;
         private String _exceptionReportingLevel;
         private String _usageReportingLevel;
@@ -2524,6 +2534,18 @@ public int getReadOnlyHttpRequestTimeout()
             return _readOnlyHttpRequestTimeout;
         }
 
+        /** Null when the request omits or blanks the parameter; rejected in validateCommand so an omitted value can never bind to 0 and silently disable the timeout. */
+        @Nullable
+        public Integer getScriptExecutionTimeout()
+        {
+            return _scriptExecutionTimeout;
+        }
+
+        public void setScriptExecutionTimeout(@Nullable Integer timeout)
+        {
+            _scriptExecutionTimeout = timeout;
+        }
+
         public void setReadOnlyHttpRequestTimeout(int timeout)
         {
             _readOnlyHttpRequestTimeout = timeout;
diff --git a/core/src/org/labkey/core/admin/customizeSite.jsp b/core/src/org/labkey/core/admin/customizeSite.jsp
index 8bc659eb5ac..1de822de1e6 100644
--- a/core/src/org/labkey/core/admin/customizeSite.jsp
+++ b/core/src/org/labkey/core/admin/customizeSite.jsp
@@ -312,6 +312,11 @@ Click the Save button at any time to accept the current settings and continue.</
         "After the timeout, resources like database connections and spawned processes will be killed to abort processing the request. Set to 0 to disable the timeout.")%></label></td>
     <td><input type="text" name="<%=readOnlyHttpRequestTimeout%>" id="<%=readOnlyHttpRequestTimeout%>" size="4" value="<%=appProps.getReadOnlyHttpRequestTimeout()%>"></td>
 </tr>
+<tr>
+    <td class="labkey-form-label"><label for="<%=scriptExecutionTimeout%>">Timeout for server-side scripts, in seconds<%=helpPopup("Script execution timeout",
+        "Maximum time a server-side JavaScript invocation (such as a trigger script) may run before it is terminated. Measured in wall-clock time, including database and other Java operations invoked by the script. Set to 0 to disable the timeout.")%></label></td>
+    <td><input type="text" name="<%=scriptExecutionTimeout%>" id="<%=scriptExecutionTimeout%>" size="4" value="<%=appProps.getScriptExecutionTimeout()%>"></td>
+</tr>
 <tr>
     <td class="labkey-form-label"><label for="<%=maxBLOBSize%>">Maximum file size, in bytes, to allow in database BLOBs</label></td>
     <td><input type="text" name="<%=maxBLOBSize%>" id="<%=maxBLOBSize%>" size="10" value="<%=appProps.getMaxBLOBSize()%>"></td>
diff --git a/core/src/org/labkey/core/script/RhinoService.java b/core/src/org/labkey/core/script/RhinoService.java
index 497a6d99b1b..71d41196269 100644
--- a/core/src/org/labkey/core/script/RhinoService.java
+++ b/core/src/org/labkey/core/script/RhinoService.java
@@ -40,11 +40,15 @@
 import org.labkey.api.resource.Resource;
 import org.labkey.api.script.ScriptReference;
 import org.labkey.api.script.ScriptService;
+import org.labkey.api.security.User;
+import org.labkey.api.settings.AppProps;
+import org.labkey.api.settings.WriteableAppProps;
 import org.labkey.api.test.TestWhen;
 import org.labkey.api.util.HeartBeat;
 import org.labkey.api.util.JunitUtil;
 import org.labkey.api.util.MemTracker;
 import org.labkey.api.util.Path;
+import org.labkey.api.util.TestContext;
 import org.labkey.api.util.UnexpectedException;
 import org.labkey.api.view.HttpView;
 import org.mozilla.javascript.ClassShutter;
@@ -199,6 +203,44 @@ public void reportTest() throws Exception
             test("reportTest");
         }
 
+        @Test
+        public void timeoutTest() throws Exception
+        {
+            int original = AppProps.getInstance().getScriptExecutionTimeout();
+            User user = TestContext.get().getUser();
+
+            try
+            {
+                // Busy-loop bounded at 15 seconds of wall-clock time; the 1-second watchdog should abort it long before that. HeartBeat ticks once per second, so the abort lands after 2-3 real seconds.
+                setScriptExecutionTimeout(1, user);
+                try
+                {
+                    RhinoService.RHINO_FACTORY.getScriptEngine().eval("var start = new Date().getTime(); while (new Date().getTime() - start < 15000) {}");
+                    fail("Expected script to be terminated by the execution timeout");
+                }
+                catch (Exception e)
+                {
+                    assertTrue("Unexpected script error: " + e.getMessage(), e.getMessage().contains("Script execution exceeded 1 seconds"));
+                }
+
+                // 0 disables the watchdog: a loop that runs well past the 1-second timeout above should complete normally
+                setScriptExecutionTimeout(0, user);
+                Object result = RhinoService.RHINO_FACTORY.getScriptEngine().eval("var start = new Date().getTime(); while (new Date().getTime() - start < 2500) {} 'completed';");
+                assertEquals("completed", result);
+            }
+            finally
+            {
+                setScriptExecutionTimeout(original, user);
+            }
+        }
+
+        private void setScriptExecutionTimeout(int seconds, User user)
+        {
+            WriteableAppProps props = AppProps.getWriteableInstance();
+            props.setScriptExecutionTimeout(seconds);
+            props.save(user);
+        }
+
         private void test(String scriptName) throws ScriptException, NoSuchMethodException
         {
             Path js = Path.parse(ScriptService.SCRIPTS_DIR + "/validationTest/" + scriptName + ".js");
@@ -1006,9 +1048,8 @@ protected void observeInstructionCount(Context cx, int instructionCount)
     {
         SandboxContext ctx = (SandboxContext)cx;
         long currentTime = HeartBeat.currentTimeMillis();
-        final int timeout = 60;
-        if (currentTime - ctx.startTime > timeout*1000)
-            Context.reportError("Script execution exceeded " + timeout + " seconds.");
+        if (ctx.timeoutSeconds > 0 && currentTime - ctx.startTime > ctx.timeoutSeconds * 1000L)
+            Context.reportError("Script execution exceeded " + ctx.timeoutSeconds + " seconds.");
     }
 
     @Override
@@ -1044,12 +1085,15 @@ public boolean visibleToScripts(String fullClassName)
     private static class SandboxContext extends Context
     {
         private final long startTime;
+        // resolved once per context; observeInstructionCount runs far too often for a property lookup
+        private final int timeoutSeconds;
 
         private SandboxContext(SandboxContextFactory factory)
         {
             super(factory);
             setLanguageVersion(Context.VERSION_1_8);
             startTime = HeartBeat.currentTimeMillis();
+            timeoutSeconds = AppProps.getInstance().getScriptExecutionTimeout();
         }
     }
 

From d9c1fbc16c7c2fd4d13a33a79efa78d837dbc7ff Mon Sep 17 00:00:00 2001
From: Trey Chadick <tchad@labkey.com>
Date: Wed, 22 Jul 2026 13:32:57 -0700
Subject: [PATCH 2/6] Fix provider parameter in addUsers.jsp (#7872)

https://github.com/LabKey/internal-issues/issues/1328
---
 core/src/org/labkey/core/security/addUsers.jsp | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/core/src/org/labkey/core/security/addUsers.jsp b/core/src/org/labkey/core/security/addUsers.jsp
index 80dcd6df68f..25741c0362f 100644
--- a/core/src/org/labkey/core/security/addUsers.jsp
+++ b/core/src/org/labkey/core/security/addUsers.jsp
@@ -40,11 +40,6 @@
     boolean excludeSiteAdmins = !getUser().hasSiteAdminPermission(); // App admins can't clone permissions from site admins
 %>
 <script type="text/javascript" nonce="<%=getScriptNonce()%>">
-    document.addEventListener("DOMContentLoaded", function() {
-        if (LABKEY.ActionURL.getParameter('provider')) {
-            document.getElementById('provider').value = LABKEY.ActionURL.getParameter('provider');
-        }
-    });
 
     function enableText()
     {
@@ -139,7 +134,7 @@
     <%
         if (form.getProvider() != null)
         {
-            %><input type="hidden" name="provider" id="provider" value=<%=h(form.getProvider())%>><%
+            %><input type="hidden" name="provider" id="provider" value="<%=h(form.getProvider())%>"><%
         }
         else
         {

From 0361a9f83b53dcd62ee955191ceb2dc3c06febf0 Mon Sep 17 00:00:00 2001
From: labkey-matthewb <matthewb@labkey.com>
Date: Thu, 23 Jul 2026 15:57:29 -0700
Subject: [PATCH 3/6] use appendInClauseSql() (#7878)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Rationale
This code is cleaner and avoids false positive sql check.

## Related Pull Requests
- <!-- list of links to related pull requests (replace this comment) -->

## Changes
- <!-- list of descriptions of changes that are worth noting (replace
this comment) -->

<!-- list of standard tasks (remove this comment to enable)
## Tasks 📍
- [ ] Claude Code Review
- [ ] Manual Testing
- [ ] Test Automation
- [ ] Verify Fix
-->
---
 .../labkey/study/model/DatasetDefinition.java | 26 ++++++-------------
 1 file changed, 8 insertions(+), 18 deletions(-)

diff --git a/study/src/org/labkey/study/model/DatasetDefinition.java b/study/src/org/labkey/study/model/DatasetDefinition.java
index dc32f4b8a07..fd9c1cebc1a 100644
--- a/study/src/org/labkey/study/model/DatasetDefinition.java
+++ b/study/src/org/labkey/study/model/DatasetDefinition.java
@@ -2495,7 +2495,7 @@ private HashMap<String, Object[]> checkAndDeleteDupes(DataIterator rows,
             // duplicate keys found in error
             final LinkedHashMap<String,Object[]> noDeleteMap = new LinkedHashMap<>();
 
-            StringBuilder sbIn = new StringBuilder();
+            ArrayList<String> idList = new ArrayList<>();
             final Map<String, Object[]> uriMap = new HashMap<>();
             int count = 0;
             while (rows.next())
@@ -2527,12 +2527,9 @@ private HashMap<String, Object[]> checkAndDeleteDupes(DataIterator rows,
                     noDeleteMap.put(uniq,key);
 
                 // partial fix for 16647, we should handle the replace case differently (do we ever replace?)
-                String sep = "";
                 if (uriMap.size() < 10000 || Boolean.TRUE==replace)
                 {
-                    if (uniq.contains(("'")))
-                        uniq = uniq.replaceAll("'","''");
-                    sbIn.append(sep).append("'").append(uniq).append("'");
+                    idList.add(uniq);
                 }
                 count++;
             }
@@ -2549,7 +2546,7 @@ private HashMap<String, Object[]> checkAndDeleteDupes(DataIterator rows,
                     return null;
             }
             else // also check target dataset
-                return checkTargetDupesAndDelete(isDemographic, noDeleteMap, sbIn, uriMap);
+                return checkTargetDupesAndDelete(isDemographic, noDeleteMap, idList, uriMap);
         }
         catch (BatchValidationException vex)
         {
@@ -2569,14 +2566,15 @@ private HashMap<String, Object[]> checkAndDeleteDupes(DataIterator rows,
         }
     }
 
-    private HashMap<String, Object[]> checkTargetDupesAndDelete(final boolean demographic, final LinkedHashMap<String, Object[]> noDeleteMap, StringBuilder sbIn, final Map<String, Object[]> uriMap)
+    private HashMap<String, Object[]> checkTargetDupesAndDelete(final boolean demographic, final LinkedHashMap<String, Object[]> noDeleteMap, ArrayList<String> idList, final Map<String, Object[]> uriMap)
     {
         // duplicate keys found that should be deleted
         final Set<String> deleteSet = new HashSet<>();
 
         TableInfo tinfo = getStorageTableInfo(false);
         SimpleFilter filter = new SimpleFilter();
-        filter.addWhereClause((demographic ?"ParticipantId":"LSID") + " IN (" + sbIn + ")", new Object[]{});
+        SQLFragment checkInClause = tinfo.getSqlDialect().appendInClauseSql(new SQLFragment(demographic ?"ParticipantId":"LSID"), idList);
+        filter.addWhereClause(checkInClause);
         if (isShared())
         {
             Container rowsContainer = getContainer();
@@ -2610,16 +2608,8 @@ private HashMap<String, Object[]> checkTargetDupesAndDelete(final boolean demogr
             return null;
 
         SimpleFilter deleteFilter = new SimpleFilter();
-        StringBuilder sbDelete = new StringBuilder();
-        String sep = "";
-        for (String s : deleteSet)
-        {
-            if (s.contains(("'")))
-                s = s.replaceAll("'","''");
-            sbDelete.append(sep).append("'").append(s).append("'");
-            sep = ", ";
-        }
-        deleteFilter.addWhereClause("LSID IN (" + sbDelete + ")", new Object[]{});
+        SQLFragment deleteInClause = tinfo.getSqlDialect().appendInClauseSql(new SQLFragment("LSID"), deleteSet);
+        deleteFilter.addWhereClause(deleteInClause);
         Table.delete(tinfo, deleteFilter);
 
         return null;

From c67aa08454596cfbf4d0ad92d6f3f734f375c810 Mon Sep 17 00:00:00 2001
From: Josh Eckels <jeckels@labkey.com>
Date: Sun, 26 Jul 2026 17:11:49 -0700
Subject: [PATCH 4/6] GitHub Issue 1332: Reduce per-row logging (#7877)

## Rationale
A misconfigured query produced ~2 million messages in 30 minutes because
it logged once per row per query execution.

## Changes
- Throttle the complaints when we have a format string that can't be
applied to the value given
- Tame similar areas that do per-row logging about config/value problems
---
 api/src/org/labkey/api/ApiModule.java         |  2 +
 api/src/org/labkey/api/cache/Throttle.java    | 20 +++++
 .../org/labkey/api/data/DisplayColumn.java    | 77 ++++++++++++++++++-
 .../api/dataiterator/SimpleTranslator.java    | 11 ++-
 .../study/query/PublishResultsQueryView.java  | 10 ++-
 .../labkey/assay/query/TypeDisplayColumn.java |  9 ++-
 .../org/labkey/issue/query/IssuesTable.java   | 19 +++--
 .../query/controllers/QueryController.java    |  6 +-
 8 files changed, 137 insertions(+), 17 deletions(-)

diff --git a/api/src/org/labkey/api/ApiModule.java b/api/src/org/labkey/api/ApiModule.java
index 1a0ebb21c07..407bae5d230 100644
--- a/api/src/org/labkey/api/ApiModule.java
+++ b/api/src/org/labkey/api/ApiModule.java
@@ -57,6 +57,7 @@
 import org.labkey.api.data.DbSchema;
 import org.labkey.api.data.DbScope;
 import org.labkey.api.data.DbSequenceManager;
+import org.labkey.api.data.DisplayColumn;
 import org.labkey.api.data.ExcelColumn;
 import org.labkey.api.data.ExcelWriter;
 import org.labkey.api.data.InlineInClauseGenerator;
@@ -522,6 +523,7 @@ public void registerServlets(ServletContext servletCtx)
             DbScope.SchemaNameTestCase.class,
             DbScope.TransactionTestCase.class,
             DbSequenceManager.TestCase.class,
+                DisplayColumn.TestCase.class,
             DomTestCase.class,
             DomainTemplateGroup.TestCase.class,
             Encryption.TestCase.class,
diff --git a/api/src/org/labkey/api/cache/Throttle.java b/api/src/org/labkey/api/cache/Throttle.java
index 585af71ee66..8c26b4d8c43 100644
--- a/api/src/org/labkey/api/cache/Throttle.java
+++ b/api/src/org/labkey/api/cache/Throttle.java
@@ -15,6 +15,7 @@
  */
 package org.labkey.api.cache;
 
+import java.util.concurrent.atomic.AtomicLong;
 import java.util.function.Consumer;
 
 /**
@@ -36,15 +37,21 @@
  *        THROTTLE.execute(user);
  * }
  * </pre>
+ *
+ * <p>Tracks how many times the consumer actually ran ({@link #getExecutionCount()}) versus was throttled
+ * ({@link #getThrottledCount()}), useful for metrics and for tests asserting the throttling behavior.</p>
  */
 public class Throttle<K>
 {
     private final BlockingCache<K, K> _cache;
+    private final AtomicLong _executionCount = new AtomicLong();
+    private final AtomicLong _requestCount = new AtomicLong();
 
     public Throttle(String name, int limit, long timeToLive, Consumer<K> consumer)
     {
         _cache = CacheManager.getBlockingCache(limit, timeToLive, "Throttle for " + name, (key, argument) ->
         {
+            _executionCount.incrementAndGet();
             consumer.accept(key);
             return key;
         });
@@ -52,6 +59,19 @@ public Throttle(String name, int limit, long timeToLive, Consumer<K> consumer)
 
     public void execute(K key)
     {
+        _requestCount.incrementAndGet();
         _cache.get(key);
     }
+
+    /** @return the number of times the consumer actually ran (i.e., calls that were not throttled) */
+    public long getExecutionCount()
+    {
+        return _executionCount.get();
+    }
+
+    /** @return the number of {@link #execute} calls that were throttled (the consumer did not run) */
+    public long getThrottledCount()
+    {
+        return _requestCount.get() - _executionCount.get();
+    }
 }
diff --git a/api/src/org/labkey/api/data/DisplayColumn.java b/api/src/org/labkey/api/data/DisplayColumn.java
index 659a1b69dda..c46fbd12b20 100644
--- a/api/src/org/labkey/api/data/DisplayColumn.java
+++ b/api/src/org/labkey/api/data/DisplayColumn.java
@@ -24,7 +24,11 @@
 import org.apache.poi.ss.usermodel.Workbook;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.junit.Assert;
+import org.junit.Test;
 import org.labkey.api.action.HasViewContext;
+import org.labkey.api.cache.CacheManager;
+import org.labkey.api.cache.Throttle;
 import org.labkey.api.collections.NullPreventingSet;
 import org.labkey.api.compliance.PhiTransformedColumnInfo;
 import org.labkey.api.ontology.Concept;
@@ -64,6 +68,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
 
 import static org.apache.commons.lang3.StringUtils.isBlank;
 import static org.apache.commons.lang3.StringUtils.trimToEmpty;
@@ -112,6 +117,10 @@ public abstract class DisplayColumn extends RenderColumn
     private String _description = null;
     private String _displayClass;
 
+    // GH Issue 1332: Throttle to one warning per column + value type per hour, across all renders.
+    private static final Throttle<String> FORMAT_MISMATCH_THROTTLE = new Throttle<>("DisplayColumn format mismatch", 1000, CacheManager.HOUR, key ->
+            LOG.warn("Unable to apply format to {}, likely a SQL type mismatch between XML metadata and actual ResultSet", key));
+
     private final List<ColumnAnalyticsProvider> _analyticsProviders = new ArrayList<>();
 
     /** Handles spanning multiple rows in a grid. A separate interface to allow for easier mixing and matching with DisplayColumn implementations. */
@@ -488,7 +497,7 @@ public String getFormattedText(RenderContext ctx)
             }
             catch (IllegalArgumentException e)
             {
-                LOG.warn("Unable to apply format to {} value \"{}\" for column \"{}\", likely a SQL type mismatch between XML metadata and actual ResultSet", value.getClass().getName(), value, getName());
+                warnFormatMismatch(value);
                 return value.toString();
             }
         }
@@ -497,6 +506,13 @@ public String getFormattedText(RenderContext ctx)
     }
 
 
+    private void warnFormatMismatch(Object value)
+    {
+        ColumnInfo col = getColumnInfo();
+        String key = "column \"" + (col != null ? col.getFieldKey() : getName()) + "\" (value type " + value.getClass().getName() + ")";
+        FORMAT_MISMATCH_THROTTLE.execute(key);
+    }
+
     /**
      * Render the value as text using the <code>expr</code> or <code>format</code> if provided without
      * any html encoding.
@@ -540,7 +556,7 @@ else if (null != format)
             }
             catch (IllegalArgumentException e)
             {
-                LOG.warn("Unable to apply format to {} value \"{}\" for column \"{}\", likely a SQL type mismatch between XML metadata and actual ResultSet", value.getClass().getName(), value, getName());
+                warnFormatMismatch(value);
                 formattedString = ConvertUtils.convert(value);
             }
         }
@@ -1344,4 +1360,61 @@ else if (null == formatString && col.isNumericType())
             }
         }
     }
+
+    // GH Issue 1332: a type-mismatched column logs in format() on every cell; verify we warn once per column, not once per row
+    public static class TestCase extends Assert
+    {
+        // Unique per column so each test gets its own throttle key
+        private static final AtomicInteger UNIQUE = new AtomicInteger();
+        public static final String NOT_A_NUMBER_VALUE = "not-a-number";
+
+        // A column whose configured format rejects the value type, mimicking XML metadata that disagrees with the ResultSet.
+        private DisplayColumn columnThatFailsFormatting()
+        {
+            String name = "formatMismatchTestColumn-" + UNIQUE.incrementAndGet();
+            Format numberFormat = new DecimalFormat("0.00"); // format() throws IllegalArgumentException on a non-Number
+            return new SimpleDisplayColumn()
+            {
+                @Override
+                public Object getValue(RenderContext ctx)
+                {
+                    return NOT_A_NUMBER_VALUE;
+                }
+
+                @Override
+                public Format getFormat()
+                {
+                    return numberFormat;
+                }
+
+                @Override
+                public String getName()
+                {
+                    return name;
+                }
+            };
+        }
+
+        @Test
+        public void getFormattedTextWarnsOncePerColumn()
+        {
+            RenderContext ctx = new RenderContext(new ViewContext());
+            DisplayColumn dc = columnThatFailsFormatting();
+            long before = FORMAT_MISMATCH_THROTTLE.getExecutionCount();
+            for (int row = 0; row < 1000; row++)
+                assertEquals("Fallback must be the unformatted value", NOT_A_NUMBER_VALUE, dc.getFormattedText(ctx));
+            assertEquals("A format mismatch must warn once per column, not once per row", 1, FORMAT_MISMATCH_THROTTLE.getExecutionCount() - before);
+        }
+
+        @Test
+        public void formatValueWarnsOncePerColumn()
+        {
+            RenderContext ctx = new RenderContext(new ViewContext());
+            DisplayColumn dc = columnThatFailsFormatting();
+            long before = FORMAT_MISMATCH_THROTTLE.getExecutionCount();
+            for (int row = 0; row < 1000; row++)
+                assertEquals("Fallback must be the converted value", NOT_A_NUMBER_VALUE, dc.formatValue(ctx, NOT_A_NUMBER_VALUE, null, dc.getFormat(), null));
+            assertEquals("A format mismatch must warn once per column, not once per row", 1, FORMAT_MISMATCH_THROTTLE.getExecutionCount() - before);
+        }
+    }
 }
diff --git a/api/src/org/labkey/api/dataiterator/SimpleTranslator.java b/api/src/org/labkey/api/dataiterator/SimpleTranslator.java
index 3dcad2bc631..3d3fe1528bf 100644
--- a/api/src/org/labkey/api/dataiterator/SimpleTranslator.java
+++ b/api/src/org/labkey/api/dataiterator/SimpleTranslator.java
@@ -692,6 +692,10 @@ public class ContainerColumn implements Supplier
 
         final Set<Object> allowableContainers = new HashSet<>();
 
+        // GH Issue 1332: a bad container value recurs on every row; warn once per distinct value, not per row
+        final Set<Object> loggedUnresolvedContainers = new HashSet<>();
+        final Set<Object> loggedRejectedContainers = new HashSet<>();
+
         public ContainerColumn(UserSchema us, TableInfo tableInfo, String containerId, int idx)
         {
             this.us = us;
@@ -723,7 +727,8 @@ public Object get()
                     if (!this.us.getContainer().allowRowMutationForContainer(rowContainer))
                     {
                         getRowError().addError(new SimpleValidationError("Row supplied container value: " + rowContainerVal + " cannot be used for actions against the container: " + us.getContainer().getPath()));
-                        LOG.warn("Resolved container to {} but rejected as valid location for import into {} in {}.{}", rowContainer.getPath(), us.getContainer().getPath(), us.getSchemaName(), tableInfo.getPublicSchemaName());
+                        if (loggedRejectedContainers.add(rowContainerVal))
+                            LOG.warn("Resolved container to {} but rejected as valid location for import into {} in {}.{}", rowContainer.getPath(), us.getContainer().getPath(), us.getSchemaName(), tableInfo.getPublicSchemaName());
                     }
                     else
                     {
@@ -734,8 +739,8 @@ public Object get()
                 }
                 else
                 {
-                    // only log if the incoming value is GUID-like
-                    if (rowContainerVal instanceof String && GUID.isGUID((String)rowContainerVal))
+                    // only log if the incoming value is GUID-like, and only once per distinct value
+                    if (rowContainerVal instanceof String s && GUID.isGUID(s) && loggedUnresolvedContainers.add(rowContainerVal))
                     {
                         LOG.warn("Failed to resolve container value '{}' to container for import into {}.{}, defaulting to original target container of {}", rowContainerVal, us.getSchemaName(), tableInfo.getPublicSchemaName(), us.getContainer().getPath());
                     }
diff --git a/api/src/org/labkey/api/study/query/PublishResultsQueryView.java b/api/src/org/labkey/api/study/query/PublishResultsQueryView.java
index b59a2109d52..bf005ad6d8f 100644
--- a/api/src/org/labkey/api/study/query/PublishResultsQueryView.java
+++ b/api/src/org/labkey/api/study/query/PublishResultsQueryView.java
@@ -94,22 +94,26 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-import static org.labkey.api.util.IntegerUtils.asInteger;
-import static org.labkey.api.util.IntegerUtils.asLong;
 import static org.labkey.api.study.publish.StudyPublishService.LinkToStudyKeys;
 import static org.labkey.api.util.DOM.Attribute.id;
 import static org.labkey.api.util.DOM.DIV;
 import static org.labkey.api.util.DOM.SCRIPT;
 import static org.labkey.api.util.DOM.at;
+import static org.labkey.api.util.IntegerUtils.asInteger;
+import static org.labkey.api.util.IntegerUtils.asLong;
 import static org.labkey.api.util.IntegerUtils.asLongElseNull;
 
 public class PublishResultsQueryView extends QueryView
 {
     private static final Logger LOG = LogManager.getLogger(PublishResultsQueryView.class);
 
+    // GH Issue 1332: Only warn once per distinct column
+    private static final Set<String> LOGGED_MULTIVALUE_COLUMNS = ConcurrentHashMap.newKeySet();
+
     private final SimpleFilter _filter;
     private final Container _targetStudyContainer;
     private final boolean _mismatched;
@@ -303,7 +307,7 @@ public static Object getColumnValue(ColumnInfo col, RenderContext ctx)
             List<Object> values = ((IMultiValuedDisplayColumn)dc).getDisplayValues(ctx);
             if (values.size() == 1)
                 return values.getFirst();
-            else
+            else if (LOGGED_MULTIVALUE_COLUMNS.add(col.getFieldKey().toString()))
                 LOG.warn("Unable to use the value returned from column : {} because this multi-value column returned more than a single value.", col.getName());
         }
         return col.getValue(ctx);
diff --git a/assay/src/org/labkey/assay/query/TypeDisplayColumn.java b/assay/src/org/labkey/assay/query/TypeDisplayColumn.java
index e62b1816151..dff03ba31e0 100644
--- a/assay/src/org/labkey/assay/query/TypeDisplayColumn.java
+++ b/assay/src/org/labkey/assay/query/TypeDisplayColumn.java
@@ -42,6 +42,9 @@ public class TypeDisplayColumn extends DataColumn
 
     private static final FieldKey LSID_FIELD_KEY = new FieldKey(null, "LSID");
 
+    // GH Issue 1332: a broken provider pattern misses on every row; warn once per instance, not once per cell
+    private boolean _loggedProviderMismatch = false;
+
     public TypeDisplayColumn(ColumnInfo colInfo)
     {
         super(colInfo);
@@ -74,7 +77,11 @@ public void renderGridCellContents(RenderContext ctx, HtmlWriter out)
                 AssayProvider provider = AssayService.get().getProvider(protocol);
                 if (provider != null)
                 {
-                    LOG.warn("Failed to match AssayProvider '{}' using pattern '{}' for LSID: {}", provider.getName(), provider.getProtocolPattern(), lsid);
+                    if (!_loggedProviderMismatch)
+                    {
+                        _loggedProviderMismatch = true;
+                        LOG.warn("Failed to match AssayProvider '{}' using pattern '{}' for LSID: {}", provider.getName(), provider.getProtocolPattern(), lsid);
+                    }
                     out.write(provider.getName());
                     return;
                 }
diff --git a/issues/src/org/labkey/issue/query/IssuesTable.java b/issues/src/org/labkey/issue/query/IssuesTable.java
index c5fcb38f569..2da3fe5323b 100644
--- a/issues/src/org/labkey/issue/query/IssuesTable.java
+++ b/issues/src/org/labkey/issue/query/IssuesTable.java
@@ -114,6 +114,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
@@ -906,6 +907,9 @@ class PullRequestsDisplayColumn extends DataColumn
 {
     private static final Pattern GITHUB_HTTP_PR_URL = Pattern.compile("https://github.com/(?<org>[^/]*)/(?<project>[^/]*)/pull/(?<pullId>\\d*)");
 
+    // GH Issue 1332: parseGithubUrl is a per-cell static call; warn once per distinct unparseable url, not once per row
+    private static final Set<String> LOGGED_BAD_PR_URLS = ConcurrentHashMap.newKeySet();
+
     public PullRequestsDisplayColumn(ColumnInfo col)
     {
         super(col);
@@ -976,13 +980,16 @@ public void renderGridCellContents(RenderContext ctx, HtmlWriter out)
             }
             catch (NumberFormatException e)
             {
-                // The issueId value can be null if it the column isn't included in the select for a custom query
-                @Nullable Integer issueId = ctx.get(FieldKey.fromParts("IssueId"), Integer.class);
+                if (LOGGED_BAD_PR_URLS.add(url))
+                {
+                    // The issueId value can be null if it the column isn't included in the select for a custom query
+                    @Nullable Integer issueId = ctx.get(FieldKey.fromParts("IssueId"), Integer.class);
 
-                StringBuilder sb = new StringBuilder("Failed to parse pull request url '" + url + "'");
-                if (issueId != null)
-                    sb.append(" for issue ").append(issueId);
-                IssuesTable.LOG.warn(sb.toString());
+                    StringBuilder sb = new StringBuilder("Failed to parse pull request url '" + url + "'");
+                    if (issueId != null)
+                        sb.append(" for issue ").append(issueId);
+                    IssuesTable.LOG.warn(sb.toString());
+                }
             }
         }
 
diff --git a/query/src/org/labkey/query/controllers/QueryController.java b/query/src/org/labkey/query/controllers/QueryController.java
index 17ec1971efe..b4ebe9d8ed5 100644
--- a/query/src/org/labkey/query/controllers/QueryController.java
+++ b/query/src/org/labkey/query/controllers/QueryController.java
@@ -4615,6 +4615,7 @@ protected JSONObject executeJson(JSONObject json, CommandType commandType, boole
             if (commandType == CommandType.insert || commandType == CommandType.insertWithKeys || commandType == CommandType.delete)
                 f = new RowMapFactory<>();
             CaseInsensitiveHashMap<Object> referenceCasing = new CaseInsensitiveHashMap<>();
+            boolean loggedConflictingCasing = false;
 
             for (int idx = 0; idx < rows.length(); ++idx)
             {
@@ -4632,9 +4633,10 @@ protected JSONObject executeJson(JSONObject json, CommandType commandType, boole
                     Map<String, Object> rowMap = null == f ? new CaseInsensitiveHashMap<>(new HashMap<>(), referenceCasing) : f.getRowMap();
                     // Use shallow copy since jsonObj.toMap() will translate contained JSONObjects into Maps, which we don't want
                     boolean conflictingCasing = JsonUtil.fillMapShallow(jsonObj, rowMap);
-                    if (conflictingCasing)
+                    if (conflictingCasing && !loggedConflictingCasing)
                     {
-                        // Issue 52616
+                        loggedConflictingCasing = true;
+                        // Issue 52616; GH Issue 1332: log once per request, not once per conflicting row
                         LOG.error("Row contained conflicting casing for key names in the incoming row: {}", jsonObj);
                     }
                     if (allowRowAttachments())

From 6ffe7a13f1dc4c5d84fb6ba41277eee662721759 Mon Sep 17 00:00:00 2001
From: Josh Eckels <jeckels@labkey.com>
Date: Mon, 27 Jul 2026 10:04:46 -0700
Subject: [PATCH 5/6] GitHub Issue 1306: Refine announcement permission check
 (#7876)

## Rationale
Previous work to better ensure the user has permission to see the
announcement wasn't specific enough.

## Changes
- Switch to asking the announcement itself about permissions, supporting
secure and normal message boards
---
 .../announcements/AnnouncementModule.java     |  3 +-
 .../AnnouncementsController.java              | 91 ++++++++++++++++++-
 2 files changed, 90 insertions(+), 4 deletions(-)

diff --git a/announcements/src/org/labkey/announcements/AnnouncementModule.java b/announcements/src/org/labkey/announcements/AnnouncementModule.java
index 7daa6d907a8..ba9c68000d2 100644
--- a/announcements/src/org/labkey/announcements/AnnouncementModule.java
+++ b/announcements/src/org/labkey/announcements/AnnouncementModule.java
@@ -242,7 +242,8 @@ public void startBackgroundThreads()
     public @NotNull Set<Class<?>> getIntegrationTests()
     {
         return Set.of(
-            AnnouncementManager.TestCase.class
+            AnnouncementManager.TestCase.class,
+            AnnouncementsController.ContainerScopingTestCase.class
         );
     }
 
diff --git a/announcements/src/org/labkey/announcements/AnnouncementsController.java b/announcements/src/org/labkey/announcements/AnnouncementsController.java
index 236fb8df9c3..fe47452e09c 100644
--- a/announcements/src/org/labkey/announcements/AnnouncementsController.java
+++ b/announcements/src/org/labkey/announcements/AnnouncementsController.java
@@ -25,6 +25,8 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.json.JSONObject;
+import org.junit.Before;
+import org.junit.Test;
 import org.labkey.announcements.model.AnnouncementDigestProvider;
 import org.labkey.announcements.model.AnnouncementFullModel;
 import org.labkey.announcements.model.AnnouncementManager;
@@ -94,12 +96,14 @@
 import org.labkey.api.security.SecurityManager;
 import org.labkey.api.security.User;
 import org.labkey.api.security.UserManager;
+import org.labkey.api.security.permissions.AbstractContainerScopingTest;
 import org.labkey.api.security.permissions.AdminPermission;
 import org.labkey.api.security.permissions.DeletePermission;
 import org.labkey.api.security.permissions.InsertPermission;
 import org.labkey.api.security.permissions.Permission;
 import org.labkey.api.security.permissions.ReadPermission;
 import org.labkey.api.security.roles.EditorRole;
+import org.labkey.api.security.roles.ReaderRole;
 import org.labkey.api.security.roles.Role;
 import org.labkey.api.security.roles.RoleManager;
 import org.labkey.api.util.DateUtil;
@@ -2447,9 +2451,15 @@ public boolean handlePost(SubscriptionBean bean, BindException errors)
             {
                 throw new NotFoundException("No such message thread: " + id);
             }
-            // Make sure they have permission to see the container for the specific message they're
-            // requesting
-            if (!ann.lookupContainer().hasPermission(getUser(), ReadPermission.class))
+            // Resolve permissions against the thread's own container since this action resolves threads cross-container.
+            // Use allowRead() not a plain container ReadPermission check: secure boards additionally enforce member-list membership.
+            Container threadContainer = ann.lookupContainer();
+            if (threadContainer == null)
+            {
+                throw new UnauthorizedException();
+            }
+            Permissions perm = getPermissions(threadContainer, getUser(), getSettings(threadContainer));
+            if (!perm.allowRead(ann))
             {
                 throw new UnauthorizedException();
             }
@@ -2883,4 +2893,79 @@ public Object execute(ThreadForm form, BindException errors)
             return success(updatedThread);
         }
     }
+
+    public static class ContainerScopingTestCase extends AbstractContainerScopingTest
+    {
+        private Container _folderA;
+        private Container _folderB;
+        private AnnouncementModel _thread;
+
+        @Before
+        public void createThread() throws Exception
+        {
+            // A message thread that lives in folder B. SubscribeThreadAction resolves threads by global entityId
+            // (cross-container by design), so each test addresses B's thread through a folder-A request.
+            _folderA = createContainer("A");
+            _folderB = createContainer("B");
+            AnnouncementModel insert = new AnnouncementModel();
+            insert.setTitle("Container scoping test thread");
+            insert.setBody("body");
+            _thread = AnnouncementManager.insertAnnouncement(_folderB, getAdmin(), insert, null, false);
+        }
+
+        @Test
+        public void testSubscribeThreadRequiresReadOnThreadContainer() throws Exception
+        {
+            ActionURL url = new ActionURL(SubscribeThreadAction.class, _folderA)
+                    .addParameter("threadId", _thread.getEntityId());
+
+            // Negative: the @RequiresPermission(ReadPermission) gate only proves read on folder A; a caller who
+            // cannot read the thread's own folder must not be able to subscribe to it.
+            User readerA = createUserInRole(_folderA, ReaderRole.class);
+            assertStatus(HttpServletResponse.SC_FORBIDDEN, post(url, readerA));
+
+            // Positive control: the same subscription succeeds (302 to the success URL) once the caller can also
+            // read the thread's folder.
+            User readerAB = createUserInRole(_folderA, ReaderRole.class);
+            grantRole(readerAB, _folderB, ReaderRole.class);
+            assertStatus(HttpServletResponse.SC_FOUND, post(url, readerAB));
+        }
+
+        @Test
+        public void testSubscribeThreadEnforcesSecureBoardMemberList() throws Exception
+        {
+            // A secure board scopes read to its member list, so allowRead() rejects a board reader who is not on the
+            // thread's member list. The old plain container-ReadPermission check missed exactly this: it let any
+            // reader subscribe to a secure thread they cannot read. Address the request to the thread's own folder so
+            // only member-list membership varies.
+            Container secure = createContainer("Secure");
+            Settings settings = AnnouncementManager.getMessageBoardSettings(secure);
+            settings.setSecure(Settings.SECURE_WITHOUT_EMAIL);
+            settings.setMemberList(true);
+            AnnouncementManager.saveMessageBoardSettings(secure, settings);
+
+            // Both are plain readers (ReaderRole lacks SecureMessageBoardReadPermission, so neither is an editor who
+            // could read every thread). Create them before insert: the member-list validation checks that each listed
+            // member can read the thread.
+            User member = createUserInRole(secure, ReaderRole.class);
+            User nonMember = createUserInRole(secure, ReaderRole.class);
+
+            AnnouncementModel insert = new AnnouncementModel();
+            insert.setTitle("Secure member-list test thread");
+            insert.setBody("body");
+            // insertAnnouncement rebuilds memberListIds from memberListInput, so set the input, not the ids directly.
+            insert.setMemberListInput(String.valueOf(member.getUserId()));
+            AnnouncementModel secureThread = AnnouncementManager.insertAnnouncement(secure, getAdmin(), insert, null, false);
+
+            ActionURL url = new ActionURL(SubscribeThreadAction.class, secure)
+                    .addParameter("threadId", secureThread.getEntityId());
+
+            // Negative: a reader of the secure board who is not on the member list cannot read the thread, so cannot
+            // subscribe. Under the old container-ReadPermission check this incorrectly succeeded.
+            assertStatus(HttpServletResponse.SC_FORBIDDEN, post(url, nonMember));
+
+            // Positive control: a reader who is on the member list can read the thread, so the subscription succeeds.
+            assertStatus(HttpServletResponse.SC_FOUND, post(url, member));
+        }
+    }
 }

From 5feb5cd1ec1d2b5b21612fc92bbd42c2e0f0b46a Mon Sep 17 00:00:00 2001
From: labkey-matthewb <matthewb@labkey.com>
Date: Mon, 27 Jul 2026 17:45:19 -0700
Subject: [PATCH 6/6] LabKey SQL hints and nits (#7835)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Rationale
Targeted changes to help AI Assistant avoid and self-correct SQL
generation mistakes.
Added support for CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP

## Related Pull Requests
- <!-- list of links to related pull requests (replace this comment) -->

## Changes
- <!-- list of descriptions of changes that are worth noting (replace
this comment) -->

<!-- list of standard tasks (remove this comment to enable)
## Tasks 📍
- [ ] Claude Code Review
- [ ] Manual Testing
- [ ] Test Automation
- [ ] Verify Fix
-->
---
 .../data/dialect/BasePostgreSqlDialect.java   |   6 +
 .../labkey/api/data/dialect/SqlDialect.java   |  11 +
 query/src/org/labkey/query/QueryTestCase.jsp  |  26 +-
 .../query/controllers/prompts/LabKeySql.md    | 639 ++++++++----------
 query/src/org/labkey/query/sql/Method.java    | 127 +++-
 .../src/org/labkey/query/sql/QMethodCall.java |   4 +-
 query/src/org/labkey/query/sql/SqlBase.g      |  21 +-
 query/src/org/labkey/query/sql/SqlParser.java | 285 +++++++-
 8 files changed, 719 insertions(+), 400 deletions(-)

diff --git a/api/src/org/labkey/api/data/dialect/BasePostgreSqlDialect.java b/api/src/org/labkey/api/data/dialect/BasePostgreSqlDialect.java
index fa53d3cf3c9..68b2b29b5e1 100644
--- a/api/src/org/labkey/api/data/dialect/BasePostgreSqlDialect.java
+++ b/api/src/org/labkey/api/data/dialect/BasePostgreSqlDialect.java
@@ -924,6 +924,12 @@ public boolean supportsNativeGreatestAndLeast()
         return true;
     }
 
+    @Override
+    public boolean supportsNativeIsDistinctFrom()
+    {
+        return true;
+    }
+
     @Override
     public boolean supportsIsNumeric()
     {
diff --git a/api/src/org/labkey/api/data/dialect/SqlDialect.java b/api/src/org/labkey/api/data/dialect/SqlDialect.java
index 73cdd4cadb4..b0c8cfa8a97 100644
--- a/api/src/org/labkey/api/data/dialect/SqlDialect.java
+++ b/api/src/org/labkey/api/data/dialect/SqlDialect.java
@@ -882,6 +882,17 @@ public SQLFragment isNumericExpr(SQLFragment expression)
         throw new UnsupportedOperationException(getClass().getSimpleName() + " does not implement");
     }
 
+    /**
+     * Does the dialect natively support the standard "IS [NOT] DISTINCT FROM" predicate? PostgreSQL and Snowflake
+     * do; SQL Server, MySQL, and Oracle do not (SQL Server added GREATEST/LEAST in recent versions but has never
+     * added this predicate). Dialects that return false here get a portable CASE-based rewrite instead; see
+     * Method.IsDistinctFromMethodInfo.
+     */
+    public boolean supportsNativeIsDistinctFrom()
+    {
+        return false;
+    }
+
     public void handleCreateDatabaseException(SQLException e) throws ServletException
     {
         throw(new ServletException("Can't create database", e));
diff --git a/query/src/org/labkey/query/QueryTestCase.jsp b/query/src/org/labkey/query/QueryTestCase.jsp
index 684f0569dfd..95a7f7f8b54 100644
--- a/query/src/org/labkey/query/QueryTestCase.jsp
+++ b/query/src/org/labkey/query/QueryTestCase.jsp
@@ -892,7 +892,7 @@ d,seven,twelve,day,month,date,duration,guid
                 assertNull(rs.getColumn(1).getFormat());
             }
         },
-        new SqlTest("SELECT 1 AS name @hidden'")
+        new SqlTest("SELECT 1 AS name @hidden")
         {
             @Override
             protected void validateResults(Results rs) throws Exception
@@ -914,18 +914,10 @@ d,seven,twelve,day,month,date,duration,guid
         },
 
         // test operators in THEN expression
-        new SqlTest("SELECT CASE WHEN 1=1 THEN 'a' || 'b' ELSE 'x' || 'y' END")
-    );
-
-    List<SqlTest> postgres = List.of(
-        // ORDER BY tests
-        new SqlTest("SELECT R.day, R.month, R.date FROM R ORDER BY R.date", 3, Rsize),
-        new SqlTest("SELECT R.day, R.month, R.date FROM R UNION SELECT R.day, R.month, R.date FROM R ORDER BY date"),
-        new SqlTest("SELECT R.guid FROM R WHERE overlaps(CAST('2001-01-01' AS DATE), CAST('2001-01-10' AS DATE), CAST('2001-01-05' AS DATE), CAST('2001-01-15' AS DATE))", 1, Rsize),
-
-        // regression test: field reference in sub-select (https://www.labkey.org/home/Developer/issues/issues-details.view?issueId=43580)
-        new SqlTest("SELECT (SELECT GROUP_CONCAT(b.displayname, ', ') FROM core.UsersAndGroups b WHERE b.email IN (SELECT UNNEST(STRING_TO_ARRAY(a.title, ',')))) AS procedurename, a.parent.rowid FROM core.containers a ", 2, 1),
+        new SqlTest("SELECT CASE WHEN 1=1 THEN 'a' || 'b' ELSE 'x' || 'y' END"),
 
+        // is_distinct_from()/is_not_distinct_from() are portable: native "IS [NOT] DISTINCT FROM" on PostgreSQL and
+        // Snowflake, a CASE-based rewrite elsewhere (e.g. SQL Server) -- see IsDistinctFromMethodInfo.getSQL()
         new MethodSqlTest("SELECT is_distinct_from(NULL,NULL)", JdbcType.BOOLEAN, false),
         new MethodSqlTest("SELECT is_not_distinct_from(NULL,NULL)", JdbcType.BOOLEAN, true),
         new MethodSqlTest("SELECT is_distinct_from(1,NULL)", JdbcType.BOOLEAN, true),
@@ -936,6 +928,16 @@ d,seven,twelve,day,month,date,duration,guid
         new MethodSqlTest("SELECT is_not_distinct_from(1,2)", JdbcType.BOOLEAN, false)
     );
 
+    List<SqlTest> postgres = List.of(
+        // ORDER BY tests
+        new SqlTest("SELECT R.day, R.month, R.date FROM R ORDER BY R.date", 3, Rsize),
+        new SqlTest("SELECT R.day, R.month, R.date FROM R UNION SELECT R.day, R.month, R.date FROM R ORDER BY date"),
+        new SqlTest("SELECT R.guid FROM R WHERE overlaps(CAST('2001-01-01' AS DATE), CAST('2001-01-10' AS DATE), CAST('2001-01-05' AS DATE), CAST('2001-01-15' AS DATE))", 1, Rsize),
+
+        // regression test: field reference in sub-select (https://www.labkey.org/home/Developer/issues/issues-details.view?issueId=43580)
+        new SqlTest("SELECT (SELECT GROUP_CONCAT(b.displayname, ', ') FROM core.UsersAndGroups b WHERE b.email IN (SELECT UNNEST(STRING_TO_ARRAY(a.title, ',')))) AS procedurename, a.parent.rowid FROM core.containers a ", 2, 1)
+    );
+
     List<SqlTest> postgresOnlyFunctions()
     {
         int majorVersion = ((BasePostgreSqlDialect) CoreSchema.getInstance().getSqlDialect()).getMajorVersion();
diff --git a/query/src/org/labkey/query/controllers/prompts/LabKeySql.md b/query/src/org/labkey/query/controllers/prompts/LabKeySql.md
index 51666e4d111..2346ea35687 100644
--- a/query/src/org/labkey/query/controllers/prompts/LabKeySql.md
+++ b/query/src/org/labkey/query/controllers/prompts/LabKeySql.md
@@ -1,415 +1,366 @@
 ### **LabKey SQL Documentation**
 
-LabKey SQL is a unique SQL dialect that extends standard SQL functionality with features tailored for the LabKey Server platform, particularly for scientific data management.
-LabKey SQL only implements data read operations.  It does not support INSERT/UPDATE/DELETE, nor does it support creating or altering tables.
+LabKey SQL is a SQL dialect that extends standard SQL with features tailored for the LabKey Server platform. Queries are checked against the user's permissions and cross-compiled to the underlying database (PostgreSQL, or MS SQL Server for some premium installations).
+
+Core facts:
+* **SELECT only.** No INSERT/UPDATE/DELETE, no DDL. A statement is: `[PARAMETERS(...)] [WITH ...] SELECT ... [set ops] [ORDER BY ...] [LIMIT n]`.
+* Keywords, function names, schema/table/column names are **case-insensitive**.
+* Comments: `-- line` and `/* block */`.
+* If a `validateSQL` tool is available, use it to check syntax before saving or executing a query. Note that parse-time errors are descriptive, but type errors and dialect issues may only surface at execution time as an unhelpful generic message — apply the rules below proactively.
 
 -----
 
-### **1. Lookups and Joins**
-
-LabKey SQL simplifies data joining by providing an intuitive **lookup syntax** that often eliminates the need for explicit `JOIN` statements.
-
-* **Syntax:**
-  `SELECT parent_table.lookup_column.target_column FROM parent_table`
-* **Functionality:**
-  This syntax allows you to access columns from a foreign table by following the lookup relationship with dot notation. This is a powerful feature for simplifying queries that involve related data.
-* **Examples:**
-    * **Simple Lookup:** To retrieve a participant's gender from the `Demographics` table using a lookup from the `PhysicalExam` table:
-      ```sql
-      SELECT PhysicalExam.ParticipantId, PhysicalExam.weight_kg, Demographics.Gender, Demographics.Height
-      FROM PhysicalExam
-      ```
-    * **Joining Across Folders:** To join data from a `Demographics` table in one folder with a `Languages` list in a different folder:
-      ```sql
-      JOIN "/Other/Folder".lists.Languages ON Demographics.Language=Languages.Language
-      ```
+### **1. NOT SUPPORTED — Write This Instead**
+
+LabKey SQL rejects many constructs that are valid in PostgreSQL/ANSI SQL. **Check generated SQL against this table first.**
+
+| Do NOT write | Why | Write instead |
+| --- | --- | --- |
+| `ROW_NUMBER() OVER (...)`, `RANK`, `LAG`, `SUM(x) OVER (...)` | No window functions, no `OVER` | Self-join or correlated subquery |
+| `LIMIT 10 OFFSET 20`, `FETCH FIRST n ROWS`, `TOP n` | Only `LIMIT <integer literal>` exists; no OFFSET | `LIMIT 10`; page via client API `maxRows`/`offset` |
+| `GROUP BY 1` | Ordinals/constants rejected in GROUP BY (error: "Expression in Group By clause must not be a constant") | Repeat the expression: `GROUP BY YEAR(Date)`. (`ORDER BY 1` **is** allowed.) |
+| `EXTRACT(YEAR FROM d)` | Not supported | `YEAR(d)`, `MONTH(d)`, `DAYOFMONTH(d)`, `HOUR(d)`, … |
+| `col::integer` | No `::` cast | `CAST(col AS INTEGER)` |
+| `SUM(DISTINCT x)`, `AVG(DISTINCT x)` | `DISTINCT` only inside `COUNT()` and `GROUP_CONCAT()` | Aggregate over a `SELECT DISTINCT` subquery |
+| `x ILIKE 'a%'`, `x ~ 'regex'`, `x SIMILAR TO p` | Operators not supported | `LOWER(x) LIKE 'a%'`; PostgreSQL only: `similar_to(x, pattern[, escape])` |
+| `a IS DISTINCT FROM b` | Operator form not supported | `is_distinct_from(a, b)` / `is_not_distinct_from(a, b)` (both databases); `isequal(a, b)` = null-safe equals |
+| `ORDER BY x NULLS LAST` | Not supported | `ORDER BY x IS NULL, x` |
+| `d + INTERVAL '1 day'` | No INTERVAL literals | `TIMESTAMPADD('SQL_TSI_DAY', 1, d)` |
+| `CONCAT(a, b, c)` | `CONCAT` takes exactly 2 arguments | `a \|\| b \|\| c` (note: `\|\|` yields NULL if any operand is NULL — wrap with `COALESCE`) |
+| `POSITION(a IN b)` | Unknown method | `LOCATE(a, b[, startIndex])` |
+| `TRIM(BOTH ' ' FROM x)` | Not supported | `LTRIM(RTRIM(x))`; PostgreSQL only: `btrim(x)` |
+| `COUNT(*) FILTER (WHERE c)` | No FILTER clause | `SUM(CASE WHEN c THEN 1 ELSE 0 END)` |
+| `JOIN b USING (id)`, `NATURAL JOIN` | Every non-CROSS join requires `ON` | `JOIN b ON a.id = b.id` |
+| `SUM(a \|\| b)`, `MIN(a & b)` | Aggregate arguments cannot directly contain `\|\|` or bitwise operators | Add parentheses: `SUM((a \|\| b))` |
+| `DATE '2001-02-03'` | No typed literals | `{d '2001-02-03'}` or `CAST('2001-02-03' AS DATE)` |
+| `{d'2001-02-03'}` (no space) | Parse error — the space after `{d`/`{ts` is part of the token | `{d '2001-02-03'}`, `{ts '2001-02-03 04:05:06'}` |
+| `WITH cte (col1, col2) AS (...)` | No CTE column lists | Alias inside: `WITH cte AS (SELECT x AS col1 ...)` |
+| `a < b < c` | Comparisons don't chain | `a < b AND b < c` |
+| `PARAMETERS (D DATE)` | DATE/TIME/BOOLEAN not parameter types | Use `TIMESTAMP` (or `BIT` for boolean) |
+| `GROUPING SETS / ROLLUP / CUBE / LATERAL / TABLESAMPLE` | Not supported | Restructure (UNION of grouped queries, etc.) |
 
 -----
 
-### **2. Calculated Columns**
+### **2. Identifiers, Literals, and Reserved Words**
 
-LabKey SQL allows you to create virtual columns within a query by using SQL expressions. These calculated columns are not stored in the database but are computed on the fly.
+* **Identifiers**: double-quote names containing spaces/special characters or matching reserved words: `"Physical Exam"`. Escape an embedded `"` by doubling it.
+* **String literals**: single quotes; escape `'` by doubling: `'Jim''s Item'`. No backslash escapes.
+* **Date/time literals**: `{d '2001-02-03'}` and `{ts '2001-02-03 04:05:06'}` — JDBC escape syntax, **space after `{d`/`{ts` required**.
+* **Booleans**: `TRUE`, `FALSE`. Special doubles: `CAST('Infinity' AS DOUBLE)`, `CAST('-Infinity' AS DOUBLE)`, `CAST('NaN' AS DOUBLE)`.
+* **Reserved words** — these cannot be used as bare identifiers/aliases; double-quote them (`SELECT COUNT(*) AS "Count"`):
 
-* **Syntax:**
-  `SELECT expression AS column_name FROM table`
-* **Functionality:**
-  The syntax involves performing a calculation and then aliasing the result with a new column name using the `as` keyword.
-* **Reserved words as aliases:** SQL function names (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`) and other SQL keywords are reserved and cannot be used as bare column aliases. Quote them or choose a different name:
-  ```sql
-  -- Wrong:  COUNT(MouseId) AS Count   → parse error
-  -- Right:  COUNT(MouseId) AS "Count"
-  -- Right:  COUNT(MouseId) AS TotalCount
-  ```
-* **Examples:**
-    * **Pulse Pressure:** To calculate pulse pressure from systolic and diastolic blood pressure values:
-      ```sql
-      PhysicalExam.systolicBP-PhysicalExam.diastolicBP as PulsePressure
-      ```
-    * **BMI (Body Mass Index):** A more complex example that uses an intermediate query to calculate BMI from height and weight data:
-      ```sql
-      ROUND(weight_kg / (height_m * height_m), 2) AS BMI
-      ```
+  `all, any, and, as, asc, avg, between, both, case, class, count, current_date, current_time, current_timestamp, delete, desc, distinct, elements, else, empty, end, escape, except, exists, false, fetch, from, full, group, having, in, indices, inner, insert, intersect, into, is, join, leading, left, like, limit, max, member, min, new, not, null, of, on, or, order, outer, right, select, set, some, stddev, sum, trailing, then, true, union, update, user, versioned, when, where`
+
+* Do not end statements with `;` (produces a warning) and do not submit multiple statements.
 
 -----
 
-### **3. Pivoting**
+### **3. Query Structure and Clause Rules**
 
-A `PIVOT` query helps you summarize and re-visualize data by transforming rows into columns.
+* **SELECT list**: `expr [AS] alias`. Alias every expression column — unaliased expressions get auto-names (`Expression1`, …) plus a warning. Duplicate output names are an error (`Duplicate column 'x'`). `*` and `table.*` cannot be aliased. A scalar subquery must return exactly one column. `SELECT 1 AS x` with no FROM is allowed.
+* **FROM/JOIN**: `INNER | LEFT | RIGHT | FULL [OUTER] JOIN ... ON cond` and `CROSS JOIN` (no ON). Comma joins and nested parenthesized joins are supported. Subqueries in FROM should be aliased (warning otherwise). An unqualified column name found in two FROM tables is an error (`Ambiguous field`).
+* **WHERE**: standard comparisons `= <> != < <= > >=`, `[NOT] IN (list | subquery)`, `[NOT] BETWEEN a AND b`, `[NOT] LIKE p [ESCAPE e]`, `IS [NOT] NULL`, `EXISTS (subquery)`, `ANY/SOME/ALL (subquery)`.
+* **GROUP BY**: expressions only — no ordinals, no constants. **HAVING requires GROUP BY or an aggregate in the SELECT list** (an aggregate appearing only in HAVING is rejected).
+* **ORDER BY**: column names, aliases, expressions, or ordinals (`ORDER BY 1`); `ASC`/`DESC`. **When a query is used as a subquery or saved and wrapped by the server (common), its ORDER BY is IGNORED unless LIMIT is also present.** Prefer sorting via the client API / grid view; if SQL sorting is needed, add `LIMIT`. To sort by an expression, put it in the SELECT list (optionally `@hidden`) and sort by its alias.
+* **LIMIT**: `LIMIT <integer literal>` only, placed after ORDER BY. Applies to the whole UNION when used at the end of one.
+* **Set operations**: `UNION`, `UNION ALL`, `INTERSECT`, `EXCEPT`. All terms need the same column count and compatible types; result column names come from the first term. A trailing ORDER BY may reference only output column names or ordinals. Parenthesized sub-statements are allowed.
+* **Division**: `/` warns unless the divisor is guarded — write `dividend / NULLIF(divisor, 0)`. Integer ÷ integer truncates; cast one operand: `CAST(a AS DOUBLE) / b`.
 
-* **Syntax for PIVOT...BY Query:**
-  A pivot query is a `SELECT` statement specifying how to pivot and group columns. The basic syntax is `PIVOT [aggregating_column] BY [pivoting_column]`.
-* **PIVOT...BY...IN Syntax:**
-  You can use an `IN` clause to specify a fixed set of column names to pivot. This is more efficient.
-  ```sql
-  PIVOT new_column_name BY pivoting_column IN ('value1', 'value2')
-  ```
-  Note that pivot column names are case-sensitive. You may need to use `LOWER()` or `UPPER()` in your query to work around this issue.
-  * **Pivoting by Two Columns:**
-    Two levels of `PIVOT` are not directly supported. However, you can achieve a similar result by concatenating the two values together and pivoting on that "calculated" column.
-    ```sql
-    SELECT
-      Run.SampleCondition || ' ' || PeakLabel AS ConditionPeak,
-      AVG(Data.PercTimeCorrArea) AS AvgPercTimeCorrArea
-    FROM Data
-    GROUP BY Run.SampleCondition || ' ' || PeakLabel
-    PIVOT AvgPercTimeCorrArea BY ConditionPeak
-    ```
+-----
+
+### **4. Lookups (Foreign-Key Dot Traversal) and Joins**
+
+Lookup columns (foreign keys) can be traversed with dot notation instead of writing a JOIN. Follow the FK column with the target column name:
+
+```sql
+-- CreatedBy is a lookup to the Users table:
+SELECT c.Name, c.CreatedBy.DisplayName AS Creator
+FROM core.Containers c
+```
+
+Multi-hop traversal works (`Issues.AssignedTo.DisplayName`). Only reference tables in the FROM clause or reachable through lookups — referencing another table's columns directly is an error.
+
+**Study datasets**: every dataset has a `Datasets` column joining to other datasets by subject(/visit):
+
+```sql
+SELECT a.MouseId, a.Datasets."DEM-1".DEMsex
+FROM "APX-1" a
+```
+
+**Joining across folders** (see also section 12):
+
+```sql
+SELECT d.Language, l.TranslatorName
+FROM Demographics d JOIN "/Other/Folder".lists.Languages l ON d.Language = l.Language
+```
+
+`IFDEFINED(ColumnName)` references a column that may not exist — it evaluates as NULL instead of failing, useful over PIVOT results or variable assay schemas.
 
 -----
 
-### **4. Cross-Folder Queries**
+### **5. Aggregate Functions**
 
-You can write queries that access data from different folders within the LabKey Server instance, allowing for data integration across projects.
+Available on both databases:
 
-* **Syntax:**
-  `SELECT * FROM Project."folder_path".schema.table`
-* **Functionality:**
-  The folder path is a dot-delimited string that specifies the location of the table, including the project name. The user must have "Reader" permissions in each folder referenced in the query.
-* **Example:**
-  ```sql
-  SELECT
-  p.ParticipantID,
-  ROUND(AVG(p.Temp_C), 1) AS AverageTemp
-  FROM Project."Tutorials/Demo/".study."Physical Exam" p
-  GROUP BY p.ParticipantID
-  ```
+* `COUNT(*)`, `COUNT(expr)`, `COUNT(DISTINCT expr)`
+* `SUM(expr)`, `MIN(expr)`, `MAX(expr)`, `AVG(expr)`
+* `GROUP_CONCAT([DISTINCT] expr [, separator])`: comma-separated values of the group; e.g. `GROUP_CONCAT(DISTINCT Category, ';')`. (On MS SQL Server requires a separately-installed function and cannot be used in a sub-select.)
+* `STDDEV(expr)`, `STDDEV_POP(expr)`, `VARIANCE(expr)`, `VAR_POP(expr)`, `STDERR(expr)`
+* `MEDIAN(expr)`
+
+PostgreSQL only: `BOOL_AND, BOOL_OR, EVERY, BIT_AND, BIT_OR, MODE, STDDEV_SAMP, VAR_SAMP` and two-argument regression aggregates `CORR(Y,X), COVAR_POP, COVAR_SAMP, REGR_AVGX, REGR_AVGY, REGR_COUNT, REGR_INTERCEPT, REGR_R2, REGR_SLOPE, REGR_SXX, REGR_SXY, REGR_SYY`.
+
+Rules: `DISTINCT` is allowed only in `COUNT` and `GROUP_CONCAT`. No `FILTER` clause, no `OVER`, no `ARRAY_AGG`. To nest `||` or bitwise operators inside an aggregate, parenthesize: `MIN((a || b))`.
 
 -----
 
-### **5. Parameterized Queries**
+### **6. Scalar Functions (Both Databases)**
 
-LabKey SQL supports **parameterized queries** to improve security and reusability.
+#### Mathematical
+`abs(v)`, `acos(v)`, `asin(v)`, `atan(v)`, `atan2(v1,v2)`, `ceiling(v)`, `cos(r)`, `cot(r)`, `degrees(r)`, `exp(n)`, `floor(v)`, `log(n)` (natural), `log10(n)`, `mod(dividend, divider)`, `pi()`, `power(base, exp)`, `radians(d)`, `rand([seed])`, `round(v[, precision])`, `sign(v)`, `sin(v)`, `sqrt(v)`, `tan(v)`, `truncate(v, precision)` (may require `CAST(v AS NUMERIC)`)
 
-* **Syntax:**
-  `PARAMETERS(param1 type, param2 type DEFAULT value) SELECT * FROM table WHERE column = param1`
-* **Functionality:**
-  The `PARAMETERS` keyword declares parameters that can be passed into the query.  If a DEFAULT is
-  not specified, the value will default to NULL.
-* **Example:** A query with two parameters, `MinTemp` and `MinWeight`:
-  ```sql
-  PARAMETERS(MinTemp double, MinWeight double DEFAULT 0.0)
-  SELECT
-    ParticipantID,
-    temperature_C,
-    weight_kg
-  FROM PhysicalExam
-  WHERE temperature_C >= MinTemp AND weight_kg >= MinWeight
-  ```
+#### String
+`concat(a, b)` (exactly 2 args; prefer `||`), `lcase(s)`/`lower(s)`, `ucase(s)`/`upper(s)`, `left(s, n)`, `right(s, n)`, `length(s)`, `locate(substr, s[, start])`, `ltrim(s)`, `rtrim(s)`, `repeat(s, count)`, `startswith(s, prefix)`, `substring(s, start[, length])` (1-based)
+
+#### Date and Time
+* `curdate()`, `curtime()`, `now()` — and the SQL-standard niladic keyword forms `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP` (**no parentheses** — `CURRENT_DATE()` is a syntax error, unlike the function forms)
+* `year(d)`, `quarter(d)`, `month(d)`, `monthname(d)`, `week(d)`, `dayofyear(d)`, `dayofmonth(d)`, `dayofweek(d)`, `hour(t)`, `minute(t)`, `second(t)`
+* `timestampadd(interval, n, ts)` — interval is a quoted constant, one of `'SQL_TSI_FRAC_SECOND'`, `'SQL_TSI_SECOND'`, `'SQL_TSI_MINUTE'`, `'SQL_TSI_HOUR'`, `'SQL_TSI_DAY'`, `'SQL_TSI_WEEK'`, `'SQL_TSI_MONTH'`, `'SQL_TSI_QUARTER'`, `'SQL_TSI_YEAR'` (the `SQL_TSI_` prefix may be omitted: `'DAY'`).
+* `timestampdiff(interval, ts1, ts2)` — same constants, **but on PostgreSQL only `'SQL_TSI_SECOND'`, `'SQL_TSI_MINUTE'`, `'SQL_TSI_HOUR'`, `'SQL_TSI_DAY'` work**; YEAR/MONTH/WEEK/QUARTER fail at execution time. For those use:
+* `age(d1, d2)` (years), `age(d1, d2, interval)` with `'SQL_TSI_DAY' | 'SQL_TSI_MONTH' | 'SQL_TSI_YEAR'`, `age_in_years(d1, d2)`, `age_in_months(d1, d2)`, `age_in_days(d1, d2)`
+
+#### Conditional and Utility
+`coalesce(v1, ..., vN)`, `nullif(a, b)` (NULL if a=b, else a — use for divide-by-zero guards), `ifnull(test, default)`, `isequal(a, b)` (true when equal or both NULL), `is_distinct_from(a, b)`, `is_not_distinct_from(a, b)`, `greatest(a, b, ...)`, `least(a, b, ...)`, `isnumeric(expr)`, `ifdefined(col)`, `CASE [operand] WHEN ... THEN ... [ELSE ...] END`
+
+#### LabKey Extensions
+`userid()`, `username()`, `ismemberof(groupid)`, `contextPath()`, `folderName()`, `folderPath()`, `moduleProperty('module','property')`, `javaConstant('class.FIELD')`, `version()`, `overlaps(start1, end1, start2, end2)` (PostgreSQL only)
 
 -----
 
-### **6. Metadata Annotations**
+### **7. PostgreSQL-Only Scalar Functions**
 
-LabKey SQL allows you to directly annotate your SQL statements to override how column metadata is displayed in the LabKey interface.
+Only when the server runs PostgreSQL (the common case). Passed through natively:
 
-* **Syntax:**
-  `SELECT column_name @annotation FROM table`
-* **Functionality:**
-  Annotations control the display of a column without changing the underlying data.
-* **Examples:**
-    * **Hiding a Column:**
-      ```sql
-      SELECT ratio @hidden, log(ratio) as log_ratio
-      ```
-    * **Setting a Title and Format:**
-      ```sql
-      SELECT 10/7.0 AS Num @title='Calculated Number' @Format='0.00'
-      ```
+`ascii`, `btrim(s[,chars])`, `char_length`, `character_length`, `chr(code)`, `concat_ws(sep, v1, ...)` (variadic, skips NULLs), `decode`, `encode`, `initcap`, `lpad(s,n[,fill])`, `rpad(s,n[,fill])`, `md5`, `octet_length`, `quote_ident`, `quote_literal`, `regexp_replace(s, pattern, replacement[, flags])`, `replace(s, match, replacement)`, `similar_to(s, pattern[, escape])`, `split_part(s, delim, n)`, `strpos(s, sub)`, `substr(s, from[, count])`, `to_ascii`, `to_hex`, `translate(s, from, to)`, `to_char(v, format)`, `to_date(text, format)`, `to_timestamp(text, format)`, `to_number(text, format)`, `string_to_array`, `unnest`
+
+(MS SQL Server-only equivalents exist — `charindex`, `len`, `patindex`, `replicate`, `stuff`, etc. — only relevant for premium MSSQL deployments.)
 
 -----
 
-### **7. Container Filters**
-
-In addition to targeting a container by its path, LabKey SQL supports container filters to alter the scope
-of a query. Annotate tables in the FROM clause with an optional container filter. Syntax:
-
-SELECT * FROM Issues [ContainerFilter='CurrentAndSubfolders'] alias
-
-Possible values include:
-- AllFolders
-- AllInProject
-- AllInProjectPlusShared
-- Current
-- CurrentAndFirstChildren
-- CurrentAndParents
-- CurrentAndSubfolders
-- CurrentAndSubfoldersPlusShared
-- CurrentPlusProject
-- CurrentPlusProjectAndShared.
-
-### **8. Available Methods**
-
-Here is a summary of the available functions and methods in LabKey SQL.
-
-#### **Mathematical Functions**
-
-* `abs(value)`: Returns the absolute value.
-* `acos(value)`: Returns the arc cosine.
-* `asin(value)`: Returns the arc sine.
-* `atan(value)`: Returns the arc tangent.
-* `atan2(value1, value2)`: Returns the arctangent of the quotient.
-* `ceiling(value)`: Rounds the value up.
-* `cos(radians)`: Returns the cosine.
-* `cot(radians)`: Returns the cotangent.
-* `degrees(radians)`: Returns degrees.
-* `exp(n)`: Returns Euler's number 'e' raised to the nth power.
-* `floor(value)`: Rounds down.
-* `log(n)`: Returns the natural logarithm.
-* `log10(n)`: Returns the base 10 logarithm.
-* `mod(dividend, divider)`: Returns the remainder.
-* `pi()`: Returns the value of pi.
-* `power(base, exponent)`: Returns the base raised to the power of the exponent.
-* `radians(degrees)`: Returns the radians.
-* `rand()`, `rand(seed)`: Returns a random number.
-* `round(value, precision)`: Rounds to the specified decimal places.
-* `sign(value)`: Returns the sign of the value.
-* `sin(value)`: Returns the sine.
-* `sqrt(value)`: Returns the square root.
-* `tan(value)`: Returns the tangent.
-* `truncate(numeric value, precision)`: Truncates the numeric value.
-
-#### **String Functions**
-
-* `concat(value1, value2)`: Concatenates two values.
-* `lcase(string)`, `lower(string)`: Converts to lower case.
-* `left(string, integer)`: Returns the left side of the string.
-* `length(string)`: Returns the length.
-* `locate(substring, string, [startIndex])`: Returns the location of a substring.
-* `ltrim(string)`: Trims white space from the left.
-* `repeat(string, count)`: Repeats the string.
-* `rtrim(string)`: Trims white space from the right.
-* `startswith(string, prefix)`: Tests if a string starts with a prefix.
-* `substring(string, start, length)`: Returns a portion of the string.
-* `ucase(string)`, `upper(string)`: Converts to upper case.
-
-#### **Date and Time Functions**
-
-* `age(date1, date2, [interval])`: Supplies the difference in age.
-* `age_in_days(date1, date2)`: Returns age in days.
-* `age_in_months(date1, date2)`: Returns age in months.
-* `age_in_years(date1, date2)`: Returns age in years.
-* `curdate()`, `curtime()`: Returns the current date/time.
-* `dayofmonth(date)`: Returns the day of the month.
-* `dayofweek(date)`: Returns the day of the week.
-* `dayofyear(date)`: Returns the day of the year.
-* `hour(time)`, `minute(time)`, `second(time)`: Return time components.
-* `month(date)`, `monthname(date)`: Return month values.
-* `now()`: Returns the system date and time.
-* `quarter(date)`: Returns the yearly quarter.
-* `timestampadd(interval, number, timestamp)`: Adds an interval.
-* `timestampdiff(interval, ts1, ts2)`: Finds the difference between timestamps.
-* `week(date)`, `year(date)`: Return week and year values.
-
-#### **Conditional and Utility Functions**
-
-* `coalesce(v1,...,vN)`: Returns the first non-null value.
-* `greatest(a, b, c, ...)`: Returns the greatest value.
-* `ifdefined(column_name)`: References columns that may not exist.
-* `ifnull(testValue, defaultValue)`: Returns a default value if the test value is null.
-* `isequal(a,b)`: Returns true if `a` equals `b` or if both are `NULL`.
-* `least(a, b, c, ...)`: Returns the smallest value.
-
-#### **LabKey SQL Extensions**
-
-* `contextPath()`, `folderName()`, `folderPath()`: Return path information.
-* `ismemberof(groupid)`: Checks if a user is a member of a group.
-* `javaConstant(fieldName)`: Provides access to Java static final variables.
-* `moduleProperty(module name, property name)`: Returns a module property.
-* `overlaps(START1, END1, START2, END2)`: Tests for overlapping time intervals (PostgreSQL only).
-* `userid()`, `username()`: Return user information.
-* `version()`: Returns the current schema version.
+### **8. WITH (Common Table Expressions)**
+
+```sql
+WITH AllDemo AS (
+  SELECT * FROM "/Studies/Study A/".study.Demographics
+  UNION
+  SELECT * FROM "/Studies/Study B/".study.Demographics
+)
+SELECT ParticipantId FROM AllDemo
+```
+
+Rules:
+* `WITH name AS (SELECT ...)` — **no column list** after the name.
+* Multiple CTEs allowed; each may reference earlier ones.
+* Recursive CTEs are supported (no `RECURSIVE` keyword needed). The recursive form is `anchor-query UNION ALL recursive-query`; the **first (anchor) branch must not reference the CTE**, and the CTE may be referenced **only once** in the recursive branch.
+* **Warning**: a non-terminating recursive CTE can hang the server (PostgreSQL raises no error) — always ensure termination.
+
+```sql
+PARAMETERS ( Source VARCHAR DEFAULT NULL )
+WITH Derivations AS (
+  SELECT Item, Parent FROM Items WHERE Parent = Source
+  UNION ALL
+  SELECT i.Item, i.Parent FROM Items i INNER JOIN Derivations p ON i.Parent = p.Item
+)
+SELECT * FROM Derivations
+```
 
 -----
 
-### **9. JSON and JSONB Operators and Functions (PostgreSQL Only)**
-
-LabKey SQL supports PostgreSQL JSON and JSONB operators and functions for working with JSON data stored in columns. These are **not available on MS SQL Server**. See the [PostgreSQL docs](https://www.postgresql.org/docs/14/functions-json.html) for detailed usage. 
-
-#### **Operators via `json_op`**
-
-Native PostgreSQL operator syntax (`->`, `->>`, etc.) cannot be used directly in LabKey SQL. Instead, use the `json_op` pass-through function with three arguments: the left operand, the operator as a string, and the right operand.
-
-* **Supported operators:** `->`, `->>`, `#>`, `#>>`, `@>`, `<@`, `?`, `?|`, `?&`, `||`, `-`, `#-`
-* **Syntax:** `json_op(left_operand, 'operator', right_operand)`
-* **Examples:**
-    * **Extract by key (as JSON):** Get a nested value from a JSONB column:
-      ```sql
-      SELECT json_op(metadata, '->', 'name') AS name_json FROM samples
-      ```
-    * **Extract by key (as text):** Get the text value:
-      ```sql
-      SELECT json_op(metadata, '->>', 'name') AS name_text FROM samples
-      ```
-    * **Containment check:** Filter rows where JSONB contains a given structure:
-      ```sql
-      SELECT * FROM samples WHERE json_op(metadata, '@>', parse_jsonb('{"status":"active"}'))
-      ```
-    * **Key existence check:**
-      ```sql
-      SELECT * FROM samples WHERE json_op(metadata, '?', 'name')
-      ```
-
-#### **Conversion / Parsing Functions**
-
-* `parse_json(text)`, `parse_jsonb(text)`: Cast a text value to JSON or JSONB. Use instead of `::jsonb` or `CAST(... AS JSONB)`.
-  ```sql
-  SELECT parse_jsonb('{"a":1, "b":null}')
-  ```
-* `to_json(value)`, `to_jsonb(value)`: Convert a value to JSON/JSONB. Text values become a single JSON string.
-* `array_to_json(array)`: Convert an array to JSON.
-* `row_to_json(value)`: Convert a scalar row to JSON. **Note:** Does not support converting an entire table to JSON; use `to_jsonb()` instead.
+### **9. VALUES (Constant Tables)**
 
-#### **Builder Functions**
+```sql
+SELECT t.column1 AS Id, t.column2 AS Name
+FROM (VALUES (1, 'one'), (2, 'two'), (3, 'three')) AS t
+```
 
-* `json_build_array(...)`, `jsonb_build_array(...)`: Build a JSON array from arguments.
-  ```sql
-  SELECT jsonb_build_array(1, 'two', 3.0)
-  ```
-* `json_build_object(...)`, `jsonb_build_object(...)`: Build a JSON object from key/value arguments.
-  ```sql
-  SELECT jsonb_build_object('name', sample_name, 'type', sample_type) FROM samples
-  ```
-* `json_object(text_array)`, `jsonb_object(text_array)`: Build a JSON object from a text array.
+* The table alias (`AS t`) is **required**; column names are always `column1`, `column2`, … and cannot be declared in the VALUES clause — rename them in the outer SELECT.
+* Rows must have equal length and compatible types; only constants/parameters (no column references or subqueries).
 
-#### **Query and Extraction Functions**
+-----
 
-* `json_array_length(json)`, `jsonb_array_length(jsonb)`: Return the length of the outermost JSON array.
-* `json_each(json)`, `jsonb_each(jsonb)`: Expand the outermost JSON object into key/value pairs. **Note:** Only scalar function usage is supported, not the table-returning version.
-  ```sql
-  SELECT json_each('{"a":"foo", "b":"bar"}') AS Value
-  ```
-* `json_each_text(json)`, `jsonb_each_text(jsonb)`: Like `json_each` but values are returned as text. Only scalar usage supported.
-* `json_extract_path(json, ...)`, `jsonb_extract_path(jsonb, ...)`: Return the JSON value at the given path.
-  ```sql
-  SELECT jsonb_extract_path(metadata, 'address', 'city') FROM samples
-  ```
-* `json_extract_path_text(json, ...)`, `jsonb_extract_path_text(jsonb, ...)`: Return the value at the given path as text.
-* `json_object_keys(json)`, `jsonb_object_keys(jsonb)`: Return the keys of the outermost JSON object.
-* `json_array_elements(json)`, `jsonb_array_elements(jsonb)`: Expand a JSON array into a set of values.
-* `json_array_elements_text(json)`, `jsonb_array_elements_text(jsonb)`: Expand a JSON array into a set of text values.
+### **10. PIVOT**
 
-#### **Type Inspection and Cleanup Functions**
+A pivot query summarizes and rotates a **grouped** query: `PIVOT aggCol [, aggCol...] BY pivotColumn [IN (...)]`.
 
-* `json_typeof(json)`, `jsonb_typeof(jsonb)`: Return the type of the outermost JSON value (e.g., `"object"`, `"array"`, `"string"`, `"number"`).
-* `json_strip_nulls(json)`, `jsonb_strip_nulls(jsonb)`: Remove all null-valued keys from a JSON object.
+```sql
+SELECT ParticipantId, Visit, AVG(Score) AS AvgScore
+FROM Results
+GROUP BY ParticipantId, Visit
+PIVOT AvgScore BY Visit IN ('V1', 'V2', 'V3')
+```
 
-#### **Modification Functions**
+Hard rules (violations are errors):
+* The query **must have a GROUP BY clause**, and the BY column's expression must appear in GROUP BY **exactly as written**.
+* Each pivoted column (`AvgScore` above) must be an aggregate in the SELECT list.
+* Any additional non-pivoted, non-grouping aggregate column may only use `SUM`, `MIN`, `MAX`, or `COUNT` — not AVG/GROUP_CONCAT/stddev.
+* `IN (...)` takes constants with optional aliases (`IN ('a' AS ColA, 'b' ColB)`) **or a subselect** (`IN (SELECT DISTINCT ...)`). Omitting IN computes distinct values automatically, but **a parameterized query requires an explicit IN list**.
+* Pivot output columns are named `value::aggAlias` (e.g. `V1::AvgScore`). Names are case-insensitive; duplicate pivot values differing only by case are an error — normalize with `LOWER()`/`UPPER()` in the query.
+* Two-level pivots are not supported; concatenate the two values into one column and pivot on that.
 
-* `jsonb_insert(jsonb, path, new_value)`: Insert a value at a given path within a JSONB object.
-* `jsonb_pretty(jsonb)`: Format a JSONB value as indented text.
-* `jsonb_set(jsonb, path, new_value)`: Set the value at a given path. Strict: returns NULL on NULL input.
-* `jsonb_set_lax(jsonb, path, new_value, null_behavior)`: Like `jsonb_set` but not strict. The `null_behavior` argument must be one of: `'raise_exception'`, `'use_json_null'`, `'delete_key'`, or `'return_target'`.
+-----
 
-#### **Path Query Functions**
+### **11. Parameterized Queries**
 
-* `jsonb_path_exists(jsonb, path)`, `jsonb_path_exists_tz(...)`: Check whether the JSON path returns any item. The `_tz` variant is timezone-aware.
-* `jsonb_path_match(jsonb, path)`, `jsonb_path_match_tz(...)`: Return the result of a JSON path predicate check.
-* `jsonb_path_query(jsonb, path)`, `jsonb_path_query_tz(...)`: Return all items matched by the JSON path.
-* `jsonb_path_query_array(jsonb, path)`, `jsonb_path_query_array_tz(...)`: Return matched items as an array.
-* `jsonb_path_query_first(jsonb, path)`, `jsonb_path_query_first_tz(...)`: Return the first matched item.
+```sql
+PARAMETERS (MinTemp DOUBLE, MinWeight DOUBLE DEFAULT 0.0)
+SELECT ParticipantID, temperature_C, weight_kg
+FROM PhysicalExam
+WHERE temperature_C >= MinTemp AND weight_kg >= MinWeight
+```
 
-#### **Not Supported**
+* Allowed types: `BIGINT, BIT, CHAR, DECIMAL, DOUBLE, FLOAT, INTEGER, LONGVARCHAR, NUMERIC, REAL, SMALLINT, TIMESTAMP, TINYINT, VARCHAR` (NUMERIC accepts precision/scale). **DATE, TIME, and BOOLEAN are not allowed** — use TIMESTAMP / BIT.
+* `DEFAULT` value must be a constant; without DEFAULT the parameter is required (NULL when unset via the API).
+* A parameter name shadows an unqualified column of the same name — qualify the column (`R.X`) to disambiguate.
+* Values are passed via the client API (e.g. `query.param.MinTemp`).
 
-The following functions are **not supported** in LabKey SQL:
-`json_populate_record`, `jsonb_populate_record`, `json_populate_recordset`, `jsonb_populate_recordset`, `json_to_record`, `jsonb_to_record`, `json_to_recordset`, `jsonb_to_recordset`.
+-----
+
+### **12. Cross-Folder Queries**
+
+Prefix the schema with a quoted folder path (user needs Reader permission in each referenced folder):
+
+```sql
+SELECT p.ParticipantID, ROUND(AVG(p.Temp_C), 1) AS AverageTemp
+FROM "/Tutorials/Demo".study."Physical Exam" p
+GROUP BY p.ParticipantID
+```
+
+`Project` refers to the current project root: `Project."SubFolder".lists.MyList`.
+
+-----
+
+### **13. Container Filters**
+
+Annotate a table in the FROM clause to broaden the query scope:
+
+```sql
+SELECT * FROM Issues [ContainerFilter='CurrentAndSubfolders'] i
+```
+
+Values: `AllFolders`, `AllInProject`, `AllInProjectPlusShared`, `Current`, `CurrentAndFirstChildren`, `CurrentAndParents`, `CurrentAndSubfolders`, `CurrentAndSubfoldersPlusShared`, `CurrentPlusProject`, `CurrentPlusProjectAndShared`.
+
+-----
 
-#### **Quick Reference for Writing LabKey SQL with JSON**
+### **14. Metadata Annotations**
 
-When writing LabKey SQL queries that work with JSON columns:
+Column annotations after a select expression override display metadata:
 
-1. **Always use `json_op()` for operators** — never use raw PostgreSQL operator syntax like `->` or `->>`. Wrap them: `json_op(col, '->>', 'key')`.
-2. **Use `parse_jsonb()` to create JSONB literals** — there is no `::jsonb` cast in LabKey SQL. Write `parse_jsonb('{"key":"value"}')`.
-3. **Use `jsonb_extract_path_text()` for nested field access** — this is often the clearest way to extract a deeply nested text value: `jsonb_extract_path_text(col, 'level1', 'level2', 'field')`.
-4. **Use `jsonb_build_object()` to construct JSON** — for building JSON from column values: `jsonb_build_object('id', rowid, 'name', label)`.
-5. **Check database type first** — these functions only work on PostgreSQL. If the target server may use MS SQL Server, do not use them.
-6. **The `validateSQL` MCP tool can verify syntax** — use it to check JSON function calls before the user saves a query.
+```sql
+SELECT ratio @hidden,
+       10/7.0 AS Num @title='Calculated Number' @format='0.00'
+```
+
+Recognized: `@title`, `@format`, `@hidden`, `@concept`, `@nolookup`, `@preservetitle`. Value syntax: `@title='x'` or `@title('x')`.
 
 -----
 
-### **10. Array Functions (PostgreSQL Only)**
+### **15. CAST**
+
+`CAST(expression AS type)`. LabKey SQL does **not** reliably check argument types at parse time — type errors surface at execution as a generic error, so cast proactively (e.g., a date stored as VARCHAR passed to a date function).
 
-LabKey SQL supports a set of array construction and comparison functions. These are **not available on MS SQL Server**. They route through dialect-specific SQL generation rather than passing through directly to PostgreSQL.
+* Target types: `TINYINT, SMALLINT, INTEGER, BIGINT, REAL, FLOAT, DOUBLE, NUMERIC, DECIMAL, BOOLEAN, BIT, CHAR, VARCHAR, LONGVARCHAR, DATE, TIME, TIMESTAMP, GUID, BINARY, VARBINARY, LONGVARBINARY`. Precision/scale on NUMERIC/DECIMAL: `CAST(n AS NUMERIC(10,2))`; length on CHAR/VARCHAR.
+* Common patterns: `CAST(stringCol AS TIMESTAMP)`, `CAST(numericCol AS VARCHAR) || ' units'`, `CAST(numerator AS DOUBLE) / denominator` (avoid integer-division truncation).
 
-#### **Construction**
+-----
 
-* `ARRAY[elem, ...]` → ARRAY: builds an array from zero or more elements of any type. Equivalent to PostgreSQL `ARRAY[...]`.
-* `TEXT_ARRAY[elem, ...]` → TEXT[]: like `ARRAY[]` but casts the result to `TEXT[]`.
+### **16. JSON and JSONB Operators and Functions (PostgreSQL Only)**
 
-#### **Element Membership**
+Not available on MS SQL Server. See the [PostgreSQL docs](https://www.postgresql.org/docs/14/functions-json.html) for semantics.
 
-* `array_contains_element(array, element)` → BOOLEAN: true if the element appears in the array. Equivalent to PostgreSQL `element = ANY(array)`. Use `NOT array_contains_element(arr, val)` for the negative — there is no separate "does not contain" function.
+#### Operators via `json_op`
 
-#### **Array-vs-Array Comparisons**
+Native operator syntax (`->`, `->>`, etc.) cannot be used. Use the `json_op` pass-through function: `json_op(left_operand, 'operator', right_operand)`.
 
-* `array_contains_all(array_a, array_b)` → BOOLEAN: true if every element of `array_b` is in `array_a`. Equivalent to PostgreSQL `array_a @> array_b`.
-* `array_contains_any(array_a, array_b)` → BOOLEAN: true if at least one element of `array_b` is in `array_a`. Equivalent to PostgreSQL `array_a && array_b`.
-* `array_contains_none(array_a, array_b)` → BOOLEAN: true if no element of `array_b` is in `array_a`.
-* `array_is_same(array_a, array_b)` → BOOLEAN: unordered set equality — both arrays contain exactly the same elements regardless of order. Use `NOT array_is_same(...)` for the negative.
+* Supported operators: `->`, `->>`, `#>`, `#>>`, `@>`, `<@`, `?`, `?|`, `?&`, `||`, `-`, `#-`
+* Examples:
+  ```sql
+  SELECT json_op(metadata, '->>', 'name') AS name_text FROM samples
+  SELECT * FROM samples WHERE json_op(metadata, '@>', parse_jsonb('{"status":"active"}'))
+  SELECT * FROM samples WHERE json_op(metadata, '?', 'name')
+  ```
 
-#### **Emptiness**
+#### Conversion / Parsing
+* `parse_json(text)`, `parse_jsonb(text)`: cast text to JSON/JSONB (instead of `::jsonb` / `CAST(... AS JSONB)`).
+* `to_json(value)`, `to_jsonb(value)`; `array_to_json(array)`; `row_to_json(value)` (scalar rows only — use `to_jsonb()` for whole-row).
 
-* `array_is_empty(array)` → BOOLEAN: true if the array has no elements. The argument must be of type ARRAY; a type mismatch is caught at query-parse time.
+#### Builders
+* `json_build_array(...)`, `jsonb_build_array(...)`; `json_build_object(k1, v1, ...)`, `jsonb_build_object(...)`; `json_object(text_array)`, `jsonb_object(text_array)`.
 
-#### **Not Supported**
+#### Query and Extraction
+* `json_array_length`, `jsonb_array_length`; `json_extract_path(json, ...)`, `jsonb_extract_path(...)`; `json_extract_path_text(...)`, `jsonb_extract_path_text(...)` (clearest for nested text values); `json_object_keys`, `jsonb_object_keys`; `json_array_elements[_text]`, `jsonb_array_elements[_text]`; `json_each`, `jsonb_each`, `json_each_text`, `jsonb_each_text` (**scalar usage only** — not usable as table sources in FROM).
 
-`array_length`, `array_append`, `array_prepend`, `array_cat`, `array_remove`, `array_replace`, `array_position`, `array_to_string`, and subscript access (`arr[n]`) are not available in LabKey SQL.
+#### Type Inspection, Cleanup, Modification
+* `json_typeof`, `jsonb_typeof`; `json_strip_nulls`, `jsonb_strip_nulls`; `jsonb_insert(jsonb, path, val)`; `jsonb_pretty(jsonb)`; `jsonb_set(jsonb, path, val)` (strict — NULL in, NULL out); `jsonb_set_lax(jsonb, path, val, null_behavior)` where null_behavior ∈ `'raise_exception' | 'use_json_null' | 'delete_key' | 'return_target'`.
 
-### **11. CAST**
+#### Path Queries
+* `jsonb_path_exists`, `jsonb_path_match`, `jsonb_path_query`, `jsonb_path_query_array`, `jsonb_path_query_first` — each with a timezone-aware `_tz` variant.
+
+#### Not Supported
+`json_populate_record`, `jsonb_populate_record`, `json_populate_recordset`, `jsonb_populate_recordset`, `json_to_record`, `jsonb_to_record`, `json_to_recordset`, `jsonb_to_recordset`.
+
+-----
 
-Use `CAST(expression AS type)` to convert a value from one type to another. **LabKey SQL's validator does not 
-reliably detect type mismatches** — errors only surface as runtime exceptions, so use CAST proactively whenever 
-there is ambiguity (e.g., a date stored as VARCHAR passed to a date/time function).
+### **17. Array Functions (PostgreSQL Only)**
 
-**Important:** PostgreSQL's `::type` shorthand (e.g., `col::integer`) is **not** supported in LabKey SQL. Always use `CAST()`.
+Not available on MS SQL Server.
 
-* **Supported target types:**
-  * Integers: `TINYINT`, `SMALLINT`, `INTEGER`, `BIGINT`
-  * Floating point: `REAL`, `FLOAT`, `DOUBLE`
-  * Fixed-point: `NUMERIC`, `DECIMAL`
-  * Boolean: `BOOLEAN`, `BIT`
-  * String: `CHAR`, `VARCHAR`, `LONGVARCHAR`
-  * Date/time: `DATE`, `TIME`, `TIMESTAMP`
-  * Other: `GUID`
+#### Construction
+* `ARRAY[elem, ...]` — builds an array. **No space between `ARRAY` and `[`.**
+* `TEXTARRAY[elem, ...]` — like `ARRAY[]` but cast to `TEXT[]`. (One word — `TEXT_ARRAY` is wrong.)
 
-* **Examples:**
-    * **String column used as a number:**
-      ```sql
-      CAST(stringCol AS DOUBLE)
-      ```
-    * **String column used as a timestamp:**
-      ```sql
-      CAST(stringCol AS TIMESTAMP)
-      ```
-    * **Number formatted as a string (e.g., for concatenation):**
-      ```sql
-      CAST(numericCol AS VARCHAR) || ' units'
-      ```
-    * **Ensuring integer division doesn't truncate:**
-      ```sql
-      CAST(numerator AS DOUBLE) / denominator
-      ```
+#### Membership and Comparison
+* `array_contains_element(array, elem)` — true if elem in array (`= ANY`). Negate with `NOT array_contains_element(...)`.
+* `array_contains_all(a, b)` — every element of b is in a (`a @> b`).
+* `array_contains_any(a, b)` — at least one element of b is in a (`a && b`).
+* `array_contains_none(a, b)` — no element of b is in a.
+* `array_is_same(a, b)` — unordered set equality.
+* `array_is_empty(a)` — argument must be an ARRAY type (checked at parse time).
+
+#### Not Supported
+`array_agg`, `array_length`, `array_append`, `array_prepend`, `array_cat`, `array_remove`, `array_replace`, `array_position`, `array_to_string`, and subscript access (`arr[n]`).
+
+-----
+
+### **18. Database Portability Notes**
+
+Most LabKey servers run PostgreSQL; some premium deployments run MS SQL Server. If the target may be MSSQL:
+
+* Avoid PostgreSQL-only features: JSON functions (§16), arrays (§17), `similar_to`/`regexp_replace`/`to_char`-family (§7), `overlaps()`, and the PG-only aggregates (§5).
+* `GROUP_CONCAT` on MSSQL requires a separately-installed function and cannot appear in a sub-select; when missing, it returns a literal `'<GROUP_CONCAT function not supported...>'` string instead of data.
+* String comparison and grouping are case-sensitive on PostgreSQL, case-insensitive on MSSQL.
+* `timestampdiff` interval limits differ (§6) — the `age*` functions are portable.
+
+-----
 
-* **Quick Reference:**
-  1. **VARCHAR passed to a date/time function** — wrap it: `CAST(col AS TIMESTAMP)`.
-  2. **Integer arithmetic truncates unexpectedly** — cast one operand to `DOUBLE`.
-  3. **Do not rely on `validateSQL` for type errors** — mismatches only appear at runtime.
\ No newline at end of file
+### **19. Common Error Messages → Fixes**
+
+Many parse errors now include an inline suggestion (e.g. `Syntax error near 'OFFSET' ... OFFSET is not supported. Use LIMIT n...` or `Unknown method TRIM. Use LTRIM(RTRIM(x)).`). When a suggestion is present, apply it directly — it is dialect-appropriate for the server that produced it.
+
+| Error | Likely cause / fix |
+| --- | --- |
+| `Syntax error near 'OFFSET'` / near `'('` after OVER | Unsupported OFFSET / window function — see §1 |
+| `Expression in Group By clause must not be a constant` | `GROUP BY 1` — repeat the expression instead |
+| `Syntax error near 'DISTINCT'` | `SUM(DISTINCT ...)` or `IS DISTINCT FROM` — see §1 |
+| `CURRENT_DATE/CURRENT_TIME/CURRENT_TIMESTAMP take no parentheses` | Drop the parens: bare `CURRENT_DATE`, not `CURRENT_DATE()` |
+| `Unknown method X` | Function doesn't exist in LabKey SQL (check §6-§7) or is dialect-specific |
+| `CONCAT function expects 2 arguments` | Use `\|\|` for 3+ values |
+| `Syntax error near 'Count'` (or other keyword) | Reserved word used as alias — double-quote it |
+| `HAVING requires an aggregate in the SELECT list` | Add the aggregate to the SELECT list or add GROUP BY |
+| `Duplicate column 'x'` | Two select items produce the same name — alias one |
+| `Ambiguous field: x` | Column exists in multiple FROM tables — qualify it |
+| `VALUES expression requires an alias` | Add `AS t` after `(VALUES ...)` |
+| `PIVOT queries must include a GROUP BY clause` | See §10 |
+| `Could not find pivot column in group by list, expression must match exactly` | GROUP BY entry must textually match the PIVOT BY column's expression |
+| `Parameter type is not supported: DATE` | Use TIMESTAMP (§11) |
+| `The underlying database does not support nested ORDER BY unless LIMIT...` (warning) | ORDER BY is being dropped — add `LIMIT` or sort via the API |
+| `ExecutingSelector; bad SQL grammar []` | Runtime (database-level) failure with no detail — usually a type mismatch (add CASTs) or a dialect-specific function limit (e.g. `timestampdiff` YEAR on PostgreSQL, `sum` over text) |
diff --git a/query/src/org/labkey/query/sql/Method.java b/query/src/org/labkey/query/sql/Method.java
index abcf8d683f6..cb47eccc5ce 100644
--- a/query/src/org/labkey/query/sql/Method.java
+++ b/query/src/org/labkey/query/sql/Method.java
@@ -27,10 +27,12 @@
 import org.labkey.api.data.CompareType;
 import org.labkey.api.data.Container;
 import org.labkey.api.data.CoreSchema;
+import org.labkey.api.data.DbScope;
 import org.labkey.api.data.JdbcType;
 import org.labkey.api.data.MethodInfo;
 import org.labkey.api.data.MutableColumnInfo;
 import org.labkey.api.data.SQLFragment;
+import org.labkey.api.data.SqlSelector;
 import org.labkey.api.data.TableInfo;
 import org.labkey.api.data.dialect.SqlDialect;
 import org.labkey.api.module.Module;
@@ -167,7 +169,7 @@ public MethodInfo getMethodInfo()
         labkeyMethod.put("cos", new JdbcMethod("cos", JdbcType.DOUBLE, 1, 1));
         labkeyMethod.put("cot", new JdbcMethod("cot", JdbcType.DOUBLE, 1, 1));
         labkeyMethod.put("curdate", new JdbcMethod("curdate", JdbcType.DATE, 0, 0));
-        labkeyMethod.put("curtime", new JdbcMethod("curtime", JdbcType.DATE, 0, 0));
+        labkeyMethod.put("curtime", new JdbcMethod("curtime", JdbcType.TIME, 0, 0));
         labkeyMethod.put("dayofmonth", new JdbcMethod("dayofmonth", JdbcType.INTEGER, 1, 1));
         labkeyMethod.put("dayofweek", new JdbcMethod("dayofweek", JdbcType.INTEGER, 1, 1));
         labkeyMethod.put("dayofyear", new JdbcMethod("dayofyear", JdbcType.INTEGER, 1, 1));
@@ -214,6 +216,22 @@ public JdbcType getJdbcType(JdbcType[] args)
                 };
             }
         });
+        labkeyMethod.put("is_distinct_from", new Method(JdbcType.BOOLEAN, 2, 2)
+        {
+            @Override
+            public MethodInfo getMethodInfo()
+            {
+                return new IsDistinctFromMethodInfo(IS);
+            }
+        });
+        labkeyMethod.put("is_not_distinct_from", new Method(JdbcType.BOOLEAN, 2, 2)
+        {
+            @Override
+            public MethodInfo getMethodInfo()
+            {
+                return new IsDistinctFromMethodInfo(IS_NOT);
+            }
+        });
         labkeyMethod.put("isequal", new Method("isequal", JdbcType.BOOLEAN, 2, 2)
         {
             @Override
@@ -1843,24 +1861,6 @@ public SQLFragment getSQL(SqlDialect dialect, SQLFragment[] arguments)
         postgresMethods.put("jsonb_path_query_tz", new PassthroughMethod("jsonb_path_query_tz", JdbcType.VARCHAR, 2, 4));
         postgresMethods.put("jsonb_path_query_array_tz", new PassthroughMethod("jsonb_path_query_array_tz", JdbcType.VARCHAR, 2, 4));
         postgresMethods.put("jsonb_path_query_first_tz", new PassthroughMethod("jsonb_path_query_first_tz", JdbcType.VARCHAR, 2, 4));
-
-        // "is distinct from" and "is not distinct from" operators in method form
-        labkeyMethod.put("is_distinct_from", new Method(JdbcType.BOOLEAN, 2, 2)
-        {
-            @Override
-            public MethodInfo getMethodInfo()
-            {
-                return new IsDistinctFromMethodInfo(IS);
-            }
-        });
-        labkeyMethod.put("is_not_distinct_from", new Method(JdbcType.BOOLEAN, 2, 2)
-        {
-            @Override
-            public MethodInfo getMethodInfo()
-            {
-                return new IsDistinctFromMethodInfo(IS_NOT);
-            }
-        });
     }
 
     private static class IsDistinctFromMethodInfo extends AbstractMethodInfo
@@ -1876,13 +1876,37 @@ private static class IsDistinctFromMethodInfo extends AbstractMethodInfo
         @Override
         public SQLFragment getSQL(SqlDialect dialect, SQLFragment[] arguments)
         {
+            SQLFragment a = arguments[0];
+            SQLFragment b = arguments[1];
             SQLFragment ret = new SQLFragment();
-            ret.append(" ((").append(arguments[0]).append(")");
-            if (token == IS)
-                ret.append(" IS DISTINCT FROM ");
+
+            if (dialect.supportsNativeIsDistinctFrom())
+            {
+                ret.append(" ((").append(a).append(")");
+                if (token == IS)
+                    ret.append(" IS DISTINCT FROM ");
+                else
+                    ret.append(" IS NOT DISTINCT FROM ");
+                ret.append("(").append(b).append(")) ");
+            }
             else
-                ret.append(" IS NOT DISTINCT FROM ");
-            ret.append("(").append(arguments[1]).append(")) ");
+            {
+                // "IS [NOT] DISTINCT FROM" isn't standard/portable SQL -- it's native only on PostgreSQL-family and
+                // Snowflake dialects (and recent SQL Server). Elsewhere rewrite as a CASE expression that always
+                // evaluates to a real TRUE/FALSE -- never NULL, even when exactly one side is null -- so it behaves
+                // the same as the native predicate would.
+
+                // This is more complicated than the obvious (a=b or a is null and b is null).
+                // That expression can return NULL, we need to return only TRUE/FALSE.
+                if (token == IS)
+                    ret.append(" NOT ");
+                ret.append("(");
+                ret.append("((").append(a).append(") IS NOT NULL AND (").append(b).append(") IS NOT NULL AND (").append(a).append(")=(").append(b).append("))");
+                ret.append(" OR ");
+                ret.append("((").append(a).append(") IS NULL AND (").append(b).append(") IS NULL)");
+                ret.append(")");
+            }
+
             return ret;
         }
     }
@@ -2013,5 +2037,60 @@ public void testSimpleString()
             assertNotSimpleString(new SQLFragment("SELECT 'test'"));
             assertNotSimpleString(new SQLFragment("'test''string'"));
         }
+
+        // Exercises both the native and portable-fallback branches of IsDistinctFromMethodInfo.getSQL() against every
+        // dialect that's actually connected in this environment, not just whichever dialect the current CI leg happens
+        // to be running against. A FROM-less SELECT works everywhere except Oracle, which requires FROM DUAL.
+        //
+        // Covers both usage contexts: as a selected boolean value (where three-valued logic would otherwise leak NULL
+        // for the one-null-argument case) and as a WHERE clause filter (where three-valued logic normally treats NULL
+        // as non-matching, so this instead confirms the CASE-based rewrite still evaluates to a real TRUE/FALSE there).
+        @Test
+        public void testIsDistinctFrom()
+        {
+            record Case(String a, String b, boolean distinct) {}
+            List<Case> cases = List.of(
+                new Case("1", "2", true),
+                new Case("1", "1", false),
+                new Case("NULL", "NULL", false),
+                new Case("1", "NULL", true)
+            );
+
+            for (DbScope scope : DbScope.getDbScopesToTest())
+            {
+                SqlDialect d = scope.getSqlDialect();
+
+                for (Case c : cases)
+                {
+                    assertIsDistinctFrom(scope, d, IS, c.a(), c.b(), c.distinct());
+                    assertIsDistinctFrom(scope, d, IS_NOT, c.a(), c.b(), !c.distinct());
+                    assertIsDistinctFromWhere(scope, d, IS, c.a(), c.b(), c.distinct());
+                    assertIsDistinctFromWhere(scope, d, IS_NOT, c.a(), c.b(), !c.distinct());
+                }
+            }
+        }
+
+        private void assertIsDistinctFrom(DbScope scope, SqlDialect d, int token, String a, String b, boolean expected)
+        {
+            SQLFragment expr = new IsDistinctFromMethodInfo(token).getSQL(d, new SQLFragment[]{new SQLFragment(a), new SQLFragment(b)});
+            SQLFragment T = new SQLFragment(d.getBooleanTRUE()), F = new SQLFragment(d.getBooleanFALSE());
+            SQLFragment sql = new SQLFragment("SELECT ").append("CASE WHEN ").append(expr).append(" THEN ").append(T).append(" ELSE ").append(F).append(" END");
+            if (d.isOracle())
+                sql.append(" FROM DUAL");
+            Boolean result = new SqlSelector(scope, sql).getObject(Boolean.class);
+            assertEquals(d.getClass().getSimpleName() + ": " + sql.toDebugString(), expected, result);
+        }
+
+        private void assertIsDistinctFromWhere(DbScope scope, SqlDialect d, int token, String a, String b, boolean expected)
+        {
+            SQLFragment expr = new IsDistinctFromMethodInfo(token).getSQL(d, new SQLFragment[]{new SQLFragment(a), new SQLFragment(b)});
+            SQLFragment sql = new SQLFragment("SELECT 1");
+            if (d.isOracle())
+                sql.append(" FROM DUAL");
+            sql.append(" WHERE ").append(expr);
+
+            boolean matched = new SqlSelector(scope, sql).exists();
+            assertEquals(d.getClass().getSimpleName() + " (WHERE): " + sql.toDebugString(), expected, matched);
+        }
     }
 }
diff --git a/query/src/org/labkey/query/sql/QMethodCall.java b/query/src/org/labkey/query/sql/QMethodCall.java
index 1de51edf65d..65dfe69b6ae 100644
--- a/query/src/org/labkey/query/sql/QMethodCall.java
+++ b/query/src/org/labkey/query/sql/QMethodCall.java
@@ -139,7 +139,9 @@ public QueryParseException fieldCheck(QNode parent, SqlDialect d)
     {
         if (getMethod(d) == null)
         {
-            return new QueryParseException("Unknown method " + getField().getName(), null, getLine(), getColumn());
+            String name = getField().getName();
+            String hint = SqlParser.forUnknownMethod(name, d);
+            return new QueryParseException("Unknown method " + name + (null == hint ? "" : ". " + hint), null, getLine(), getColumn());
         }
         return null;
     }
diff --git a/query/src/org/labkey/query/sql/SqlBase.g b/query/src/org/labkey/query/sql/SqlBase.g
index 72c652d9de7..28cb905d5be 100644
--- a/query/src/org/labkey/query/sql/SqlBase.g
+++ b/query/src/org/labkey/query/sql/SqlBase.g
@@ -57,9 +57,6 @@ tokens
 @lexer::header
 {
 	package org.labkey.query.sql.antlr;
-
-    import org.apache.logging.log4j.Logger;
-    import org.apache.logging.log4j.LogManager;
 }
 
 
@@ -134,17 +131,14 @@ tokens
 
 @lexer::members
 {
-    Logger _log = LogManager.getLogger(org.labkey.query.sql.SqlParser.class);
-    
     protected void setPossibleID(boolean possibleID)
     {
     }
 
-    @Override
-    public void emitErrorMessage(String msg)
-    {
-        _log.debug(msg);
-    }
+    // NOTE: lexer errors are reported via reportError(), which SqlParser._SqlLexer overrides to collect
+    // them as parse errors. Always use _SqlLexer rather than instantiating SqlBaseLexer directly -- the
+    // default ANTLR emitErrorMessage() prints unmatchable input to System.err and then drops it, letting
+    // the remaining characters re-lex into a different, valid-looking query.
 }
 
 
@@ -180,6 +174,9 @@ REGR_SXY : 'regr_sxy';
 REGR_SYY : 'regr_syy';
 COUNT : 'count';
 CROSS : 'cross';
+CURRENT_DATE : 'current_date';
+CURRENT_TIME : 'current_time';
+CURRENT_TIMESTAMP : 'current_timestamp';
 DELETE : 'delete';
 DISTINCT : 'distinct';
 DOT : '.';
@@ -761,6 +758,10 @@ starAtom
 primaryExpression
 	:   ARRAY exprList ']' -> ^(METHOD_CALL IDENT["ARRAY_CONSTRUCT"] exprList)
 	|   TEXTARRAY exprList ']' -> ^(METHOD_CALL IDENT["TEXTARRAY_CONSTRUCT"] exprList)
+	// SQL-standard niladic datetime keywords -- no parens allowed; sugar for curdate()/curtime()/now()
+	|   CURRENT_DATE -> ^(METHOD_CALL IDENT["CURDATE"] ^(EXPR_LIST))
+	|   CURRENT_TIME -> ^(METHOD_CALL IDENT["CURTIME"] ^(EXPR_LIST))
+	|   CURRENT_TIMESTAMP -> ^(METHOD_CALL IDENT["NOW"] ^(EXPR_LIST))
 	|   id=identPrimary
 	|   constant
 	|   OPEN! ( expression | subQuery) CLOSE!
diff --git a/query/src/org/labkey/query/sql/SqlParser.java b/query/src/org/labkey/query/sql/SqlParser.java
index 62d84726a6d..7cd2730c5d3 100644
--- a/query/src/org/labkey/query/sql/SqlParser.java
+++ b/query/src/org/labkey/query/sql/SqlParser.java
@@ -17,8 +17,10 @@
 package org.labkey.query.sql;
 
 import org.antlr.runtime.ANTLRStringStream;
+import org.antlr.runtime.CharStream;
 import org.antlr.runtime.CommonToken;
 import org.antlr.runtime.CommonTokenStream;
+import org.antlr.runtime.MismatchedTokenException;
 import org.antlr.runtime.MissingTokenException;
 import org.antlr.runtime.ParserRuleReturnScope;
 import org.antlr.runtime.RecognitionException;
@@ -35,6 +37,7 @@
 import org.junit.Test;
 import org.labkey.api.collections.CaseInsensitiveHashSet;
 import org.labkey.api.data.Container;
+import org.labkey.api.data.CoreSchema;
 import org.labkey.api.data.JdbcType;
 import org.labkey.api.data.dialect.SqlDialect;
 import org.labkey.api.module.Module;
@@ -433,9 +436,10 @@ else if (null != warnings)
                     errors.add(new QueryParseException("This does not look like a WITH, SELECT or UNION query", null, 0, 0));
             }
 
+            CommonTokenStream tokens = parser.getTokenStream() instanceof CommonTokenStream cts ? cts : null;
             for (Throwable e : _parseErrors)
             {
-                errors.add(wrapParseException(e));
+                errors.add(wrapParseException(e, tokens));
             }
 
             if (null != _root)
@@ -517,9 +521,10 @@ public QExpr parseExpr(String str, boolean constExpression, List<? super QueryPa
                 _root = qnodeRoot instanceof QExpr ? (QExpr) qnodeRoot : null;
             }
 
+            CommonTokenStream tokens = parser.getTokenStream() instanceof CommonTokenStream cts ? cts : null;
             for (Throwable e : _parseErrors)
             {
-                errors.add(wrapParseException(e));
+                errors.add(wrapParseException(e, tokens));
             }
             return (QExpr)_root;
         }
@@ -717,7 +722,7 @@ static public boolean isLegalIdentifier(String str)
     static private final Set<String> keywords = new CaseInsensitiveHashSet(PageFlowUtil.set(
             "all","any","and","as","asc","avg",
             "between","both",
-            "case","class","count",
+            "case","class","count","current_date","current_time","current_timestamp",
             "delete","desc","distinct",
             "elements","else","empty","end","escape","except","exists",
             "false","fetch","from","full",
@@ -739,6 +744,12 @@ static public boolean isLegalIdentifier(String str)
 
 
     static QueryParseException wrapParseException(Throwable e)
+    {
+        return wrapParseException(e, null);
+    }
+
+
+    static QueryParseException wrapParseException(Throwable e, @Nullable CommonTokenStream tokens)
     {
         if (e instanceof QueryParseException)
         {
@@ -750,7 +761,7 @@ static QueryParseException wrapParseException(Throwable e)
 //        }
         else if (e instanceof RecognitionException re)
         {
-            String message = formatRecognitionException(re);
+            String message = formatRecognitionException(re, tokens);
             return new QueryParseException(message, re, re.line, re.charPositionInLine);
         }
         else if (e instanceof RuntimeException)
@@ -761,7 +772,7 @@ else if (e instanceof RuntimeException)
     }
 
 
-    static String formatRecognitionException(RecognitionException re)
+    static String formatRecognitionException(RecognitionException re, @Nullable CommonTokenStream tokens)
     {
         String message = re.getMessage();
         if (null != message)
@@ -769,14 +780,22 @@ static String formatRecognitionException(RecognitionException re)
 
         String missing = null;
         String near = null;
-        
+
         if (null != re.token)
             near = re.token.getText();
+        else if (re.c < 0)
+            near = "<EOF>";     // lexer error at end of input (e.g. unterminated string literal)
+        else if (re.c > 0)
+            near = String.valueOf((char)re.c);      // lexer error: no token, but we know the offending character
         if (re instanceof MissingTokenException mte)
         {
             if (null != mte.inserted)
                 missing = tokenName(((CommonToken)mte.inserted).getType());
         }
+        else if (re instanceof MismatchedTokenException mte && null == re.token && mte.expecting > 0)
+        {
+            missing = String.valueOf((char)mte.expecting);      // lexer error: expected character
+        }
 
         if (null != near)
             message = "Syntax error near '" + near + "'";
@@ -784,10 +803,137 @@ static String formatRecognitionException(RecognitionException re)
             message = "Syntax error";
         if (null != missing)
             message += ", expected '" + missing + "'";
+
+        // append a targeted hint when the failure looks like a recognizable unsupported construct
+        String hint = forSyntaxError(re, tokens);
+        if (null != hint)
+            message += ". " + hint;
         return message;
     }
 
 
+    /**
+     * Suggestions for common standard-SQL constructs that LabKey SQL does not support. Authors (and AI assistants)
+     * regularly reach for window functions, OFFSET, EXTRACT, ILIKE, etc.; the generic "Syntax error near '...'" gives
+     * them no way to converge on working LabKey SQL, so we append a targeted hint when the failure looks recognizable.
+     *
+     * These hints are consulted ONLY after a parse error has already occurred, keyed off the token ANTLR blames (with a
+     * little look-behind for constructs where the blamed token is generic). None of the trigger words are reserved in
+     * LabKey SQL -- most are legal identifiers -- so this method must never influence what parses; message text only.
+     */
+    @Nullable
+    static String forSyntaxError(RecognitionException re, @Nullable CommonTokenStream tokens)
+    {
+        if (null == re.token || null == re.token.getText())
+            return null;
+        String near = re.token.getText().toLowerCase();
+        String prev1 = previousToken(tokens, re.token, 1);
+        String prev2 = previousToken(tokens, re.token, 2);
+        String prev3 = previousToken(tokens, re.token, 3);
+
+        switch (near)
+        {
+            case "offset":
+                return "OFFSET is not supported. Use LIMIT n; apply paging via the client API (maxRows/offset).";
+            case "fetch":
+                return "FETCH FIRST is not supported. Use LIMIT n.";
+            case "ilike":
+                return "ILIKE is not supported. Use LOWER(x) LIKE LOWER(pattern).";
+            case "using":
+                return "JOIN ... USING is not supported. Use JOIN ... ON a.col = b.col.";
+            case "nulls":
+                return "NULLS FIRST/LAST is not supported. Try ORDER BY x IS NULL, x.";
+            case ":":
+                return "The '::' cast syntax is not supported. Use CAST(expr AS TYPE).";
+            case "(":
+                // "MAX(a) OVER (...)" parses OVER as a column alias, so the '(' gets the blame
+                if ("over".equals(prev1))
+                    return "Window functions (OVER) are not supported in LabKey SQL.";
+                if ("filter".equals(prev1))
+                    return "FILTER is not supported. Use an aggregate over CASE: SUM(CASE WHEN condition THEN 1 ELSE 0 END).";
+                // "JOIN S USING (x)" parses USING as the table alias, so the '(' gets the blame
+                if ("using".equals(prev1))
+                    return "JOIN ... USING is not supported. Use JOIN ... ON a.col = b.col.";
+                // "CURRENT_DATE()" -- these are niladic keywords, not functions, so the trailing '(' is unexpected
+                if ("current_date".equals(prev1) || "current_time".equals(prev1) || "current_timestamp".equals(prev1))
+                    return "CURRENT_DATE/CURRENT_TIME/CURRENT_TIMESTAMP take no parentheses; use them as bare keywords.";
+                return null;
+            case "distinct":
+                if ("is".equals(prev1) || "not".equals(prev1))
+                    return "IS [NOT] DISTINCT FROM is not supported. Use is_distinct_from(a, b) or is_not_distinct_from(a, b).";
+                if ("(".equals(prev1))
+                    return "DISTINCT is only supported inside COUNT() and GROUP_CONCAT().";
+                return null;
+            case "from":
+                // "EXTRACT(YEAR FROM d)" parses as a method call, so the FROM gets the blame
+                if ("(".equals(prev2) && "extract".equals(prev3))
+                    return "EXTRACT is not supported. Use YEAR(), MONTH(), DAYOFMONTH(), HOUR(), etc.";
+                return null;
+            default:
+                if (near.startsWith("'") && "interval".equals(prev1))
+                    return "INTERVAL literals are not supported. Use TIMESTAMPADD('SQL_TSI_DAY', n, ts) and TIMESTAMPDIFF().";
+                // "SELECT TOP 10 a FROM R" parses TOP as an expression, so the blame lands on a later token
+                if (("top".equals(prev1) && "select".equals(prev2)) || ("top".equals(prev2) && "select".equals(prev3)))
+                    return "TOP is not supported. Use LIMIT n at the end of the statement.";
+                return null;
+        }
+    }
+
+
+    @Nullable
+    private static String previousToken(@Nullable CommonTokenStream tokens, Token t, int back)
+    {
+        if (null == tokens)
+            return null;
+        int i = t.getTokenIndex();
+        if (i < back || i >= tokens.size())
+            return null;
+        Token p = tokens.get(i - back);
+        return null == p || null == p.getText() ? null : p.getText().toLowerCase();
+    }
+
+
+    // Suggestions for unrecognized method names, keyed by lower-cased name. These entries are valid on both
+    // databases; dialect-specific suggestions live in forUnknownMethod(). Some entries (len, charindex, instr)
+    // are dialect-specific methods that resolve on one database and land here on the other.
+    private static final Map<String, String> methodHints = Map.ofEntries(
+            Map.entry("position", "Use LOCATE(substring, string[, start])."),
+            Map.entry("extract", "Use YEAR(), MONTH(), DAYOFMONTH(), HOUR(), etc."),
+            Map.entry("string_agg", "Use GROUP_CONCAT([DISTINCT] expr[, separator])."),
+            Map.entry("nvl", "Use COALESCE(a, b) or IFNULL(a, b)."),
+            Map.entry("isnull", "Use IFNULL(a, b) or COALESCE(a, b)."),
+            Map.entry("iif", "Use CASE WHEN condition THEN a ELSE b END."),
+            Map.entry("if", "Use CASE WHEN condition THEN a ELSE b END."),
+            Map.entry("datediff", "Use TIMESTAMPDIFF('SQL_TSI_DAY', ts1, ts2) or AGE()/age_in_days()."),
+            Map.entry("dateadd", "Use TIMESTAMPADD('SQL_TSI_DAY', n, ts)."),
+            Map.entry("date_part", "Use YEAR(), MONTH(), DAYOFMONTH(), HOUR(), etc."),
+            Map.entry("day", "Use DAYOFMONTH(date)."),
+            Map.entry("len", "Use LENGTH(string)."),
+            Map.entry("instr", "Use LOCATE(substring, string)."),
+            Map.entry("charindex", "Use LOCATE(substring, string)."),
+            Map.entry("getdate", "Use NOW()."),
+            Map.entry("sysdate", "Use NOW().")
+    );
+
+    /**
+     * The suggestion should simply be appropriate for the current dialect -- never name a database product.
+     * A null dialect (expression parsing, tests) gets the portable suggestion.
+     */
+    @Nullable
+    static String forUnknownMethod(String name, @Nullable SqlDialect dialect)
+    {
+        boolean pg = null != dialect && dialect.isPostgreSQL();
+        return switch (name.toLowerCase())
+        {
+            case "trim" -> pg ? "Use btrim(x) or LTRIM(RTRIM(x))." : "Use LTRIM(RTRIM(x)).";
+            case "substring_index" -> pg ? "Use split_part(string, delimiter, n)." : null;
+            case "regexp_like", "regexp_matches" -> pg ? "Use similar_to(x, pattern) or regexp_replace(x, pattern, replacement)." : "Use LIKE with wildcards.";
+            case "date_trunc" -> pg ? "Use CAST(ts AS DATE) for day granularity, or to_char(ts, format)." : "Use CAST(ts AS DATE) for day granularity.";
+            default -> methodHints.get(name.toLowerCase());
+        };
+    }
+
+
     public static String tokenName(int type)
     {
         return switch (type)
@@ -1159,7 +1305,10 @@ else if (divisorType== SqlBaseParser.NUM_DOUBLE || divisorType== SqlBaseParser.N
                     catch (IllegalArgumentException x)
                     {
                         if (failOnUnrecognizedMethodName)
-                            _parseErrors.add(new QueryParseException("Unknown method " + name, null, id.getLine(), id.getColumn()));
+                        {
+                            String hint = forUnknownMethod(name, _dialect);
+                            _parseErrors.add(new QueryParseException("Unknown method " + name + (null == hint ? "" : ". " + hint), null, id.getLine(), id.getColumn()));
+                        }
                     }
                 }
                 break;
@@ -1727,6 +1876,30 @@ public int LA(int i)
     }
 
 
+    /**
+     * The default ANTLR lexer error handling prints unmatchable input to System.err and then drops it,
+     * letting the remaining characters re-lex into a different, valid-looking query (e.g.
+     * "{d'2001-02-03'}" -- missing the space after "{d" -- evaluated as 2001-02-03 = 1996 and swallowed
+     * the rest of the statement). Collect lexer errors so they surface as parse errors instead.
+     */
+    private static class _SqlLexer extends SqlBaseLexer
+    {
+        private final ArrayList<Exception> _errors;
+
+        _SqlLexer(CharStream input, ArrayList<Exception> errors)
+        {
+            super(input);
+            _errors = errors;
+        }
+
+        @Override
+        public void reportError(RecognitionException e)
+        {
+            _errors.add(e);
+        }
+    }
+
+
     private static class _SqlParser extends SqlBaseParser implements AutoCloseable
     {
         ArrayList<Exception> _errors;
@@ -1748,7 +1921,7 @@ public _SqlParser(String str, ArrayList<Exception> errors)
         public void reset(String str, ArrayList<Exception> errors)
         {
             _errors = errors;
-            setTokenStream(new CommonTokenStream(new SqlBaseLexer(new CaseInsensitiveStringStream(str))));
+            setTokenStream(new CommonTokenStream(new _SqlLexer(new CaseInsensitiveStringStream(str), errors)));
         }
 
         @Override
@@ -2062,6 +2235,9 @@ class delete elements fetch indices insert into limit new set update versioned b
         "SELECT TIMESTAMPDIFF('SQL_TSI_Second',a,b), TIMESTAMPDIFF('Second',a,b), TIMESTAMPDIFF('SQL_TSI_Day',a,b), TIMESTAMPDIFF('Day',a,b) FROM R",
         "SELECT TIMESTAMPADD(SQL_TSI_SECOND,1,b), TIMESTAMPADD(SECOND,1,b), TIMESTAMPADD('SQL_TSI_DAY',1,b), TIMESTAMPADD('DAY',1,b) FROM R",
 
+        // date/timestamp literals (JDBC escape syntax; note the space after {d and {ts is required)
+        "SELECT {d '2001-02-03'} AS d, {ts '2001-02-03 04:05:06'} AS ts FROM R",
+
         "SELECT (SELECT value FROM S WHERE S.x=R.x) AS V FROM R",
         "SELECT R.value AS V FROM R WHERE R.y > (SELECT MAX(S.y) FROM S WHERE S.x=R.x)",
         "SELECT R.value, T.a, T.b FROM R INNER JOIN (SELECT S.a, S.b FROM S) T ON R.z=T.z",
@@ -2129,6 +2305,15 @@ class delete elements fetch indices insert into limit new set update versioned b
         "SELECT a, GROUP_CONCAT(b, '%$', 'STUPID') FROM R GROUP BY a",
         "SELECT a, GROUP_CONCAT() FROM R GROUP BY a",
 
+        // lexer errors must be reported, not silently dropped (see _SqlLexer)
+        // missing space after {d used to evaluate as arithmetic (2001-02-03 = 1996) and swallow the rest of the statement
+        "SELECT {d'2001-02-03'} AS d FROM R",
+        "SELECT {ts'2001-02-03 04:05:06'} AS ts FROM R",
+        // unmatchable character used to be dropped, silently parsing as "SELECT a b FROM R"
+        "SELECT a # b FROM R",
+        // unterminated string literal
+        "SELECT a FROM R WHERE a = 'unterminated",
+
         "BROKEN",
             
         // empty select list
@@ -2143,6 +2328,39 @@ class delete elements fetch indices insert into limit new set update versioned b
         "SELECT * FROM (WITH peeps AS (SELECT * FROM study.participant) SELECT * FROM peeps)"
     };
 
+    // unsupported standard-SQL constructs that should fail with a targeted hint (see forSyntaxError() above):
+    // sql -> expected substring of the error message
+    static List<Pair<String, String>> hintSql = Arrays.asList(
+        new Pair<>("SELECT a FROM R LIMIT 5 OFFSET 10", "OFFSET is not supported"),
+        new Pair<>("SELECT a FROM R ORDER BY a FETCH FIRST 5 ROWS ONLY", "FETCH FIRST is not supported"),
+        new Pair<>("SELECT ROW_NUMBER() OVER (ORDER BY a) FROM R", "Window functions"),
+        new Pair<>("SELECT SUM(x) OVER (PARTITION BY a) FROM R", "Window functions"),
+        new Pair<>("SELECT COUNT(*) FILTER (WHERE a > 0) FROM R", "FILTER is not supported"),
+        new Pair<>("SELECT a FROM R WHERE a ILIKE 'x%'", "ILIKE is not supported"),
+        new Pair<>("SELECT a FROM R JOIN S USING (x)", "USING is not supported"),
+        new Pair<>("SELECT a FROM R ORDER BY a NULLS LAST", "NULLS FIRST/LAST is not supported"),
+        new Pair<>("SELECT a::INTEGER FROM R", "CAST(expr AS TYPE)"),
+        new Pair<>("SELECT SUM(DISTINCT a) FROM R", "DISTINCT is only supported inside COUNT()"),
+        new Pair<>("SELECT a FROM R WHERE a IS DISTINCT FROM b", "is_distinct_from"),
+        new Pair<>("SELECT a FROM R WHERE a IS NOT DISTINCT FROM b", "is_distinct_from"),
+        new Pair<>("SELECT EXTRACT(YEAR FROM d) FROM R", "EXTRACT is not supported"),
+        new Pair<>("SELECT d + INTERVAL '1 day' FROM R", "INTERVAL literals are not supported"),
+        new Pair<>("SELECT TOP 10 a FROM R", "TOP is not supported"),
+        new Pair<>("SELECT CURRENT_DATE() FROM R", "take no parentheses"),
+        new Pair<>("SELECT CURRENT_TIME() FROM R", "take no parentheses"),
+        new Pair<>("SELECT CURRENT_TIMESTAMP() FROM R", "take no parentheses")
+    );
+
+    // unrecognized method names that should fail with a suggested replacement (see forUnknownMethod() above)
+    static List<Pair<String, String>> methodHintSql = Arrays.asList(
+        new Pair<>("SELECT POSITION('a' IN b) FROM R", "LOCATE"),
+        new Pair<>("SELECT DATEDIFF('day', a, b) FROM R", "TIMESTAMPDIFF"),
+        new Pair<>("SELECT ISNULL(a, b) FROM R", "IFNULL"),
+        new Pair<>("SELECT DAY(a) FROM R", "DAYOFMONTH"),
+        new Pair<>("SELECT STRING_AGG(a, ',') FROM R", "GROUP_CONCAT"),
+        new Pair<>("SELECT TRIM(a) FROM R", "LTRIM(RTRIM")
+    );
+
     @SuppressWarnings("JUnitMalformedDeclaration")
     public static class SqlParserTestCase extends Assert
     {
@@ -2203,6 +2421,9 @@ public static class SqlParserTestCase extends Assert
             new Pair<>("a.b","(. a b)"),
             new Pair<>("a.b.fn(5)","(METHOD_CALL (. (. a b) fn) (EXPR_LIST 5))"),
             new Pair<>("CURDATE()","(METHOD_CALL CURDATE EXPR_LIST)"),
+            new Pair<>("CURRENT_DATE","(METHOD_CALL CURDATE EXPR_LIST)"),
+            new Pair<>("CURRENT_TIME","(METHOD_CALL CURTIME EXPR_LIST)"),
+            new Pair<>("CURRENT_TIMESTAMP","(METHOD_CALL NOW EXPR_LIST)"),
             new Pair<>("LCASE('a')","(METHOD_CALL LCASE (EXPR_LIST 'a'))"),
             new Pair<>("AGE(a,b)", "(METHOD_CALL AGE (EXPR_LIST a b))"),
             new Pair<>("SUM(a+b)","(SUM (+ a b))"),
@@ -2229,7 +2450,13 @@ public static class SqlParserTestCase extends Assert
             new Pair<>("1 + 2.1", JdbcType.DECIMAL),
             new Pair<>("ROUND(0.0,1)", JdbcType.DOUBLE),
             new Pair<>("1 + ROUND(0.0,1)", JdbcType.DOUBLE),
-            new Pair<>("CASE WHEN TRUE THEN ROUND(0.0,1) ELSE ROUND(0.0,1) END", JdbcType.DOUBLE)
+            new Pair<>("CASE WHEN TRUE THEN ROUND(0.0,1) ELSE ROUND(0.0,1) END", JdbcType.DOUBLE),
+            new Pair<>("CURDATE()", JdbcType.DATE),
+            new Pair<>("CURTIME()", JdbcType.TIME),
+            new Pair<>("NOW()", JdbcType.TIMESTAMP),
+            new Pair<>("CURRENT_DATE", JdbcType.DATE),
+            new Pair<>("CURRENT_TIME", JdbcType.TIME),
+            new Pair<>("CURRENT_TIMESTAMP", JdbcType.TIMESTAMP)
         );
 
 
@@ -2357,6 +2584,46 @@ public void testSql()
             _log.trace("SqlParser.testSql(): {}", DateUtil.formatDuration(end - start));
         }
 
+        @Test
+        public void testSyntaxHints()
+        {
+            for (Pair<String, String> test : hintSql)
+            {
+                List<QueryParseException> errors = new ArrayList<>();
+                new SqlParser().parseQuery(test.first, errors, null);
+                assertFalse("expected a parse error: " + test.first, errors.isEmpty());
+                assertTrue("expected error containing <<" + test.second + ">> for: " + test.first + "\nfound: " + errors.getFirst().getMessage(),
+                        errors.stream().anyMatch(e -> StringUtils.contains(e.getMessage(), test.second)));
+            }
+        }
+
+        @Test
+        public void testUnknownMethodHints()
+        {
+            for (Pair<String, String> test : methodHintSql)
+            {
+                List<QueryParseException> errors = new ArrayList<>();
+                new SqlParser().setFailOnUnrecognizedMethodName(true).parseQuery(test.first, errors, null);
+                assertFalse("expected a parse error: " + test.first, errors.isEmpty());
+                assertTrue("expected error containing <<" + test.second + ">> for: " + test.first + "\nfound: " + errors.getFirst().getMessage(),
+                        errors.stream().anyMatch(e -> StringUtils.contains(e.getMessage(), test.second)));
+            }
+        }
+
+        @Test
+        public void testDialectMethodHints()
+        {
+            // the suggestion should be appropriate for the current dialect and never name a database product
+            SqlDialect d = CoreSchema.getInstance().getSqlDialect();
+            List<QueryParseException> errors = new ArrayList<>();
+            new SqlParser(d, null).setFailOnUnrecognizedMethodName(true).parseQuery("SELECT TRIM(a) FROM R", errors, null);
+            assertFalse(errors.isEmpty());
+            String message = errors.getFirst().getMessage();
+            assertTrue(message, StringUtils.contains(message, "LTRIM(RTRIM"));
+            assertEquals(message, d.isPostgreSQL(), StringUtils.contains(message, "btrim"));
+            assertFalse(message, StringUtils.containsIgnoreCase(message, "postgres"));
+        }
+
         @Test
         public void testPrecedence() throws SQLException
         {