feat(parser): add ClickHouse SAMPLE clause support (#454)

Parse SAMPLE <ratio|count|N/D> [OFFSET N/D] after FROM in ClickHouse
dialect. Adds SampleClause AST node and sampleSQL formatter function.

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

Author: 2 people

pkg/formatter/render.go

@@ -238,6 +238,11 @@ func renderSelect(s *ast.SelectStatement, opts ast.FormatOptions) string {
 		sb.WriteString(joinSQL(&j))
 	}
 
+	if s.Sample != nil {
+		sb.WriteString(f.clauseSep())
+		sb.WriteString(sampleSQL(s.Sample, f))
+	}
+
 	if s.Where != nil {
 		sb.WriteString(f.clauseSep())
 		sb.WriteString(f.kw("WHERE"))
@@ -1188,6 +1193,29 @@ func tableRefSQL(t *ast.TableReference) string {
 	return sb.String()
 }
 
+// sampleSQL renders a ClickHouse SAMPLE clause.
+func sampleSQL(s *ast.SampleClause, f *nodeFormatter) string {
+	var sb strings.Builder
+	sb.WriteString(f.kw("SAMPLE"))
+	sb.WriteString(" ")
+	sb.WriteString(s.Value)
+	if s.Denominator != "" {
+		sb.WriteString("/")
+		sb.WriteString(s.Denominator)
+	}
+	if s.Offset != "" {
+		sb.WriteString(" ")
+		sb.WriteString(f.kw("OFFSET"))
+		sb.WriteString(" ")
+		sb.WriteString(s.Offset)
+		if s.OffsetDenominator != "" {
+			sb.WriteString("/")
+			sb.WriteString(s.OffsetDenominator)
+		}
+	}
+	return sb.String()
+}
+
 // joinSQL renders a JOIN clause.
 func joinSQL(j *ast.JoinClause) string {
 	var sb strings.Builder

pkg/sql/ast/ast.go

@@ -396,7 +396,8 @@ type SelectStatement struct {
 	From              []TableReference
 	TableName         string // Added for pool operations
 	Joins             []JoinClause
-	PrewhereClause    Expression // ClickHouse PREWHERE clause (applied before WHERE, before reading data)
+	PrewhereClause    Expression    // ClickHouse PREWHERE clause (applied before WHERE, before reading data)
+	Sample            *SampleClause // ClickHouse SAMPLE clause (comes after FROM/FINAL, before PREWHERE)
 	Where             Expression
 	GroupBy           []Expression
 	Having            Expression
@@ -2022,3 +2023,32 @@ func (c ConnectByClause) Children() []Node {
 	}
 	return nil
 }
+
+// SampleClause represents a ClickHouse SAMPLE clause on a SELECT statement.
+//
+// ClickHouse supports three sampling forms:
+//
+//	SAMPLE 0.1         — ratio (10% of data)
+//	SAMPLE 1000        — approximate row count
+//	SAMPLE 1/10        — fraction (1 part out of 10)
+//	SAMPLE 1/10 OFFSET 2/10 — fraction with offset
+//
+// The clause is dialect-specific to ClickHouse (and partly Snowflake/Redshift
+// via TABLESAMPLE, but this implementation targets SAMPLE).
+// Value is stored as a raw string to preserve the original representation
+// (e.g., "0.1", "1000", "1/10").
+type SampleClause struct {
+	// Value is the sampling size/ratio as a raw token string (e.g., "0.1", "1000", "1/10").
+	Value string
+	// Denominator is set when the fraction form "N/D" is used (denominator part).
+	Denominator string
+	// Offset is the optional OFFSET fraction (e.g., "2/10" in SAMPLE 1/10 OFFSET 2/10).
+	Offset string
+	// OffsetDenominator is set for fractional offsets.
+	OffsetDenominator string
+	Pos               models.Location
+}
+
+func (s *SampleClause) expressionNode()     {}
+func (s SampleClause) TokenLiteral() string { return "SAMPLE" }
+func (s SampleClause) Children() []Node     { return nil }

pkg/sql/parser/select.go

@@ -87,6 +87,13 @@ func (p *Parser) parseSelectStatement() (ast.Statement, error) {
 		TableName:         tableName,
 	}
 
+	// SAMPLE (ClickHouse-specific, specifies sampling rate/size; comes after FROM/FINAL)
+	if p.dialect == string(keywords.DialectClickHouse) && p.isTokenMatch("SAMPLE") {
+		if selectStmt.Sample, err = p.parseSampleClause(); err != nil {
+			return nil, err
+		}
+	}
+
 	// PREWHERE (ClickHouse-specific, applied before WHERE for early data filtering)
 	if p.dialect == string(keywords.DialectClickHouse) {
 		if selectStmt.PrewhereClause, err = p.parsePrewhereClause(); err != nil {

pkg/sql/parser/select_clauses.go

@@ -301,6 +301,88 @@ func (p *Parser) parseJoinCondition(joinType string, isNatural, isApply bool) (a
 	return nil, p.expectedError("ON or USING")
 }
 
+// parseSampleClause parses the ClickHouse SAMPLE clause that specifies data sampling.
+// It is called when the current token is SAMPLE (already verified by caller).
+//
+// Supported forms:
+//
+//	SAMPLE 0.1              — ratio (floating-point fraction, e.g., 10%)
+//	SAMPLE 1000             — approximate row count (integer)
+//	SAMPLE 1/10             — fractional form (numerator/denominator)
+//	SAMPLE 1/10 OFFSET 2/10 — fractional with an offset fraction
+func (p *Parser) parseSampleClause() (*ast.SampleClause, error) {
+	samplePos := p.currentLocation()
+	p.advance() // Consume SAMPLE
+
+	if p.isType(models.TokenTypeEOF) || p.isType(models.TokenTypeSemicolon) {
+		return nil, goerrors.ExpectedTokenError(
+			"sampling size after SAMPLE",
+			p.currentToken.Token.Type.String(),
+			p.currentLocation(),
+			"SAMPLE clause requires a numeric argument",
+		)
+	}
+
+	clause := &ast.SampleClause{Pos: samplePos}
+
+	// Read the primary sampling value (numerator / whole number / float)
+	if !p.isNumericLiteral() {
+		return nil, goerrors.ExpectedTokenError(
+			"numeric literal after SAMPLE",
+			p.currentToken.Token.Type.String(),
+			p.currentLocation(),
+			"SAMPLE clause requires a numeric argument (ratio, row count, or N/D fraction)",
+		)
+	}
+	clause.Value = p.currentToken.Token.Value
+	p.advance()
+
+	// Check for fractional form: SAMPLE N / D
+	if p.isType(models.TokenTypeDiv) {
+		p.advance() // consume /
+		if !p.isNumericLiteral() {
+			return nil, goerrors.ExpectedTokenError(
+				"denominator after /",
+				p.currentToken.Token.Type.String(),
+				p.currentLocation(),
+				"SAMPLE N/D fraction requires an integer denominator",
+			)
+		}
+		clause.Denominator = p.currentToken.Token.Value
+		p.advance()
+	}
+
+	// Optional OFFSET N/D
+	if p.isTokenMatch("OFFSET") {
+		p.advance() // Consume OFFSET
+		if !p.isNumericLiteral() {
+			return nil, goerrors.ExpectedTokenError(
+				"numeric literal after SAMPLE ... OFFSET",
+				p.currentToken.Token.Type.String(),
+				p.currentLocation(),
+				"SAMPLE OFFSET requires a numeric argument",
+			)
+		}
+		clause.Offset = p.currentToken.Token.Value
+		p.advance()
+		if p.isType(models.TokenTypeDiv) {
+			p.advance() // consume /
+			if !p.isNumericLiteral() {
+				return nil, goerrors.ExpectedTokenError(
+					"denominator after OFFSET /",
+					p.currentToken.Token.Type.String(),
+					p.currentLocation(),
+					"SAMPLE OFFSET N/D fraction requires an integer denominator",
+				)
+			}
+			clause.OffsetDenominator = p.currentToken.Token.Value
+			p.advance()
+		}
+	}
+
+	return clause, nil
+}
+
 // parsePrewhereClause parses "PREWHERE <expr>" if present (ClickHouse-specific).
 // PREWHERE is a ClickHouse optimisation that filters data blocks before reading
 // all columns. It is semantically similar to WHERE but executed earlier in the