@dbsp/nql 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -427,8 +427,13 @@ interface ColumnValidatorRelation {
     readonly target: string;
     readonly type?: 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany';
     readonly foreignKey?: string | readonly string[] | undefined;
-    readonly sourceKey?: string | undefined;
-    readonly targetKey?: string | undefined;
+    readonly through?: string | undefined;
+    readonly otherKey?: string | undefined;
+    readonly throughSourceKey?: string | undefined;
+    readonly throughTargetKey?: string | undefined;
+    readonly recursive?: unknown;
+    readonly sourceKey?: string | readonly string[] | undefined;
+    readonly targetKey?: string | readonly string[] | undefined;
 }
 /**
  * Options for the NQL compiler.

package/dist/index.js

@@ -1,5 +1,5 @@
-import { NQL_INTERNAL_COMPILER_OPTIONS, markNqlTrustedRelationFilter, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
-import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_VALUE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction, isParamIntent } from '@dbsp/types';
+import { NQL_INTERNAL_COMPILER_OPTIONS, explainUnsupportedNqlBindingIncludeHop, markNqlTrustedRelationFilter, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
+import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_VALUE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, toColumnList, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction, isParamIntent } from '@dbsp/types';
 import { createToken, Lexer, CstParser } from 'chevrotain';
 
 // src/compiler/index.ts
@@ -43,8 +43,6 @@ var NqlSemanticException = class extends Error {
     this.relatedSymbol = relatedSymbol;
   }
 };
-
-// src/compiler/column-validator.ts
 var ColumnValidator = class _ColumnValidator {
   constructor(schema) {
     this.schema = schema;
@@ -110,6 +108,88 @@ var ColumnValidator = class _ColumnValidator {
   getVirtualBindingScalarRelation(bindingName, relationName) {
     return this.virtualBindingRelationFilters.get(bindingName)?.scalarRelations?.find((relation) => relation.relation === relationName);
   }
+  static virtualRelationIncludeShape(relation) {
+    const relationType = relation.relationType;
+    const foreignKey = relationType === "belongsTo" ? relation.sourceColumn : relation.targetColumn;
+    return {
+      type: relationType,
+      foreignKey,
+      source: relation.sourceTable,
+      target: relation.targetTable
+    };
+  }
+  resolveVirtualBindingScalarRelationForInclude(bindingName, relationPath) {
+    const relationName = relationPath.join(".");
+    if (relationPath.length < 1) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): the relation path must name a source-table relation.`
+      );
+    }
+    const relation = relationPath[0];
+    if (!relation) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): the relation path must name a source-table relation.`
+      );
+    }
+    const virtualRelation = this.getVirtualBindingScalarRelation(
+      bindingName,
+      relation
+    );
+    if (virtualRelation) {
+      const resolvedFirstHop = this.getRelation(virtualRelation.sourceTable, relation) ?? _ColumnValidator.virtualRelationIncludeShape(virtualRelation);
+      const unsupportedFirstHopReason = explainUnsupportedNqlBindingIncludeHop(
+        relation,
+        resolvedFirstHop,
+        { relation }
+      );
+      if (unsupportedFirstHopReason) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): ${unsupportedFirstHopReason}.`
+        );
+      }
+      let sourceTable = virtualRelation.targetTable;
+      for (let i = 1; i < relationPath.length; i++) {
+        const tailRelation = relationPath[i];
+        if (!tailRelation) {
+          throw new NqlSemanticException(
+            NqlErrorCodes.SEM_INVALID_SYNTAX,
+            `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): relation path segment ${i + 1} is empty.`
+          );
+        }
+        const resolvedTail = this.getRelation(sourceTable, tailRelation);
+        if (!resolvedTail) {
+          throw new NqlSemanticException(
+            NqlErrorCodes.SEM_INVALID_SYNTAX,
+            `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): tail relation '${tailRelation}' is not declared on table '${sourceTable}'.`
+          );
+        }
+        const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+          tailRelation,
+          resolvedTail,
+          { relation: tailRelation }
+        );
+        if (unsupportedReason) {
+          throw new NqlSemanticException(
+            NqlErrorCodes.SEM_INVALID_SYNTAX,
+            `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relationName}' (ref-#192): tail ${unsupportedReason}.`
+          );
+        }
+        sourceTable = resolvedTail.target;
+      }
+      return virtualRelation;
+    }
+    const reason = this.explainVirtualBindingScalarRelationRejection(
+      bindingName,
+      relation
+    );
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName}' reads from an NQL binding and cannot use relation include '${relation}' (ref-#192): ${reason}.`
+    );
+  }
   explainVirtualBindingRelationRejection(bindingName, relationName) {
     const metadata = this.virtualBindingRelationFilters.get(bindingName);
     if (!metadata) {
@@ -124,27 +204,24 @@ var ColumnValidator = class _ColumnValidator {
     if (!relation) {
       return `relation '${relationName}' is not declared on source table '${sourceTable}'`;
     }
-    const fk = relation.foreignKey;
-    const fkColumns = typeof fk === "string" ? [fk] : Array.isArray(fk) ? [...fk] : [];
+    const fkColumns = toColumnList(relation.foreignKey);
     if (relation.type !== "belongsTo") {
       return `relation '${relationName}' is '${relation.type ?? "unknown"}'; A-lite only supports relations whose FK column is on the binding source table`;
     }
-    if (fkColumns.length !== 1) {
-      return `relation '${relationName}' must have exactly one FK column for A-lite binding relation filters`;
+    if (fkColumns.length === 0) {
+      return `relation '${relationName}' must have at least one FK column for A-lite binding relation filters`;
     }
-    const fkColumn = fkColumns[0];
-    if (fkColumn === void 0) {
-      return `relation '${relationName}' must have exactly one FK column for A-lite binding relation filters`;
-    }
-    const directProjection = metadata.directProjectionLineage?.find(
-      (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, fkColumn)
-    );
-    if (!directProjection) {
-      const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
-      return `relation '${relationName}' FK column '${fkColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+    for (const fkColumn of fkColumns) {
+      const directProjection = metadata.directProjectionLineage?.find(
+        (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, fkColumn)
+      );
+      if (!directProjection) {
+        const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
+        return `relation '${relationName}' FK column '${fkColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+      }
     }
     const available = this.virtualBindingTables.get(bindingName)?.join(", ");
-    return `relation '${relationName}' FK column '${fkColumn}' is not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
+    return `relation '${relationName}' FK columns '${fkColumns.join(", ")}' are not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
   }
   explainVirtualBindingScalarRelationRejection(bindingName, relationName) {
     const metadata = this.virtualBindingRelationFilters.get(bindingName);
@@ -160,29 +237,25 @@ var ColumnValidator = class _ColumnValidator {
     if (!relation) {
       return `relation '${relationName}' is not declared on source table '${sourceTable}'`;
     }
-    const fk = relation.foreignKey;
-    const fkColumns = typeof fk === "string" ? [fk] : Array.isArray(fk) ? [...fk] : [];
-    if (relation.type !== "belongsTo" && relation.type !== "hasOne") {
-      return `relation '${relationName}' is '${relation.type ?? "unknown"}'; binding relation columns require a scalar belongsTo/hasOne relation`;
-    }
-    if (fkColumns.length !== 1) {
-      return `relation '${relationName}' must have exactly one FK column for binding relation columns`;
-    }
-    const fkColumn = fkColumns[0];
-    if (fkColumn === void 0) {
-      return `relation '${relationName}' must have exactly one FK column for binding relation columns`;
-    }
-    const sourceColumn = relation.type === "belongsTo" ? fkColumn : relation.sourceKey ?? "id";
-    const directProjection = metadata.directProjectionLineage?.find(
-      (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, sourceColumn)
+    const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+      relationName,
+      relation
     );
-    if (!directProjection) {
-      const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
-      const sourceColumnLabel = relation.type === "belongsTo" ? "FK column" : "source key column";
-      return `relation '${relationName}' ${sourceColumnLabel} '${sourceColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+    if (unsupportedReason) return unsupportedReason;
+    const fkColumns = toColumnList(relation.foreignKey);
+    const sourceColumns = relation.type === "belongsTo" ? fkColumns : toColumnList(relation.sourceKey).length > 0 ? toColumnList(relation.sourceKey) : ["id"];
+    for (const sourceColumn of sourceColumns) {
+      const directProjection = metadata.directProjectionLineage?.find(
+        (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, sourceColumn)
+      );
+      if (!directProjection) {
+        const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
+        const sourceColumnLabel = relation.type === "belongsTo" ? "FK column" : "source key column";
+        return `relation '${relationName}' ${sourceColumnLabel} '${sourceColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+      }
     }
     const available = this.virtualBindingTables.get(bindingName)?.join(", ");
-    return `relation '${relationName}' source column '${sourceColumn}' is not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
+    return `relation '${relationName}' source columns '${sourceColumns.join(", ")}' are not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
   }
   /**
    * Convert camelCase to snake_case for column name matching.
@@ -281,6 +354,28 @@ var ColumnValidator = class _ColumnValidator {
     );
   }
 };
+var DEFAULT_RELATION_TARGET_COLUMN = "id";
+function relationForeignKeys(relation) {
+  if (!relation) return void 0;
+  const columns = toColumnList(relation.foreignKey);
+  return columns.length > 0 ? columns : void 0;
+}
+function relationCardinality(relation) {
+  return relation?.type === "hasMany" || relation?.type === "belongsToMany" ? "many" : "one";
+}
+function scalarRelationJoinColumns(relation) {
+  if (!relation) return void 0;
+  if (relation.type !== "belongsTo" && relation.type !== "hasOne" && relation.type !== "hasMany") {
+    return void 0;
+  }
+  const fkColumns = relationForeignKeys(relation);
+  if (!fkColumns) return void 0;
+  const sourceKeys = toColumnList(relation.sourceKey);
+  const targetKeys = toColumnList(relation.targetKey);
+  const sourceJoinColumn = relation.type === "belongsTo" ? fkColumns : sourceKeys.length > 0 ? sourceKeys : [DEFAULT_RELATION_TARGET_COLUMN];
+  const targetJoinColumn = relation.type === "belongsTo" ? targetKeys.length > 0 ? targetKeys : [DEFAULT_RELATION_TARGET_COLUMN] : fkColumns;
+  return { sourceJoinColumn, targetJoinColumn };
+}
 var FORBIDDEN_PARAM_NAMES = /* @__PURE__ */ new Set([
   "__proto__",
   "constructor",
@@ -401,6 +496,17 @@ function throwBindingRelationColumn182(bindingName, relationName, reason) {
     `Query '${bindingName}' reads from an NQL binding and cannot select relation column '${relationName}' under A-full (ref-#182): ${reason}.`
   );
 }
+function bindingRelationColumnUnsupportedReason(relationName, relation) {
+  const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+    relationName,
+    relation
+  );
+  if (unsupportedReason) return unsupportedReason;
+  if (relationCardinality(relation) !== "one") {
+    return `relation '${relationName}' is '${relation.type ?? "unknown"}'; scalar binding relation columns require every hop to be to-one (belongsTo/hasOne) (ref-#192)`;
+  }
+  return void 0;
+}
 function resolveBindingRelationFilter(ctx, bindingName, relationPath) {
   if (!isBindingTable(ctx, bindingName)) return void 0;
   const actualBindingName = bindingName;
@@ -435,19 +541,19 @@ function resolveBindingRelationColumn(ctx, bindingName, relationPath, selectedCo
   if (!isBindingTable(ctx, bindingName)) return void 0;
   const actualBindingName = bindingName;
   const relationName = relationPath.join(".");
-  if (relationPath.length !== 1) {
+  const relation = relationPath[0];
+  if (!relation) {
     throwBindingRelationColumn182(
       actualBindingName,
       relationName,
-      "multi-hop binding relation columns are not supported; the relation path must be a single source-table relation"
+      "the relation path must name a source-table relation"
     );
   }
-  const relation = relationPath[0];
-  if (!relation) {
+  if (!ctx.validator) {
     throwBindingRelationColumn182(
       actualBindingName,
       relationName,
-      "the relation path must name a source-table relation"
+      "model metadata is not available"
     );
   }
   const virtualRelation = ctx.validator?.getVirtualBindingScalarRelation(
@@ -459,10 +565,92 @@ function resolveBindingRelationColumn(ctx, bindingName, relationPath, selectedCo
       actualBindingName,
       relation
     ) ?? "model metadata is not available";
-    throwBindingRelationColumn182(actualBindingName, relation, reason);
+    throwBindingRelationColumn182(actualBindingName, relationName, reason);
+  }
+  if (relationPath.length === 1) {
+    ctx.validator.validateColumn(virtualRelation.targetTable, selectedColumn);
+    return virtualRelation;
+  }
+  const firstHop = ctx.validator.getRelation(
+    virtualRelation.sourceTable,
+    relation
+  );
+  if (!firstHop) {
+    throwBindingRelationColumn182(
+      actualBindingName,
+      relationName,
+      `relation '${relation}' is not declared on source table '${virtualRelation.sourceTable}'`
+    );
   }
-  ctx.validator?.validateColumn(virtualRelation.targetTable, selectedColumn);
-  return virtualRelation;
+  const firstHopReason = bindingRelationColumnUnsupportedReason(
+    relation,
+    firstHop
+  );
+  if (firstHopReason) {
+    throwBindingRelationColumn182(
+      actualBindingName,
+      relationName,
+      firstHopReason
+    );
+  }
+  let sourceTable = virtualRelation.targetTable;
+  const hops = [];
+  for (let i = 1; i < relationPath.length; i++) {
+    const tailRelation = relationPath[i];
+    if (!tailRelation) {
+      throwBindingRelationColumn182(
+        actualBindingName,
+        relationName,
+        `relation path segment ${i + 1} is empty (ref-#192)`
+      );
+    }
+    const resolvedTail = ctx.validator.getRelation(sourceTable, tailRelation);
+    if (!resolvedTail) {
+      throwBindingRelationColumn182(
+        actualBindingName,
+        relationName,
+        `tail relation '${tailRelation}' is not declared on table '${sourceTable}' (ref-#192)`
+      );
+    }
+    const tailReason = bindingRelationColumnUnsupportedReason(
+      tailRelation,
+      resolvedTail
+    );
+    if (tailReason) {
+      throwBindingRelationColumn182(
+        actualBindingName,
+        relationName,
+        `tail ${tailReason}`
+      );
+    }
+    const joinColumns = scalarRelationJoinColumns(resolvedTail);
+    if (!joinColumns) {
+      throwBindingRelationColumn182(
+        actualBindingName,
+        relationName,
+        `tail relation '${tailRelation}' cannot be resolved to a scalar join (ref-#192)`
+      );
+    }
+    if (joinColumns.sourceJoinColumn.length !== joinColumns.targetJoinColumn.length) {
+      throwBindingRelationColumn182(
+        actualBindingName,
+        relationName,
+        `tail relation '${tailRelation}' has mismatched join column counts (${joinColumns.sourceJoinColumn.length} source, ${joinColumns.targetJoinColumn.length} target) (ref-#179)`
+      );
+    }
+    hops.push({
+      target: resolvedTail.target,
+      fkColumn: joinColumns.sourceJoinColumn,
+      joinColumn: joinColumns.targetJoinColumn
+    });
+    sourceTable = resolvedTail.target;
+  }
+  ctx.validator.validateColumn(sourceTable, selectedColumn);
+  return {
+    ...virtualRelation,
+    relation: relationName,
+    hops
+  };
 }
 function assertNoBindingRelationPath(ctx, bindingName, path) {
   if (!isBindingTable(ctx, bindingName)) return;
@@ -1099,7 +1287,6 @@ var PORTABLE_BINDING_FINAL_FUNCTIONS = /* @__PURE__ */ new Set([
   ...NQL_SELECT_AGGREGATE_FUNCTIONS,
   ...NQL_SELECT_VALUE_FUNCTIONS
 ]);
-var DEFAULT_RELATION_TARGET_COLUMN = "id";
 function compileNestedQuery(query, ctx, fns, bindings) {
   const savedContext = {
     currentFromTable: ctx.currentFromTable,
@@ -1182,19 +1369,9 @@ function selectContainsAggregate(select) {
   );
 }
 function relationForeignKeysOnSource(relation) {
-  if (!relation || relation.type !== "belongsTo") return void 0;
-  if (typeof relation.foreignKey === "string") return [relation.foreignKey];
-  if (Array.isArray(relation.foreignKey)) return relation.foreignKey;
-  return void 0;
-}
-function relationForeignKeys(relation) {
-  if (!relation) return void 0;
-  if (typeof relation.foreignKey === "string") return [relation.foreignKey];
-  if (Array.isArray(relation.foreignKey)) return relation.foreignKey;
-  return void 0;
-}
-function relationCardinality(relation) {
-  return relation?.type === "hasMany" || relation?.type === "belongsToMany" ? "many" : "one";
+  if (relation?.type !== "belongsTo") return void 0;
+  const fkColumns = toColumnList(relation.foreignKey);
+  return fkColumns.length > 0 ? fkColumns : void 0;
 }
 function unsafeBindingRelationReason(intent, ctx, bindingDependencies) {
   if (!ctx.validator) return "model metadata is not available";
@@ -1229,48 +1406,70 @@ function findDirectSourceProjection(sourceTable, sourceColumn, directProjectionL
     (projection) => projection.sourceTable === sourceTable && columnsMatch(projection.sourceColumn, sourceColumn)
   );
 }
+function findDirectSourceProjections(sourceTable, sourceColumns, directProjectionLineage) {
+  const projections = [];
+  for (const sourceColumn of sourceColumns) {
+    const projection = findDirectSourceProjection(
+      sourceTable,
+      sourceColumn,
+      directProjectionLineage
+    );
+    if (!projection) return void 0;
+    projections.push(projection);
+  }
+  return projections;
+}
 function virtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
   const fkColumns = relationForeignKeysOnSource(relation);
-  if (!relation || !fkColumns || fkColumns.length !== 1) return void 0;
-  const fkColumn = fkColumns[0];
-  const sourceProjection = findDirectSourceProjection(
+  if (!relation || !fkColumns) return void 0;
+  const sourceProjections = findDirectSourceProjections(
     sourceTable,
-    fkColumn,
+    fkColumns,
     directProjectionLineage
   );
-  if (!sourceProjection) return void 0;
+  if (!sourceProjections) return void 0;
+  const targetKey = toColumnList(relation.targetKey);
+  const targetColumns = targetKey.length > 0 ? targetKey : [DEFAULT_RELATION_TARGET_COLUMN];
+  if (targetColumns.length !== fkColumns.length) return void 0;
   return {
     relation: relation.name,
     sourceTable,
     targetTable: relation.target,
-    sourceColumn: sourceProjection.outputColumn,
-    targetColumn: relation.targetKey ?? DEFAULT_RELATION_TARGET_COLUMN,
+    sourceColumn: sourceProjections.map(
+      (projection) => projection.outputColumn
+    ),
+    targetColumn: targetColumns,
+    hops: [],
     cardinality: "one"
   };
 }
 function scalarVirtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
   if (!relation) return void 0;
-  if (relation.type !== "belongsTo" && relation.type !== "hasOne") {
+  if (relation.type !== "belongsTo" && relation.type !== "hasOne" && relation.type !== "hasMany") {
     return void 0;
   }
-  const fkColumns = relationForeignKeys(relation);
-  if (!fkColumns || fkColumns.length !== 1) return void 0;
-  const fkColumn = fkColumns[0];
-  const sourceJoinColumn = relation.type === "belongsTo" ? fkColumn : relation.sourceKey ?? DEFAULT_RELATION_TARGET_COLUMN;
-  const targetJoinColumn = relation.type === "belongsTo" ? relation.targetKey ?? DEFAULT_RELATION_TARGET_COLUMN : fkColumn;
-  const sourceProjection = findDirectSourceProjection(
+  const joinColumns = scalarRelationJoinColumns(relation);
+  if (!joinColumns) return void 0;
+  if (joinColumns.sourceJoinColumn.length !== joinColumns.targetJoinColumn.length) {
+    return void 0;
+  }
+  const sourceProjections = findDirectSourceProjections(
     sourceTable,
-    sourceJoinColumn,
+    joinColumns.sourceJoinColumn,
     directProjectionLineage
   );
-  if (!sourceProjection) return void 0;
+  if (!sourceProjections) return void 0;
   return {
     relation: relation.name,
     sourceTable,
     targetTable: relation.target,
-    sourceColumn: sourceProjection.outputColumn,
-    targetColumn: targetJoinColumn,
-    cardinality: relationCardinality(relation)
+    sourceColumn: sourceProjections.map(
+      (projection) => projection.outputColumn
+    ),
+    targetColumn: joinColumns.targetJoinColumn,
+    hops: [],
+    cardinality: relationCardinality(relation),
+    relationType: relation.type
   };
 }
 function getBindingRelationFilterMetadata(intent, ctx, outputSchema, bindingDependencies) {
@@ -1338,6 +1537,19 @@ function validateBindingFinalPath(expr, ctx, bindingName) {
   }
   assertNoBindingRelationPath(ctx, bindingName, segments.join("."));
 }
+function resolveBindingRelationInclude(ctx, bindingName, relationPath) {
+  if (!isBindingTable(ctx, bindingName)) return void 0;
+  if (!bindingName || !ctx.validator) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName ?? "<unknown>"}' reads from an NQL binding and cannot use relation include '${relationPath.join(".")}' (ref-#192): model metadata is not available.`
+    );
+  }
+  return ctx.validator.resolveVirtualBindingScalarRelationForInclude(
+    bindingName,
+    relationPath
+  );
+}
 function validateBindingFinalFunction(expr, ctx, bindingName, allowRelationFilters) {
   const fn = expr.name.toLowerCase();
   if (!PORTABLE_BINDING_FINAL_FUNCTIONS.has(fn)) {
@@ -1538,12 +1750,7 @@ function validateBindingFinalSelectClause(clause, ctx, bindingName) {
       case "star":
         break;
       case "relationStar":
-        assertNoBindingRelationConstruct(
-          ctx,
-          bindingName,
-          "select relation columns",
-          item.relation.join(".")
-        );
+        resolveBindingRelationInclude(ctx, bindingName, item.relation);
         break;
       case "expression":
         if (item.expression.type === "path" && item.expression.segments.length > 1) {
@@ -1779,21 +1986,38 @@ function compileQueryInternal(query, ctx, fns, bindings) {
       }
     }
   }
-  if (select && select.type === "expressions" && !isBindingSource) {
+  if (select && select.type === "expressions") {
     const relationPaths = /* @__PURE__ */ new Set();
     for (const expr of select.columns) {
       if (expr.kind === "relationColumn") {
-        relationPaths.add(expr.relation);
+        if (!isBindingSource || expr.column === "*") {
+          relationPaths.add(expr.relation);
+        }
       }
     }
     if (relationPaths.size > 0) {
-      const nestedIncludes = buildNestedIncludes(relationPaths, flatMode);
-      for (const inc of nestedIncludes) {
-        const exists = allIncludes.some(
-          (existing) => existing.relation === inc.relation
-        );
-        if (!exists) {
-          allIncludes.push(inc);
+      if (isBindingSource) {
+        for (const relation of relationPaths) {
+          resolveBindingRelationInclude(ctx, query.table, relation.split("."));
+        }
+        const nestedIncludes = buildNestedIncludes(relationPaths, flatMode);
+        for (const inc of nestedIncludes) {
+          const exists = allIncludes.some(
+            (existing) => existing.relation === inc.relation
+          );
+          if (!exists) {
+            allIncludes.push(inc);
+          }
+        }
+      } else {
+        const nestedIncludes = buildNestedIncludes(relationPaths, flatMode);
+        for (const inc of nestedIncludes) {
+          const exists = allIncludes.some(
+            (existing) => existing.relation === inc.relation
+          );
+          if (!exists) {
+            allIncludes.push(inc);
+          }
         }
       }
     }
@@ -2858,6 +3082,7 @@ function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
     targetTable: bindingRelation.targetTable,
     sourceColumn: bindingRelation.sourceColumn,
     targetColumn: bindingRelation.targetColumn,
+    hops: bindingRelation.hops,
     ...bindingRelation.cardinality !== void 0 && {
       cardinality: bindingRelation.cardinality
     }
@@ -2967,6 +3192,20 @@ var SELECT_SCALAR_FUNCTION_NAMES = /* @__PURE__ */ new Set([
   ...NQL_SELECT_JSON_FUNCTIONS,
   ...NQL_SELECT_SCALAR_FUNCTIONS
 ]);
+function resolveBindingRelationInclude2(ctx, bindingName, relationPath) {
+  if (!isBindingTable(ctx, bindingName)) return false;
+  if (!bindingName || !ctx.validator) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName ?? "<unknown>"}' reads from an NQL binding and cannot use relation include '${relationPath.join(".")}' (ref-#192): model metadata is not available.`
+    );
+  }
+  ctx.validator.resolveVirtualBindingScalarRelationForInclude(
+    bindingName,
+    relationPath
+  );
+  return true;
+}
 function validateSelectPathExpression(expr, ctx) {
   if (!ctx.currentFromTable) return;
   const { segments } = expr;
@@ -3022,12 +3261,14 @@ function compileSelectClause(clause, ctx, fns) {
     } else if (item.type === "relationStar") {
       hasExpressions = true;
       const relation = item.relation.join(".");
-      assertNoBindingRelationConstruct(
-        ctx,
-        ctx.currentFromTable,
-        "select relation columns",
-        relation
-      );
+      if (!resolveBindingRelationInclude2(ctx, ctx.currentFromTable, item.relation)) {
+        assertNoBindingRelationConstruct(
+          ctx,
+          ctx.currentFromTable,
+          "select relation columns",
+          relation
+        );
+      }
       expressions.push({
         kind: "relationColumn",
         relation,
@@ -3368,7 +3609,8 @@ function compileMultiSegmentPath(expr, item, ctx) {
     );
   }
   if (ctx.currentFromTable && ctx.validator) {
-    const targetTable = bindingRelation?.targetTable ?? ctx.validator.resolveRelationTarget(ctx.currentFromTable, segments[0]);
+    const lastBindingHop = bindingRelation?.hops[bindingRelation.hops.length - 1];
+    const targetTable = lastBindingHop?.target ?? bindingRelation?.targetTable ?? ctx.validator.resolveRelationTarget(ctx.currentFromTable, segments[0]);
     if (targetTable) {
       ctx.validator.validateColumn(targetTable, column);
     }
@@ -3384,9 +3626,13 @@ function compileMultiSegmentPath(expr, item, ctx) {
     targetTable: bindingRelation.targetTable,
     sourceColumn: bindingRelation.sourceColumn,
     targetColumn: bindingRelation.targetColumn,
+    hops: bindingRelation.hops,
     selectedColumn: column,
     ...bindingRelation.cardinality !== void 0 && {
       cardinality: bindingRelation.cardinality
+    },
+    ...bindingRelation.relationType !== void 0 && {
+      relationType: bindingRelation.relationType
     }
   }) : relationColumnIntent;
 }