feat(parser): Snowflake time-travel AT/BEFORE/CHANGES (#483)

[ajitpratap0]

Summary

Adds Snowflake time-travel / change-tracking clauses on table references.

What now parses

• `SELECT * FROM users AT (TIMESTAMP => '2024-01-01'::TIMESTAMP)`
• `SELECT * FROM users AT (OFFSET => -300)`
• `SELECT * FROM users AT (STATEMENT => '')`
• `SELECT * FROM users BEFORE (STATEMENT => '')`
• `SELECT * FROM users CHANGES (INFORMATION => DEFAULT)`
• `SELECT * FROM users CHANGES (INFORMATION => DEFAULT) AT (TIMESTAMP => ...)` — chained
• Time-travel + trailing alias: `FROM users AT (...) t WHERE t.id = 1`

Implementation

• AST: new `TimeTravelClause` node with `Kind` (AT/BEFORE/CHANGES), a `Named` map of `name => expr` arguments (upper-cased keys like TIMESTAMP, OFFSET, STATEMENT, INFORMATION), and `Chained` for the CHANGES+AT combination. Attached to `TableReference.TimeTravel`. `TableReference.Children()` descends into it.
• Parser: new `parseSnowflakeTimeTravel` / `parseOneTimeTravelClause` helpers in `pivot.go`. Permissive about argument-name token types (TIMESTAMP, OFFSET, STATEMENT tokenize as their own keywords, not identifiers) and about value tokens (INFORMATION => DEFAULT uses a bare keyword value).
• Dispatch: `isSnowflakeTimeTravelStart` helper detects AT/BEFORE/CHANGES followed by `(`. Wired into `parseFromTableReference` after the table name and also used as a guard in the FROM-alias parser so these keywords aren't consumed as table aliases.

Test plan

• `TestSnowflakeTimeTravel`: 7 shapes covering AT/BEFORE/CHANGES, all three argument kinds, chained CHANGES+AT, trailing alias
• `TestSnowflakeTimeTravelASTShape`: asserts the `TimeTravelClause` is reachable via Children() and exposes `Kind` + `Named[TIMESTAMP]`
• `go test -race ./pkg/sql/parser/ ./pkg/sql/ast/ ./pkg/gosqlx/` green

Part of #483.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gosqlx-website	Ready	Preview, Comment	Apr 8, 2026 2:15pm

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

Code Review Complete ✅

I've completed a comprehensive review of the Snowflake time-travel feature implementation. Here's my detailed feedback:

Review Tasks

• Analyze AST changes and structure
• Review parser implementation
• Check test coverage and quality
• Assess code quality and best practices
• Look for potential bugs or security issues
• Evaluate performance considerations

---

✅ Excellent Implementation Quality

This is a well-designed and thoroughly implemented feature that follows the project's established patterns and conventions.

Code Quality & Best Practices

🟢 AST Design (ast.go:2036-2070)

• Clean TimeTravelClause structure with proper separation of concerns
• Smart use of map[string]Expression for named arguments with upper-cased keys
• Proper Children() implementation for tree traversal
• Good chaining support via Chained []*TimeTravelClause

🟢 Parser Implementation (pivot.go:282-377)

• Well-structured parsing with clear separation: parseSnowflakeTimeTravel() → parseOneTimeTravelClause()
• Robust error handling with descriptive messages
• Proper dialect gating (p.dialect != string(keywords.DialectSnowflake))
• Smart token lookahead for disambiguation (p.peekToken().Token.Type == models.TokenTypeLParen)

🟢 Integration (select_subquery.go:102-108)

• Clean integration into table reference parsing flow
• Proper placement after table function parsing but before alias parsing
• Consistent with existing pattern for optional clauses

Security & Robustness

🟢 No Security Concerns

• No SQL injection risks - uses proper AST expression parsing
• No exposed secrets or sensitive information
• Input validation through parser bounds checking

🟢 Error Handling

• Comprehensive error messages: "( after " + kind, "=> after " + argName
• Proper token type validation before advancing
• Graceful fallback for malformed input

Performance Considerations

🟢 Efficient Implementation

• Minimal lookahead operations (single token peek)
• Reuses existing expression parsing infrastructure
• No unnecessary allocations in hot paths
• Proper integration with object pooling system

Test Coverage

🟢 Comprehensive Test Suite (snowflake_time_travel_test.go)

• 7 test cases covering all syntax variations:
  • AT with TIMESTAMP, OFFSET, STATEMENT
  • BEFORE with STATEMENT
  • CHANGES with INFORMATION
  • Chained CHANGES + AT
  • Table aliases after time-travel clauses
• AST verification test ensures proper tree integration
• Good use of map-driven tests for maintainability

Minor Suggestions

1. Consider adding bounds validation for OFFSET values (negative numbers are valid, but extremely large values might be worth flagging)

2. Performance: The strings.ToUpper() calls in the parsing loop could potentially be optimized by using a lookup map for known argument names, though this is likely premature optimization given the small set of valid arguments.

3. Documentation: Consider adding examples in the AST struct comments showing the map structure for different argument types.

Strengths

✅ Follows Project Conventions: Consistent with existing PIVOT/UNPIVOT and temporal clause patterns
✅ Proper Dialect Gating: Snowflake-specific features properly isolated
✅ Excellent Error Messages: Clear, context-aware error reporting
✅ Comprehensive Testing: Good coverage of edge cases and AST integration
✅ Clean Architecture: Well-separated concerns between parsing and AST representation
✅ Future-Proof Design: Chaining support anticipates complex time-travel scenarios

Verdict

This is production-ready code that demonstrates solid software engineering practices. The implementation is clean, well-tested, and integrates seamlessly with the existing codebase architecture. I would approve this PR without hesitation.

---

Job run

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

Code Review Complete ✅

I've completed a comprehensive review of the Snowflake time-travel feature implementation. Here's my detailed feedback:

Review Tasks

• Analyze AST changes and structure
• Review parser implementation
• Check test coverage and quality
• Assess code quality and best practices
• Look for potential bugs or security issues
• Evaluate performance considerations

---

✅ Excellent Implementation Quality

This is a well-designed and thoroughly implemented feature that follows the project's established patterns and conventions.

Code Quality & Best Practices

🟢 AST Design (ast.go:2036-2070)

• Clean TimeTravelClause structure with proper separation of concerns
• Smart use of map[string]Expression for named arguments with upper-cased keys
• Proper Children() implementation for tree traversal
• Good chaining support via Chained []*TimeTravelClause

🟢 Parser Implementation (pivot.go:282-377)

• Well-structured parsing with clear separation: parseSnowflakeTimeTravel() → parseOneTimeTravelClause()
• Robust error handling with descriptive messages
• Proper dialect gating (p.dialect != string(keywords.DialectSnowflake))
• Smart token lookahead for disambiguation (p.peekToken().Token.Type == models.TokenTypeLParen)

🟢 Integration (select_subquery.go:102-108)

• Clean integration into table reference parsing flow
• Proper placement after table function parsing but before alias parsing
• Consistent with existing pattern for optional clauses

Security & Robustness

🟢 No Security Concerns

• No SQL injection risks - uses proper AST expression parsing
• No exposed secrets or sensitive information
• Input validation through parser bounds checking

🟢 Error Handling

• Comprehensive error messages: "( after " + kind, "=> after " + argName
• Proper token type validation before advancing
• Graceful fallback for malformed input

Performance Considerations

🟢 Efficient Implementation

• Minimal lookahead operations (single token peek)
• Reuses existing expression parsing infrastructure
• No unnecessary allocations in hot paths
• Proper integration with object pooling system

Test Coverage

🟢 Comprehensive Test Suite (snowflake_time_travel_test.go)

• 7 test cases covering all syntax variations:
  • AT with TIMESTAMP, OFFSET, STATEMENT
  • BEFORE with STATEMENT
  • CHANGES with INFORMATION
  • Chained CHANGES + AT
  • Table aliases after time-travel clauses
• AST verification test ensures proper tree integration
• Good use of map-driven tests for maintainability

Minor Suggestions

1. Consider adding bounds validation for OFFSET values (negative numbers are valid, but extremely large values might be worth flagging)

2. Performance: The strings.ToUpper() calls in the parsing loop could potentially be optimized by using a lookup map for known argument names, though this is likely premature optimization given the small set of valid arguments.

3. Documentation: Consider adding examples in the AST struct comments showing the map structure for different argument types.

Strengths

✅ Follows Project Conventions: Consistent with existing PIVOT/UNPIVOT and temporal clause patterns
✅ Proper Dialect Gating: Snowflake-specific features properly isolated
✅ Excellent Error Messages: Clear, context-aware error reporting
✅ Comprehensive Testing: Good coverage of edge cases and AST integration
✅ Clean Architecture: Well-separated concerns between parsing and AST representation
✅ Future-Proof Design: Chaining support anticipates complex time-travel scenarios

Verdict

This is production-ready code that demonstrates solid software engineering practices. The implementation is clean, well-tested, and integrates seamlessly with the existing codebase architecture. I would approve this PR without hesitation.

---

Job run

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

Code Review Complete ✅

I've completed a comprehensive review of the Snowflake time-travel feature implementation. Here's my detailed feedback:

Review Tasks

• Analyze AST changes and structure
• Review parser implementation
• Check test coverage and quality
• Assess code quality and best practices
• Look for potential bugs or security issues
• Evaluate performance considerations

---

✅ Excellent Implementation Quality

This is a well-designed and thoroughly implemented feature that follows the project's established patterns and conventions.

Code Quality & Best Practices

🟢 AST Design (ast.go:2036-2070)

• Clean TimeTravelClause structure with proper separation of concerns
• Smart use of map[string]Expression for named arguments with upper-cased keys
• Proper Children() implementation for tree traversal
• Good chaining support via Chained []*TimeTravelClause

🟢 Parser Implementation (pivot.go:282-377)

• Well-structured parsing with clear separation: parseSnowflakeTimeTravel() → parseOneTimeTravelClause()
• Robust error handling with descriptive messages
• Proper dialect gating (p.dialect != string(keywords.DialectSnowflake))
• Smart token lookahead for disambiguation (p.peekToken().Token.Type == models.TokenTypeLParen)

🟢 Integration (select_subquery.go:102-108)

• Clean integration into table reference parsing flow
• Proper placement after table function parsing but before alias parsing
• Consistent with existing pattern for optional clauses

Security & Robustness

🟢 No Security Concerns

• No SQL injection risks - uses proper AST expression parsing
• No exposed secrets or sensitive information
• Input validation through parser bounds checking

🟢 Error Handling

• Comprehensive error messages: "( after " + kind, "=> after " + argName
• Proper token type validation before advancing
• Graceful fallback for malformed input

Performance Considerations

🟢 Efficient Implementation

• Minimal lookahead operations (single token peek)
• Reuses existing expression parsing infrastructure
• No unnecessary allocations in hot paths
• Proper integration with object pooling system

Test Coverage

🟢 Comprehensive Test Suite (snowflake_time_travel_test.go)

• 7 test cases covering all syntax variations:
  • AT with TIMESTAMP, OFFSET, STATEMENT
  • BEFORE with STATEMENT
  • CHANGES with INFORMATION
  • Chained CHANGES + AT
  • Table aliases after time-travel clauses
• AST verification test ensures proper tree integration
• Good use of map-driven tests for maintainability

Minor Suggestions

1. Consider adding bounds validation for OFFSET values (negative numbers are valid, but extremely large values might be worth flagging)

2. Performance: The strings.ToUpper() calls in the parsing loop could potentially be optimized by using a lookup map for known argument names, though this is likely premature optimization given the small set of valid arguments.

3. Documentation: Consider adding examples in the AST struct comments showing the map structure for different argument types.

Strengths

✅ Follows Project Conventions: Consistent with existing PIVOT/UNPIVOT and temporal clause patterns
✅ Proper Dialect Gating: Snowflake-specific features properly isolated
✅ Excellent Error Messages: Clear, context-aware error reporting
✅ Comprehensive Testing: Good coverage of edge cases and AST integration
✅ Clean Architecture: Well-separated concerns between parsing and AST representation
✅ Future-Proof Design: Chaining support anticipates complex time-travel scenarios

Verdict

This is production-ready code that demonstrates solid software engineering practices. The implementation is clean, well-tested, and integrates seamlessly with the existing codebase architecture. I would approve this PR without hesitation.

---

Job run