data-finder-ts 0.1.3 → 0.1.4

package/dist/index.cjs

@@ -22,6 +22,7 @@ var src_exports = {};
 __export(src_exports, {
   AggregateOperation: () => AggregateOperation,
   AggregateOperator: () => AggregateOperator,
+  Alias: () => Alias,
   Attribute: () => Attribute,
   BiTemporalColumns: () => BiTemporalColumns,
   BinaryOperation: () => BinaryOperation,
@@ -34,6 +35,7 @@ __export(src_exports, {
   ComparisonOperator: () => ComparisonOperator,
   ConstantOperation: () => ConstantOperation,
   CountAllOperation: () => CountAllOperation,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   DataCatalog: () => DataCatalog,
   DataStore: () => DataStore,
   Database: () => Database,
@@ -68,11 +70,13 @@ __export(src_exports, {
   NumericAttribute: () => NumericAttribute,
   Operation: () => Operation,
   ProcessingTemporalColumns: () => ProcessingTemporalColumns,
+  QueryTimeoutError: () => QueryTimeoutError,
   RelatedFinder: () => RelatedFinder,
   RelationalOperationElement: () => RelationalOperationElement,
   ScalarFunction: () => ScalarFunction,
   ScalarFunctionOperation: () => ScalarFunctionOperation,
   Schema: () => Schema,
+  SelectOperation: () => SelectOperation,
   SingleBusinessDateColumn: () => SingleBusinessDateColumn,
   SortDirection: () => SortDirection,
   SortOperation: () => SortOperation,
@@ -85,11 +89,14 @@ __export(src_exports, {
   WindowSpecification: () => WindowSpecification,
   clearRunner: () => clearRunner,
   convertInputsAndSelect: () => convertInputsAndSelect,
+  convertInputsAndSelectForDateRange: () => convertInputsAndSelectForDateRange,
+  embeddedUnder: () => embeddedUnder,
   getRelatedFinderClass: () => getRelatedFinderClass,
   getRunner: () => getRunner,
   registerRelatedFinderClass: () => registerRelatedFinderClass,
   registerRunner: () => registerRunner,
   selectSqlToString: () => selectSqlToString,
+  titleCase: () => titleCase,
   toSql: () => toSql
 });
 module.exports = __toCommonJS(src_exports);
@@ -462,6 +469,10 @@ var JoinOperation = class {
   left;
   right;
   filter;
+  /** Property-equality filters on the join target (property id -> value), set by a related finder given a filter. */
+  filterKwargs = {};
+  /** Maps property ids to [column, type, table] for `filterKwargs`. */
+  filterColumnMap = {};
 };
 var JoinTreeNodeOperation = class {
   constructor(join, parent) {
@@ -472,13 +483,19 @@ var JoinTreeNodeOperation = class {
   parent;
 };
 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) {
     super();
     this.column = column;
     this.parent = parent;
+    this.embedded = embedded;
   }
   column;
   parent;
+  embedded;
 };
 var SortOperation = class {
   constructor(column, direction) {
@@ -495,18 +512,67 @@ var CountAllOperation = class extends RelationalOperationElement {
   }
   table;
 };
+var Alias = class extends RelationalOperationElement {
+  constructor(element, name) {
+    super();
+    this.element = element;
+    this.name = name;
+  }
+  element;
+  name;
+};
+var ExistsOperation = class extends RelationalOperationElement {
+  constructor(node) {
+    super();
+    this.node = node;
+  }
+  node;
+  andOp(other) {
+    return new LogicalOperation(this, "AND" /* AND */, other);
+  }
+};
+var NotExistsOperation = class extends RelationalOperationElement {
+  constructor(node) {
+    super();
+    this.node = node;
+  }
+  node;
+  andOp(other) {
+    return new LogicalOperation(this, "AND" /* AND */, other);
+  }
+};
+var SelectOperation = class {
+  constructor(display, filter, orderBy = [], groupBy = [], limit, table, joinFilters = /* @__PURE__ */ new Map()) {
+    this.display = display;
+    this.filter = filter;
+    this.orderBy = orderBy;
+    this.groupBy = groupBy;
+    this.limit = limit;
+    this.table = table;
+    this.joinFilters = joinFilters;
+  }
+  display;
+  filter;
+  orderBy;
+  groupBy;
+  limit;
+  table;
+  joinFilters;
+};
 
 // src/datafinder/attribute.ts
-var Attribute = class {
+var Attribute = class _Attribute {
   _displayName;
   _column;
   _owner;
   _parent;
-  constructor(displayName, columnName, columnDbType, owner, parent) {
+  _embedded;
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
     this._displayName = displayName;
     this._column = new Column(columnName, columnDbType, owner);
     this._owner = owner;
     this._parent = parent;
+    this._embedded = embedded;
   }
   column() {
     return this._column;
@@ -520,33 +586,58 @@ 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;
+  }
   cwj() {
-    return new ColumnWithJoin(this._column, this._parent);
+    return new ColumnWithJoin(this._column, this._parent, this._embedded?.cwj());
   }
+  /** Count the number of non-null values. Use in a projection with `groupByOp` to aggregate per group. */
   count() {
     return new AggregateOperation(
-      new ColumnWithJoin(this._column, this._parent),
+      this.cwj(),
       "COUNT" /* COUNT */,
       this._displayName + " Count"
     );
   }
+  /** Sort this attribute in ascending order. Pass to `orderByOp` 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 `orderByOp` 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());
   }
   _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;
@@ -571,6 +662,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,
@@ -581,12 +677,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),
@@ -594,9 +695,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,
@@ -604,9 +709,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,
@@ -627,183 +736,236 @@ function getRelatedFinderClass(name) {
 
 // src/datafinder/typed-attributes.ts
 var StringAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
-  upper() {
+  /** Convert every character to uppercase. */
+  toUpperCase() {
     return new ScalarFunctionOperation(this.cwj(), "UPPER" /* UPPER */, "Upper " + this.displayName());
   }
-  lower() {
+  /** Convert every character to lowercase. */
+  toLowerCase() {
     return new ScalarFunctionOperation(this.cwj(), "LOWER" /* LOWER */, "Lower " + this.displayName());
   }
-  strip() {
-    return new ScalarFunctionOperation(this.cwj(), "TRIM" /* TRIM */, "Strip " + this.displayName());
+  /** Remove leading and trailing whitespace. */
+  trim() {
+    return new ScalarFunctionOperation(this.cwj(), "TRIM" /* TRIM */, "Trim " + this.displayName());
   }
-  lstrip() {
-    return new ScalarFunctionOperation(this.cwj(), "LTRIM" /* LTRIM */, "LStrip " + this.displayName());
+  /** Remove leading whitespace. */
+  trimStart() {
+    return new ScalarFunctionOperation(this.cwj(), "LTRIM" /* LTRIM */, "Trim Start " + this.displayName());
   }
-  rstrip() {
-    return new ScalarFunctionOperation(this.cwj(), "RTRIM" /* RTRIM */, "RStrip " + this.displayName());
+  /** Remove trailing whitespace. */
+  trimEnd() {
+    return new ScalarFunctionOperation(this.cwj(), "RTRIM" /* RTRIM */, "Trim End " + this.displayName());
   }
+  /** Return the number of characters in the string. */
   length() {
     return new ScalarFunctionOperation(this.cwj(), "LENGTH" /* LENGTH */, "Length " + this.displayName());
   }
+  /** Return the string with characters in reverse order. */
   reverse() {
     return new ScalarFunctionOperation(this.cwj(), "REVERSE" /* REVERSE */, "Reverse " + this.displayName());
   }
+  /** Return the first `n` characters. */
   left(n) {
     return new ScalarFunctionOperation(this.cwj(), "LEFT" /* LEFT */, "Left " + this.displayName(), n);
   }
+  /** Return the last `n` characters. */
   right(n) {
     return new ScalarFunctionOperation(this.cwj(), "RIGHT" /* RIGHT */, "Right " + this.displayName(), n);
   }
+  /** Return the string repeated `n` times. */
   repeat(n) {
     return new ScalarFunctionOperation(this.cwj(), "REPEAT" /* REPEAT */, "Repeat " + this.displayName(), n);
   }
+  /** Replace all occurrences of `fromStr` with `toStr`. */
   replace(fromStr, toStr) {
     return new ScalarFunctionOperation(this.cwj(), "REPLACE" /* REPLACE */, "Replace " + this.displayName(), 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 new ScalarFunctionOperation(this.cwj(), "SUBSTRING" /* SUBSTRING */, "Substring " + this.displayName(), void 0, args);
   }
+  /** 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(`%${value}%`));
   }
+  /** Filter to rows where this attribute begins with `prefix`. */
   startsWith(prefix) {
     return new ComparisonOperation(this.cwj(), "LIKE" /* LIKE */, new StringConstantOperation(`${prefix}%`));
   }
+  /** Filter to rows where this attribute ends with `suffix`. */
   endsWith(suffix) {
     return new ComparisonOperation(this.cwj(), "LIKE" /* LIKE */, new StringConstantOperation(`%${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(`%${value}%`));
   }
 };
 var NumericAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Sum of all values in the group. */
   sum() {
-    return new AggregateOperation(this.cwj(), "SUM" /* SUM */, this.displayName() + " Sum");
+    return new AggregateOperation(this.cwj(), "SUM" /* SUM */, "Sum " + this.displayName());
   }
+  /** Smallest value in the group. */
   min() {
-    return new AggregateOperation(this.cwj(), "MIN" /* MIN */, this.displayName() + " Min");
+    return new AggregateOperation(this.cwj(), "MIN" /* MIN */, "Min " + this.displayName());
   }
+  /** Largest value in the group. */
   max() {
-    return new AggregateOperation(this.cwj(), "MAX" /* MAX */, this.displayName() + " Max");
+    return new AggregateOperation(this.cwj(), "MAX" /* MAX */, "Max " + this.displayName());
   }
+  /** Arithmetic mean of all values in the group. */
   average() {
-    return new AggregateOperation(this.cwj(), "AVERAGE" /* AVERAGE */, this.displayName() + " Average");
+    return new AggregateOperation(this.cwj(), "AVERAGE" /* AVERAGE */, "Average " + this.displayName());
   }
+  /** Absolute value (distance from zero, always non-negative). */
   abs() {
     return new ScalarFunctionOperation(this.cwj(), "ABS" /* ABS */, "Abs " + this.displayName());
   }
+  /** Round up to the nearest integer. */
   ceil() {
     return new ScalarFunctionOperation(this.cwj(), "CEILING" /* CEILING */, "Ceil " + this.displayName());
   }
+  /** Round down to the nearest integer. */
   floor() {
     return new ScalarFunctionOperation(this.cwj(), "FLOOR" /* FLOOR */, "Floor " + this.displayName());
   }
+  /** Square root. */
   sqrt() {
     return new ScalarFunctionOperation(this.cwj(), "SQRT" /* SQRT */, "Sqrt " + this.displayName());
   }
+  /** Remainder after dividing by `n`. */
   mod(n) {
     return new ScalarFunctionOperation(this.cwj(), "MOD" /* MOD */, "Mod " + this.displayName(), n);
   }
+  /** Raise to the power of `n`. */
   power(n) {
     return new ScalarFunctionOperation(this.cwj(), "POWER" /* POWER */, "Power " + this.displayName(), n);
   }
+  /** Round to `d` decimal places, or to the nearest integer when `d` is omitted. */
   round(d) {
     return new ScalarFunctionOperation(this.cwj(), "ROUND" /* ROUND */, "Round " + this.displayName(), d);
   }
 };
 var DoubleAttribute = class extends NumericAttribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Filter to rows where this attribute equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new FloatConstantOperation(value));
   }
+  /** Filter to rows where this attribute does not equal `value`. */
   ne(value) {
     return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new FloatConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than `value`. */
   gt(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new FloatConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than `value`. */
   lt(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, new FloatConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than or equal to `value`. */
   gte(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, new FloatConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than or equal to `value`. */
   lte(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, new FloatConstantOperation(value));
   }
 };
 var FloatAttribute = DoubleAttribute;
 var DecimalAttribute = class extends NumericAttribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Filter to rows where this attribute equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new DecimalConstantOperation(value));
   }
+  /** Filter to rows where this attribute does not equal `value`. */
   ne(value) {
     return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new DecimalConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than `value`. */
   gt(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new DecimalConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than `value`. */
   lt(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, new DecimalConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than or equal to `value`. */
   gte(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, new DecimalConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than or equal to `value`. */
   lte(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, new DecimalConstantOperation(value));
   }
 };
 var IntegerAttribute = class extends NumericAttribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Filter to rows where this attribute equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new IntegerConstantOperation(value));
   }
+  /** Filter to rows where this attribute does not equal `value`. */
   ne(value) {
     return new ComparisonOperation(this.cwj(), "NOT_EQUAL" /* NOT_EQUAL */, new IntegerConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than `value`. */
   gt(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new IntegerConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than `value`. */
   lt(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN" /* LESS_THAN */, new IntegerConstantOperation(value));
   }
+  /** Filter to rows where this attribute is greater than or equal to `value`. */
   gte(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN_OR_EQUAL_TO" /* GREATER_THAN_OR_EQUAL_TO */, new IntegerConstantOperation(value));
   }
+  /** Filter to rows where this attribute is less than or equal to `value`. */
   lte(value) {
     return new ComparisonOperation(this.cwj(), "LESS_THAN_OR_EQUAL_TO" /* LESS_THAN_OR_EQUAL_TO */, new IntegerConstantOperation(value));
   }
 };
 var BooleanAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Filter to rows where this attribute equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new BooleanConstantOperation(value));
   }
+  /** Filter to rows where this attribute is true. */
   isTrue() {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new BooleanConstantOperation(true));
   }
+  /** Filter to rows where this attribute is false. */
   isFalse() {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new BooleanConstantOperation(false));
   }
@@ -815,173 +977,227 @@ function parseDate(value) {
   return d;
 }
 var DateAttribute = class extends Attribute {
-  constructor(displayName, columnName, columnDbType, owner, parent) {
-    super(displayName, columnName, columnDbType, owner, parent);
+  constructor(displayName, columnName, columnDbType, owner, parent, embedded) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** 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());
   }
+  /** 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) {
+    super(displayName, columnName, columnDbType, owner, parent, embedded);
   }
+  /** Filter to rows where this timestamp equals `value`. */
   eq(value) {
     return new ComparisonOperation(this.cwj(), "EQUAL" /* EQUAL */, new DateTimeConstantOperation(parseDate(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)));
   }
+  /** Filter to rows where this timestamp is after `value`. */
   gt(value) {
     return new ComparisonOperation(this.cwj(), "GREATER_THAN" /* GREATER_THAN */, new DateTimeConstantOperation(parseDate(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)));
   }
+  /** 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)));
   }
+  /** 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)));
   }
+  /** 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());
   }
+  /** 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());
   }
@@ -1064,49 +1280,7 @@ var MilestonedTable = class extends Table {
   milestoningColumns;
 };
 
-// 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);
-  }
-};
-var NotExistsOperation = class extends RelationalOperationElement {
-  constructor(node) {
-    super();
-    this.node = node;
-  }
-  node;
-  andOp(other) {
-    return new LogicalOperation(this, "AND" /* AND */, other);
-  }
-};
-var RelatedFinder = class {
-  constructor(_node) {
-    this._node = _node;
-  }
-  _node;
-  exists() {
-    return new ExistsOperation(this._node);
-  }
-  notExists() {
-    return new NotExistsOperation(this._node);
-  }
-};
-
 // 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;
@@ -1134,22 +1308,6 @@ var Join = class {
   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;
-  }
-  display;
-  filter;
-  orderBy;
-  groupBy;
-  limit;
-  table;
-};
 function sqlFormatDatetime(value) {
   const pad = (n, w = 2) => String(n).padStart(w, "0");
   return `'${value.getUTCFullYear()}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())} ${pad(value.getUTCHours())}:${pad(value.getUTCMinutes())}:${pad(value.getUTCSeconds())}'`;
@@ -1281,6 +1439,9 @@ function sqlOperationToString(operation) {
   }
   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;
@@ -1330,38 +1491,125 @@ function buildMilestoningFilterOperation(businessDate, processingDatetime, table
   if (ops.length === 1) return ops[0];
   return new LogicalOperation(ops[0], "AND" /* AND */, ops[1]);
 }
-function buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit) {
+function buildMilestoningFilterOperationForDateRange(businessDateFrom, businessDateTo, processingDatetime, table, joinNode) {
+  const mc = table.milestoningColumns;
+  const ops = [];
+  const hasRange = businessDateFrom !== null && businessDateTo !== null;
+  const processingOp = (m) => {
+    const startAt = new DateTimeAttribute("start_at", m.startAtColumn.name, m.startAtColumn.type, m.startAtColumn.table.qualifiedName, joinNode);
+    const endAt = new DateTimeAttribute("end_at", m.endAtColumn.name, m.endAtColumn.type, m.endAtColumn.table.qualifiedName, joinNode);
+    return new LogicalOperation(startAt.lte(processingDatetime), "AND" /* AND */, openEndClause(endAt, processingDatetime, m.infiniteDatetime));
+  };
+  if (mc instanceof BiTemporalColumns) {
+    if (hasRange) {
+      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(businessDateTo), "AND" /* AND */, openEndClause(dateTo, businessDateFrom, mc.infiniteDatetime)));
+    }
+    if (processingDatetime !== null) ops.push(processingOp(mc));
+  } else if (mc instanceof BusinessDateAndProcessingTemporalColumns) {
+    if (hasRange) {
+      const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
+      ops.push(new LogicalOperation(businessAtt.gte(businessDateFrom), "AND" /* AND */, businessAtt.lte(businessDateTo)));
+    }
+    if (processingDatetime !== null) ops.push(processingOp(mc));
+  } else if (mc instanceof ProcessingTemporalColumns) {
+    if (processingDatetime !== null) ops.push(processingOp(mc));
+  } else if (mc instanceof SingleBusinessDateColumn && hasRange) {
+    const businessAtt = new DateAttribute("business_date", mc.businessDateColumn.name, mc.businessDateColumn.type, mc.businessDateColumn.table.qualifiedName, joinNode);
+    ops.push(new LogicalOperation(businessAtt.gte(businessDateFrom), "AND" /* AND */, businessAtt.lte(businessDateTo)));
+  }
+  if (ops.length === 0) return null;
+  if (ops.length === 1) return ops[0];
+  return new LogicalOperation(ops[0], "AND" /* AND */, ops[1]);
+}
+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);
+  } 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 DateArithmeticOperation || op instanceof DateDiffOperation || op instanceof IsNullOperation || op instanceof IsNotNullOperation) {
+    walkRefs(op.element, 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 = [];
+  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(", ")}`);
+    }
+    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 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) {
   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);
 }
 var SQLQueryGenerator = class {
   _select = [];
@@ -1375,8 +1623,12 @@ var SQLQueryGenerator = class {
   _tableAliasesByTable = /* @__PURE__ */ new Map();
   _addedJoinIds = /* @__PURE__ */ new Set();
   _rootTable;
+  _elidableNodes = /* @__PURE__ */ new Set();
+  _joinFilters = /* @__PURE__ */ new Map();
   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));
     }
@@ -1396,39 +1648,49 @@ var SQLQueryGenerator = class {
     this._limit = select.limit;
   }
   _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);
-    }
-    for (const s of window.orderBy) {
-      this._collectRequiredJoins(s.column, 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);
     }
+    return { column, parent };
   }
   _rewriteWindowSpec(window) {
     const partitionBy = window.partitionBy.map((p) => this._rewriteOperation(p));
@@ -1436,13 +1698,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);
@@ -1491,15 +1749,15 @@ var SQLQueryGenerator = class {
     }
     for (const col of cols) {
       if (col instanceof Attribute) {
-        const node = col.parent();
+        const { column, parent: node } = this._resolve(col);
         let ta;
         if (node !== void 0) {
-          ta = this._tableAliasForTable(col.owner(), node);
+          ta = this._tableAliasForTable(column.owner, node);
         } else {
-          ta = this._tableAliasForTable(col.owner(), col.owner());
+          ta = this._tableAliasForTable(column.owner, column.owner);
           this._from.add(ta);
         }
-        this._select.push(new Alias(new TableAliasColumn(col.column(), ta), col.displayName()));
+        this._select.push(new Alias(new TableAliasColumn(column, ta), col.displayName()));
       } else if (col instanceof WindowFunctionOperation) {
         const rewritten = this._rewriteOperation(col);
         let alias;
@@ -1514,7 +1772,7 @@ var SQLQueryGenerator = class {
         }
         this._select.push(new Alias(rewritten, alias));
       } else if (col instanceof AggregateOperation) {
-        const colNested = findColumn(col);
+        const colNested = this._resolve(findColumn(col));
         const node = colNested.parent;
         let ta;
         if (node !== void 0) {
@@ -1523,7 +1781,7 @@ var SQLQueryGenerator = class {
           ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
           this._from.add(ta);
         }
-        const alias = col.displayName ?? col.operator + " " + colNested.column.name;
+        const alias = col.displayName ?? col.operator + " " + findColumn(col).column.name;
         const rewrittenAgg = new AggregateOperation(
           new TableAliasColumn(colNested.column, ta),
           col.operator,
@@ -1532,7 +1790,7 @@ var SQLQueryGenerator = class {
         );
         this._select.push(new Alias(rewrittenAgg, alias));
       } else if (col instanceof ScalarFunctionOperation) {
-        const colNested = findColumn(col);
+        const colNested = this._resolve(findColumn(col));
         const node = colNested.parent;
         let ta;
         if (node !== void 0) {
@@ -1541,13 +1799,13 @@ var SQLQueryGenerator = class {
           ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
           this._from.add(ta);
         }
-        const alias = col.displayName ?? col.func + " " + colNested.column.name;
+        const alias = col.displayName ?? col.func + " " + findColumn(col).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 colNested = this._resolve(findColumn(col));
         const node = colNested.parent;
         let ta;
         if (node !== void 0) {
@@ -1556,7 +1814,7 @@ var SQLQueryGenerator = class {
           ta = this._tableAliasForTable(colNested.column.owner, colNested.column.owner);
           this._from.add(ta);
         }
-        const alias = col.displayName ?? colNested.column.name;
+        const alias = col.displayName ?? findColumn(col).column.name;
         let aliasedOp;
         if (col instanceof DateExtractOperation) {
           aliasedOp = new DateExtractOperation(new TableAliasColumn(colNested.column, ta), col.part);
@@ -1584,7 +1842,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 "";
@@ -1610,15 +1870,15 @@ var SQLQueryGenerator = class {
     }
     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);
@@ -1658,12 +1918,50 @@ function selectSqlToString(selectOperation) {
   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);
+function toSql(businessDate, processingDatetime, columns, table, op, orderBy = [], groupBy = [], limit, businessDateTo = null) {
+  const selectOp = buildQueryOperation(businessDate, processingDatetime, columns, table, op, orderBy, groupBy, limit, businessDateTo);
   return selectSqlToString(selectOp);
 }
 
+// src/datafinder/naming.ts
+function titleCase(value) {
+  return value.replace(/[A-Za-z]+/g, (w) => w[0].toUpperCase() + w.slice(1).toLowerCase());
+}
+
+// src/datafinder/embedded.ts
+function embeddedUnder(embedded, prefix) {
+  if (!embedded) return void 0;
+  const result = {};
+  for (const [key, attr] of Object.entries(embedded)) {
+    if (key.startsWith(prefix)) result[key.slice(prefix.length)] = attr;
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+
+// src/datafinder/finder.ts
+var RelatedFinder = class {
+  constructor(_node) {
+    this._node = _node;
+  }
+  _node;
+  exists() {
+    return new ExistsOperation(this._node);
+  }
+  notExists() {
+    return new NotExistsOperation(this._node);
+  }
+};
+
 // 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;
@@ -1676,21 +1974,24 @@ function getRunner() {
   return _runner;
 }
 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;
+  _timeoutMs = DEFAULT_TIMEOUT_MS;
   orderByOp(...sorts) {
     this._orderBy = sorts;
     return this;
@@ -1703,6 +2004,11 @@ var FinderResult = class {
     this._limit = n;
     return this;
   }
+  /** Abort the query and throw QueryTimeoutError if it runs longer than `milliseconds` (default 60000). */
+  timeout(milliseconds) {
+    this._timeoutMs = milliseconds;
+    return this;
+  }
   toSql() {
     return toSql(
       this._businessDate,
@@ -1712,7 +2018,8 @@ var FinderResult = class {
       this._op,
       this._orderBy,
       this._groupBy,
-      this._limit
+      this._limit,
+      this._businessDateTo
     );
   }
   async toRows() {
@@ -1724,14 +2031,18 @@ var FinderResult = class {
       this._op,
       this._orderBy,
       this._groupBy,
-      this._limit
+      this._limit,
+      this._timeoutMs,
+      this._businessDateTo
     );
   }
 };
 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 (/^\d{4}-\d{2}-\d{2}$/.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;
@@ -1745,10 +2056,24 @@ function convertInputsAndSelect(businessDate, 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),
+    convertDate(processingDatetime),
+    columns,
+    table,
+    op,
+    convertDate(businessDateTo)
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AggregateOperation,
   AggregateOperator,
+  Alias,
   Attribute,
   BiTemporalColumns,
   BinaryOperation,
@@ -1761,6 +2086,7 @@ function convertInputsAndSelect(businessDate, processingDatetime, columns, table
   ComparisonOperator,
   ConstantOperation,
   CountAllOperation,
+  DEFAULT_TIMEOUT_MS,
   DataCatalog,
   DataStore,
   Database,
@@ -1795,11 +2121,13 @@ function convertInputsAndSelect(businessDate, processingDatetime, columns, table
   NumericAttribute,
   Operation,
   ProcessingTemporalColumns,
+  QueryTimeoutError,
   RelatedFinder,
   RelationalOperationElement,
   ScalarFunction,
   ScalarFunctionOperation,
   Schema,
+  SelectOperation,
   SingleBusinessDateColumn,
   SortDirection,
   SortOperation,
@@ -1812,11 +2140,14 @@ function convertInputsAndSelect(businessDate, processingDatetime, columns, table
   WindowSpecification,
   clearRunner,
   convertInputsAndSelect,
+  convertInputsAndSelectForDateRange,
+  embeddedUnder,
   getRelatedFinderClass,
   getRunner,
   registerRelatedFinderClass,
   registerRunner,
   selectSqlToString,
+  titleCase,
   toSql
 });
 //# sourceMappingURL=index.cjs.map