Support DuckDB USING SAMPLE sizes and methods

DuckDB writes the sample size first and the method behind it:
USING SAMPLE 10%, USING SAMPLE 10 PERCENT (bernoulli),
USING SAMPLE 10 ROWS (system, 377), USING SAMPLE reservoir (50 ROWS).
The method is now optional, RESERVOIR is a known method, and a bare
sample size accepts a unit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EqinwHBKuAtPEmtXr3b5P2

Author: hayssams

src/main/java/net/sf/jsqlparser/statement/select/SampleClause.java

@@ -17,6 +17,7 @@ public class SampleClause {
     private Number percentageArgument;
     private String percentageUnit;
     private boolean argumentInBrackets = true;
+    private boolean methodInBrackets = false;
     // ClickHouse specific
     private Number offsetArgument;
     private Number repeatArgument;
@@ -130,10 +131,23 @@ public SampleClause setMethod(String method) {
         return this;
     }
 
+    /**
+     * DuckDB writes the sampling method behind the sample size:
+     * {@code USING SAMPLE 10 PERCENT (bernoulli)}.
+     */
+    public boolean isMethodInBrackets() {
+        return methodInBrackets;
+    }
+
+    public SampleClause setMethodInBrackets(boolean methodInBrackets) {
+        this.methodInBrackets = methodInBrackets;
+        return this;
+    }
+
     public StringBuilder appendTo(StringBuilder builder) {
 
         builder.append(" ").append(keyword);
-        if (method != null) {
+        if (method != null && !methodInBrackets) {
             builder.append(" ").append(method);
         }
 
@@ -144,11 +158,20 @@ public StringBuilder appendTo(StringBuilder builder) {
             } else {
                 builder.append(" ").append(percentageArgument);
                 if (percentageUnit != null) {
-                    builder.append(" ").append(percentageUnit);
+                    // "10%" has no blank, "10 PERCENT" and "10 ROWS" do
+                    builder.append("%".equals(percentageUnit) ? "" : " ").append(percentageUnit);
                 }
             }
         }
 
+        if (methodInBrackets) {
+            builder.append(" (").append(method);
+            if (seedArgument != null) {
+                builder.append(", ").append(seedArgument);
+            }
+            builder.append(")");
+        }
+
         if (offsetArgument != null) {
             builder.append(" OFFSET ").append(offsetArgument);
         }
@@ -157,7 +180,7 @@ public StringBuilder appendTo(StringBuilder builder) {
             builder.append(" REPEATABLE (").append(repeatArgument).append(")");
         }
 
-        if (seedArgument != null) {
+        if (seedArgument != null && !methodInBrackets) {
             builder.append(" SEED (").append(seedArgument).append(")");
         }
 
@@ -189,7 +212,7 @@ public String toString() {
     }
 
     public enum SampleMethod {
-        BERNOULLI, SYSTEM, BLOCK;
+        BERNOULLI, SYSTEM, BLOCK, RESERVOIR;
 
         public static SampleMethod from(String sampleMethod) {
             return Enum.valueOf(SampleMethod.class,

src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

@@ -1211,6 +1211,12 @@ public class CCJSqlParser extends AbstractJSqlParser<CCJSqlParser> {
         return isReservedKeywordSafeByFollower();
     }
 
+    /** DuckDB sampling methods, which are ordinary identifiers except for SYSTEM/BERNOULLI. */
+    private boolean isSampleMethod(Token token) {
+        return token.kind == K_SYSTEM || token.kind == K_BERNOULLI
+                || (token.image != null && "RESERVOIR".equalsIgnoreCase(token.image));
+    }
+
     /** DuckDB's INSERT ... BY NAME|POSITION column matching, never a table alias. */
     private boolean isColumnMatchingAhead() {
         return getToken(1).kind == K_BY
@@ -5871,6 +5877,7 @@ SampleClause SampleClause():
     Number offsetArgument = null;
     Number repeatArgument=null;
     Number seedArgument=null;
+    boolean methodInBrackets = false;
 }
 {
     (
@@ -5887,9 +5894,13 @@ SampleClause SampleClause():
         )
         |
         (
-            // Duck DB
+            // Duck DB: the method is optional and may follow the sample size instead
             <K_USING> <K_SAMPLE> { keyword = "USING SAMPLE"; }
-            ( token = <K_SYSTEM> | token = <K_BERNOULLI> ) { method = token.image; }
+            [
+                LOOKAHEAD({ isSampleMethod(getToken(1)) })
+                ( token = <K_SYSTEM> | token = <K_BERNOULLI> | token = <S_IDENTIFIER> )
+                { method = token.image; }
+            ]
         )
     )
 
@@ -5909,12 +5920,34 @@ SampleClause SampleClause():
         [ LOOKAHEAD(2) <K_SEED> "(" seedArgument = Number() ")" ]
         |
         percentageArgument = Number() { argumentInBrackets = false; }
+        // greedy: a unit directly after the sample size always belongs to the clause
+        [
+            LOOKAHEAD(1)
+            (
+                "%" { percentageUnit="%"; }
+                |
+                <K_PERCENT> { percentageUnit="PERCENT"; }
+                |
+                <K_ROWS> { percentageUnit="ROWS"; }
+            )
+        ]
         [ LOOKAHEAD(2) <K_OFFSET> offsetArgument = Number() ]
     )
 
+    // DuckDB: USING SAMPLE 10 PERCENT (bernoulli[, seed])
+    [
+        LOOKAHEAD({ method == null && getToken(1).kind == OPENING_BRACKET
+                && isSampleMethod(getToken(2)) })
+        "(" ( token = <K_SYSTEM> | token = <K_BERNOULLI> | token = <S_IDENTIFIER> )
+        { method = token.image; methodInBrackets = true; }
+        [ "," seedArgument = Number() ]
+        ")"
+    ]
+
     {
         sampleClause = new SampleClause(keyword, method, percentageArgument, percentageUnit, repeatArgument, seedArgument);
         sampleClause.setArgumentInBrackets(argumentInBrackets);
+        sampleClause.setMethodInBrackets(methodInBrackets);
         sampleClause.setOffsetArgument(offsetArgument);
         return sampleClause;
     }

src/test/java/net/sf/jsqlparser/statement/select/DuckDBTest.java

@@ -142,4 +142,38 @@ void testInsertWithoutColumnMatching() throws JSQLParserException {
 
         Assertions.assertNull(insert.getColumnMatching());
     }
+
+    @Test
+    void testUsingSamplePercentShorthand() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM t USING SAMPLE 10%";
+        PlainSelect select = (PlainSelect) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+        SampleClause sampleClause = select.getFromItem().getSampleClause();
+
+        Assertions.assertEquals("%", sampleClause.getPercentageUnit());
+        Assertions.assertNull(sampleClause.getMethod());
+    }
+
+    @Test
+    void testUsingSamplePercentWithMethodInBrackets() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM t USING SAMPLE 10 PERCENT (bernoulli)";
+        PlainSelect select = (PlainSelect) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertEquals(SampleClause.SampleMethod.BERNOULLI,
+                select.getFromItem().getSampleClause().getMethod());
+    }
+
+    @Test
+    void testUsingSampleRowsWithSeed() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM t USING SAMPLE 10 ROWS (system, 377)";
+        TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+    }
+
+    @Test
+    void testUsingSampleReservoir() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM t USING SAMPLE reservoir (50 ROWS)";
+        PlainSelect select = (PlainSelect) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertEquals(SampleClause.SampleMethod.RESERVOIR,
+                select.getFromItem().getSampleClause().getMethod());
+    }
 }