@cap-js/db-service 2.8.2 → 2.10.0

package/lib/cqn4sql.js

@@ -9,10 +9,11 @@ const {
   prettyPrintRef,
   isCalculatedOnRead,
   isCalculatedElement,
-  getImplicitAlias,
+  getImplicitAlias: _getImplicitAlias,
   defineProperty,
   getModelUtils,
   hasOwnSkip,
+  isRuntimeView,
 } = require('./utils')
 
 /**
@@ -53,7 +54,8 @@ const { pseudos } = require('./infer/pseudos')
  * @param {object} model
  * @returns {object} transformedQuery the transformed query
  */
-function cqn4sql(originalQuery, model) {
+function cqn4sql(originalQuery, model, useTechnicalAlias = true) {
+  const getImplicitAlias = str => _getImplicitAlias(str, useTechnicalAlias)
   let inferred = typeof originalQuery === 'string' ? cds.parse.cql(originalQuery) : cds.ql.clone(originalQuery)
   const hasCustomJoins =
     originalQuery.SELECT?.from.args && (!originalQuery.joinTree || originalQuery.joinTree.isInitial)
@@ -80,7 +82,7 @@ function cqn4sql(originalQuery, model) {
   if (inferred.UPDATE?.entity.ref?.at(-1).id) {
     assignQueryModifiers(inferred.UPDATE, inferred.UPDATE.entity.ref.at(-1))
   }
-  inferred = infer(inferred, model)
+  inferred = infer(inferred, model, useTechnicalAlias)
   const { getLocalizedName, isLocalized, getDefinition } = getModelUtils(model, originalQuery) // TODO: pass model to getModelUtils
   // if the query has custom joins we don't want to transform it
   // TODO: move all the way to the top of this function once cds.infer supports joins as well
@@ -133,7 +135,7 @@ function cqn4sql(originalQuery, model) {
       // match primary keys of the target entity with the subquery
       primaryKey.list.forEach(k => subquery.SELECT.columns.push({ ref: k.ref.slice(1) }))
 
-      const transformedSubquery = cqn4sql(subquery, model)
+      const transformedSubquery = cqn4sql(subquery, model, useTechnicalAlias)
 
       // replace where condition of original query with the transformed subquery
       // correlate UPDATE / DELETE query with subquery by primary key matches
@@ -173,8 +175,114 @@ function cqn4sql(originalQuery, model) {
     }
   }
 
+  if (cds.env.features.runtime_views) processRuntimeViews(transformedQuery, model)
+
   return transformedQuery
 
+  /**
+   * If the target entity is annotated with persistence skip and has an underlying db entity,
+   * we treat it as a runtime view and transform it into a CTE.
+   * 
+   * @param {object} transformedQuery - The query object to be transformed.
+   * @param {string} model - The data model used for inference and transformation.
+   */
+  function processRuntimeViews(transformedQuery, model) {
+    const currentDef = transformedQuery._target
+
+    if (hasOwnSkip(currentDef)) {
+      if (!isRuntimeView(currentDef)) throw new Error(`${currentDef.name} is not a runtime view`)
+
+      addWith(currentDef, transformedQuery, model)
+      updateRefsWithRTVAlias(transformedQuery._with, transformedQuery)
+    }
+  }
+
+  /**
+   * Recursively call cqn4sql for all nested runtime views to calculate cte and 
+   * add it as a with clause to the transformed query.
+   * Alias the runtime view with a unique alias and update all references to the runtime view to point to the alias.
+   * 
+   * @param {object} rootDefinition - The root definition of the query. This is used to recursively process nested runtime views.
+   * @param {object} transformedQuery - The query object to be transformed.
+   * @param {string} model - The data model used for infer and cqn4sql.
+   */
+  function addWith(rootDefinition, transformedQuery, model) {
+    if (!rootDefinition?.query) return
+
+    // early exit if already processed
+    if (transformedQuery._with?.some(w => w._source === rootDefinition)) return
+
+    const q = cds.ql.clone(rootDefinition.query)
+    if (q.SELECT) {
+      if (!q.SELECT.columns) q.SELECT.columns = ['*']
+      if (q.SELECT.columns.includes('*')) {
+        // cache element names for faster lookup
+        const existingColumns = new Set(
+          q.SELECT.columns
+            .map(col => col.as || col.ref?.at(-1))
+            .filter(Boolean)
+        )
+
+        for (let el of rootDefinition.elements) {
+          if (el.type === 'cds.LargeBinary' && !existingColumns.has(el.name)) {
+            q.SELECT.columns.push({ ref: [el.name] })
+          }
+        }
+      }
+    }
+    const inferredDQ = infer(q, model, useTechnicalAlias)
+    inferredDQ._with = transformedQuery._with
+    const transformedDQ = cqn4sql(inferredDQ, model, useTechnicalAlias)
+
+    if (q.SELECT?.from?.args) {
+      for (const arg of q.SELECT.from.args) {
+        addWith(arg.$refLinks.at(-1).definition, inferredDQ, model)
+        arg.as ??= arg.ref.at(-1).split('.').at(-1) // apply @sap/cds-compiler default alias
+        updateRefsWithRTVAlias(inferredDQ._with, transformedDQ, arg.ref)
+      }
+    }
+
+    const newWiths = transformedDQ._with || []
+    const rootDefinitionName = rootDefinition.name
+
+    defineProperty(transformedDQ, '_source', rootDefinition)
+    const alias = `RTV_${getImplicitAlias(rootDefinitionName)}`
+    transformedDQ.as = transformedDQ.joinTree.addNextAvailableTableAlias(alias, newWiths, rootDefinitionName)
+
+    // update SELECT.from with runtime view alias
+    if (hasOwnSkip(transformedDQ._target)) updateRefsWithRTVAlias(transformedDQ._with, transformedDQ)
+
+    if (transformedDQ._with) delete transformedDQ._with
+    newWiths.push(transformedDQ)
+
+    // propagate with clauses
+    if (!transformedQuery._with) transformedQuery._with = newWiths
+  }
+
+  function updateRefsWithRTVAlias(_with, query, ref) {
+    if (!_with?.length) return
+
+    const _updateRef = (ref) => {
+      const refAlias = ref[0]
+      if (/RTV_$/.test(refAlias)) return
+      for (const w of _with) {
+        const aliasValue = w.joinTree._queryAliases.get(refAlias)
+        if (aliasValue) {
+          ref[0] = aliasValue
+          if (query.joinTree?._queryAliases) {
+            query.joinTree._queryAliases.set(refAlias, aliasValue)
+          }
+          break
+        }
+      }
+    }
+
+    if (ref) return _updateRef(ref)
+
+    if (query.SELECT.from.args) for (const arg of query.SELECT.from.args) _updateRef(arg.ref)
+    else if (query.SELECT.from.ref) _updateRef(query.SELECT.from.ref)
+  }
+
   function transformSelectQuery(queryProp, transformedFrom, transformedWhere, transformedQuery) {
     const { columns, having, groupBy, orderBy, limit } = queryProp
 
@@ -314,7 +422,9 @@ function cqn4sql(originalQuery, model) {
         ),
       )
 
-      const id = getDefinition(nextAssoc.$refLink.definition.target).name
+      const def = getDefinition(nextAssoc.$refLink.definition.target)
+      const id = def.name
+      if (hasOwnSkip(def) && isRuntimeView(def)) addWith(model.definitions[id], transformedQuery, model)
       const { args } = nextAssoc
       const arg = {
         ref: [args ? { id, args } : id],
@@ -352,7 +462,7 @@ function cqn4sql(originalQuery, model) {
     for (let i = 0; i < columns.length; i++) {
       const col = columns[i]
 
-      if (isCalculatedOnRead(col.$refLinks?.[col.$refLinks.length - 1].definition)) {
+      if (isCalculatedOnRead(col.$refLinks?.at(-1).definition) && !col.$refLinks?.at(-1).target?.SELECT) {
         const name = getName(col)
         if (!transformedColumns.some(inserted => getName(inserted) === name)) {
           const calcElement = resolveCalculatedElement(col)
@@ -473,7 +583,13 @@ function cqn4sql(originalQuery, model) {
       const refNavigation = col.ref.slice(col.$refLinks[0].definition.kind !== 'element' ? 1 : 0).join('_')
       if (!columnAlias && col.flatName && col.flatName !== refNavigation) columnAlias = refNavigation
 
-      if (col.$refLinks.some(link => hasOwnSkip(getDefinition(link.definition.target)))) return
+      if (
+        col.$refLinks.some(link => {
+          const def = getDefinition(link.definition.target)
+          return hasOwnSkip(def) && !isRuntimeView(def)
+        })
+      )
+        return
 
       const flatColumns = getFlatColumnsFor(col, { baseName, columnAlias, tableAlias })
       flatColumns.forEach(flatColumn => {
@@ -507,6 +623,11 @@ function cqn4sql(originalQuery, model) {
 
     function getTransformedColumn(col) {
       let ret
+      if (col !== null && typeof col === 'object' && '#' in col) {
+        ret = resolveEnumToken(col, [], -1)
+        // cast is already resolved inside resolveEnumToken; do not overwrite it here
+        return ret
+      }
       if (col.func) {
         ret = {
           func: col.func,
@@ -519,7 +640,7 @@ function cqn4sql(originalQuery, model) {
         ret.xpr = getTransformedTokenStream(col.xpr)
       }
       if (ret) {
-        if (col.cast) ret.cast = col.cast
+        if (col.cast) ret.cast = resolveEnumCastType(col.cast)
         return ret
       }
       return copy(col)
@@ -560,6 +681,7 @@ function cqn4sql(originalQuery, model) {
       res = { args: getTransformedFunctionArgs(value.args, $baseLink), func: value.func }
     }
     if (!omitAlias) res.as = column.as || column.name || column.flatName
+    setElementOnColumns(res, column.element || column)
     return res
   }
 
@@ -610,10 +732,11 @@ function cqn4sql(originalQuery, model) {
           },
         })
       } else {
-        // target column is `val` or `xpr`, destructure and throw away the ref with the $self
+        // target column is `val`, `xpr`, or `func` — destructure and throw away the ref with the $self
         // eslint-disable-next-line no-unused-vars
-        const { xpr, val, ref, as: _as, ...rest } = referencedColumn
+        const { xpr, val, func, args, ref, as: _as, ...rest } = referencedColumn
         if (xpr) rest.xpr = xpr
+        else if (func) { rest.func = func; rest.args = args }
         else rest.val = val
         dollarSelfColumn = { ...rest } // reassign dummyColumn without 'ref'
         if (!omitAlias) dollarSelfColumn.as = as
@@ -643,8 +766,7 @@ function cqn4sql(originalQuery, model) {
         nameParts.push(nestedProjection.as ? nestedProjection.as : nestedProjection.ref.map(idOnly).join('_'))
         const name = nameParts.join('_')
         if (nestedProjection.ref) {
-          const augmentedInlineCol = { ...nestedProjection }
-          augmentedInlineCol.ref = col.ref ? [...col.ref, ...nestedProjection.ref] : nestedProjection.ref
+          const augmentedInlineCol = augmentInlineRefWithParent(nestedProjection, col)
           if (
             col.as ||
             nestedProjection.as ||
@@ -653,19 +775,6 @@ function cqn4sql(originalQuery, model) {
           ) {
             augmentedInlineCol.as = nameParts.join('_')
           }
-          Object.defineProperties(augmentedInlineCol, {
-            $refLinks: { value: [...nestedProjection.$refLinks], writable: true },
-            isJoinRelevant: {
-              value: nestedProjection.isJoinRelevant,
-              writable: true,
-            },
-          })
-          // if the expand is not anonymous, we must prepend the expand columns path
-          // to make sure the full path is resolvable
-          if (col.ref) {
-            augmentedInlineCol.$refLinks.unshift(...col.$refLinks)
-            augmentedInlineCol.isJoinRelevant = augmentedInlineCol.isJoinRelevant || col.isJoinRelevant
-          }
           const flatColumns = getTransformedColumns([augmentedInlineCol])
           flatColumns.forEach(flatColumn => {
             const flatColumnName = flatColumn.as || flatColumn.ref[flatColumn.ref.length - 1]
@@ -682,6 +791,10 @@ function cqn4sql(originalQuery, model) {
           if (!res.some(c => (c.as || c.ref.slice(1).map(idOnly).join('_')) === name)) {
             const rewrittenColumn = { ...nestedProjection }
             rewrittenColumn.as = name
+            // For xpr, we need to transform refs inside to include the struct prefix
+            if (nestedProjection.xpr && col.ref) {
+              rewrittenColumn.xpr = augmentInlineXprRefs(nestedProjection.xpr, col)
+            }
             rewrittenColumns.push(rewrittenColumn)
           }
         }
@@ -690,6 +803,55 @@ function cqn4sql(originalQuery, model) {
     })
 
     return res
+
+    /**
+     * Augment a ref column with the parent column's path and $refLinks.
+     */
+    function augmentInlineRefWithParent(refCol, parentCol) {
+      const augmented = { ...refCol }
+      augmented.ref = parentCol.ref ? [...parentCol.ref, ...refCol.ref] : refCol.ref
+      Object.defineProperties(augmented, {
+        $refLinks: { value: [...refCol.$refLinks], writable: true },
+        isJoinRelevant: { value: refCol.isJoinRelevant, writable: true },
+      })
+      if (parentCol.ref) {
+        augmented.$refLinks.unshift(...parentCol.$refLinks)
+        augmented.isJoinRelevant = augmented.isJoinRelevant || parentCol.isJoinRelevant
+      }
+      return augmented
+    }
+
+    /**
+     * Augment refs inside an xpr with the parent column's path and $refLinks,
+     * then transform them to flat refs.
+     */
+    function augmentInlineXprRefs(xpr, parentCol) {
+      return xpr.map(token => {
+        if (typeof token === 'string' || token.val !== undefined) {
+          return token
+        }
+        if (token.ref && token.$refLinks) {
+          const augmented = augmentInlineRefWithParent(token, parentCol)
+          // Transform this single ref column to get the flat version
+          const transformed = getTransformedColumns([augmented])
+          if (transformed.length === 1) {
+            return transformed[0]
+          }
+          return augmented
+        }
+        if (token.xpr) {
+          return { ...token, xpr: augmentInlineXprRefs(token.xpr, parentCol) }
+        }
+        if (token.func && token.args) {
+          return {
+            ...token, args: token.args.map(arg =>
+              arg.ref ? augmentInlineXprRefs([arg], parentCol)[0] : arg
+            )
+          }
+        }
+        return token
+      })
+    }
   }
 
   /**
@@ -747,6 +909,9 @@ function cqn4sql(originalQuery, model) {
 
     if (baseRefLinks.at(-1).definition.kind === 'entity') {
       res.push(...getColumnsForWildcard(exclude, replace, col.as))
+    } else if (baseRefLinks.at(-1).definition.target) {
+      // Wildcard on association - need to include FK columns and join-relevant target columns
+      res.push(...expandAssociationWildcard(col, baseRef, baseRefLinks, exclude, replace))
     } else
       res.push(
         ...getFlatColumnsFor(col, { columnAlias: col.as, tableAlias: getTableAlias(col) }, [], {
@@ -757,6 +922,117 @@ function cqn4sql(originalQuery, model) {
     return res
   }
 
+  /**
+   * Expands a wildcard on an association into:
+   * 1. FK columns from the source table
+   * 2. Non-FK columns from the target via join
+   */
+  function expandAssociationWildcard(col, baseRef, baseRefLinks, exclude, replace) {
+    const res = []
+    const assocDef = baseRefLinks.at(-1).definition
+    const targetDef = getDefinition(assocDef.target)
+    const columnAlias = col.as || baseRef.map(idOnly).join('_')
+    const sourceTableAlias = getTableAlias(col)
+
+    // Get the join alias for this association (set during join tree merge)
+    const joinAlias = baseRefLinks.at(-1).alias
+
+    // Collect FK element names
+    const fkNames = new Set()
+    if (assocDef.keys) {
+      for (const k of assocDef.keys) {
+        fkNames.add(k.ref[0])
+      }
+    }
+
+    // First, add FK columns from source table
+    // These are accessed via the source table alias, not the join
+    const fkColumns = getFlatColumnsFor(col, { tableAlias: sourceTableAlias }, [], {
+      exclude,
+      replace,
+    })
+    res.push(...fkColumns.filter(fk => !col.excluding?.some(e => targetDef.elements[e] === fk.element)))
+
+    // Then, add non-FK columns from target via join
+    if (targetDef?.elements) {
+      for (const [elemName, elemDef] of Object.entries(targetDef.elements)) {
+        // Skip FK elements (already included above), virtual, blobs, and unmanaged assocs
+        if (fkNames.has(elemName)) continue
+        if (elemDef.virtual) continue
+        if (elemDef.type === 'cds.LargeBinary') continue
+        if (elemDef.on && !elemDef.keys) continue // unmanaged association
+
+        // Check exclusions
+        const fullName = `${columnAlias}_${elemName}`
+        if (exclude.some(e => (e.ref?.at(-1) || e.as || e) === elemName)) continue
+        if (exclude.some(e => (e.ref?.at(-1) || e.as || e) === fullName)) continue
+
+        // Check for replacement
+        const replacement = replace.find(r => (r.ref?.at(-1) || r.as) === elemName)
+        if (replacement) {
+          // Handle replacement - create augmented column
+          const augmented = { ...replacement }
+          augmented.as = fullName
+          res.push(...getTransformedColumns([augmented]))
+          continue
+        }
+
+        // Create column referencing the join alias
+        if (elemDef.elements) {
+          // Structured element - need to flatten it
+          const structCols = getFlatColumnsFor(
+            elemDef,
+            { baseName: elemName, columnAlias: fullName, tableAlias: joinAlias },
+            [],
+            { exclude, replace },
+            true,
+          )
+          res.push(...structCols)
+        } else if (elemDef.keys) {
+          // Association element - flatten its foreign keys
+          // The FK column name is: assocName_keyName (e.g., 'head_id')
+          for (const k of elemDef.keys) {
+            const keyName = k.as || k.ref.join('_')
+            const fkName = `${elemName}_${keyName}`  // e.g., 'head_id'
+            const fkFullName = `${columnAlias}_${fkName}`  // e.g., 'department_head_id'
+            
+            // Check if this FK is excluded
+            if (exclude.some(e => (e.ref?.at(-1) || e.as || e) === fkName)) continue
+            if (exclude.some(e => (e.ref?.at(-1) || e.as || e) === fkFullName)) continue
+            
+            const flatColumn = {
+              ref: [joinAlias, fkName],
+              as: fkFullName,
+            }
+            const fkElement = getElementForRef(k.ref, getDefinition(elemDef.target))
+            setElementOnColumns(flatColumn, fkElement)
+            res.push(flatColumn)
+          }
+        } else if (elemDef.value) {
+          // Calculated element - resolve it
+          const calcElement = resolveCalculatedElement({ $refLinks: [{ definition: elemDef }] }, true)
+          if (calcElement.as) {
+            calcElement.as = fullName
+          } else {
+            calcElement.as = fullName
+          }
+          res.push(calcElement)
+        }        
+        else {
+          // Scalar element
+          const flatColumn = {
+            ref: [joinAlias, elemName],
+            as: fullName,
+          }
+          setElementOnColumns(flatColumn, elemDef)
+          res.push(flatColumn)
+        }
+      }
+    }
+
+    return res
+  }
+
   /**
    * This function converts a column with an `expand` property into a subquery.
    *
@@ -972,7 +1248,12 @@ function cqn4sql(originalQuery, model) {
       } else if (pseudos.elements[col.ref?.[0]]) {
         res.push({ ...col })
       } else if (col.ref) {
-        if (col.$refLinks.some(link => hasOwnSkip(getDefinition(link.definition.target))))
+        if (
+          col.$refLinks.some(link => {
+            const def = getDefinition(link.definition.target)
+            return hasOwnSkip(def) && !isRuntimeView(def)
+          })
+        )
           continue
         if (col.ref.length > 1 && col.ref[0] === '$self' && !col.$refLinks[0].definition.kind) {
           const dollarSelfReplacement = calculateDollarSelfColumn(col)
@@ -1070,10 +1351,18 @@ function cqn4sql(originalQuery, model) {
       outerQueries.push(inferred)
       defineProperty(q, 'outerQueries', outerQueries)
     }
+
     const target = cds.infer.target(inferred) // REVISIT: we should reliably use inferred._target instead
     if (isLocalized(target)) q.SELECT.localized = true
     if (q.SELECT.from.ref && !q.SELECT.from.as) assignUniqueSubqueryAlias()
-    return cqn4sql(q, model)
+    if (cds.env.features.runtime_views) q._with = transformedQuery._with
+    const _q = cqn4sql(q, model, useTechnicalAlias)
+    if (cds.env.features.runtime_views && _q._with) {
+      if (!transformedQuery._with) transformedQuery._with = _q._with
+      delete _q._with
+    }
+    return _q
+
 
     function assignUniqueSubqueryAlias() {
       if (q.SELECT.from.uniqueSubqueryAlias) return
@@ -1108,8 +1397,8 @@ function cqn4sql(originalQuery, model) {
       if (!exclude.includes(k)) {
         const { index, tableAlias } = inferred.$combinedElements[k][0]
         const element = tableAlias.elements[k]
-        // ignore FK for odata csn / ignore blobs from wildcard expansion
-        if (isManagedAssocInFlatMode(element) || element.type === 'cds.LargeBinary') continue
+        // ignore FK for odata csn (but not for subquery sources where FK is not a separate element) / ignore blobs from wildcard expansion
+        if ((!tableAlias.SELECT && isManagedAssocInFlatMode(element)) || element.type === 'cds.LargeBinary') continue
         // for wildcard on subquery in from, just reference the elements
         if (tableAlias.SELECT && !element.elements && !element.target) {
           wildcardColumns.push(index ? { ref: [index, k] } : { ref: [k] })
@@ -1157,35 +1446,23 @@ function cqn4sql(originalQuery, model) {
 
   /**
    * Recursively expands a structured element into flat columns, representing all leaf paths.
-   * This function transforms complex structured elements into simple column representations.
-   *
-   * For each element, the function checks if it's a structure, an association or a scalar,
-   * and proceeds accordingly. If the element is a structure, it recursively fetches flat columns for all sub-elements.
-   * If it's an association, it fetches flat columns for it's foreign keys.
-   * If it's a scalar, it creates a flat column for it.
    *
-   * Columns excluded in a wildcard expansion or replaced by other columns are also handled accordingly.
+   * Structures → flat sub-element columns. Associations → flat foreign key columns.
+   * Scalars → single column reference.
    *
-   * @param {object} column - The structured element which needs to be expanded.
+   * @param {object} column - The element to expand (may be a ref with $refLinks, or a raw element definition).
    * @param {{
-   *  columnAlias: string
-   *  tableAlias: string
-   *  baseName: string
-   * }} names - configuration object for naming parameters:
-   * columnAlias - The explicit alias which the user has defined for the column.
-   *                               For instance `{ struct.foo as bar}` will be transformed into
-   *                               `{ struct_foo_leaf1 as bar_foo_leaf1, struct_foo_leaf2 as bar_foo_leaf2 }`.
-   * tableAlias - The table alias to prepend to the column name. Optional.
-   * baseName - The prefixes of the column reference (joined with '_'). Optional.
-   * @param {string} columnAlias - The explicit alias which the user has defined for the column.
-   *                               For instance `{ struct.foo as bar}` will be transformed into
-   *                               `{ struct_foo_leaf1 as bar_foo_leaf1, struct_foo_leaf2 as bar_foo_leaf2 }`.
-   * @param {string} tableAlias - The table alias to prepend to the column name. Optional.
-   * @param {Array} csnPath - An array containing CSN paths. Optional.
-   * @param {Array} exclude - An array of columns to be excluded from the flat structure. Optional.
-   * @param {Array} replace - An array of columns to be replaced in the flat structure. Optional.
-   *
-   * @returns {object[]} Returns an array of flat column(s) for the given element.
+   *  baseName?: string,
+   *  columnAlias?: string,
+   *  tableAlias?: string
+   * }} [names] - Naming context:
+   *   - `baseName` — accumulated underscore-joined prefix for the flat column ref (e.g. `'address'` → `'address_street'`).
+   *   - `columnAlias` — explicit alias for the output column. Defaults to `column.as` when omitted.
+   *   - `tableAlias` — table alias prepended to the column ref.
+   * @param {string[]} [csnPath=[]] - Accumulated CSN element path (used for `_csnPath` metadata on leaf columns).
+   * @param {{ exclude?: Array, replace?: Array }} [excludeAndReplace] - Columns to exclude or replace during wildcard expansion.
+   * @param {boolean} [isWildcard=false] - Whether this expansion originates from a wildcard; filters out LargeBinary.
+   * @returns {object[]} Flat column(s) for the given element.
    */
   function getFlatColumnsFor(column, names, csnPath = [], excludeAndReplace, isWildcard = false) {
     if (!column) return column
@@ -1198,28 +1475,13 @@ function cqn4sql(originalQuery, model) {
     let firstNonJoinRelevantAssoc, stepAfterAssoc
     let element = $refLinks ? $refLinks[$refLinks.length - 1].definition : column
     if (isWildcard && element.type === 'cds.LargeBinary') return []
-    if (element.on && !element.keys)
-      return [] // unmanaged doesn't make it into columns
-    else if (element.virtual === true) return []
-    else if (!isJoinRelevant && flatName) baseName = flatName
-    else if (isJoinRelevant) {
-      const leafAssocIndex = column.$refLinks.findIndex(link => link.definition.isAssociation && link.onlyForeignKeyAccess)
-      firstNonJoinRelevantAssoc = column.$refLinks[leafAssocIndex] || [...column.$refLinks].reverse().find(link => link.definition.isAssociation)
-      stepAfterAssoc = column.$refLinks.at(leafAssocIndex + 1) || column.$refLinks.at(-1)
-      let elements = firstNonJoinRelevantAssoc.definition.elements || firstNonJoinRelevantAssoc.definition.foreignKeys
-      if (elements && stepAfterAssoc.definition.name in elements) {
-        element = firstNonJoinRelevantAssoc.definition
-        baseName = getFullName(firstNonJoinRelevantAssoc.definition)
-        columnAlias = column.as || column.ref.slice(0, -1).map(idOnly).join('_')
-      } else baseName = getFullName(column.$refLinks[column.$refLinks.length - 1].definition)
-
-      if(column.element && !isAssocOrStruct(column.element)) {
-        columnAlias = column.as || leafAssocIndex === -1 ? columnAlias : column.ref.slice(leafAssocIndex - 1).map(idOnly).join('_')
-        const res = { ref: [tableAlias, calculateElementName(column)], as: columnAlias }
-        setElementOnColumns(res, column.element)
-        return [res]
-      }
+    if (element.on && !element.keys) return [] // unmanaged doesn't make it into columns
+    if (element.virtual === true) return []
 
+    if (!isJoinRelevant && flatName) baseName = flatName
+    else if (isJoinRelevant) {
+      const earlyResult = resolveJoinRelevantNames()
+      if (earlyResult) return earlyResult
     } else if (!baseName && structsAreUnfoldedAlready) {
       baseName = element.name // name is already fully constructed
     } else {
@@ -1250,108 +1512,41 @@ function cqn4sql(originalQuery, model) {
       return getFlatColumnsFor(replacedBy, { baseName, columnAlias: replacedBy.as, tableAlias }, csnPath)
     }
 
-    csnPath.push(element.name)
+    csnPath = [...csnPath, element.name]
 
-    if (element.keys) {
-      const flatColumns = []
-      for (const k of element.keys) {
-        // if only one part of a foreign key is requested, only flatten the partial key
-        const keyElement = getElementForRef(k.ref, getDefinition(element.target))
-        const flattenThisForeignKey =
-          !$refLinks || // the association is passed as element, not as ref --> flatten full foreign key
-          element === $refLinks.at(-1).definition || // the association is the leaf of the ref --> flatten full foreign key
-          keyElement === stepAfterAssoc.definition // the foreign key is the leaf of the ref --> only flatten this specific foreign key
-        if (flattenThisForeignKey) {
-          const fkElement = getElementForRef(k.ref, getDefinition(element.target))
-          let fkBaseName
-          if (!firstNonJoinRelevantAssoc || firstNonJoinRelevantAssoc.onlyForeignKeyAccess) fkBaseName = `${baseName}_${k.as || k.ref.at(-1)}`
-          // e.g. if foreign key is accessed via infix filter - use join alias to access key in target
-          else fkBaseName = k.ref.at(-1)
-          const fkPath = [...csnPath, k.ref.at(-1)]
-          if (fkElement.elements) {
-            // structured key
-            for (const e of Object.values(fkElement.elements)) {
-              let alias
-              if (columnAlias) {
-                const fkName = k.as
-                  ? `${k.as}_${e.name}` // foreign key might also be re-named: `assoc { id as foo }`
-                  : `${k.ref.join('_')}_${e.name}`
-                alias = `${columnAlias}_${fkName}`
-              }
-              flatColumns.push(
-                ...getFlatColumnsFor(
-                  e,
-                  { baseName: fkBaseName, columnAlias: alias, tableAlias },
-                  [...fkPath],
-                  excludeAndReplace,
-                  isWildcard,
-                ),
-              )
-            }
-          } else if (fkElement.isAssociation) {
-            // assoc as key
-            flatColumns.push(
-              ...getFlatColumnsFor(
-                fkElement,
-                { baseName, columnAlias, tableAlias },
-                csnPath,
-                excludeAndReplace,
-                isWildcard,
-              ),
-            )
-          } else {
-            // leaf reached
-            let flatColumn
-            if (columnAlias) {
-              // if the column has an explicit alias AND the original ref
-              // directly resolves to the foreign key, we must not append the fk name to the column alias
-              // e.g. `assoc.fk as FOO` => columns.alias = FOO
-              //      `assoc as FOO`    => columns.alias = FOO_fk
-              let columnAliasWithFlatFk
-              if (!(column.as && fkElement === column.$refLinks?.at(-1).definition))
-                columnAliasWithFlatFk = `${columnAlias}_${k.as || k.ref.join('_')}`
-              flatColumn = { ref: [fkBaseName], as: columnAliasWithFlatFk || columnAlias }
-            } else flatColumn = { ref: [fkBaseName] }
-            if (tableAlias) flatColumn.ref.unshift(tableAlias)
-
-            // in a flat model, we must assign the foreign key rather than the key in the target
-            const flatForeignKey = getDefinition(element.parent.name)?.elements[fkBaseName]
-
-            setElementOnColumns(flatColumn, flatForeignKey || fkElement)
-            defineProperty(flatColumn, '_csnPath', csnPath)
-            flatColumns.push(flatColumn)
-          }
-        }
-      }
-      return flatColumns
-    } else if (element.elements && element.type !== 'cds.Map') {
+    if (element.keys) return flattenForeignKeys()
+    if (element.elements && element.type !== 'cds.Map') return flattenStructElements()
+    return buildScalarColumn()
+
+    function flattenStructElements() {
       const flatRefs = []
-      Object.values(element.elements).forEach(e => {
+      for (const e of Object.values(element.elements)) {
         const alias = columnAlias ? `${columnAlias}_${e.name}` : null
         flatRefs.push(
           ...getFlatColumnsFor(
             e,
             { baseName, columnAlias: alias, tableAlias },
-            [...csnPath],
+            csnPath,
             excludeAndReplace,
             isWildcard,
           ),
         )
-      })
+      }
       return flatRefs
     }
-    const flatRef = tableAlias ? { ref: [tableAlias, baseName] } : { ref: [baseName] }
-    if (column.cast) {
-      flatRef.cast = column.cast
-      if (!columnAlias)
-        // provide an explicit alias
-        columnAlias = baseName
+
+    function buildScalarColumn() {
+      const flatRef = tableAlias ? { ref: [tableAlias, baseName] } : { ref: [baseName] }
+      if (column.cast) {
+        flatRef.cast = column.cast
+        if (!columnAlias) columnAlias = baseName
+      }
+      if (column.sort) flatRef.sort = column.sort
+      if (columnAlias) flatRef.as = columnAlias
+      setElementOnColumns(flatRef, element)
+      defineProperty(flatRef, '_csnPath', csnPath)
+      return [flatRef]
     }
-    if (column.sort) flatRef.sort = column.sort
-    if (columnAlias) flatRef.as = columnAlias
-    setElementOnColumns(flatRef, element)
-    defineProperty(flatRef, '_csnPath', csnPath)
-    return [flatRef]
 
     function getReplacement(from) {
       return from?.find(replacement => {
@@ -1359,6 +1554,101 @@ function cqn4sql(originalQuery, model) {
         return nameOfExcludedColumn === element.name
       })
     }
+
+    function resolveJoinRelevantNames() {
+      const leafAssocIndex = column.$refLinks.findIndex(
+        link => link.definition.isAssociation && link.onlyForeignKeyAccess,
+      )
+      firstNonJoinRelevantAssoc =
+        column.$refLinks[leafAssocIndex] || [...column.$refLinks].reverse().find(link => link.definition.isAssociation)
+      stepAfterAssoc = column.$refLinks.at(leafAssocIndex + 1) || column.$refLinks.at(-1)
+      const targetElements = firstNonJoinRelevantAssoc.definition.elements || firstNonJoinRelevantAssoc.definition.foreignKeys
+      if (targetElements && stepAfterAssoc.definition.name in targetElements) {
+        element = firstNonJoinRelevantAssoc.definition
+        baseName = getFullName(firstNonJoinRelevantAssoc.definition)
+        columnAlias = column.as || column.ref.slice(0, -1).map(idOnly).join('_')
+      } else {
+        baseName = getFullName(column.$refLinks.at(-1).definition)
+      }
+
+      if (column.element && !isAssocOrStruct(column.element)) {
+        columnAlias =
+          column.as || (leafAssocIndex === -1 ? columnAlias : column.ref.slice(leafAssocIndex - 1).map(idOnly).join('_'))
+        const res = { ref: [tableAlias, calculateElementName(column)], as: columnAlias }
+        setElementOnColumns(res, column.element)
+        return [res]
+      }
+      return null
+    }
+
+    function flattenForeignKeys() {
+      const flatColumns = []
+      for (const k of element.keys) {
+        const fkElement = getElementForRef(k.ref, getDefinition(element.target))
+        // if only one part of a foreign key is requested, only flatten the partial key
+        const shouldFlatten =
+          !$refLinks || // the association is passed as element, not as ref --> flatten full foreign key
+          element === $refLinks.at(-1).definition || // the association is the leaf of the ref --> flatten full foreign key
+          fkElement === stepAfterAssoc.definition // the foreign key is the leaf of the ref --> only flatten this specific foreign key
+        if (!shouldFlatten) continue
+
+        // e.g. if foreign key is accessed via infix filter - use join alias to access key in target
+        const fkBaseName = !firstNonJoinRelevantAssoc || firstNonJoinRelevantAssoc.onlyForeignKeyAccess
+          ? `${baseName}_${k.as || k.ref.at(-1)}`
+          : k.ref.at(-1)
+        const fkPath = [...csnPath, k.ref.at(-1)]
+
+        if (fkElement.elements) {
+          // structured key
+          for (const e of Object.values(fkElement.elements)) {
+            let alias
+            if (columnAlias) {
+              const fkName = k.as
+                ? `${k.as}_${e.name}` // foreign key might also be re-named: `assoc { id as foo }`
+                : `${k.ref.join('_')}_${e.name}`
+              alias = `${columnAlias}_${fkName}`
+            }
+            flatColumns.push(
+              ...getFlatColumnsFor(
+                e,
+                { baseName: fkBaseName, columnAlias: alias, tableAlias },
+                fkPath,
+                excludeAndReplace,
+                isWildcard,
+              ),
+            )
+          }
+        } else if (fkElement.isAssociation) {
+          // assoc as key
+          flatColumns.push(
+            ...getFlatColumnsFor(fkElement, { baseName, columnAlias, tableAlias }, csnPath, excludeAndReplace, isWildcard),
+          )
+        } else {
+          // leaf reached
+          let flatColumn
+          if (columnAlias) {
+            // if the column has an explicit alias AND the original ref
+            // directly resolves to the foreign key, we must not append the fk name to the column alias
+            // e.g. `assoc.fk as FOO` => columns.alias = FOO
+            //      `assoc as FOO`    => columns.alias = FOO_fk
+            let fkAlias = columnAlias
+            if (!(column.as && fkElement === column.$refLinks?.at(-1).definition))
+              fkAlias = `${columnAlias}_${k.as || k.ref.join('_')}`
+            flatColumn = { ref: [fkBaseName], as: fkAlias }
+          } else {
+            flatColumn = { ref: [fkBaseName] }
+          }
+          if (tableAlias) flatColumn.ref.unshift(tableAlias)
+
+          // in a flat model, we must assign the foreign key rather than the key in the target
+          const flatForeignKey = getDefinition(element.parent.name)?.elements[fkBaseName]
+          setElementOnColumns(flatColumn, flatForeignKey || fkElement)
+          defineProperty(flatColumn, '_csnPath', csnPath)
+          flatColumns.push(flatColumn)
+        }
+      }
+      return flatColumns
+    }
   }
 
   /**
@@ -1446,6 +1736,9 @@ function cqn4sql(originalQuery, model) {
         transformedTokenStream[i + 1] = whereExists
         // skip newly created subquery from being iterated
         i += 1
+      } else if (token !== null && typeof token === 'object' && '#' in token) {
+        // Enum token: resolve to its value
+        transformedTokenStream.push(resolveEnumToken(token, tokenStream, i))
       } else if (token.list) {
         if (token.list.length === 0) {
           // replace `[not] in <empty list>` to harmonize behavior across dbs
@@ -1463,8 +1756,13 @@ function cqn4sql(originalQuery, model) {
             transformedTokenStream.push({ list: [] })
           }
         } else {
-          const { list } = token
-          if (list.every(e => e.val))
+          let { list } = token
+          // Resolve enum tokens in list items using context from the parent token stream
+          if (list.some(e => e !== null && typeof e === 'object' && '#' in e)) {
+            const enumDef = findEnumDefinition(tokenStream, i)
+            list = list.map(item => (item !== null && typeof item === 'object' && '#' in item) ? resolveEnumToken(item, tokenStream, i, enumDef) : item)
+          }
+          if (list.every(e => 'val' in e))
             // no need for transformation
             transformedTokenStream.push({ list })
           else transformedTokenStream.push({ list: getTransformedTokenStream(list, { $baseLink, prop: 'list' }) })
@@ -1496,14 +1794,13 @@ function cqn4sql(originalQuery, model) {
             ops.push(rhs)
             rhs = tokenStream[i + 3]
             indexRhs += 1
-            rhsDef = rhs?.$refLinks?.at(-1)?.definition
           }
 
           if (notSupportedOps.some(([firstOp]) => firstOp === next))
             throw new Error(`The operator "${next}" can only be used with scalar operands`)
 
           const newTokens = expandComparison(token, ops, rhs, $baseLink)
-          if(newTokens.length === 0)
+          if (newTokens.length === 0)
             throw new Error(`Can't compare two empty structures`)
 
           const needXpr = Boolean(tokenStream[i - 1] || tokenStream[indexRhs + 1])
@@ -1538,9 +1835,9 @@ function cqn4sql(originalQuery, model) {
             const lastAssoc =
               token.isJoinRelevant && [...token.$refLinks].reverse().find(l => l.definition.isAssociation)
             const tableAlias = getTableAlias(token, (!lastAssoc?.onlyForeignKeyAccess && lastAssoc) || $baseLink)
-            if(isAssocOrStruct(definition)) {
-              const flat =  getFlatColumnsFor(token, { tableAlias: $baseLink?.alias || tableAlias })
-              if(flat.length === 0)
+            if (isAssocOrStruct(definition)) {
+              const flat = getFlatColumnsFor(token, { tableAlias: $baseLink?.alias || tableAlias })
+              if (flat.length === 0)
                 throw new Error(`Structured element “${getFullName(definition)}” expands to nothing and can't be used in expressions`)
               else if (flat.length > 1 && context.prop !== 'list') // only acceptable in `list`
                 throw new Error(`Structured element “${getFullName(definition)}” expands to multiple fields and can't be used in expressions`)
@@ -1566,6 +1863,7 @@ function cqn4sql(originalQuery, model) {
             }
           }
 
+          if (result.cast) result.cast = resolveEnumCastType(result.cast)
           transformedTokenStream.push(result)
         }
       }
@@ -1673,7 +1971,7 @@ function cqn4sql(originalQuery, model) {
 
   function assertNoStructInXpr(token, context) {
     const definition = token.$refLinks?.at(-1).definition
-    if(!definition) return
+    if (!definition) return
     const rejectStructs = context && (context.prop in { where: 1, having: 1 })
     // unmanaged is always forbidden
     // expanding a ref in a `where`/`having` context
@@ -1785,7 +2083,7 @@ function cqn4sql(originalQuery, model) {
 
       // OData variant w/o mentioning key
       if (refReverse[0].where?.length === 1 && refReverse[0].where[0].val) {
-        filterConditions.push(getTransformedTokenStream(refReverse[0].where,{ $baseLink: $refLinksReverse[0] }))
+        filterConditions.push(getTransformedTokenStream(refReverse[0].where, { $baseLink: $refLinksReverse[0] }))
       }
 
       if (existingWhere.length > 0) filterConditions.push(existingWhere)
@@ -2231,7 +2529,7 @@ function cqn4sql(originalQuery, model) {
     return SELECT
   }
 
-/**
+  /**
    * For a given search term calculate a search expression which can be used in a where clause.
    * The search function is pushed to a subquery and the primary key(s) of the entity is/are used to match
    * the search results of the subquery.
@@ -2259,13 +2557,13 @@ function cqn4sql(originalQuery, model) {
     // for aggregated queries / search on subqueries we do not do a subquery search
     if (inferred.SELECT.groupBy || entity.SELECT)
       return searchFunc
-    
+
     const matchColumns = getPrimaryKey(entity)
     if (matchColumns.length === 0 || searchIn.every(r => r.ref.length === 1)) // keyless or not deep, fallback to old behavior
       return searchFunc
-    
-      const subquery = SELECT.from(entity).columns(...matchColumns).where(searchFunc)
-    return { xpr: [ matchColumns.length === 1 ? matchColumns[0] : {list: matchColumns}, 'in', subquery] }
+
+    const subquery = SELECT.from(entity).columns(...matchColumns).where(searchFunc)
+    return { xpr: [matchColumns.length === 1 ? matchColumns[0] : { list: matchColumns }, 'in', subquery] }
   }
 
   /**
@@ -2282,7 +2580,7 @@ function cqn4sql(originalQuery, model) {
     if (!node || !node.$refLinks || !node.ref) {
       throw new Error('Invalid node')
     }
-    if(node.$refLinks[0].$main) {
+    if (node.$refLinks[0].$main) {
       if (node.isJoinRelevant) {
         return getJoinRelevantAlias(node)
       }
@@ -2354,6 +2652,116 @@ function cqn4sql(originalQuery, model) {
     }
     return result
   }
+
+  /**
+   * Resolves an enum token to a value literal.
+   *
+   * If the token already has a `val`, it is used directly.
+   * Otherwise, the enum value is resolved by looking up the symbol
+   * in the enum definition found from the surrounding context.
+   *
+   * @param {object} token - The enum token with a `#` property.
+   * @param {object[]} tokenStream - The surrounding token stream for context discovery.
+   * @param {number} index - The index of the enum token in the token stream.
+   * @param {object} [enumDef] - An already-discovered enum definition (optimization for lists).
+   * @returns {object} A value token `{ val: resolvedValue }`.
+   */
+  function resolveEnumToken(token, tokenStream, index, enumDef) {
+    if ('val' in token) {
+      const result = { val: token.val }
+      if (token.cast) result.cast = resolveEnumCastType(token.cast)
+      return result
+    }
+
+    // Check if the token itself has a cast with an enum type
+    if (!enumDef && token.cast?.type) {
+      const typeDef = model.definitions[token.cast.type]
+      if (typeDef?.enum) enumDef = typeDef.enum
+    }
+
+    if (!enumDef) enumDef = findEnumDefinition(tokenStream, index)
+    if (!enumDef) {
+      throw new Error(`Can't resolve enum value "#${token['#']}"`)
+    }
+
+    const entry = enumDef[token['#']]
+    if (!entry) {
+      throw new Error(`Unknown enum symbol "#${token['#']}"`)
+    }
+
+    const result = { val: 'val' in entry ? entry.val : token['#'] }
+    if (token.cast) result.cast = resolveEnumCastType(token.cast)
+    return result
+  }
+
+  /**
+   * If `cast.type` refers to a user-defined enum type, resolves it to the
+   * underlying scalar CDS built-in type so that the SQL builder (`cqn2sql`)
+   * can render a valid SQL type name.
+   *
+   * Example: `{ type: 'enums.Priority' }` → `{ type: 'cds.Integer' }`
+   *
+   * Non-enum types (including CDS built-ins) are returned unchanged.
+   *
+   * @param {object} cast - The cast descriptor with a `type` property.
+   * @returns {object} The cast descriptor with the resolved type.
+   */
+  function resolveEnumCastType(cast) {
+    if (!cast?.type) return cast
+    let def = model.definitions[cast.type]
+    while (def?.enum) {
+      const baseType = def.type
+      if (!baseType) return cast // no base type declared – leave as-is
+      if (cds.builtin.types[baseType]) return { ...cast, type: baseType }
+      def = model.definitions[baseType]
+    }
+    return cast
+  }
+
+  /**
+   * Scans the token stream around the given index to find an element
+   * definition that has an `enum` property, which can be used to resolve
+   * enum symbols to their values.
+   *
+   * @param {object[]} tokenStream - The token stream to scan.
+   * @param {number} index - The index of the enum token.
+   * @returns {object|null} The enum definition object, or null if not found.
+   */
+  function findEnumDefinition(tokenStream, index) {
+    // Scan backward
+    for (let j = index - 1; j >= 0; j--) {
+      const t = tokenStream[j]
+      if (typeof t === 'string') continue   // operators, keywords
+      if (t !== null && typeof t === 'object' && '#' in t) continue  // other enum tokens
+      if ('val' in t && !t.ref) continue    // plain value literals
+
+      const def = t.$refLinks?.at(-1)?.definition
+      if (def?.enum) return def.enum
+      if (t.cast?.type) {
+        const typeDef = model.definitions[t.cast.type]
+        if (typeDef?.enum) return typeDef.enum
+      }
+      if (def) break  // found a ref without enum type, stop
+    }
+
+    // Scan forward
+    for (let j = index + 1; j < tokenStream.length; j++) {
+      const t = tokenStream[j]
+      if (typeof t === 'string') continue
+      if (t !== null && typeof t === 'object' && '#' in t) continue
+      if ('val' in t && !t.ref) continue
+
+      const def = t.$refLinks?.at(-1)?.definition
+      if (def?.enum) return def.enum
+      if (t.cast?.type) {
+        const typeDef = model.definitions[t.cast.type]
+        if (typeDef?.enum) return typeDef.enum
+      }
+      if (def) break
+    }
+
+    return null
+  }
 }
 
 function calculateElementName(token) {
@@ -2425,7 +2833,7 @@ function assignQueryModifiers(SELECT, modifiers) {
       else SELECT.having.push('and', ...val)
     } else if (key === 'where') {
       // ignore OData shortcut variant: `… bookshop.Orders:items[2]`
-      if(!val || val.length === 1 && val[0].val) continue
+      if (!val || val.length === 1 && val[0].val) continue
       if (!SELECT.where) SELECT.where = val
       // infix filter comes first in resulting where
       else SELECT.where = [...(hasLogicalOr(val) ? [asXpr(val)] : val), 'and', ...(hasLogicalOr(SELECT.where) ? [asXpr(SELECT.where)] : SELECT.where)]