data-finder-ts 0.1.3 → 0.1.5

package/dist/datafinder/runner.cjs

@@ -20,37 +20,73 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/datafinder/runner.ts
 var runner_exports = {};
 __export(runner_exports, {
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   FinderResult: () => FinderResult,
+  QueryTimeoutError: () => QueryTimeoutError,
   clearRunner: () => clearRunner,
   convertInputsAndSelect: () => convertInputsAndSelect,
+  convertInputsAndSelectForDateRange: () => convertInputsAndSelectForDateRange,
   getRunner: () => getRunner,
   registerRunner: () => registerRunner
 });
 module.exports = __toCommonJS(runner_exports);
 
 // src/model/relational.ts
+var LIKE_ESCAPE = "!";
+function escapeLike(value) {
+  return value.replaceAll(LIKE_ESCAPE, LIKE_ESCAPE + LIKE_ESCAPE).replaceAll("%", LIKE_ESCAPE + "%").replaceAll("_", LIKE_ESCAPE + "_");
+}
 var RelationalOperationElement = class {
 };
 var Operation = class extends RelationalOperationElement {
-  andOp(other) {
+  /** Name this column in the result: `f.price().sum().alias('Total')`, `f.age().gt(30).alias('Adult')`. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  and(other) {
     return new LogicalOperation(this, "AND" /* AND */, other);
   }
+  /** Combine with `other` using OR. A chain reads left to right: `a.or(b).and(c)` is `(a OR b) AND c`. */
+  or(other) {
+    return new LogicalOperation(this, "OR" /* OR */, other);
+  }
 };
 var NoOperation = class extends Operation {
-  andOp(other) {
+  and(other) {
     return other;
   }
+  /** No filter matches every row, so OR-ing anything with it still matches every row. */
+  or(_other) {
+    return this;
+  }
 };
 var ConstantOperation = class extends RelationalOperationElement {
+  /** Name this column in the result. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+};
+var NumericConstantOperation = class extends ConstantOperation {
+  arithmeticOperand() {
+    return this;
+  }
 };
-var IntegerConstantOperation = class extends ConstantOperation {
+var IntegerConstantOperation = class extends NumericConstantOperation {
   constructor(value) {
     super();
     this.value = value;
   }
   value;
 };
-var FloatConstantOperation = class extends ConstantOperation {
+var FloatConstantOperation = class extends NumericConstantOperation {
   constructor(value) {
     super();
     this.value = value;
@@ -64,6 +100,9 @@ var StringConstantOperation = class extends ConstantOperation {
   }
   value;
 };
+var DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+var DateOnly = class extends Date {
+};
 var DateConstantOperation = class extends ConstantOperation {
   constructor(value) {
     super();
@@ -78,7 +117,7 @@ var DateTimeConstantOperation = class extends ConstantOperation {
   }
   value;
 };
-var DecimalConstantOperation = class extends ConstantOperation {
+var DecimalConstantOperation = class extends NumericConstantOperation {
   constructor(value) {
     super();
     this.value = value;
@@ -112,6 +151,20 @@ var IsNullOperation = class extends UnaryOperation {
 };
 var IsNotNullOperation = class extends UnaryOperation {
 };
+var InOperation = class extends UnaryOperation {
+  constructor(element, values) {
+    super(element);
+    this.values = values;
+  }
+  values;
+};
+var NotInOperation = class extends UnaryOperation {
+  constructor(element, values) {
+    super(element);
+    this.values = values;
+  }
+  values;
+};
 var ComparisonOperation = class extends BinaryOperation {
   constructor(left, operator, right) {
     super(left, right);
@@ -135,21 +188,41 @@ var WindowSpecification = class {
   orderBy;
 };
 var AggregateOperation = class _AggregateOperation extends UnaryOperation {
-  constructor(element, operator, displayName, window) {
+  constructor(element, operator, displayName, window, separator, orderBy = []) {
     super(element);
     this.operator = operator;
     this.displayName = displayName;
     this.window = window;
+    this.separator = separator;
+    this.orderBy = orderBy;
   }
   operator;
   displayName;
   window;
+  separator;
+  orderBy;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  arithmeticOperand() {
+    return this;
+  }
+  comparisonOperand() {
+    return this;
+  }
   over(partitionBy, orderBy) {
     return new _AggregateOperation(
       this.element,
       this.operator,
       this.displayName,
-      new WindowSpecification(partitionBy ?? [], orderBy ?? [])
+      new WindowSpecification(partitionBy ?? [], orderBy ?? []),
+      this.separator,
+      this.orderBy
     );
   }
 };
@@ -167,6 +240,14 @@ var WindowFunctionOperation = class _WindowFunctionOperation extends UnaryOperat
   secondArg;
   extraArgs;
   window;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
   over(partitionBy, orderBy) {
     return new _WindowFunctionOperation(
       this.element,
@@ -190,7 +271,38 @@ var ScalarFunctionOperation = class extends UnaryOperation {
   displayName;
   secondArg;
   extraArgs;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  /** This expression as an operand of a comparison. */
+  comparisonOperand() {
+    return this;
+  }
+  arithmeticOperand() {
+    return this;
+  }
+  /** Only a function that gives a number can be used in arithmetic. */
+  assertNumeric() {
+    if (!NUMERIC_FUNCTIONS.has(this.func)) {
+      throw new TypeError(`${this.func} does not give a number, so it cannot be used in arithmetic`);
+    }
+  }
 };
+var NUMERIC_FUNCTIONS = /* @__PURE__ */ new Set([
+  "ABS" /* ABS */,
+  "CEILING" /* CEILING */,
+  "FLOOR" /* FLOOR */,
+  "MOD" /* MOD */,
+  "POWER" /* POWER */,
+  "SQRT" /* SQRT */,
+  "ROUND" /* ROUND */,
+  "LENGTH" /* LENGTH */
+]);
 var DateExtractOperation = class extends UnaryOperation {
   constructor(element, part, displayName) {
     super(element);
@@ -199,6 +311,34 @@ var DateExtractOperation = class extends UnaryOperation {
   }
   part;
   displayName;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+};
+var DateTruncOperation = class extends UnaryOperation {
+  constructor(element, part, displayName) {
+    super(element);
+    this.part = part;
+    this.displayName = displayName;
+  }
+  part;
+  displayName;
+  /** Sort by this expression, earliest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, latest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  comparisonOperand() {
+    return this;
+  }
 };
 var DateArithmeticOperation = class extends UnaryOperation {
   constructor(element, n, unit, isAdd = true, displayName) {
@@ -212,6 +352,14 @@ var DateArithmeticOperation = class extends UnaryOperation {
   unit;
   isAdd;
   displayName;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
 };
 var DateDiffOperation = class extends UnaryOperation {
   constructor(element, other, unit, displayName) {
@@ -223,20 +371,31 @@ var DateDiffOperation = class extends UnaryOperation {
   other;
   unit;
   displayName;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
 };
 var Column = class extends RelationalOperationElement {
-  constructor(name, type, owner, primaryKey = false) {
+  constructor(name, type, owner, primaryKey = false, nullable = true) {
     super();
     this.name = name;
     this.type = type;
     this.owner = owner;
     this.primaryKey = primaryKey;
+    this.nullable = nullable && !primaryKey;
   }
   name;
   type;
   owner;
   primaryKey;
   table;
+  /** Whether the column may hold NULL. As in Legend, a primary key is never null. */
+  nullable;
 };
 var Table = class {
   constructor(name, columns, schema) {
@@ -265,13 +424,28 @@ var Table = class {
   }
 };
 var ColumnWithJoin = class extends RelationalOperationElement {
-  constructor(column, parent) {
+  /**
+   * `embedded` is an alternate reference to a flat (denormalized) column on the owning table that
+   * holds the same value without the join; the SQL generator uses it when the join can be elided.
+   */
+  constructor(column, parent, embedded, _optional = false) {
     super();
     this.column = column;
     this.parent = parent;
+    this.embedded = embedded;
+    this._optional = _optional;
   }
   column;
   parent;
+  embedded;
+  _optional;
+  /** Whether the value can be missing: its property is optional, or a navigation on the way to it is. */
+  get optional() {
+    for (let node = this.parent; node !== void 0; node = node.parent) {
+      if (node.optional) return true;
+    }
+    return this._optional;
+  }
 };
 var SortOperation = class {
   constructor(column, direction) {
@@ -287,19 +461,366 @@ var CountAllOperation = class extends RelationalOperationElement {
     this.table = table;
   }
   table;
+  /** Name this column in the result. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  comparisonOperand() {
+    return this;
+  }
+};
+var Alias = class _Alias extends RelationalOperationElement {
+  constructor(element, name) {
+    super();
+    this.element = element;
+    this.name = name;
+  }
+  element;
+  name;
+  alias(name) {
+    return new _Alias(this.element, name);
+  }
+  /** Sorts by the column the alias names. */
+  ascending() {
+    return new SortOperation(this.element, "ASC" /* ASC */);
+  }
+  /** Sorts by the column the alias names. */
+  descending() {
+    return new SortOperation(this.element, "DESC" /* DESC */);
+  }
+};
+var CaseOperation = class extends Operation {
+  constructor(condition, then, fallback, displayName) {
+    super();
+    this.condition = condition;
+    this.then = then;
+    this.fallback = fallback;
+    this.displayName = displayName;
+  }
+  condition;
+  then;
+  fallback;
+  displayName;
 };
+var ExistsOperation = class extends RelationalOperationElement {
+  constructor(node) {
+    super();
+    this.node = node;
+  }
+  node;
+  /** Name this column in the result. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  and(other) {
+    return new LogicalOperation(this, "AND" /* AND */, other);
+  }
+  or(other) {
+    return new LogicalOperation(this, "OR" /* OR */, other);
+  }
+};
+var NotExistsOperation = class extends RelationalOperationElement {
+  constructor(node) {
+    super();
+    this.node = node;
+  }
+  node;
+  /** Name this column in the result. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  and(other) {
+    return new LogicalOperation(this, "AND" /* AND */, other);
+  }
+  or(other) {
+    return new LogicalOperation(this, "OR" /* OR */, other);
+  }
+};
+var SelectOperation = class {
+  constructor(display, filter, orderBy = [], groupBy = [], limit, table, joinFilters = /* @__PURE__ */ new Map(), distinct = false, offset, having) {
+    this.display = display;
+    this.filter = filter;
+    this.orderBy = orderBy;
+    this.groupBy = groupBy;
+    this.limit = limit;
+    this.table = table;
+    this.joinFilters = joinFilters;
+    this.distinct = distinct;
+    this.offset = offset;
+    this.having = having;
+  }
+  display;
+  filter;
+  orderBy;
+  groupBy;
+  limit;
+  table;
+  joinFilters;
+  distinct;
+  offset;
+  having;
+};
+function containsAggregateOrWindow(op) {
+  if (op instanceof AggregateOperation || op instanceof WindowFunctionOperation || op instanceof CountAllOperation) return true;
+  if (op instanceof BinaryOperation) return containsAggregateOrWindow(op.left) || containsAggregateOrWindow(op.right);
+  if (op instanceof UnaryOperation || op instanceof Alias) return containsAggregateOrWindow(op.element);
+  return false;
+}
+function containsAggregate(op) {
+  if (op instanceof AggregateOperation || op instanceof CountAllOperation) return true;
+  if (op instanceof BinaryOperation) return containsAggregate(op.left) || containsAggregate(op.right);
+  if (op instanceof UnaryOperation || op instanceof Alias) return containsAggregate(op.element);
+  return false;
+}
+function valueOperand(value) {
+  if (typeof value === "boolean") return new BooleanConstantOperation(value);
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Number.isInteger(value) ? new IntegerConstantOperation(value) : new FloatConstantOperation(value);
+  }
+  if (typeof value === "string") return new StringConstantOperation(value);
+  if (value instanceof DateOnly) return new DateConstantOperation(value);
+  if (value instanceof Date) return new DateTimeConstantOperation(value);
+  throw new TypeError(`A value to compare with is a boolean, a finite number, a string or a date, not ${value === null ? "null" : typeof value}`);
+}
+function operandOf(other) {
+  if (other instanceof RelationalOperationElement) return other;
+  if (typeof other?.cwj === "function") return other.cwj();
+  return valueOperand(other);
+}
+var Comparable = class {
+  _compared(operator, other) {
+    return new ComparisonOperation(this.comparisonOperand(), operator, operandOf(other));
+  }
+  /** Filter to rows where this expression equals `other`. */
+  eq(other) {
+    return this._compared("EQUAL" /* EQUAL */, other);
+  }
+  /** Filter to rows where this expression does not equal `other`. */
+  ne(other) {
+    return this._compared("NOT_EQUAL" /* NOT_EQUAL */, other);
+  }
+  /** Filter to rows where this expression is less than `other`. */
+  lt(other) {
+    return this._compared("LESS_THAN" /* LESS_THAN */, other);
+  }
+  /** Filter to rows where this expression is at most `other`. */
+  lte(other) {
+    return this._compared("LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, other);
+  }
+  /** Filter to rows where this expression is greater than `other`. */
+  gt(other) {
+    return this._compared("GREATER_THAN" /* GREATER_THAN */, other);
+  }
+  /** Filter to rows where this expression is at least `other`. */
+  gte(other) {
+    return this._compared("GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, other);
+  }
+};
+function sample(ddof) {
+  if (ddof !== 0 && ddof !== 1) throw new RangeError(`ddof is 0 (population) or 1 (sample), not ${ddof}`);
+  return ddof === 1;
+}
+var StringPredicates = class {
+  _like(pattern) {
+    return new ComparisonOperation(this.comparisonOperand(), "LIKE" /* LIKE */, new StringConstantOperation(pattern));
+  }
+  /** Filter to rows where this text contains `value`. */
+  contains(value) {
+    return this._like(`%${escapeLike(value)}%`);
+  }
+  /** Filter to rows where this text starts with `prefix`. */
+  startsWith(prefix) {
+    return this._like(`${escapeLike(prefix)}%`);
+  }
+  /** Filter to rows where this text ends with `suffix`. */
+  endsWith(suffix) {
+    return this._like(`%${escapeLike(suffix)}`);
+  }
+};
+var Aggregates = class {
+  _aggregate(operator, label) {
+    return new AggregateOperation(this, operator, label + " Expression");
+  }
+  /** Sum of the values in the group. */
+  sum() {
+    return this._aggregate("SUM" /* SUM */, "Sum");
+  }
+  /** Smallest value in the group. */
+  min() {
+    return this._aggregate("MIN" /* MIN */, "Min");
+  }
+  /** Largest value in the group. */
+  max() {
+    return this._aggregate("MAX" /* MAX */, "Max");
+  }
+  /** Arithmetic mean of the values in the group. */
+  average() {
+    return this._aggregate("AVERAGE" /* AVERAGE */, "Average");
+  }
+  /** Number of non-null values in the group. */
+  count() {
+    return this._aggregate("COUNT" /* COUNT */, "Count");
+  }
+  /** Standard deviation of the values in the group: the sample one by default, `ddof = 0` for the population one. */
+  std(ddof = 1) {
+    return this._aggregate(sample(ddof) ? "STDDEV_SAMP" /* STDDEV_SAMP */ : "STDDEV_POP" /* STDDEV_POP */, "Std");
+  }
+  /** Variance of the values in the group: the sample one by default, `ddof = 0` for the population one. */
+  var(ddof = 1) {
+    return this._aggregate(sample(ddof) ? "VAR_SAMP" /* VAR_SAMP */ : "VAR_POP" /* VAR_POP */, "Var");
+  }
+};
+var BooleanAggregates = class {
+  /** True for a group where every row satisfies the condition. */
+  all() {
+    return new AggregateOperation(this, "BOOL_AND" /* BOOL_AND */, "All Expression");
+  }
+  /** True for a group where at least one row satisfies the condition. */
+  any() {
+    return new AggregateOperation(this, "BOOL_OR" /* BOOL_OR */, "Any Expression");
+  }
+};
+function applyMixins(derived, bases) {
+  for (const base of bases) {
+    for (const name of Object.getOwnPropertyNames(base.prototype)) {
+      if (name === "constructor" || Object.prototype.hasOwnProperty.call(derived.prototype, name)) continue;
+      Object.defineProperty(derived.prototype, name, Object.getOwnPropertyDescriptor(base.prototype, name));
+    }
+  }
+}
+var Arithmetic = class {
+  /** Raises if this expression is not a number. */
+  assertNumeric() {
+  }
+  _arithmetic(operator, other) {
+    this.assertNumeric();
+    let operand;
+    if (typeof other === "number") {
+      if (!Number.isFinite(other)) throw new TypeError("Arithmetic is between numbers and numeric columns, not a non-finite number");
+      operand = valueOperand(other);
+    } else if (other !== null && typeof other === "object" && typeof other.arithmeticOperand === "function") {
+      other.assertNumeric?.();
+      operand = other.arithmeticOperand();
+    } else {
+      throw new TypeError(`Arithmetic is between numbers and numeric columns, not ${other === null ? "null" : typeof other}`);
+    }
+    return new ArithmeticOperation(this.arithmeticOperand(), operator, operand);
+  }
+  /** `this + other`. */
+  plus(other) {
+    return this._arithmetic("+" /* ADD */, other);
+  }
+  /** `this - other`. */
+  minus(other) {
+    return this._arithmetic("-" /* SUBTRACT */, other);
+  }
+  /** `this * other`. */
+  times(other) {
+    return this._arithmetic("*" /* MULTIPLY */, other);
+  }
+  /** `this / other`. */
+  dividedBy(other) {
+    return this._arithmetic("/" /* DIVIDE */, other);
+  }
+};
+var ArithmeticOperation = class extends BinaryOperation {
+  constructor(left, operator, right, displayName) {
+    super(left, right);
+    this.operator = operator;
+    this.displayName = displayName;
+  }
+  operator;
+  displayName;
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  arithmeticOperand() {
+    return this;
+  }
+  comparisonOperand() {
+    return this;
+  }
+};
+var ConcatOperation = class extends Operation {
+  constructor(parts, displayName) {
+    super();
+    this.parts = parts;
+    this.displayName = displayName;
+  }
+  parts;
+  displayName;
+  /** Join more text on the end: `f.first().concat(' ', f.last())`. A concatenation joins into one. */
+  concat(...more) {
+    return concat(this, ...more);
+  }
+  /** Sort by this expression, smallest first. */
+  ascending() {
+    return new SortOperation(this, "ASC" /* ASC */);
+  }
+  /** Sort by this expression, largest first. */
+  descending() {
+    return new SortOperation(this, "DESC" /* DESC */);
+  }
+  comparisonOperand() {
+    return this;
+  }
+};
+function concat(...parts) {
+  const partsOf = (part) => {
+    if (part instanceof ConcatOperation) return part.parts;
+    if (typeof part === "string") return [new StringConstantOperation(part)];
+    if (part instanceof RelationalOperationElement) return [part];
+    if (part !== null && typeof part === "object" && typeof part.functionInput === "function") return [part.functionInput()];
+    throw new TypeError(`Text is joined with text, not ${part === null ? "null" : typeof part}`);
+  };
+  return new ConcatOperation(parts.flatMap(partsOf));
+}
+applyMixins(ConcatOperation, [Comparable, StringPredicates]);
+applyMixins(DateTruncOperation, [Comparable]);
+applyMixins(ArithmeticOperation, [Arithmetic, Comparable]);
+applyMixins(ScalarFunctionOperation, [Comparable, Arithmetic, StringPredicates]);
+applyMixins(AggregateOperation, [Arithmetic, Comparable, StringPredicates]);
+applyMixins(CountAllOperation, [Comparable]);
+applyMixins(NumericConstantOperation, [Arithmetic]);
+applyMixins(ConstantOperation, [Aggregates]);
+applyMixins(ArithmeticOperation, [Aggregates]);
+applyMixins(ScalarFunctionOperation, [Aggregates]);
+applyMixins(CaseOperation, [Aggregates]);
+applyMixins(IsNullOperation, [BooleanAggregates]);
+applyMixins(IsNotNullOperation, [BooleanAggregates]);
+applyMixins(InOperation, [BooleanAggregates]);
+applyMixins(NotInOperation, [BooleanAggregates]);
+applyMixins(ComparisonOperation, [BooleanAggregates]);
+applyMixins(LogicalOperation, [BooleanAggregates]);
 
 // src/datafinder/attribute.ts
-var Attribute = class {
+var Attribute = class _Attribute {
   _displayName;
   _column;
   _owner;
   _parent;
-  constructor(displayName, columnName, columnDbType, owner, parent) {
+  _embedded;
+  _optional;
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded, nullable = true, optional = false) {
+    this._optional = optional;
     this._displayName = displayName;
-    this._column = new Column(columnName, columnDbType, owner);
+    this._column = new Column(columnName, columnDbType, owner, false, nullable);
     this._owner = owner;
     this._parent = parent;
+    this._embedded = embedded;
   }
   column() {
     return this._column;
@@ -313,33 +834,102 @@ var Attribute = class {
   displayName() {
     return this._displayName;
   }
+  /** Alternate attribute on a flat column of the owning table, used in place of this one when its join is elided. */
+  embedded() {
+    return this._embedded;
+  }
+  /** @internal The expression a function of this attribute applies to: its column. */
+  functionInput() {
+    return this.cwj();
+  }
+  /** @internal What a function of this attribute is labelled after: its display name. */
+  functionLabel() {
+    return this._displayName;
+  }
+  /** @internal This attribute as an operand of arithmetic: its column. */
+  arithmeticOperand() {
+    return this.cwj();
+  }
   cwj() {
-    return new ColumnWithJoin(this._column, this._parent);
+    return new ColumnWithJoin(this._column, this._parent, this._embedded?.cwj(), this._optional);
   }
+  /** Count the number of non-null values. Use in a projection with `groupBy` to aggregate per group. */
   count() {
     return new AggregateOperation(
-      new ColumnWithJoin(this._column, this._parent),
+      this.cwj(),
       "COUNT" /* COUNT */,
       this._displayName + " Count"
     );
   }
+  /** Name this column in the result: `f.price().sum().alias('Total')`. */
+  alias(name) {
+    return new Alias(this, name);
+  }
+  /** The number of different non-NULL values in the group: `COUNT(DISTINCT column)`. Use with `groupBy` to count per group. */
+  countDistinct() {
+    return new AggregateOperation(this.cwj(), "COUNT_DISTINCT" /* COUNT_DISTINCT */, this._displayName + " Count Distinct");
+  }
+  /** The value, or `defaultValue` when it is NULL: `name().orElse('N/A')`. Like `COALESCE` in SQL. */
+  orElse(defaultValue) {
+    if (!["string", "number", "boolean"].includes(typeof defaultValue)) {
+      throw new TypeError(`An orElse default is a string, number or boolean, not ${defaultValue === null ? "null" : typeof defaultValue}`);
+    }
+    return new ScalarFunctionOperation(this.cwj(), "COALESCE" /* COALESCE */, "Or Else " + this._displayName, void 0, [defaultValue]);
+  }
+  /** Sort this attribute in ascending order. Pass to `orderBy` or a window function's `orderBy`. */
   ascending() {
-    return new SortOperation(new ColumnWithJoin(this._column, this._parent), "ASC" /* ASC */);
+    return new SortOperation(this.cwj(), "ASC" /* ASC */);
   }
+  /** Sort this attribute in descending order. Pass to `orderBy` or a window function's `orderBy`. */
   descending() {
-    return new SortOperation(new ColumnWithJoin(this._column, this._parent), "DESC" /* DESC */);
+    return new SortOperation(this.cwj(), "DESC" /* DESC */);
   }
+  /** Filter to rows where this attribute has no value. */
   isNull() {
-    return new IsNullOperation(new ColumnWithJoin(this._column, this._parent));
+    return new IsNullOperation(this.cwj());
   }
+  /** Filter to rows where this attribute has a value. */
   isNotNull() {
-    return new IsNotNullOperation(new ColumnWithJoin(this._column, this._parent));
+    return new IsNotNullOperation(this.cwj());
+  }
+  /** Wrap a value as a constant of this attribute's type. Overridden by the typed attributes. */
+  toConstant(_value) {
+    throw new TypeError(`${this.constructor.name} does not support isIn / isNotIn`);
+  }
+  _constants(values) {
+    const constants = values.map((v) => this.toConstant(v));
+    if (constants.length === 0) throw new Error("isIn / isNotIn need at least one value");
+    return constants;
+  }
+  /** Filter to rows where this attribute equals any of `values`. */
+  isIn(values) {
+    return new InOperation(this.cwj(), this._constants(values));
+  }
+  /** Filter to rows where this attribute equals none of `values`. Rows with no value are excluded, as in SQL. */
+  isNotIn(values) {
+    return new NotInOperation(this.cwj(), this._constants(values));
   }
   _windowSpec(partitionBy, orderBy) {
-    const pb = partitionBy === void 0 ? [] : Array.isArray(partitionBy) ? partitionBy : [partitionBy];
+    const pbArr = partitionBy === void 0 ? [] : Array.isArray(partitionBy) ? partitionBy : [partitionBy];
+    const pb = pbArr.map((x) => x instanceof _Attribute ? x.cwj() : x);
     const ob = orderBy === void 0 ? [] : Array.isArray(orderBy) ? orderBy : [orderBy];
     return new WindowSpecification(pb, ob);
   }
+  /**
+   * Assign a rank to each row within the ordered window, following pandas `Series.rank` conventions.
+   *
+   * `method` controls tie-breaking (default `'min'`):
+   * - `'min'`   — tied rows share the lowest rank; the next rank skips.
+   * - `'dense'` — like `'min'` but ranks are contiguous (no gaps).
+   * - `'first'` — each row gets a unique sequential integer (no ties).
+   * - `'max'`   — only meaningful with `pct: true` (see below).
+   *
+   * When `pct: true` the result is a relative rank between 0 and 1:
+   * - `method: 'min'` (default) → fraction of values strictly below this row (PERCENT_RANK).
+   * - `method: 'max'` → fraction of values at or below this row (cumulative distribution).
+   *
+   * `partitionBy` restarts the ranking within each group of distinct values.
+   */
   rank(opts = {}) {
     const { method = "min", pct = false, partitionBy, orderBy } = opts;
     let func;
@@ -364,6 +954,11 @@ var Attribute = class {
     }
     return new WindowFunctionOperation(null, func, name, void 0, [], this._windowSpec(partitionBy, orderBy));
   }
+  /**
+   * Split rows into `buckets` equal-sized quantile bins ordered by `orderBy`.
+   * Each row receives a bucket number from 1 (lowest) to `buckets` (highest).
+   * Named after `pandas.qcut`.
+   */
   qcut(buckets, opts = {}) {
     return new WindowFunctionOperation(
       null,
@@ -374,12 +969,17 @@ var Attribute = class {
       this._windowSpec(opts.partitionBy, opts.orderBy)
     );
   }
+  /**
+   * Return the value of this attribute from `periods` rows earlier (positive) or later (negative)
+   * within the ordered window, following `pandas.Series.shift`.
+   * Rows with no neighbour at the given offset return `null` (or `fillValue` if provided).
+   */
   shift(periods = 1, opts = {}) {
     const extraArgs = opts.fillValue !== void 0 ? [opts.fillValue] : [];
     const func = periods >= 0 ? "LAG" /* LAG */ : "LEAD" /* LEAD */;
     const label = periods >= 0 ? "Lag" : "Lead";
     return new WindowFunctionOperation(
-      new ColumnWithJoin(this._column, this._parent),
+      this.cwj(),
       func,
       label + " " + this._displayName,
       Math.abs(periods),
@@ -387,9 +987,13 @@ var Attribute = class {
       this._windowSpec(opts.partitionBy, opts.orderBy)
     );
   }
+  /**
+   * Return the first value of this attribute in the window frame.
+   * Use `partitionBy` to restart the frame for each group.
+   */
   first(opts = {}) {
     return new WindowFunctionOperation(
-      new ColumnWithJoin(this._column, this._parent),
+      this.cwj(),
       "FIRST_VALUE" /* FIRST_VALUE */,
       "First " + this._displayName,
       void 0,
@@ -397,9 +1001,13 @@ var Attribute = class {
       this._windowSpec(opts.partitionBy, opts.orderBy)
     );
   }
+  /**
+   * Return the last value of this attribute in the window frame.
+   * Use `partitionBy` to restart the frame for each group.
+   */
   last(opts = {}) {
     return new WindowFunctionOperation(
-      new ColumnWithJoin(this._column, this._parent),
+      this.cwj(),
       "LAST_VALUE" /* LAST_VALUE */,
       "Last " + this._displayName,
       void 0,
@@ -486,217 +1094,538 @@ var MilestonedTable = class extends Table {
   milestoningColumns;
 };
 
+// src/datafinder/scalar-functions.ts
+var StringFunctionOperation = class extends ScalarFunctionOperation {
+  functionInput() {
+    return this;
+  }
+  functionLabel() {
+    return labelOf(this);
+  }
+};
+var NumericFunctionOperation = class extends ScalarFunctionOperation {
+  functionInput() {
+    return this;
+  }
+  functionLabel() {
+    return labelOf(this);
+  }
+};
+function labelOf(operation) {
+  return operation.displayName ?? operation.func.charAt(0) + operation.func.slice(1).toLowerCase();
+}
+function stringFunction(element, func, label, secondArg, extraArgs = []) {
+  return new StringFunctionOperation(element, func, label, secondArg, extraArgs);
+}
+function numberFunction(element, func, label, secondArg) {
+  return new NumericFunctionOperation(element, func, label, secondArg);
+}
+var StringFunctions = class {
+  /** Join text on the end: `f.first().concat(' ', f.last())`. A NULL part makes the whole NULL. */
+  concat(...more) {
+    return concat(this, ...more);
+  }
+  /** Convert every character to uppercase. */
+  toUpperCase() {
+    return stringFunction(this.functionInput(), "UPPER" /* UPPER */, "Upper " + this.functionLabel());
+  }
+  /** Convert every character to lowercase. */
+  toLowerCase() {
+    return stringFunction(this.functionInput(), "LOWER" /* LOWER */, "Lower " + this.functionLabel());
+  }
+  /** Remove leading and trailing whitespace. */
+  trim() {
+    return stringFunction(this.functionInput(), "TRIM" /* TRIM */, "Trim " + this.functionLabel());
+  }
+  /** Remove leading whitespace. */
+  trimStart() {
+    return stringFunction(this.functionInput(), "LTRIM" /* LTRIM */, "Trim Start " + this.functionLabel());
+  }
+  /** Remove trailing whitespace. */
+  trimEnd() {
+    return stringFunction(this.functionInput(), "RTRIM" /* RTRIM */, "Trim End " + this.functionLabel());
+  }
+  /** Return the number of characters in the string. */
+  length() {
+    return numberFunction(this.functionInput(), "LENGTH" /* LENGTH */, "Length " + this.functionLabel());
+  }
+  /** Return the string with characters in reverse order. */
+  reverse() {
+    return stringFunction(this.functionInput(), "REVERSE" /* REVERSE */, "Reverse " + this.functionLabel());
+  }
+  /** Return the first `n` characters. */
+  left(n) {
+    return stringFunction(this.functionInput(), "LEFT" /* LEFT */, "Left " + this.functionLabel(), n);
+  }
+  /** Return the last `n` characters. */
+  right(n) {
+    return stringFunction(this.functionInput(), "RIGHT" /* RIGHT */, "Right " + this.functionLabel(), n);
+  }
+  /** Return the string repeated `n` times. */
+  repeat(n) {
+    return stringFunction(this.functionInput(), "REPEAT" /* REPEAT */, "Repeat " + this.functionLabel(), n);
+  }
+  /** Replace all occurrences of `fromStr` with `toStr`. */
+  replace(fromStr, toStr) {
+    return stringFunction(this.functionInput(), "REPLACE" /* REPLACE */, "Replace " + this.functionLabel(), void 0, [fromStr, toStr]);
+  }
+  /**
+   * Extract a portion of the string.
+   * `start` is zero-based (following Python convention); `length` is optional.
+   */
+  substring(start, length) {
+    const args = length !== void 0 ? [start + 1, length] : [start + 1];
+    return stringFunction(this.functionInput(), "SUBSTRING" /* SUBSTRING */, "Substring " + this.functionLabel(), void 0, args);
+  }
+};
+var NumericFunctions = class {
+  /** Absolute value (distance from zero, always non-negative). */
+  abs() {
+    return numberFunction(this.functionInput(), "ABS" /* ABS */, "Abs " + this.functionLabel());
+  }
+  /** Round up to the nearest integer. */
+  ceil() {
+    return numberFunction(this.functionInput(), "CEILING" /* CEILING */, "Ceil " + this.functionLabel());
+  }
+  /** Round down to the nearest integer. */
+  floor() {
+    return numberFunction(this.functionInput(), "FLOOR" /* FLOOR */, "Floor " + this.functionLabel());
+  }
+  /** Square root. */
+  sqrt() {
+    return numberFunction(this.functionInput(), "SQRT" /* SQRT */, "Sqrt " + this.functionLabel());
+  }
+  /** Remainder after dividing by `n`. */
+  mod(n) {
+    return numberFunction(this.functionInput(), "MOD" /* MOD */, "Mod " + this.functionLabel(), n);
+  }
+  /** Raise to the power of `n`. */
+  power(n) {
+    return numberFunction(this.functionInput(), "POWER" /* POWER */, "Power " + this.functionLabel(), n);
+  }
+  /** Round to `d` decimal places, or to the nearest integer when `d` is omitted. */
+  round(d) {
+    return numberFunction(this.functionInput(), "ROUND" /* ROUND */, "Round " + this.functionLabel(), d);
+  }
+};
+applyMixins(StringFunctionOperation, [StringFunctions]);
+applyMixins(NumericFunctionOperation, [NumericFunctions]);
+
 // src/datafinder/typed-attributes.ts
+var MinMax = class {
+  /** Smallest value in the group. */
+  min() {
+    return new AggregateOperation(this.cwj(), "MIN" /* MIN */, "Min " + this.displayName());
+  }
+  /** Largest value in the group. */
+  max() {
+    return new AggregateOperation(this.cwj(), "MAX" /* MAX */, "Max " + this.displayName());
+  }
+};
+var StringAttribute = class extends Attribute {
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded, nullable = true, optional = false) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded, nullable, optional);
+  }
+  toConstant(value) {
+    return new StringConstantOperation(String(value));
+  }
+  /**
+   * Join the values of a group into one text with `separator` between them. `orderBy` is the order they are
+   * joined in (`[f.name().ascending()]`); without it the order is not defined. Missing values are skipped.
+   */
+  join(separator = "", orderBy = []) {
+    return new AggregateOperation(this.cwj(), "STRING_AGG" /* STRING_AGG */, "Join " + this.displayName(), void 0, separator, orderBy);
+  }
+  /** Filter to rows where this attribute equals `value`. */
+  eq(value) {
+    return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new StringConstantOperation(value));
+  }
+  /** Filter to rows where this attribute does not equal `value`. */
+  ne(value) {
+    return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new StringConstantOperation(value));
+  }
+  /** Filter to rows where this attribute contains `value` as a substring. */
+  contains(value) {
+    return new ComparisonOperation(this.cwj(), "LIKE" /* LIKE */, new StringConstantOperation(`%${escapeLike(value)}%`));
+  }
+  /** Filter to rows where this attribute begins with `prefix`. */
+  startsWith(prefix) {
+    return new ComparisonOperation(this.cwj(), "LIKE" /* LIKE */, new StringConstantOperation(`${escapeLike(prefix)}%`));
+  }
+  /** Filter to rows where this attribute ends with `suffix`. */
+  endsWith(suffix) {
+    return new ComparisonOperation(this.cwj(), "LIKE" /* LIKE */, new StringConstantOperation(`%${escapeLike(suffix)}`));
+  }
+  /** Filter to rows where this attribute does not contain `value` as a substring. */
+  notContains(value) {
+    return new ComparisonOperation(this.cwj(), "NOT_LIKE" /* NOT_LIKE */, new StringConstantOperation(`%${escapeLike(value)}%`));
+  }
+};
+applyMixins(StringAttribute, [MinMax, StringFunctions]);
+var NumericAttribute = class extends Attribute {
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded, nullable = true, optional = false) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded, nullable, optional);
+  }
+  /** Sum of all values in the group. */
+  sum() {
+    return new AggregateOperation(this.cwj(), "SUM" /* SUM */, "Sum " + this.displayName());
+  }
+  /** Arithmetic mean of all values in the group. */
+  average() {
+    return new AggregateOperation(this.cwj(), "AVERAGE" /* AVERAGE */, "Average " + this.displayName());
+  }
+  /** Standard deviation of the values in the group: the sample one by default, `ddof = 0` for the population one, as `Series.std`. */
+  std(ddof = 1) {
+    const operator = sample(ddof) ? "STDDEV_SAMP" /* STDDEV_SAMP */ : "STDDEV_POP" /* STDDEV_POP */;
+    return new AggregateOperation(this.cwj(), operator, "Std " + this.displayName());
+  }
+  /** Variance of the values in the group: the sample one by default, `ddof = 0` for the population one, as `Series.var`. */
+  var(ddof = 1) {
+    const operator = sample(ddof) ? "VAR_SAMP" /* VAR_SAMP */ : "VAR_POP" /* VAR_POP */;
+    return new AggregateOperation(this.cwj(), operator, "Var " + this.displayName());
+  }
+};
+applyMixins(NumericAttribute, [MinMax, NumericFunctions, Arithmetic]);
 function parseDate(value) {
   if (value instanceof Date) return value;
   const d = new Date(value);
   if (isNaN(d.getTime())) throw new Error(`Cannot parse date: ${value}`);
   return d;
 }
+function temporalConstant(value) {
+  if (typeof value === "string" && DATE_ONLY_PATTERN.test(value)) return new DateConstantOperation(new DateOnly(value));
+  const date = parseDate(value);
+  return date instanceof DateOnly ? new DateConstantOperation(date) : new DateTimeConstantOperation(date);
+}
 var DateAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded, nullable = true, optional = false) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded, nullable, optional);
+  }
+  toConstant(value) {
+    return new DateConstantOperation(parseDate(value));
   }
+  /** Filter to rows where this date equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new DateConstantOperation(parseDate(value)));
   }
+  /** Filter to rows where this date does not equal `value`. */
   ne(value) {
     return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new DateConstantOperation(parseDate(value)));
   }
+  /** Filter to rows where this date is after `value`. */
   gt(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new DateConstantOperation(parseDate(value)));
   }
+  /** Filter to rows where this date is before `value`. */
   lt(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, new DateConstantOperation(parseDate(value)));
   }
+  /** Filter to rows where this date is on or after `value`. */
   gte(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, new DateConstantOperation(parseDate(value)));
   }
+  /** Filter to rows where this date is on or before `value`. */
   lte(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, new DateConstantOperation(parseDate(value)));
   }
+  /** Extract the four-digit calendar year. */
   year() {
     return new DateExtractOperation(this.cwj(), "YEAR" /* YEAR */, "Year " + this.displayName());
   }
+  /** Extract the month number (1–12). */
   month() {
     return new DateExtractOperation(this.cwj(), "MONTH" /* MONTH */, "Month " + this.displayName());
   }
+  /** Extract the day of the month (1–31). */
   day() {
     return new DateExtractOperation(this.cwj(), "DAY" /* DAY */, "Day " + this.displayName());
   }
+  /** Extract the quarter (1–4). */
   quarter() {
     return new DateExtractOperation(this.cwj(), "QUARTER" /* QUARTER */, "Quarter " + this.displayName());
   }
+  /** Extract the ISO week number (1–53). */
   week() {
     return new DateExtractOperation(this.cwj(), "WEEK" /* WEEK */, "Week " + this.displayName());
   }
+  /** Extract the day of the week (0 = Sunday through 6 = Saturday). */
   dayOfWeek() {
     return new DateExtractOperation(this.cwj(), "DOW" /* DOW */, "Day Of Week " + this.displayName());
   }
+  /** The date of the first day of the week the date falls in (a Monday). */
+  firstDayOfWeek() {
+    return new DateTruncOperation(this.cwj(), "WEEK" /* WEEK */, "First Day Of Week " + this.displayName());
+  }
+  /** The date of the first day of the month the date falls in. */
+  firstDayOfMonth() {
+    return new DateTruncOperation(this.cwj(), "MONTH" /* MONTH */, "First Day Of Month " + this.displayName());
+  }
+  /** The date of the first day of the quarter the date falls in. */
+  firstDayOfQuarter() {
+    return new DateTruncOperation(this.cwj(), "QUARTER" /* QUARTER */, "First Day Of Quarter " + this.displayName());
+  }
+  /** The date of the first day of the year the date falls in. */
+  firstDayOfYear() {
+    return new DateTruncOperation(this.cwj(), "YEAR" /* YEAR */, "First Day Of Year " + this.displayName());
+  }
+  /** Add `n` days to this date. */
   addDays(n) {
     return new DateArithmeticOperation(this.cwj(), n, "DAY" /* DAY */, true, "Add Days " + this.displayName());
   }
+  /** Add `n` months to this date. */
   addMonths(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MONTH" /* MONTH */, true, "Add Months " + this.displayName());
   }
+  /** Add `n` years to this date. */
   addYears(n) {
     return new DateArithmeticOperation(this.cwj(), n, "YEAR" /* YEAR */, true, "Add Years " + this.displayName());
   }
+  /** Subtract `n` days from this date. */
   subtractDays(n) {
     return new DateArithmeticOperation(this.cwj(), n, "DAY" /* DAY */, false, "Subtract Days " + this.displayName());
   }
+  /** Subtract `n` months from this date. */
   subtractMonths(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MONTH" /* MONTH */, false, "Subtract Months " + this.displayName());
   }
+  /** Subtract `n` years from this date. */
   subtractYears(n) {
     return new DateArithmeticOperation(this.cwj(), n, "YEAR" /* YEAR */, false, "Subtract Years " + this.displayName());
   }
+  /** Number of whole days between this date and `other`. */
   diffDays(other) {
     return new DateDiffOperation(this.cwj(), other, "DAY" /* DAY */, "Diff Days " + this.displayName());
   }
+  /** Number of whole months between this date and `other`. */
   diffMonths(other) {
     return new DateDiffOperation(this.cwj(), other, "MONTH" /* MONTH */, "Diff Months " + this.displayName());
   }
+  /** Number of whole years between this date and `other`. */
   diffYears(other) {
     return new DateDiffOperation(this.cwj(), other, "YEAR" /* YEAR */, "Diff Years " + this.displayName());
   }
 };
 var DateTimeAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded, nullable = true, optional = false) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded, nullable, optional);
+  }
+  toConstant(value) {
+    return temporalConstant(value);
   }
+  /** Filter to rows where this timestamp equals `value`. */
   eq(value) {
-    return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, temporalConstant(value));
   }
+  /** Filter to rows where this timestamp does not equal `value`. */
   ne(value) {
-    return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, temporalConstant(value));
   }
+  /** Filter to rows where this timestamp is after `value`. */
   gt(value) {
-    return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, temporalConstant(value));
   }
+  /** Filter to rows where this timestamp is before `value`. */
   lt(value) {
-    return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, temporalConstant(value));
   }
+  /** Filter to rows where this timestamp is on or after `value`. */
   gte(value) {
-    return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, temporalConstant(value));
   }
+  /** Filter to rows where this timestamp is on or before `value`. */
   lte(value) {
-    return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, new DateTimeConstantOperation(parseDate(value)));
+    return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, temporalConstant(value));
   }
+  /** Extract the four-digit calendar year. */
   year() {
     return new DateExtractOperation(this.cwj(), "YEAR" /* YEAR */, "Year " + this.displayName());
   }
+  /** Extract the month number (1–12). */
   month() {
     return new DateExtractOperation(this.cwj(), "MONTH" /* MONTH */, "Month " + this.displayName());
   }
+  /** Extract the day of the month (1–31). */
   day() {
     return new DateExtractOperation(this.cwj(), "DAY" /* DAY */, "Day " + this.displayName());
   }
+  /** Extract the hour (0–23). */
   hour() {
     return new DateExtractOperation(this.cwj(), "HOUR" /* HOUR */, "Hour " + this.displayName());
   }
+  /** Extract the minute (0–59). */
   minute() {
     return new DateExtractOperation(this.cwj(), "MINUTE" /* MINUTE */, "Minute " + this.displayName());
   }
+  /** Extract the second (0–59). */
   second() {
     return new DateExtractOperation(this.cwj(), "SECOND" /* SECOND */, "Second " + this.displayName());
   }
+  /** Extract the quarter (1–4). */
   quarter() {
     return new DateExtractOperation(this.cwj(), "QUARTER" /* QUARTER */, "Quarter " + this.displayName());
   }
+  /** Extract the ISO week number (1–53). */
   week() {
     return new DateExtractOperation(this.cwj(), "WEEK" /* WEEK */, "Week " + this.displayName());
   }
+  /** Extract the day of the week (0 = Sunday through 6 = Saturday). */
   dayOfWeek() {
     return new DateExtractOperation(this.cwj(), "DOW" /* DOW */, "Day Of Week " + this.displayName());
   }
+  /** The date of the first day of the week the date falls in (a Monday). */
+  firstDayOfWeek() {
+    return new DateTruncOperation(this.cwj(), "WEEK" /* WEEK */, "First Day Of Week " + this.displayName());
+  }
+  /** The date of the first day of the month the date falls in. */
+  firstDayOfMonth() {
+    return new DateTruncOperation(this.cwj(), "MONTH" /* MONTH */, "First Day Of Month " + this.displayName());
+  }
+  /** The date of the first day of the quarter the date falls in. */
+  firstDayOfQuarter() {
+    return new DateTruncOperation(this.cwj(), "QUARTER" /* QUARTER */, "First Day Of Quarter " + this.displayName());
+  }
+  /** The date of the first day of the year the date falls in. */
+  firstDayOfYear() {
+    return new DateTruncOperation(this.cwj(), "YEAR" /* YEAR */, "First Day Of Year " + this.displayName());
+  }
+  /** Add `n` days to this timestamp. */
   addDays(n) {
     return new DateArithmeticOperation(this.cwj(), n, "DAY" /* DAY */, true, "Add Days " + this.displayName());
   }
+  /** Add `n` months to this timestamp. */
   addMonths(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MONTH" /* MONTH */, true, "Add Months " + this.displayName());
   }
+  /** Add `n` years to this timestamp. */
   addYears(n) {
     return new DateArithmeticOperation(this.cwj(), n, "YEAR" /* YEAR */, true, "Add Years " + this.displayName());
   }
+  /** Add `n` hours to this timestamp. */
   addHours(n) {
     return new DateArithmeticOperation(this.cwj(), n, "HOUR" /* HOUR */, true, "Add Hours " + this.displayName());
   }
+  /** Add `n` minutes to this timestamp. */
   addMinutes(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MINUTE" /* MINUTE */, true, "Add Minutes " + this.displayName());
   }
+  /** Add `n` seconds to this timestamp. */
   addSeconds(n) {
     return new DateArithmeticOperation(this.cwj(), n, "SECOND" /* SECOND */, true, "Add Seconds " + this.displayName());
   }
+  /** Subtract `n` days from this timestamp. */
   subtractDays(n) {
     return new DateArithmeticOperation(this.cwj(), n, "DAY" /* DAY */, false, "Subtract Days " + this.displayName());
   }
+  /** Subtract `n` months from this timestamp. */
   subtractMonths(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MONTH" /* MONTH */, false, "Subtract Months " + this.displayName());
   }
+  /** Subtract `n` years from this timestamp. */
   subtractYears(n) {
     return new DateArithmeticOperation(this.cwj(), n, "YEAR" /* YEAR */, false, "Subtract Years " + this.displayName());
   }
+  /** Subtract `n` hours from this timestamp. */
   subtractHours(n) {
     return new DateArithmeticOperation(this.cwj(), n, "HOUR" /* HOUR */, false, "Subtract Hours " + this.displayName());
   }
+  /** Subtract `n` minutes from this timestamp. */
   subtractMinutes(n) {
     return new DateArithmeticOperation(this.cwj(), n, "MINUTE" /* MINUTE */, false, "Subtract Minutes " + this.displayName());
   }
+  /** Subtract `n` seconds from this timestamp. */
   subtractSeconds(n) {
     return new DateArithmeticOperation(this.cwj(), n, "SECOND" /* SECOND */, false, "Subtract Seconds " + this.displayName());
   }
+  /** Number of whole days between this timestamp and `other`. */
   diffDays(other) {
     return new DateDiffOperation(this.cwj(), other, "DAY" /* DAY */, "Diff Days " + this.displayName());
   }
+  /** Number of whole months between this timestamp and `other`. */
   diffMonths(other) {
     return new DateDiffOperation(this.cwj(), other, "MONTH" /* MONTH */, "Diff Months " + this.displayName());
   }
+  /** Number of whole years between this timestamp and `other`. */
   diffYears(other) {
     return new DateDiffOperation(this.cwj(), other, "YEAR" /* YEAR */, "Diff Years " + this.displayName());
   }
+  /** Number of whole hours between this timestamp and `other`. */
   diffHours(other) {
     return new DateDiffOperation(this.cwj(), other, "HOUR" /* HOUR */, "Diff Hours " + this.displayName());
   }
+  /** Number of whole minutes between this timestamp and `other`. */
   diffMinutes(other) {
     return new DateDiffOperation(this.cwj(), other, "MINUTE" /* MINUTE */, "Diff Minutes " + this.displayName());
   }
+  /** Number of whole seconds between this timestamp and `other`. */
   diffSeconds(other) {
     return new DateDiffOperation(this.cwj(), other, "SECOND" /* SECOND */, "Diff Seconds " + this.displayName());
   }
 };
+applyMixins(DateAttribute, [MinMax]);
+applyMixins(DateTimeAttribute, [MinMax]);
 
-// src/datafinder/finder.ts
-var ExistsOperation = class extends RelationalOperationElement {
-  constructor(node) {
-    super();
-    this.node = node;
-  }
-  node;
-  andOp(other) {
-    return new LogicalOperation(this, "AND" /* AND */, other);
-  }
+// src/datafinder/dialect.ts
+var doubleQuoted = (name) => '"' + name.replaceAll('"', '""') + '"';
+var quoted = (value) => "'" + value.replaceAll("'", "''") + "'";
+var SECONDS_PER = { ["HOUR" /* HOUR */]: 3600, ["MINUTE" /* MINUTE */]: 60, ["SECOND" /* SECOND */]: 1 };
+var POSTGRES = {
+  name: "postgres",
+  quoteIdentifier: doubleQuoted,
+  stringLiteral: quoted,
+  orderDirection: (direction) => direction === "ASC" /* ASC */ ? " ASC" : " DESC",
+  doubleType: "DOUBLE PRECISION",
+  dayOfWeek: (expression) => `EXTRACT(DOW FROM ${expression})`,
+  dateDiff(unit, from, to) {
+    const start = `CAST(${from} AS TIMESTAMP)`;
+    const end = `CAST(${to} AS TIMESTAMP)`;
+    switch (unit) {
+      case "DAY" /* DAY */:
+        return `(CAST(${to} AS DATE) - CAST(${from} AS DATE))`;
+      case "MONTH" /* MONTH */:
+        return `CAST(EXTRACT(YEAR FROM AGE(${end}, ${start})) * 12 + EXTRACT(MONTH FROM AGE(${end}, ${start})) AS BIGINT)`;
+      case "YEAR" /* YEAR */:
+        return `CAST(EXTRACT(YEAR FROM AGE(${end}, ${start})) AS BIGINT)`;
+      default: {
+        const seconds = SECONDS_PER[unit];
+        if (seconds === void 0) throw new Error(`Cannot take the difference in ${unit}`);
+        return `CAST(FLOOR(EXTRACT(EPOCH FROM (${end} - ${start})) / ${seconds}) AS BIGINT)`;
+      }
+    }
+  },
+  stringAgg: (expression, separator, orderBy) => `STRING_AGG(${expression}, ${separator}${orderBy.length > 0 ? " ORDER BY " + orderBy.join(", ") : ""})`
 };
-var NotExistsOperation = class extends RelationalOperationElement {
-  constructor(node) {
-    super();
-    this.node = node;
-  }
-  node;
-  andOp(other) {
-    return new LogicalOperation(this, "AND" /* AND */, other);
-  }
+var DUCKDB = {
+  ...POSTGRES,
+  name: "duckdb",
+  // DuckDB sorts nulls last whichever way the sort goes
+  orderDirection: (direction) => direction === "ASC" /* ASC */ ? " ASC" : " DESC NULLS FIRST",
+  doubleType: "DOUBLE",
+  dateDiff: (unit, from, to) => `DATE_DIFF('${unit.toLowerCase()}', ${from}, ${to})`
+};
+var DATABRICKS = {
+  name: "databricks",
+  // a double-quoted token is a string in Databricks; identifiers take backticks
+  quoteIdentifier: (name) => "`" + name.replaceAll("`", "``") + "`",
+  // a backslash starts an escape in a Databricks string literal, and a doubled quote is not one: Spark reads
+  // 'it''s' as the two literals 'it' and 's' and joins them, losing the quote. A quote is escaped with a backslash.
+  stringLiteral: (value) => "'" + value.replaceAll("\\", "\\\\").replaceAll("'", "\\'") + "'",
+  // Databricks sorts nulls first when ascending, last when descending
+  orderDirection: (direction) => direction === "ASC" /* ASC */ ? " ASC NULLS LAST" : " DESC NULLS FIRST",
+  doubleType: "DOUBLE",
+  // DAYOFWEEK is 1 = Sunday through 7 = Saturday
+  dayOfWeek: (expression) => `(DAYOFWEEK(${expression}) - 1)`,
+  dateDiff: (unit, from, to) => `DATEDIFF(${unit}, ${from}, ${to})`,
+  stringAgg: (expression, separator, orderBy) => `LISTAGG(${expression}, ${separator})${orderBy.length > 0 ? " WITHIN GROUP (ORDER BY " + orderBy.join(", ") + ")" : ""}`
 };
+var DIALECTS = { postgres: POSTGRES, duckdb: DUCKDB, databricks: DATABRICKS };
+function dialectOf(dialect) {
+  if (typeof dialect !== "string") return dialect;
+  const found = DIALECTS[dialect];
+  if (found === void 0) throw new Error(`Unknown SQL dialect '${dialect}': one of ${Object.keys(DIALECTS).join(", ")}`);
+  return found;
+}
 
 // src/datafinder/sql-generator.ts
-var Alias = class {
-  constructor(element, name) {
-    this.element = element;
-    this.name = name;
-  }
-  element;
-  name;
-};
 var TableAlias = class {
   constructor(table, alias) {
     this.table = table;
@@ -723,22 +1652,12 @@ var Join = class {
   source;
   target;
   filterOp;
-};
-var SelectOperation = class {
-  constructor(display, filter, orderBy = [], groupBy = [], limit, table) {
-    this.display = display;
-    this.filter = filter;
-    this.orderBy = orderBy;
-    this.groupBy = groupBy;
-    this.limit = limit;
-    this.table = table;
+  /** `source = target`, written with the key column first as Legend writes a join defined as key = foreign key. */
+  condition() {
+    let [first, second] = [this.source, this.target];
+    if (second.column.primaryKey && !first.column.primaryKey) [first, second] = [second, first];
+    return first.tableAlias.alias + "." + first.column.name + " = " + second.tableAlias.alias + "." + second.column.name;
   }
-  display;
-  filter;
-  orderBy;
-  groupBy;
-  limit;
-  table;
 };
 function sqlFormatDatetime(value) {
   const pad = (n, w = 2) => String(n).padStart(w, "0");
@@ -765,6 +1684,13 @@ var COMPARISON_OPERATOR_STR = {
 var AGGREGATE_SQL_NAMES = {
   ["AVERAGE" /* AVERAGE */]: "AVG"
 };
+var GUARDED_COMPARISONS = /* @__PURE__ */ new Set([
+  "LESS_THAN" /* LESS_THAN */,
+  "GREATER_THAN" /* GREATER_THAN */,
+  "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */,
+  "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */,
+  "LIKE" /* LIKE */
+]);
 var WINDOW_SQL_NAMES = {
   ["ROW_NUMBER" /* ROW_NUMBER */]: "ROW_NUMBER",
   ["RANK" /* RANK */]: "RANK",
@@ -796,31 +1722,63 @@ var SCALAR_SQL_NAMES = {
   ["RIGHT" /* RIGHT */]: "RIGHT",
   ["REPEAT" /* REPEAT */]: "REPEAT",
   ["REPLACE" /* REPLACE */]: "REPLACE",
-  ["SUBSTRING" /* SUBSTRING */]: "SUBSTRING"
+  ["SUBSTRING" /* SUBSTRING */]: "SUBSTRING",
+  ["COALESCE" /* COALESCE */]: "COALESCE"
 };
-function constantValueString(op) {
-  if (op instanceof StringConstantOperation) return "'" + op.value + "'";
+function constantValueString(op, d) {
+  if (op instanceof StringConstantOperation) return d.stringLiteral(op.value);
   if (op instanceof DateConstantOperation) return sqlFormatDate(op.value);
   if (op instanceof DateTimeConstantOperation) return sqlFormatDatetime(op.value);
   if (op instanceof IntegerConstantOperation) return String(op.value);
-  if (op instanceof FloatConstantOperation) return String(op.value);
+  if (op instanceof FloatConstantOperation) return Number.isInteger(op.value) && Math.abs(op.value) < 1e21 ? op.value.toFixed(1) : String(op.value);
   if (op instanceof BooleanConstantOperation) return op.value ? "TRUE" : "FALSE";
   if (op instanceof DecimalConstantOperation) return String(op.value);
   throw new Error("Unknown constant operation");
 }
-function windowSpecToString(window) {
+function selectedConstantString(op, d) {
+  if (op instanceof FloatConstantOperation) return "CAST(" + constantValueString(op, d) + " AS " + d.doubleType + ")";
+  if (op instanceof DateTimeConstantOperation) return "TIMESTAMP " + constantValueString(op, d);
+  if (op instanceof DateConstantOperation) return "DATE " + constantValueString(op, d);
+  return constantValueString(op, d);
+}
+function windowSpecToString(window, d) {
   const parts = [];
   if (window.partitionBy.length > 0) {
-    parts.push("PARTITION BY " + window.partitionBy.map((p) => sqlOperationToString(p)).join(", "));
+    parts.push("PARTITION BY " + window.partitionBy.map((p) => sqlOperationToString(p, d)).join(", "));
   }
   if (window.orderBy.length > 0) {
     parts.push("ORDER BY " + window.orderBy.map(
-      (s) => sqlOperationToString(s.column) + (s.direction === "ASC" /* ASC */ ? " ASC" : " DESC")
+      (s) => sqlOperationToString(s.column, d) + d.orderDirection(s.direction)
     ).join(", "));
   }
   return "OVER (" + parts.join(" ") + ")";
 }
-function sqlOperationToString(operation) {
+var ARITHMETIC_PRECEDENCE = {
+  ["+" /* ADD */]: 1,
+  ["-" /* SUBTRACT */]: 1,
+  ["*" /* MULTIPLY */]: 2,
+  ["/" /* DIVIDE */]: 2
+};
+function arithmeticNeedsParentheses(parent, child, onRight) {
+  if (!(child instanceof ArithmeticOperation)) return false;
+  const here = ARITHMETIC_PRECEDENCE[parent.operator];
+  const there = ARITHMETIC_PRECEDENCE[child.operator];
+  return there < here || there === here && onRight && (parent.operator === "-" /* SUBTRACT */ || parent.operator === "/" /* DIVIDE */);
+}
+function operandString(operation, d) {
+  return operation instanceof ConstantOperation ? constantValueString(operation, d) : sqlOperationToString(operation, d);
+}
+var RenderedSql = class extends RelationalOperationElement {
+  constructor(sql) {
+    super();
+    this.sql = sql;
+  }
+  sql;
+};
+function isCondition(op) {
+  return op instanceof ComparisonOperation || op instanceof LogicalOperation || op instanceof IsNullOperation || op instanceof IsNotNullOperation || op instanceof InOperation || op instanceof NotInOperation || op instanceof ExistsOperation || op instanceof NotExistsOperation;
+}
+function sqlOperationToString(operation, d) {
   if (operation instanceof TableAliasColumn) {
     return operation.tableAlias.alias + "." + operation.column.name;
   }
@@ -828,49 +1786,77 @@ function sqlOperationToString(operation) {
     const fn = WINDOW_SQL_NAMES[operation.func];
     const parts = [];
     if (operation.element !== null && operation.element !== void 0) {
-      parts.push(sqlOperationToString(operation.element));
+      parts.push(sqlOperationToString(operation.element, d));
     }
     if (operation.secondArg !== void 0) parts.push(String(operation.secondArg));
     for (const arg of operation.extraArgs) {
-      parts.push(typeof arg === "string" ? "'" + arg + "'" : String(arg));
+      parts.push(typeof arg === "string" ? d.stringLiteral(arg) : String(arg));
     }
     const sql = fn + "(" + parts.join(", ") + ")";
-    return sql + (operation.window !== void 0 ? " " + windowSpecToString(operation.window) : " OVER ()");
+    return sql + (operation.window !== void 0 ? " " + windowSpecToString(operation.window, d) : " OVER ()");
+  }
+  if (operation instanceof AggregateOperation && operation.operator === "COUNT_DISTINCT" /* COUNT_DISTINCT */) {
+    return "COUNT(DISTINCT " + sqlOperationToString(operation.element, d) + ")";
+  }
+  if (operation instanceof AggregateOperation && operation.operator === "STRING_AGG" /* STRING_AGG */) {
+    let sql = d.stringAgg(
+      sqlOperationToString(operation.element, d),
+      d.stringLiteral(operation.separator ?? ""),
+      operation.orderBy.map((s) => sqlOperationToString(s.column, d) + d.orderDirection(s.direction))
+    );
+    if (operation.window !== void 0) sql += " " + windowSpecToString(operation.window, d);
+    return sql;
   }
   if (operation instanceof AggregateOperation) {
     const fn = AGGREGATE_SQL_NAMES[operation.operator] ?? operation.operator;
-    let sql = fn + "(" + sqlOperationToString(operation.element) + ")";
+    let sql = fn + "(" + sqlOperationToString(operation.element, d) + ")";
     if (operation.window !== void 0) {
-      sql += " " + windowSpecToString(operation.window);
+      sql += " " + windowSpecToString(operation.window, d);
     }
     return sql;
   }
   if (operation instanceof ScalarFunctionOperation) {
     const fn = SCALAR_SQL_NAMES[operation.func];
-    const parts = [sqlOperationToString(operation.element)];
+    const parts = [sqlOperationToString(operation.element, d)];
     if (operation.secondArg !== void 0) parts.push(String(operation.secondArg));
     for (const arg of operation.extraArgs) {
-      parts.push(typeof arg === "string" ? "'" + arg + "'" : String(arg));
+      parts.push(typeof arg === "string" ? d.stringLiteral(arg) : String(arg));
     }
     return fn + "(" + parts.join(", ") + ")";
   }
   if (operation instanceof DateExtractOperation) {
-    return "EXTRACT(" + operation.part + " FROM " + sqlOperationToString(operation.element) + ")";
+    const element = sqlOperationToString(operation.element, d);
+    return operation.part === "DOW" /* DOW */ ? d.dayOfWeek(element) : "EXTRACT(" + operation.part + " FROM " + element + ")";
+  }
+  if (operation instanceof DateTruncOperation) {
+    return "CAST(DATE_TRUNC('" + operation.part.toLowerCase() + "', " + sqlOperationToString(operation.element, d) + ") AS DATE)";
   }
   if (operation instanceof DateArithmeticOperation) {
     const op = operation.isAdd ? "+" : "-";
-    return sqlOperationToString(operation.element) + " " + op + " INTERVAL " + operation.n + " " + operation.unit;
+    return sqlOperationToString(operation.element, d) + " " + op + " INTERVAL '" + operation.n + "' " + operation.unit;
   }
   if (operation instanceof DateDiffOperation) {
-    const otherSql = sqlFormatDatetime(operation.other);
-    return "DATE_DIFF('" + operation.unit.toLowerCase() + "', " + sqlOperationToString(operation.element) + ", " + otherSql + ")";
+    return d.dateDiff(operation.unit, sqlOperationToString(operation.element, d), "TIMESTAMP " + sqlFormatDatetime(operation.other));
   }
   if (operation instanceof CountAllOperation) return "COUNT(*)";
+  if (operation instanceof ConstantOperation) return selectedConstantString(operation, d);
+  if (operation instanceof RenderedSql) return operation.sql;
+  if (operation instanceof ConcatOperation) return operation.parts.map((part) => operandString(part, d)).join(" || ");
+  if (operation instanceof ArithmeticOperation) {
+    let left = operandString(operation.left, d);
+    let right = operandString(operation.right, d);
+    if (arithmeticNeedsParentheses(operation, operation.left, false)) left = "(" + left + ")";
+    if (arithmeticNeedsParentheses(operation, operation.right, true)) right = "(" + right + ")";
+    return left + " " + operation.operator + " " + right;
+  }
   if (operation instanceof Alias) {
-    return sqlOperationToString(operation.element) + ' AS "' + operation.name + '"';
+    return sqlOperationToString(operation.element, d) + " AS " + d.quoteIdentifier(operation.name);
   }
   throw new TypeError("Unknown operation in sqlOperationToString: " + operation.constructor.name);
 }
+function embeddedOf(ref) {
+  return ref instanceof Attribute ? ref.embedded() : ref.embedded;
+}
 function findColumn(operation) {
   if (operation instanceof UnaryOperation) return findColumn(operation.element);
   if (operation instanceof ColumnWithJoin) return operation;
@@ -884,89 +1870,195 @@ function openEndClause(endAttr, value, infiniteDatetime) {
   }
   return gtOp;
 }
+function andAll(ops) {
+  const present = ops.filter((op) => op !== null);
+  if (present.length === 0) return null;
+  return present.slice(1).reduce((left, right) => new LogicalOperation(left, "AND" /* AND */, right), present[0]);
+}
+function processingPredicate(mc, processingDatetime, joinNode) {
+  if (!(mc instanceof ProcessingTemporalColumns || mc instanceof BusinessDateAndProcessingTemporalColumns || mc instanceof BiTemporalColumns) || processingDatetime === null) return null;
+  const startAt = new DateTimeAttribute("start_at", mc.startAtColumn.name, mc.startAtColumn.type, mc.startAtColumn.table.qualifiedName, joinNode);
+  const endAt = new DateTimeAttribute("end_at", mc.endAtColumn.name, mc.endAtColumn.type, mc.endAtColumn.table.qualifiedName, joinNode);
+  return new LogicalOperation(startAt.lte(processingDatetime), "AND" /* AND */, openEndClause(endAt, processingDatetime, mc.infiniteDatetime));
+}
+function businessPredicate(mc, businessDate, joinNode) {
+  if (businessDate === null) return null;
+  if (mc instanceof BiTemporalColumns) {
+    const dateFrom = new DateAttribute("business_date_from", mc.businessDateFromColumn.name, mc.businessDateFromColumn.type, mc.businessDateFromColumn.table.qualifiedName, joinNode);
+    const dateTo = new DateAttribute("business_date_to", mc.businessDateToColumn.name, mc.businessDateToColumn.type, mc.businessDateToColumn.table.qualifiedName, joinNode);
+    return new LogicalOperation(dateFrom.lte(businessDate), "AND" /* AND */, openEndClause(dateTo, businessDate, mc.infiniteDatetime));
+  }
+  if (mc instanceof BusinessDateAndProcessingTemporalColumns || mc instanceof SingleBusinessDateColumn) {
+    const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
+    return businessAtt.eq(businessDate);
+  }
+  return null;
+}
+function businessRangePredicate(mc, businessDateFrom, businessDateTo, joinNode) {
+  if (businessDateFrom === null || businessDateTo === null) return null;
+  if (mc instanceof BiTemporalColumns) {
+    const dateFrom = new DateAttribute("business_date_from", mc.businessDateFromColumn.name, mc.businessDateFromColumn.type, mc.businessDateFromColumn.table.qualifiedName, joinNode);
+    const dateTo = new DateAttribute("business_date_to", mc.businessDateToColumn.name, mc.businessDateToColumn.type, mc.businessDateToColumn.table.qualifiedName, joinNode);
+    return new LogicalOperation(dateFrom.lte(businessDateTo), "AND" /* AND */, openEndClause(dateTo, businessDateFrom, mc.infiniteDatetime));
+  }
+  if (mc instanceof BusinessDateAndProcessingTemporalColumns || mc instanceof SingleBusinessDateColumn) {
+    const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
+    return new LogicalOperation(businessAtt.gte(businessDateFrom), "AND" /* AND */, businessAtt.lte(businessDateTo));
+  }
+  return null;
+}
 function buildMilestoningFilterOperation(businessDate, processingDatetime, table, joinNode) {
   const mc = table.milestoningColumns;
+  return andAll([processingPredicate(mc, processingDatetime, joinNode), businessPredicate(mc, businessDate, joinNode)]);
+}
+function buildMilestoningFilterOperationForDateRange(businessDateFrom, businessDateTo, processingDatetime, table, joinNode) {
+  const mc = table.milestoningColumns;
+  return andAll([
+    processingPredicate(mc, processingDatetime, joinNode),
+    businessRangePredicate(mc, businessDateFrom, businessDateTo, joinNode)
+  ]);
+}
+function walkRefs(op, visit, visitExists) {
+  if (op === null || op === void 0) return;
+  if (op instanceof Attribute || op instanceof ColumnWithJoin) {
+    visit(op);
+  } else if (op instanceof ExistsOperation || op instanceof NotExistsOperation) {
+    visitExists?.(op.node);
+  } else if (op instanceof AggregateOperation) {
+    walkRefs(op.element, visit, visitExists);
+    if (op.window) walkWindowSpec(op.window, visit, visitExists);
+    for (const sort of op.orderBy) walkRefs(sort, visit, visitExists);
+  } else if (op instanceof WindowFunctionOperation) {
+    if (op.element) walkRefs(op.element, visit, visitExists);
+    if (op.window) walkWindowSpec(op.window, visit, visitExists);
+  } else if (op instanceof ScalarFunctionOperation || op instanceof DateExtractOperation || op instanceof DateTruncOperation || op instanceof DateArithmeticOperation || op instanceof DateDiffOperation || op instanceof IsNullOperation || op instanceof IsNotNullOperation || op instanceof InOperation || op instanceof NotInOperation) {
+    walkRefs(op.element, visit, visitExists);
+  } else if (op instanceof Alias) {
+    walkRefs(op.element, visit, visitExists);
+  } else if (op instanceof ConcatOperation) {
+    for (const part of op.parts) walkRefs(part, visit, visitExists);
+  } else if (op instanceof ArithmeticOperation) {
+    walkRefs(op.left, visit, visitExists);
+    walkRefs(op.right, visit, visitExists);
+  } else if (op instanceof CaseOperation) {
+    walkRefs(op.condition, visit, visitExists);
+    walkRefs(op.then, visit, visitExists);
+    walkRefs(op.fallback, visit, visitExists);
+  } else if (op instanceof SortOperation) {
+    walkRefs(op.column, visit, visitExists);
+  } else if (op instanceof LogicalOperation || op instanceof ComparisonOperation) {
+    walkRefs(op.left, visit, visitExists);
+    walkRefs(op.right, visit, visitExists);
+  }
+}
+function walkWindowSpec(window, visit, visitExists) {
+  for (const p of window.partitionBy) walkRefs(p, visit, visitExists);
+  for (const s of window.orderBy) walkRefs(s.column, visit, visitExists);
+}
+function buildJoinFilterFromProperties(node, filter, columnMap) {
   const ops = [];
-  if (mc instanceof BiTemporalColumns) {
-    if (businessDate !== null) {
-      const dateFrom = new DateAttribute("business_date_from", mc.businessDateFromColumn.name, mc.businessDateFromColumn.type, mc.businessDateFromColumn.table.qualifiedName, joinNode);
-      const dateTo = new DateAttribute("business_date_to", mc.businessDateToColumn.name, mc.businessDateToColumn.type, mc.businessDateToColumn.table.qualifiedName, joinNode);
-      ops.push(new LogicalOperation(dateFrom.lte(businessDate), "AND" /* AND */, openEndClause(dateTo, businessDate, mc.infiniteDatetime)));
-    }
-    if (processingDatetime !== null) {
-      const startAt = new DateTimeAttribute("start_at", mc.startAtColumn.name, mc.startAtColumn.type, mc.startAtColumn.table.qualifiedName, joinNode);
-      const endAt = new DateTimeAttribute("end_at", mc.endAtColumn.name, mc.endAtColumn.type, mc.endAtColumn.table.qualifiedName, joinNode);
-      ops.push(new LogicalOperation(startAt.lte(processingDatetime), "AND" /* AND */, openEndClause(endAt, processingDatetime, mc.infiniteDatetime)));
-    }
-  } else if (mc instanceof BusinessDateAndProcessingTemporalColumns) {
-    if (businessDate !== null) {
-      const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
-      ops.push(businessAtt.eq(businessDate));
-    }
-    if (processingDatetime !== null) {
-      const startAt = new DateTimeAttribute("start_at", mc.startAtColumn.name, mc.startAtColumn.type, mc.startAtColumn.table.qualifiedName, joinNode);
-      const endAt = new DateTimeAttribute("end_at", mc.endAtColumn.name, mc.endAtColumn.type, mc.endAtColumn.table.qualifiedName, joinNode);
-      ops.push(new LogicalOperation(startAt.lte(processingDatetime), "AND" /* AND */, openEndClause(endAt, processingDatetime, mc.infiniteDatetime)));
+  for (const [key, value] of Object.entries(filter)) {
+    const entry = columnMap[key];
+    if (entry === void 0) {
+      throw new Error(`Unknown property '${key}' \u2014 valid properties are: ${Object.keys(columnMap).sort().join(", ")}`);
     }
-  } else if (mc instanceof ProcessingTemporalColumns && processingDatetime !== null) {
-    const startAt = new DateTimeAttribute("start_at", mc.startAtColumn.name, mc.startAtColumn.type, mc.startAtColumn.table.qualifiedName, joinNode);
-    const endAt = new DateTimeAttribute("end_at", mc.endAtColumn.name, mc.endAtColumn.type, mc.endAtColumn.table.qualifiedName, joinNode);
-    ops.push(new LogicalOperation(startAt.lte(processingDatetime), "AND" /* AND */, openEndClause(endAt, processingDatetime, mc.infiniteDatetime)));
-  } else if (mc instanceof SingleBusinessDateColumn && businessDate !== null) {
-    const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
-    ops.push(businessAtt.eq(businessDate));
-  }
-  if (ops.length === 0) return null;
-  if (ops.length === 1) return ops[0];
-  return new LogicalOperation(ops[0], "AND" /* AND */, ops[1]);
+    const [name, type, table] = entry;
+    const col = new ColumnWithJoin(new Column(name, type, table), node);
+    let constant;
+    if (typeof value === "boolean") constant = new BooleanConstantOperation(value);
+    else if (typeof value === "number") constant = Number.isInteger(value) ? new IntegerConstantOperation(value) : new FloatConstantOperation(value);
+    else if (value instanceof Date) constant = type.toUpperCase() === "DATE" ? new DateConstantOperation(value) : new DateTimeConstantOperation(value);
+    else constant = new StringConstantOperation(String(value));
+    ops.push(new ComparisonOperation(col, "EQUAL" /* EQUAL */, constant));
+  }
+  return ops.reduce((acc, op) => new LogicalOperation(acc, "AND" /* AND */, op));
 }
-function buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit) {
+function withAncestors(nodes) {
+  const ordered = /* @__PURE__ */ new Set();
+  const add = (node) => {
+    if (ordered.has(node)) return;
+    if (node.parent !== void 0) add(node.parent);
+    ordered.add(node);
+  };
+  for (const node of nodes) add(node);
+  return [...ordered];
+}
+function buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit, businessDateTo = null, distinct = false, offset, having) {
   let filter = op;
+  const milestoningFor = (t, node) => businessDateTo !== null ? buildMilestoningFilterOperationForDateRange(businessDate, businessDateTo, processingDatetime, t, node) : buildMilestoningFilterOperation(businessDate, processingDatetime, t, node);
   if (table instanceof MilestonedTable) {
-    const milestonedOp = buildMilestoningFilterOperation(businessDate, processingDatetime, table);
+    const milestonedOp = milestoningFor(table);
     if (milestonedOp !== null) {
       filter = filter instanceof NoOperation ? milestonedOp : new LogicalOperation(filter, "AND" /* AND */, milestonedOp);
     }
   }
-  const requiredJoins = [];
-  const requiredJoinIds = /* @__PURE__ */ new Set();
-  for (const col of columns) {
-    if (col instanceof CountAllOperation) continue;
-    let node;
-    if (col instanceof Attribute) {
-      node = col.parent();
-    } else {
-      node = findColumn(col).parent;
+  const requiredJoins = /* @__PURE__ */ new Set();
+  const collect = (ref) => {
+    const parent = ref instanceof Attribute ? ref.parent() : ref.parent;
+    if (parent !== void 0) requiredJoins.add(parent);
+  };
+  const collectNode = (node) => requiredJoins.add(node);
+  for (const col of columns) walkRefs(col, collect, collectNode);
+  for (const expr of groupBy) walkRefs(expr, collect, collectNode);
+  for (const sort of orderBy) walkRefs(sort, collect, collectNode);
+  walkRefs(op, collect, collectNode);
+  const joinFilters = /* @__PURE__ */ new Map();
+  for (const node of withAncestors(requiredJoins)) {
+    let combined;
+    if (Object.keys(node.join.filterKwargs).length > 0) {
+      combined = buildJoinFilterFromProperties(node, node.join.filterKwargs, node.join.filterColumnMap);
     }
-    if (node !== void 0 && !requiredJoinIds.has(node)) {
-      requiredJoinIds.add(node);
-      requiredJoins.push(node);
-    }
-  }
-  for (const node of requiredJoins) {
     if (node.join.target instanceof MilestonedTable) {
-      const milestonedOp = buildMilestoningFilterOperation(businessDate, processingDatetime, node.join.target, node);
+      const milestonedOp = milestoningFor(node.join.target, node);
       if (milestonedOp !== null) {
-        node.join.filter = milestonedOp;
+        combined = combined === void 0 ? milestonedOp : new LogicalOperation(combined, "AND" /* AND */, milestonedOp);
       }
     }
+    if (combined !== void 0) joinFilters.set(node, combined);
   }
-  return new SelectOperation(columns, filter, orderBy, groupBy, limit, table);
+  return new SelectOperation(columns, filter, orderBy, groupBy, limit, table, joinFilters, distinct, offset, having);
+}
+function needsParentheses(parent, child) {
+  return child instanceof LogicalOperation && child.operator !== parent.operator;
+}
+function reachesToMany(op) {
+  if (op instanceof ColumnWithJoin) {
+    for (let node = op.parent; node !== void 0; node = node.parent) if (node.many) return true;
+    return false;
+  }
+  if (op instanceof UnaryOperation || op instanceof Alias) return reachesToMany(op.element);
+  if (op instanceof BinaryOperation) return reachesToMany(op.left) || reachesToMany(op.right);
+  return false;
+}
+function unaliased(op) {
+  return op instanceof Alias ? unaliased(op.element) : op;
 }
 var SQLQueryGenerator = class {
+  constructor(_dialect) {
+    this._dialect = _dialect;
+  }
+  _dialect;
   _select = [];
   _from = /* @__PURE__ */ new Set();
   _join = [];
   _groupByParts = [];
+  _having = "";
   _orderByParts = [];
   _where = "";
   _limit;
+  _distinct = false;
+  _offset;
   _tableAliasIncr = 0;
   _tableAliasesByTable = /* @__PURE__ */ new Map();
   _addedJoinIds = /* @__PURE__ */ new Set();
   _rootTable;
+  _elidableNodes = /* @__PURE__ */ new Set();
+  _joinFilters = /* @__PURE__ */ new Map();
+  _guardOptional = true;
   generate(select) {
     this._rootTable = select.table;
+    this._elidableNodes = this._computeElidableNodes(select);
+    this._joinFilters = select.joinFilters;
     if (this._rootTable !== void 0) {
       this._from.add(this._tableAliasForTable(this._rootTable.qualifiedName, this._rootTable.qualifiedName));
     }
@@ -979,46 +2071,104 @@ var SQLQueryGenerator = class {
     for (const node of groupByJoins.values()) {
       this._addJoin(node);
     }
-    this._groupByParts = select.groupBy.map((a) => this._attrToColString(a));
+    this._groupByParts = this._groupByPartsFor(select);
+    this._having = "";
+    if (select.having !== void 0) {
+      const havingJoins = /* @__PURE__ */ new Map();
+      this._collectRequiredJoins(select.having, havingJoins);
+      for (const node of havingJoins.values()) this._addJoin(node);
+      this._guardOptional = false;
+      try {
+        this._having = this.buildFilter(select.having);
+      } finally {
+        this._guardOptional = true;
+      }
+    }
     this._orderByParts = select.orderBy.map(
-      (s) => this.buildFilter(s.column) + (s.direction === "ASC" /* ASC */ ? " ASC" : " DESC")
+      (s) => this._sortExpression(s.column) + this._dialect.orderDirection(s.direction)
     );
     this._limit = select.limit;
+    this._distinct = select.distinct;
+    this._offset = select.offset;
+  }
+  /**
+   * The GROUP BY of a query: the grouping it was given, else the grouping its columns imply.
+   *
+   * Columns that are not aggregated are what the aggregates are computed for, so a query that selects both is
+   * grouped by those columns (as a DataFrame's `groupby(columns).agg(...)` does). An aggregate read through a
+   * to-many association is computed for each row of the root table, as Legend does, so the root's primary key
+   * is grouped by too. A query that selects only aggregates over the root's own columns is not grouped: the
+   * aggregate covers every row. A constant needs no grouping: a bare
+   * `GROUP BY 7` would be a column position.
+   */
+  _groupByPartsFor(select) {
+    if (select.groupBy.length > 0) return select.groupBy.map((a) => this._attrToColString(a));
+    const aggregates = select.display.filter(containsAggregate);
+    if (aggregates.length === 0) return [];
+    const perRoot = select.table !== void 0 && aggregates.some(reachesToMany);
+    const keys = perRoot ? select.table.columns.filter((c) => c.primaryKey).map((c) => this._columnToString(c)) : [];
+    const grouped = select.display.map((column, i) => ({ column, shown: this._select[i] })).filter(({ column }) => !containsAggregateOrWindow(column) && !(unaliased(column) instanceof ConstantOperation)).map(({ shown }) => sqlOperationToString(shown.element, this._dialect));
+    return [.../* @__PURE__ */ new Set([...keys, ...grouped])];
+  }
+  /** What a sort orders by: a column, or an expression such as an aggregate. */
+  _sortExpression(expression) {
+    if (expression instanceof ColumnWithJoin || expression instanceof Attribute) return this.buildFilter(expression);
+    return sqlOperationToString(this._rewriteOperation(expression), this._dialect);
+  }
+  _columnToString(column) {
+    return this._tableAliasForTable(column.owner, column.owner).alias + "." + column.name;
   }
   _attrToColString(attr) {
-    const node = attr.parent();
-    const ta = this._tableAliasForTable(attr.owner(), node ?? attr.owner());
-    return ta.alias + "." + attr.column().name;
+    const { column, parent } = this._resolve(attr);
+    const ta = this._tableAliasForTable(column.owner, parent ?? column.owner);
+    return ta.alias + "." + column.name;
   }
   _collectRequiredJoins(op, out) {
-    if (op === null || op === void 0) return;
-    if (op instanceof Attribute) {
-      const p = op.parent();
-      if (p !== void 0) out.set(p, p);
-    } else if (op instanceof ColumnWithJoin) {
-      if (op.parent !== void 0) out.set(op.parent, op.parent);
-    } else if (op instanceof AggregateOperation) {
-      this._collectRequiredJoins(op.element, out);
-      if (op.window) this._collectRequiredJoins(op.window, out);
-    } else if (op instanceof WindowFunctionOperation) {
-      if (op.element) this._collectRequiredJoins(op.element, out);
-      if (op.window) this._collectRequiredJoinsFromWindowSpec(op.window, out);
-    } else if (op instanceof ScalarFunctionOperation || op instanceof DateExtractOperation || op instanceof DateArithmeticOperation || op instanceof DateDiffOperation) {
-      this._collectRequiredJoins(op.element, out);
-    } else if (op instanceof SortOperation) {
-      this._collectRequiredJoins(op.column, out);
-    } else if (op instanceof LogicalOperation || op instanceof ComparisonOperation) {
-      this._collectRequiredJoins(op.left, out);
-      this._collectRequiredJoins(op.right, out);
+    walkRefs(op, (ref) => {
+      const { parent } = this._resolve(ref);
+      if (parent !== void 0) out.set(parent, parent);
+    });
+  }
+  /**
+   * Determine upfront which join nodes can be satisfied entirely by embedded (join-less) alternates:
+   * a node is elidable when every reference to it has an embedded alternate. A reference without one
+   * (e.g. a milestoning column) keeps the join for every reference to that node.
+   */
+  _computeElidableNodes(select) {
+    const refsByNode = /* @__PURE__ */ new Map();
+    const record = (ref) => {
+      const parent = ref instanceof Attribute ? ref.parent() : ref.parent;
+      if (parent === void 0) return;
+      const refs = refsByNode.get(parent);
+      if (refs) refs.push(ref);
+      else refsByNode.set(parent, [ref]);
+    };
+    for (const col of select.display) walkRefs(col, record);
+    for (const expr of select.groupBy) walkRefs(expr, record);
+    for (const sort of select.orderBy) walkRefs(sort, record);
+    walkRefs(select.filter, record);
+    const elidable = /* @__PURE__ */ new Set();
+    for (const [node, refs] of refsByNode) {
+      if (refs.every((ref) => embeddedOf(ref) !== void 0)) elidable.add(node);
     }
-  }
-  _collectRequiredJoinsFromWindowSpec(window, out) {
-    for (const p of window.partitionBy) {
-      this._collectRequiredJoins(p, out);
+    return elidable;
+  }
+  /** The (column, parent) a reference should resolve to, substituting its embedded alternate when its join is elided. */
+  _resolve(ref) {
+    const column = ref instanceof Attribute ? ref.column() : ref.column;
+    const parent = ref instanceof Attribute ? ref.parent() : ref.parent;
+    if (parent !== void 0 && this._elidableNodes.has(parent)) {
+      const embedded = embeddedOf(ref);
+      if (embedded !== void 0) return this._resolve(embedded);
     }
-    for (const s of window.orderBy) {
-      this._collectRequiredJoins(s.column, out);
+    return { column, parent };
+  }
+  /** Whether the value `op` reads can be missing, in the join or embedded form that is used for it. */
+  _resolveOptional(op) {
+    if (op.parent !== void 0 && this._elidableNodes.has(op.parent) && op.embedded !== void 0) {
+      return this._resolveOptional(op.embedded);
     }
+    return op.optional;
   }
   _rewriteWindowSpec(window) {
     const partitionBy = window.partitionBy.map((p) => this._rewriteOperation(p));
@@ -1026,13 +2176,9 @@ var SQLQueryGenerator = class {
     return new WindowSpecification(partitionBy, orderBy);
   }
   _rewriteOperation(op) {
-    if (op instanceof Attribute) {
-      const ta = this._tableAliasForTable(op.owner(), op.parent() ?? op.owner());
-      return new TableAliasColumn(op.column(), ta);
-    }
-    if (op instanceof ColumnWithJoin) {
-      const ta = op.parent !== void 0 ? this._tableAliasForTable(op.column.owner, op.parent) : this._tableAliasForTable(op.column.owner, op.column.owner);
-      return new TableAliasColumn(op.column, ta);
+    if (op instanceof Attribute || op instanceof ColumnWithJoin) {
+      const { column, parent } = this._resolve(op);
+      return new TableAliasColumn(column, this._tableAliasForTable(column.owner, parent ?? column.owner));
     }
     if (op instanceof Column) {
       const ta = this._tableAliasForTable(op.owner, op.owner);
@@ -1043,9 +2189,17 @@ var SQLQueryGenerator = class {
         this._rewriteOperation(op.element),
         op.operator,
         op.displayName,
-        op.window ? this._rewriteWindowSpec(op.window) : void 0
+        op.window ? this._rewriteWindowSpec(op.window) : void 0,
+        op.separator,
+        op.orderBy.map((s) => new SortOperation(this._rewriteOperation(s.column), s.direction))
       );
     }
+    if (op instanceof CaseOperation) return new RenderedSql(this._caseSql(op));
+    if (isCondition(op)) return new RenderedSql(this.buildFilter(op));
+    if (op instanceof ConcatOperation) return new ConcatOperation(op.parts.map((part) => this._rewriteOperation(part)), op.displayName);
+    if (op instanceof ArithmeticOperation) {
+      return new ArithmeticOperation(this._rewriteOperation(op.left), op.operator, this._rewriteOperation(op.right), op.displayName);
+    }
     if (op instanceof WindowFunctionOperation) {
       const el = op.element ? this._rewriteOperation(op.element) : null;
       return new WindowFunctionOperation(
@@ -1063,6 +2217,9 @@ var SQLQueryGenerator = class {
     if (op instanceof DateExtractOperation) {
       return new DateExtractOperation(this._rewriteOperation(op.element), op.part, op.displayName);
     }
+    if (op instanceof DateTruncOperation) {
+      return new DateTruncOperation(this._rewriteOperation(op.element), op.part, op.displayName);
+    }
     if (op instanceof DateArithmeticOperation) {
       return new DateArithmeticOperation(this._rewriteOperation(op.element), op.n, op.unit, op.isAdd, op.displayName);
     }
@@ -1071,6 +2228,13 @@ var SQLQueryGenerator = class {
     }
     return op;
   }
+  /** The CASE written out now: its condition can only be rendered while the query is being built. */
+  _caseSql(op) {
+    const branch = (value) => value instanceof ConstantOperation ? constantValueString(value, this._dialect) : sqlOperationToString(this._rewriteOperation(value), this._dialect);
+    let sql = "CASE WHEN " + this.buildFilter(op.condition) + " THEN " + branch(op.then);
+    if (op.fallback !== void 0) sql += " ELSE " + branch(op.fallback);
+    return sql + " END";
+  }
   processSelect(cols) {
     const requiredJoins = /* @__PURE__ */ new Map();
     for (const col of cols) {
@@ -1079,88 +2243,96 @@ var SQLQueryGenerator = class {
     for (const node of requiredJoins.values()) {
       this._addJoin(node);
     }
-    for (const col of cols) {
-      if (col instanceof Attribute) {
-        const node = col.parent();
-        let ta;
-        if (node !== void 0) {
-          ta = this._tableAliasForTable(col.owner(), node);
-        } else {
-          ta = this._tableAliasForTable(col.owner(), col.owner());
-          this._from.add(ta);
-        }
-        this._select.push(new Alias(new TableAliasColumn(col.column(), ta), col.displayName()));
-      } else if (col instanceof WindowFunctionOperation) {
-        const rewritten = this._rewriteOperation(col);
-        let alias;
-        if (col.displayName) {
-          alias = col.displayName;
-        } else if (["ROW_NUMBER" /* ROW_NUMBER */, "RANK" /* RANK */, "DENSE_RANK" /* DENSE_RANK */].includes(col.func)) {
-          alias = col.func.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-        } else if (col.element) {
-          alias = col.func + " " + findColumn(col).column.name;
-        } else {
-          alias = col.func;
-        }
-        this._select.push(new Alias(rewritten, alias));
-      } else if (col instanceof AggregateOperation) {
-        const colNested = findColumn(col);
-        const node = colNested.parent;
-        let ta;
-        if (node !== void 0) {
-          ta = this._tableAliasForTable(colNested.column.owner, node);
-        } else {
-          ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
-          this._from.add(ta);
-        }
-        const alias = col.displayName ?? col.operator + " " + colNested.column.name;
-        const rewrittenAgg = new AggregateOperation(
-          new TableAliasColumn(colNested.column, ta),
-          col.operator,
-          void 0,
-          col.window ? this._rewriteWindowSpec(col.window) : void 0
-        );
-        this._select.push(new Alias(rewrittenAgg, alias));
-      } else if (col instanceof ScalarFunctionOperation) {
-        const colNested = findColumn(col);
-        const node = colNested.parent;
-        let ta;
-        if (node !== void 0) {
-          ta = this._tableAliasForTable(colNested.column.owner, node);
-        } else {
-          ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
-          this._from.add(ta);
-        }
-        const alias = col.displayName ?? col.func + " " + colNested.column.name;
-        this._select.push(new Alias(
-          new ScalarFunctionOperation(new TableAliasColumn(colNested.column, ta), col.func, void 0, col.secondArg, col.extraArgs),
-          alias
-        ));
-      } else if (col instanceof DateExtractOperation || col instanceof DateArithmeticOperation || col instanceof DateDiffOperation) {
-        const colNested = findColumn(col);
-        const node = colNested.parent;
-        let ta;
-        if (node !== void 0) {
-          ta = this._tableAliasForTable(colNested.column.owner, node);
-        } else {
-          ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
-          this._from.add(ta);
-        }
-        const alias = col.displayName ?? colNested.column.name;
-        let aliasedOp;
-        if (col instanceof DateExtractOperation) {
-          aliasedOp = new DateExtractOperation(new TableAliasColumn(colNested.column, ta), col.part);
-        } else if (col instanceof DateArithmeticOperation) {
-          aliasedOp = new DateArithmeticOperation(new TableAliasColumn(colNested.column, ta), col.n, col.unit, col.isAdd);
-        } else {
-          aliasedOp = new DateDiffOperation(new TableAliasColumn(colNested.column, ta), col.other, col.unit);
-        }
-        this._select.push(new Alias(aliasedOp, alias));
-      } else if (col instanceof CountAllOperation) {
-        const ta = this._tableAliasForTable(col.table, col.table);
+    for (const col of cols) this._selectColumn(col);
+  }
+  /** Add one column to the select list. An alias reads the column it wraps, then names the entry. */
+  _selectColumn(col) {
+    if (col instanceof Alias) {
+      this._selectColumn(col.element);
+      const read = this._select.pop();
+      this._select.push(new Alias(read.element, col.name));
+    } else if (col instanceof Attribute) {
+      const { column, parent: node } = this._resolve(col);
+      let ta;
+      if (node !== void 0) {
+        ta = this._tableAliasForTable(column.owner, node);
+      } else {
+        ta = this._tableAliasForTable(column.owner, column.owner);
+        this._from.add(ta);
+      }
+      this._select.push(new Alias(new TableAliasColumn(column, ta), col.displayName()));
+    } else if (col instanceof WindowFunctionOperation) {
+      const rewritten = this._rewriteOperation(col);
+      let alias;
+      if (col.displayName) {
+        alias = col.displayName;
+      } else if (["ROW_NUMBER" /* ROW_NUMBER */, "RANK" /* RANK */, "DENSE_RANK" /* DENSE_RANK */].includes(col.func)) {
+        alias = col.func.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+      } else if (col.element) {
+        alias = col.func + " " + findColumn(col).column.name;
+      } else {
+        alias = col.func;
+      }
+      this._select.push(new Alias(rewritten, alias));
+    } else if (col instanceof AggregateOperation && !(col.element instanceof ColumnWithJoin)) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? "Expression"));
+    } else if (col instanceof AggregateOperation) {
+      const colNested = this._resolve(findColumn(col));
+      const node = colNested.parent;
+      let ta;
+      if (node !== void 0) {
+        ta = this._tableAliasForTable(colNested.column.owner, node);
+      } else {
+        ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
         this._from.add(ta);
-        this._select.push(new Alias(col, "Count"));
       }
+      const alias = col.displayName ?? col.operator + " " + findColumn(col).column.name;
+      const rewrittenAgg = new AggregateOperation(
+        new TableAliasColumn(colNested.column, ta),
+        col.operator,
+        void 0,
+        col.window ? this._rewriteWindowSpec(col.window) : void 0,
+        col.separator,
+        col.orderBy.map((s) => new SortOperation(this._rewriteOperation(s.column), s.direction))
+      );
+      this._select.push(new Alias(rewrittenAgg, alias));
+    } else if (col instanceof ScalarFunctionOperation) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? col.func + " " + findColumn(col).column.name));
+    } else if (col instanceof DateExtractOperation || col instanceof DateArithmeticOperation || col instanceof DateDiffOperation) {
+      const colNested = this._resolve(findColumn(col));
+      const node = colNested.parent;
+      let ta;
+      if (node !== void 0) {
+        ta = this._tableAliasForTable(colNested.column.owner, node);
+      } else {
+        ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
+        this._from.add(ta);
+      }
+      const alias = col.displayName ?? findColumn(col).column.name;
+      let aliasedOp;
+      if (col instanceof DateExtractOperation) {
+        aliasedOp = new DateExtractOperation(new TableAliasColumn(colNested.column, ta), col.part);
+      } else if (col instanceof DateArithmeticOperation) {
+        aliasedOp = new DateArithmeticOperation(new TableAliasColumn(colNested.column, ta), col.n, col.unit, col.isAdd);
+      } else {
+        aliasedOp = new DateDiffOperation(new TableAliasColumn(colNested.column, ta), col.other, col.unit);
+      }
+      this._select.push(new Alias(aliasedOp, alias));
+    } else if (col instanceof CaseOperation) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? "Expression"));
+    } else if (col instanceof ConcatOperation) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? "Expression"));
+    } else if (col instanceof ArithmeticOperation) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? "Expression"));
+    } else if (col instanceof DateTruncOperation) {
+      this._select.push(new Alias(this._rewriteOperation(col), col.displayName ?? findColumn(col).column.name));
+    } else if (isCondition(col)) {
+      this._select.push(new Alias(new RenderedSql(this.buildFilter(col)), "Expression"));
+    } else if (col instanceof ConstantOperation) {
+      this._select.push(new Alias(col, "Constant"));
+    } else if (col instanceof CountAllOperation) {
+      if (col.table !== "") this._from.add(this._tableAliasForTable(col.table, col.table));
+      this._select.push(new Alias(col, "Count"));
     }
   }
   _addJoin(node) {
@@ -1174,7 +2346,9 @@ var SQLQueryGenerator = class {
     const sc = new TableAliasColumn(left, srcTa);
     const right = join.right;
     const tc = new TableAliasColumn(right, this._tableAliasForTable(right.owner, node));
-    this._join.push(new Join(sc, tc, join.filter));
+    const queryFilter = this._joinFilters.get(node);
+    const filterOp = join.filter !== void 0 && queryFilter !== void 0 ? new LogicalOperation(join.filter, "AND" /* AND */, queryFilter) : join.filter ?? queryFilter;
+    this._join.push(new Join(sc, tc, filterOp));
   }
   buildFilter(op) {
     if (op instanceof NoOperation) return "";
@@ -1186,29 +2360,53 @@ var SQLQueryGenerator = class {
       const col = op.node.join.right;
       return this.buildFilter(new ColumnWithJoin(col, op.node)) + " IS NULL";
     }
+    if (op instanceof InOperation) {
+      return this.buildFilter(op.element) + " IN (" + op.values.map((value) => constantValueString(value, this._dialect)).join(", ") + ")";
+    }
+    if (op instanceof NotInOperation) {
+      const column = this.buildFilter(op.element);
+      const sql = column + " NOT IN (" + op.values.map((value) => constantValueString(value, this._dialect)).join(", ") + ")";
+      if (op.element instanceof ColumnWithJoin && this._resolve(op.element).column.nullable) {
+        return "(" + sql + " OR " + column + " IS NULL)";
+      }
+      return sql;
+    }
     if (op instanceof IsNotNullOperation) return this.buildFilter(op.element) + " IS NOT NULL";
     if (op instanceof IsNullOperation) return this.buildFilter(op.element) + " IS NULL";
     if (op instanceof LogicalOperation) {
       let left = this.buildFilter(op.left);
       let right = this.buildFilter(op.right);
-      if (op.left instanceof LogicalOperation) left = "(" + left + ")";
-      if (op.right instanceof LogicalOperation) right = "(" + right + ")";
+      if (needsParentheses(op, op.left)) left = "(" + left + ")";
+      if (needsParentheses(op, op.right)) right = "(" + right + ")";
       return left + LOGICAL_OPERATOR_STR[op.operator] + right;
     }
     if (op instanceof ComparisonOperation) {
-      return this.buildFilter(op.left) + COMPARISON_OPERATOR_STR[op.operator] + this.buildFilter(op.right);
+      let sql = this.buildFilter(op.left) + COMPARISON_OPERATOR_STR[op.operator] + this.buildFilter(op.right);
+      if ((op.operator === "LIKE" /* LIKE */ || op.operator === "NOT_LIKE" /* NOT_LIKE */) && op.right instanceof StringConstantOperation && (op.right.value.includes(LIKE_ESCAPE) || op.right.value.includes("\\"))) {
+        sql += " ESCAPE '" + LIKE_ESCAPE + "'";
+      }
+      if (this._guardOptional && GUARDED_COMPARISONS.has(op.operator) && op.left instanceof ColumnWithJoin && this._resolveOptional(op.left)) {
+        sql = "(" + this.buildFilter(op.left) + " IS NOT NULL AND " + sql + ")";
+      }
+      return sql;
+    }
+    if (op instanceof ConstantOperation) return constantValueString(op, this._dialect);
+    if (op instanceof ScalarFunctionOperation || op instanceof ArithmeticOperation || op instanceof ConcatOperation || op instanceof DateTruncOperation || op instanceof AggregateOperation || op instanceof CountAllOperation) {
+      const required = /* @__PURE__ */ new Map();
+      this._collectRequiredJoins(op, required);
+      for (const node of required.values()) this._addJoin(node);
+      return sqlOperationToString(this._rewriteOperation(op), this._dialect);
     }
-    if (op instanceof ConstantOperation) return constantValueString(op);
     if (op instanceof ColumnWithJoin) {
-      const node = op.parent;
+      const { column, parent: node } = this._resolve(op);
       let ta;
       if (node !== void 0) {
-        ta = this._tableAliasForTable(op.column.owner, node);
+        ta = this._tableAliasForTable(column.owner, node);
         this._addJoin(node);
       } else {
-        ta = this._tableAliasForTable(op.column.owner, op.column.owner);
+        ta = this._tableAliasForTable(column.owner, column.owner);
       }
-      return ta.alias + "." + op.column.name;
+      return ta.alias + "." + column.name;
     }
     if (op instanceof Column) {
       const ta = this._tableAliasForTable(op.owner, op.owner);
@@ -1226,9 +2424,9 @@ var SQLQueryGenerator = class {
   }
   buildQueryString() {
     const joins = this._join.map(
-      (j) => " LEFT OUTER JOIN " + j.target.tableAlias.table + " AS " + j.target.tableAlias.alias + " ON " + j.source.tableAlias.alias + "." + j.source.column.name + " = " + j.target.tableAlias.alias + "." + j.target.column.name + (j.filterOp ? " AND " + this.buildFilter(j.filterOp) : "")
+      (j) => " LEFT OUTER JOIN " + j.target.tableAlias.table + " AS " + j.target.tableAlias.alias + " ON (" + j.condition() + (j.filterOp ? " AND " + this.buildFilter(j.filterOp) : "") + ")"
     );
-    return "SELECT " + this._select.map((ca) => sqlOperationToString(ca)).join(",") + " FROM " + Array.from(this._from).map((ta) => ta.table + " AS " + ta.alias).join(",") + joins.join("") + this._buildWhere() + this._buildGroupBy() + this._buildOrderBy() + this._buildLimit();
+    return (this._distinct ? "SELECT DISTINCT " : "SELECT ") + this._select.map((ca) => sqlOperationToString(ca, this._dialect)).join(",") + " FROM " + Array.from(this._from).map((ta) => ta.table + " AS " + ta.alias).join(",") + joins.join("") + this._buildWhere() + this._buildGroupBy() + this._buildHaving() + this._buildOrderBy() + this._buildLimit() + this._buildOffset();
   }
   _buildWhere() {
     return this._where.length > 0 ? " WHERE " + this._where : "";
@@ -1236,24 +2434,39 @@ var SQLQueryGenerator = class {
   _buildGroupBy() {
     return this._groupByParts.length > 0 ? " GROUP BY " + this._groupByParts.join(", ") : "";
   }
+  _buildHaving() {
+    return this._having.length > 0 ? " HAVING " + this._having : "";
+  }
   _buildOrderBy() {
     return this._orderByParts.length > 0 ? " ORDER BY " + this._orderByParts.join(", ") : "";
   }
+  _buildOffset() {
+    return this._offset !== void 0 ? " OFFSET " + this._offset : "";
+  }
   _buildLimit() {
     return this._limit !== void 0 ? " LIMIT " + this._limit : "";
   }
 };
-function selectSqlToString(selectOperation) {
-  const qg = new SQLQueryGenerator();
+function selectSqlToString(selectOperation, dialect = "postgres") {
+  const qg = new SQLQueryGenerator(dialectOf(dialect));
   qg.generate(selectOperation);
   return qg.buildQueryString();
 }
-function toSql(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit) {
-  const selectOp = buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy, groupBy, limit);
-  return selectSqlToString(selectOp);
+function toSql(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit, businessDateTo = null, distinct = false, offset, having, dialect = "postgres") {
+  const selectOp = buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy, groupBy, limit, businessDateTo, distinct, offset, having);
+  return selectSqlToString(selectOp, dialect);
 }
 
 // src/datafinder/runner.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+var QueryTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Query exceeded ${timeoutMs}ms timeout`);
+    this.timeoutMs = timeoutMs;
+    this.name = "QueryTimeoutError";
+  }
+  timeoutMs;
+};
 var _runner = null;
 function registerRunner(runner) {
   _runner = runner;
@@ -1265,27 +2478,50 @@ function getRunner() {
   if (!_runner) throw new Error("No query runner registered. Call registerRunner() first.");
   return _runner;
 }
+var expressionIds = /* @__PURE__ */ new WeakMap();
+var nextExpressionId = 1;
+function sortTarget(sort) {
+  const column = sort.column;
+  if (!(column instanceof ColumnWithJoin)) {
+    if (!expressionIds.has(column)) expressionIds.set(column, nextExpressionId++);
+    return JSON.stringify(["expression", expressionIds.get(column)]);
+  }
+  const joins = [];
+  for (let node = column.parent; node !== void 0; node = node.parent) joins.push(node.join.name);
+  return JSON.stringify([column.column.owner, column.column.name, joins]);
+}
 var FinderResult = class {
-  constructor(_businessDate, _processingDatetime, _columns, _table, _op) {
+  constructor(_businessDate, _processingDatetime, _columns, _table, _op, _businessDateTo = null) {
     this._businessDate = _businessDate;
     this._processingDatetime = _processingDatetime;
     this._columns = _columns;
     this._table = _table;
     this._op = _op;
+    this._businessDateTo = _businessDateTo;
   }
   _businessDate;
   _processingDatetime;
   _columns;
   _table;
   _op;
+  _businessDateTo;
   _orderBy = [];
   _groupBy = [];
   _limit;
-  orderByOp(...sorts) {
-    this._orderBy = sorts;
+  _distinct = false;
+  _offset;
+  _having;
+  _timeoutMs = DEFAULT_TIMEOUT_MS;
+  /**
+   * Order the rows. Calls accumulate: the sorts of the latest call take priority and earlier ones order the
+   * rows it leaves tied, as in a chain of `sortBy` calls. Sorting a column again replaces its earlier direction.
+   */
+  orderBy(...sorts) {
+    const resorted = new Set(sorts.map(sortTarget));
+    this._orderBy = [...sorts, ...this._orderBy.filter((s) => !resorted.has(sortTarget(s)))];
     return this;
   }
-  groupByOp(...attrs) {
+  groupBy(...attrs) {
     this._groupBy = attrs;
     return this;
   }
@@ -1293,7 +2529,40 @@ var FinderResult = class {
     this._limit = n;
     return this;
   }
-  toSql() {
+  /** Skip the first `n` rows. Sort the rows first: without an order, which rows are first is not defined. */
+  offset(n) {
+    if (!Number.isInteger(n) || n < 0) throw new Error("offset cannot be negative");
+    this._offset = n;
+    return this;
+  }
+  /** Rows `start` up to but not including `stop`, counting from 0: `offset(start).limit(stop - start)`. */
+  slice(start, stop) {
+    if (!Number.isInteger(start) || !Number.isInteger(stop) || start < 0 || stop < start) {
+      throw new Error("slice needs 0 <= start <= stop");
+    }
+    return this.offset(start).limit(stop - start);
+  }
+  /**
+   * Keep the groups for which every condition holds: `HAVING`. A condition tests an aggregate or a grouping column:
+   * `f.findAll(null, null, [f.category(), countAll()]).groupBy(f.category()).having(countAll().gt(1))`.
+   * Calls accumulate, as `and` does.
+   */
+  having(...conditions) {
+    for (const condition of conditions) this._having = this._having === void 0 ? condition : this._having.and(condition);
+    return this;
+  }
+  /** Return each distinct row once: `SELECT DISTINCT`. A sort on a distinct query has to use a selected column. */
+  distinct() {
+    this._distinct = true;
+    return this;
+  }
+  /** Abort the query and throw QueryTimeoutError if it runs longer than `milliseconds` (default 60000). */
+  timeout(milliseconds) {
+    this._timeoutMs = milliseconds;
+    return this;
+  }
+  /** The query as SQL, in Postgres unless a dialect is given: `toSql('databricks')`. Nothing is run. */
+  toSql(dialect = "postgres") {
     return toSql(
       this._businessDate,
       this._processingDatetime,
@@ -1302,7 +2571,12 @@ var FinderResult = class {
       this._op,
       this._orderBy,
       this._groupBy,
-      this._limit
+      this._limit,
+      this._businessDateTo,
+      this._distinct,
+      this._offset,
+      this._having,
+      dialect
     );
   }
   async toRows() {
@@ -1314,14 +2588,25 @@ var FinderResult = class {
       this._op,
       this._orderBy,
       this._groupBy,
-      this._limit
+      this._limit,
+      this._timeoutMs,
+      this._businessDateTo,
+      this._distinct,
+      this._offset,
+      this._having
     );
   }
 };
+function convertProcessingDate(value) {
+  if (typeof value === "string" && DATE_ONLY_PATTERN.test(value)) return new DateOnly(value + "T00:00:00Z");
+  return convertDate(value);
+}
 function convertDate(value) {
   if (value === null) return null;
   if (value instanceof Date) return value;
-  const normalized = /^\d{4}-\d{2}-\d{2}$/.test(value) ? value + "T00:00:00Z" : value;
+  let normalized = value;
+  if (DATE_ONLY_PATTERN.test(value)) normalized = value + "T00:00:00Z";
+  else if (/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(value)) normalized = value.replace(" ", "T") + "Z";
   const d = new Date(normalized);
   if (isNaN(d.getTime())) throw new Error(`Cannot parse date: ${value}`);
   return d;
@@ -1329,17 +2614,33 @@ function convertDate(value) {
 function convertInputsAndSelect(businessDate, processingDatetime, columns, table, op = new NoOperation()) {
   return new FinderResult(
     convertDate(businessDate),
-    convertDate(processingDatetime),
+    convertProcessingDate(processingDatetime),
     columns,
     table,
     op
   );
 }
+function convertInputsAndSelectForDateRange(businessDateFrom, businessDateTo, processingDatetime, columns, table, op = new NoOperation()) {
+  if (businessDateFrom == null) throw new Error("businessDateFrom is required for findForDateRange");
+  if (businessDateTo == null) throw new Error("businessDateTo is required for findForDateRange");
+  if (processingDatetime == null) throw new Error("processingValidAt is required for findForDateRange");
+  return new FinderResult(
+    convertDate(businessDateFrom),
+    convertProcessingDate(processingDatetime),
+    columns,
+    table,
+    op,
+    convertDate(businessDateTo)
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TIMEOUT_MS,
   FinderResult,
+  QueryTimeoutError,
   clearRunner,
   convertInputsAndSelect,
+  convertInputsAndSelectForDateRange,
   getRunner,
   registerRunner
 });