add horizon join support (#9)

Author: emrberk

src/autocomplete/provider.ts

@@ -43,9 +43,7 @@ const TABLE_NAME_TOKENS = new Set([
  * Built once at provider creation time so per-request ranking is O(N×M)
  * rather than O(N×C).
  */
-function buildColumnIndex(
-  schema: SchemaInfo,
-): Map<string, Set<string>> {
+function buildColumnIndex(schema: SchemaInfo): Map<string, Set<string>> {
   const index = new Map<string, Set<string>>()
   for (const table of schema.tables) {
     const key = table.name.toLowerCase()
@@ -98,8 +96,8 @@ function rankTableSuggestions(
     if (score === undefined) continue
     s.priority =
       score === referencedColumns.size
-        ? SuggestionPriority.High    // full match
-        : SuggestionPriority.Medium  // partial match
+        ? SuggestionPriority.High // full match
+        : SuggestionPriority.Medium // partial match
   }
 }
 

src/parser/ast.ts

@@ -840,6 +840,7 @@ export interface JoinClause extends AstNode {
     | "lt"
     | "splice"
     | "window"
+    | "horizon"
   outer?: boolean
   table: TableRef
   on?: Expression
@@ -849,6 +850,12 @@ export interface JoinClause extends AstNode {
   range?: { start: WindowJoinBound; end: WindowJoinBound }
   /** INCLUDE/EXCLUDE PREVAILING clause for WINDOW JOIN */
   prevailing?: "include" | "exclude"
+  /** RANGE FROM/TO/STEP for HORIZON JOIN */
+  horizonRange?: { from: string; to: string; step: string }
+  /** LIST offsets for HORIZON JOIN */
+  horizonList?: string[]
+  /** Alias for the horizon pseudo-table */
+  horizonAlias?: string
 }
 
 export interface WindowJoinBound extends AstNode {

src/parser/cst-types.d.ts

@@ -259,6 +259,7 @@ export type JoinClauseCstChildren = {
   asofLtJoin?: AsofLtJoinCstNode[];
   spliceJoin?: SpliceJoinCstNode[];
   windowJoin?: WindowJoinCstNode[];
+  horizonJoin?: HorizonJoinCstNode[];
   standardJoin?: StandardJoinCstNode[];
 };
 
@@ -311,6 +312,42 @@ export type WindowJoinCstChildren = {
   Exclude?: IToken[];
 };
 
+export interface HorizonJoinCstNode extends CstNode {
+  name: "horizonJoin";
+  children: HorizonJoinCstChildren;
+}
+
+export type HorizonJoinCstChildren = {
+  Horizon: IToken[];
+  Join: IToken[];
+  tableName: TableNameCstNode[];
+  As?: (IToken)[];
+  identifier?: (IdentifierCstNode)[];
+  Identifier?: IToken[];
+  On?: IToken[];
+  expression?: ExpressionCstNode[];
+  Range?: IToken[];
+  From?: IToken[];
+  horizonOffset?: (HorizonOffsetCstNode)[];
+  To?: IToken[];
+  Step?: IToken[];
+  List?: IToken[];
+  LParen?: IToken[];
+  Comma?: IToken[];
+  RParen?: IToken[];
+};
+
+export interface HorizonOffsetCstNode extends CstNode {
+  name: "horizonOffset";
+  children: HorizonOffsetCstChildren;
+}
+
+export type HorizonOffsetCstChildren = {
+  Minus?: IToken[];
+  DurationLiteral?: IToken[];
+  NumberLiteral?: IToken[];
+};
+
 export interface StandardJoinCstNode extends CstNode {
   name: "standardJoin";
   children: StandardJoinCstChildren;
@@ -2417,6 +2454,8 @@ export interface ICstNodeVisitor<IN, OUT> extends ICstVisitor<IN, OUT> {
   asofLtJoin(children: AsofLtJoinCstChildren, param?: IN): OUT;
   spliceJoin(children: SpliceJoinCstChildren, param?: IN): OUT;
   windowJoin(children: WindowJoinCstChildren, param?: IN): OUT;
+  horizonJoin(children: HorizonJoinCstChildren, param?: IN): OUT;
+  horizonOffset(children: HorizonOffsetCstChildren, param?: IN): OUT;
   standardJoin(children: StandardJoinCstChildren, param?: IN): OUT;
   windowJoinBound(children: WindowJoinBoundCstChildren, param?: IN): OUT;
   durationExpression(children: DurationExpressionCstChildren, param?: IN): OUT;

src/parser/lexer.ts

@@ -101,6 +101,7 @@ import {
   Group,
   Groups,
   Header,
+  Horizon,
   Hour,
   Hours,
   Http,
@@ -229,6 +230,7 @@ import {
   Splice,
   Squash,
   StandardConformingStrings,
+  Step,
   Start,
   StatisticsEnabled,
   String,
@@ -389,6 +391,7 @@ export {
   Group,
   Groups,
   Header,
+  Horizon,
   Hour,
   Hours,
   Http,
@@ -517,6 +520,7 @@ export {
   Splice,
   Squash,
   StandardConformingStrings,
+  Step,
   Start,
   StatisticsEnabled,
   String,

src/parser/parser.ts

@@ -310,6 +310,8 @@ import {
   LongLiteral,
   DecimalLiteral,
   Window,
+  Horizon,
+  Step,
   Ignore,
   Respect,
   Nulls,
@@ -818,6 +820,7 @@ class QuestDBParser extends CstParser {
       { ALT: () => this.SUBRULE(this.asofLtJoin) },
       { ALT: () => this.SUBRULE(this.spliceJoin) },
       { ALT: () => this.SUBRULE(this.windowJoin) },
+      { ALT: () => this.SUBRULE(this.horizonJoin) },
       { ALT: () => this.SUBRULE(this.standardJoin) },
     ])
   })
@@ -879,6 +882,72 @@ class QuestDBParser extends CstParser {
     })
   })
 
+  // HORIZON JOIN: tableName alias [ON expr] (RANGE FROM/TO/STEP | LIST (...)) AS alias
+  // Uses tableName + custom alias instead of tableRef to avoid ambiguity
+  // between implicit keyword aliases and RANGE/LIST/ON keywords.
+  private horizonJoin = this.RULE("horizonJoin", () => {
+    this.CONSUME(Horizon)
+    this.CONSUME(Join)
+    this.SUBRULE(this.tableName)
+    // Table alias (mandatory): explicit (AS <id>) or implicit (bare Identifier only, not keywords)
+    this.OR1([
+      {
+        ALT: () => {
+          this.CONSUME(As)
+          this.SUBRULE(this.identifier)
+        },
+      },
+      {
+        // Implicit alias: only base Identifier, never keywords like RANGE/LIST
+        ALT: () => this.CONSUME(Identifier),
+      },
+    ])
+    this.OPTION(() => {
+      this.CONSUME(On)
+      this.SUBRULE(this.expression)
+    })
+    this.OR2([
+      {
+        // RANGE FROM <offset> TO <offset> STEP <offset> AS <alias>
+        ALT: () => {
+          this.CONSUME(Range)
+          this.CONSUME(From)
+          this.SUBRULE(this.horizonOffset)
+          this.CONSUME(To)
+          this.SUBRULE1(this.horizonOffset)
+          this.CONSUME(Step)
+          this.SUBRULE2(this.horizonOffset)
+          this.CONSUME1(As)
+          this.SUBRULE1(this.identifier)
+        },
+      },
+      {
+        // LIST (<offset>, ...) AS <alias>
+        ALT: () => {
+          this.CONSUME(List)
+          this.CONSUME(LParen)
+          this.SUBRULE3(this.horizonOffset)
+          this.MANY(() => {
+            this.CONSUME(Comma)
+            this.SUBRULE4(this.horizonOffset)
+          })
+          this.CONSUME(RParen)
+          this.CONSUME2(As)
+          this.SUBRULE2(this.identifier)
+        },
+      },
+    ])
+  })
+
+  // Horizon offset value: optional minus sign + DurationLiteral | NumberLiteral
+  private horizonOffset = this.RULE("horizonOffset", () => {
+    this.OPTION(() => this.CONSUME(Minus))
+    this.OR([
+      { ALT: () => this.CONSUME(DurationLiteral) },
+      { ALT: () => this.CONSUME(NumberLiteral) },
+    ])
+  })
+
   // Standard joins: (INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER] | CROSS)? JOIN + ON
   private standardJoin = this.RULE("standardJoin", () => {
     this.OPTION(() => {

src/parser/toSql.ts

@@ -373,6 +373,24 @@ function joinToSql(join: AST.JoinClause): string {
     )
   }
 
+  if (join.horizonRange) {
+    parts.push("RANGE FROM")
+    parts.push(join.horizonRange.from)
+    parts.push("TO")
+    parts.push(join.horizonRange.to)
+    parts.push("STEP")
+    parts.push(join.horizonRange.step)
+  }
+
+  if (join.horizonList) {
+    parts.push("LIST (" + join.horizonList.join(", ") + ")")
+  }
+
+  if (join.horizonAlias) {
+    parts.push("AS")
+    parts.push(escapeIdentifier(join.horizonAlias))
+  }
+
   return parts.join(" ")
 }
 

src/parser/tokens.ts

@@ -229,9 +229,9 @@ export const IDENTIFIER_KEYWORD_NAMES = new globalThis.Set([
   "Capacity",
   "Cancel",
   "Prevailing",
+  "Range",
   "Writer",
   "Materialized",
-  "Range",
   "Snapshot",
   "Unlock",
   "Refresh",
@@ -350,7 +350,6 @@ export const IDENTIFIER_KEYWORD_NAMES = new globalThis.Set([
   "Every",
   "Prev",
   "Linear",
-  "Horizon",
   "Step",
 ])
 
@@ -481,6 +480,7 @@ export const Grant = getToken("Grant")
 export const Group = getToken("Group")
 export const Groups = getToken("Groups")
 export const Header = getToken("Header")
+export const Horizon = getToken("Horizon")
 export const Http = getToken("Http")
 export const If = getToken("If")
 export const Ignore = getToken("Ignore")
@@ -581,6 +581,7 @@ export const Snapshot = getToken("Snapshot")
 export const Splice = getToken("Splice")
 export const Squash = getToken("Squash")
 export const StandardConformingStrings = getToken("StandardConformingStrings")
+export const Step = getToken("Step")
 export const Start = getToken("Start")
 export const StatisticsEnabled = getToken("StatisticsEnabled")
 export const Suspend = getToken("Suspend")

src/parser/visitor.ts

@@ -139,6 +139,8 @@ import type {
   SimpleSelectCstChildren,
   SnapshotStatementCstChildren,
   SpliceJoinCstChildren,
+  HorizonJoinCstChildren,
+  HorizonOffsetCstChildren,
   StandardJoinCstChildren,
   StatementCstChildren,
   StatementsCstChildren,
@@ -659,6 +661,7 @@ class QuestDBVisitor extends BaseVisitor {
     if (ctx.asofLtJoin) return this.visit(ctx.asofLtJoin) as AST.JoinClause
     if (ctx.spliceJoin) return this.visit(ctx.spliceJoin) as AST.JoinClause
     if (ctx.windowJoin) return this.visit(ctx.windowJoin) as AST.JoinClause
+    if (ctx.horizonJoin) return this.visit(ctx.horizonJoin) as AST.JoinClause
     return this.visit(ctx.standardJoin!) as AST.JoinClause
   }
 
@@ -711,6 +714,60 @@ class QuestDBVisitor extends BaseVisitor {
     return result
   }
 
+  horizonJoin(ctx: HorizonJoinCstChildren): AST.JoinClause {
+    // Build TableRef from tableName + alias
+    const tableRef: AST.TableRef = {
+      type: "tableRef",
+      table: this.visit(ctx.tableName) as AST.QualifiedName,
+    }
+    if (ctx.Identifier) {
+      // Implicit alias (bare identifier, not a keyword)
+      tableRef.alias = ctx.Identifier[0].image
+    } else if (ctx.identifier && ctx.identifier.length > 1) {
+      // Explicit alias (AS <id>): first identifier is table alias, last is horizon alias
+      tableRef.alias = (
+        this.visit(ctx.identifier[0]) as AST.QualifiedName
+      ).parts[0]
+    }
+
+    const result: AST.JoinClause = {
+      type: "join",
+      joinType: "horizon",
+      table: tableRef,
+    }
+    if (ctx.expression) {
+      result.on = this.visit(ctx.expression) as AST.Expression
+    }
+    if (ctx.Range) {
+      // RANGE form: horizonOffset[0]=from, [1]=to, [2]=step
+      const offsets = ctx.horizonOffset!
+      result.horizonRange = {
+        from: this.visit(offsets[0]) as string,
+        to: this.visit(offsets[1]) as string,
+        step: this.visit(offsets[2]) as string,
+      }
+    } else if (ctx.List) {
+      // LIST form: all horizonOffset children are list entries
+      result.horizonList = ctx.horizonOffset!.map(
+        (o) => this.visit(o) as string,
+      )
+    }
+    // Horizon alias is always the last identifier
+    if (ctx.identifier) {
+      const lastId = ctx.identifier[ctx.identifier.length - 1]
+      result.horizonAlias = (this.visit(lastId) as AST.QualifiedName).parts[0]
+    }
+    return result
+  }
+
+  horizonOffset(ctx: HorizonOffsetCstChildren): string {
+    const sign = ctx.Minus ? "-" : ""
+    if (ctx.DurationLiteral) {
+      return sign + ctx.DurationLiteral[0].image
+    }
+    return sign + ctx.NumberLiteral![0].image
+  }
+
   standardJoin(ctx: StandardJoinCstChildren): AST.JoinClause {
     const result: AST.JoinClause = {
       type: "join",