@cap-js/db-service 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [1.20.0](https://github.com/cap-js/cds-dbs/compare/db-service-v1.19.1...db-service-v1.20.0) (2025-04-17)
+
+
+### Added
+
+* Result set streaming ([#702](https://github.com/cap-js/cds-dbs/issues/702)) ([2fe02ea](https://github.com/cap-js/cds-dbs/commit/2fe02eafd02993e5697efbdab90ad997fb2c9e00))
+
+
+### Fixed
+
+* **`expand`:** proper subquery `from` construction ([#1126](https://github.com/cap-js/cds-dbs/issues/1126)) ([e343e79](https://github.com/cap-js/cds-dbs/commit/e343e7978acc0c181a012f61b6181b7c558aa178)), closes [#1114](https://github.com/cap-js/cds-dbs/issues/1114) [#1112](https://github.com/cap-js/cds-dbs/issues/1112)
+* Improved support for special characters in column names ([#1141](https://github.com/cap-js/cds-dbs/issues/1141)) ([ba04697](https://github.com/cap-js/cds-dbs/commit/ba046971921d645e8571a80c27ef07988c8c01ad))
+* **infer:** for localized queries, use `localized.<entity>` as `_target` ([#1140](https://github.com/cap-js/cds-dbs/issues/1140)) ([b08707b](https://github.com/cap-js/cds-dbs/commit/b08707b76a53c74f1c4388a8be4d0818506388c5))
+
+## [1.19.1](https://github.com/cap-js/cds-dbs/compare/db-service-v1.19.0...db-service-v1.19.1) (2025-04-01)
+
+
+### Fixed
+
+* **scoped queries:** wrap filter in `xpr` if needed ([#1105](https://github.com/cap-js/cds-dbs/issues/1105)) ([8f44df3](https://github.com/cap-js/cds-dbs/commit/8f44df37db7bc283933023dab92b348cf92e12bf))
+
 ## [1.19.0](https://github.com/cap-js/cds-dbs/compare/db-service-v1.18.0...db-service-v1.19.0) (2025-03-31)
 
 

package/lib/SQLService.js

@@ -1,6 +1,7 @@
 const cds = require('@sap/cds'),
   DEBUG = cds.debug('sql|db')
-const { Readable } = require('stream')
+const { Readable, Transform } = require('stream')
+const { pipeline } = require('stream/promises')
 const { resolveView, getDBTable, getTransition } = require('@sap/cds/libx/_runtime/common/utils/resolveView')
 const DatabaseService = require('./common/DatabaseService')
 const cqn4sql = require('./cqn4sql')
@@ -117,7 +118,7 @@ class SQLService extends DatabaseService {
    * Handler for SELECT
    * @type {Handler}
    */
-  async onSELECT({ query, data }) {
+  async onSELECT({ query, data, iterator, objectMode }) {
     // REVISIT: for custom joins, infer is called twice, which is bad
     //          --> make cds.infer properly work with custom joins and remove this
     if (!(query._target instanceof cds.entity)) {
@@ -131,35 +132,56 @@ class SQLService extends DatabaseService {
     const { sql, values, cqn } = this.cqn2sql(query, data)
     const expand = query.SELECT.expand
     delete query.SELECT.expand
+    const isOne = cqn.SELECT.one || query.SELECT.from?.ref?.[0].cardinality?.max === 1
 
     let ps = await this.prepare(sql)
-    let rows = await ps.all(values)
-    if (rows.length)
-      if (expand) rows = rows.map(r => (typeof r._json_ === 'string' ? JSON.parse(r._json_) : r._json_ || r))
-
-    if (cds.env.features.stream_compat) {
-      if (query._streaming) {
-        this._changeToStreams(cqn.SELECT.columns, rows, true, true)
-        if (!rows.length) return
-
-        const result = rows[0]
-        // stream is always on position 0. Further properties like etag are inserted later.
-        let [key, val] = Object.entries(result)[0]
-        result.value = val
-        delete result[key]
-
-        return result
+    let rows = iterator ? await ps.stream(values, isOne, objectMode) : await ps.all(values)
+    try {
+      if (rows.length)
+        if (expand) rows = rows.map(r => (typeof r._json_ === 'string' ? JSON.parse(r._json_) : r._json_ || r))
+
+      if (!iterator) {
+        // REVISIT: remove after removing stream_compat feature flag
+        if (cds.env.features.stream_compat) {
+          if (query._streaming) {
+            if (!rows.length) return
+            this._changeToStreams(cqn.SELECT.columns, rows, true, true)
+            const result = rows[0]
+
+            // stream is always on position 0. Further properties like etag are inserted later.
+            let [key, val] = Object.entries(result)[0]
+            result.value = val
+            delete result[key]
+
+            return result
+          }
+        } else {
+          this._changeToStreams(cqn.SELECT.columns, rows, query.SELECT.one, false)
+        }
+      } else if (objectMode) {
+        const converter = (row) => this._changeToStreams(cqn.SELECT.columns, row, true)
+        const changeToStreams = new Transform({
+          objectMode: true,
+          transform(row, enc, cb) {
+            converter(row)
+            cb(null, row)
+          }
+        })
+        pipeline(rows, changeToStreams)
+        rows = changeToStreams
       }
-    } else {
-      this._changeToStreams(cqn.SELECT.columns, rows, query.SELECT.one, false)
-    }
 
-    if (cqn.SELECT.count) {
-      // REVISIT: the runtime always expects that the count is preserved with .map, required for renaming in mocks
-      return SQLService._arrayWithCount(rows, await this.count(query, rows))
-    }
+      if (cqn.SELECT.count) {
+        // REVISIT: the runtime always expects that the count is preserved with .map, required for renaming in mocks
+        return SQLService._arrayWithCount(rows, await this.count(query, rows))
+      }
 
-    return cqn.SELECT.one || query.SELECT.from?.ref?.[0].cardinality?.max === 1 ? rows[0] : rows
+      return iterator !== false && isOne ? rows[0] : rows
+    } catch (err) {
+      // Ensure that iterators receive pre stream errors
+      if (iterator) rows.emit('error', err)
+      throw err
+    }
   }
 
   /**
@@ -314,7 +336,7 @@ class SQLService extends DatabaseService {
    * @returns {Promise<number>}
    */
   async count(query, ret) {
-    if (ret) {
+    if (ret?.length) {
       const { one, limit: _ } = query.SELECT,
         n = ret.length
       const [max, offset = 0] = one ? [1] : _ ? [_.rows?.val, _.offset?.val] : []
@@ -355,6 +377,7 @@ class SQLService extends DatabaseService {
   // preserves $count for .map calls on array
   static _arrayWithCount = function (a, count) {
     const _map = a.map
+
     const map = function (..._) {
       return SQLService._arrayWithCount(_map.call(a, ..._), count)
     }
@@ -475,7 +498,6 @@ SQLService.prototype.PreparedStatement = PreparedStatement
 const _target_name4 = q => {
   const target =
     q._target_ref ||
-    q.from_into_ntt ||
     q.SELECT?.from ||
     q.INSERT?.into ||
     q.UPSERT?.into ||

package/lib/cqn2sql.js

@@ -119,7 +119,7 @@ class CQN2SQLRenderer {
    * @param {import('./infer/cqn').CREATE} q
    */
   CREATE(q) {
-    let { target } = q
+    let { _target: target } = q
     let query = target?.query || q.CREATE.as
     if (!target || target._unresolved) {
       const entity = q.CREATE.entity
@@ -213,7 +213,7 @@ class CQN2SQLRenderer {
    * @param {import('./infer/cqn').DROP} q
    */
   DROP(q) {
-    const { target } = q
+    const { _target: target } = q
     const isView = target?.query || target?.projection || q.DROP.view
     const name = target?.name || q.DROP.table?.ref?.[0] || q.DROP.view?.ref?.[0]
     return (this.sql = `DROP ${isView ? 'VIEW' : 'TABLE'} IF EXISTS ${this.quote(this.name(name, q))}`)
@@ -307,8 +307,7 @@ class CQN2SQLRenderer {
       }
       : x => {
         const name = this.column_name(x)
-        const escaped = `${name.replace(/"/g, '""')}`
-        return `'$."${escaped}"',${this.output_converter4(x.element, this.quote(name))}`
+        return `${this.string(`$.${JSON.stringify(name)}`)},${this.output_converter4(x.element, this.quote(name))}`
       }).flat()
 
     if (isSimple) return `SELECT ${cols} FROM (${sql})`
@@ -429,8 +428,8 @@ class CQN2SQLRenderer {
     return orderBy.map(c => {
       const o = localized
         ? this.expr(c) +
-          (c.element?.[this.class._localized] ? ' COLLATE NOCASE' : '') +
-          (c.sort?.toLowerCase() === 'desc' || c.sort === -1 ? ' DESC' : ' ASC')
+        (c.element?.[this.class._localized] ? ' COLLATE NOCASE' : '') +
+        (c.sort?.toLowerCase() === 'desc' || c.sort === -1 ? ' DESC' : ' ASC')
         : this.expr(c) + (c.sort?.toLowerCase() === 'desc' || c.sort === -1 ? ' DESC' : ' ASC')
       if (c.nulls) return o + ' NULLS ' + (c.nulls.toLowerCase() === 'first' ? 'FIRST' : 'LAST')
       return o
@@ -524,13 +523,14 @@ class CQN2SQLRenderer {
     // Include this.values for placeholders
     /** @type {unknown[][]} */
     this.entries = []
-    if (INSERT.entries[0] instanceof Readable) {
+    if (INSERT.entries[0] instanceof Readable && !INSERT.entries[0].readableObjectMode) {
       INSERT.entries[0].type = 'json'
       this.entries = [[...this.values, INSERT.entries[0]]]
     } else {
-      const stream = Readable.from(this.INSERT_entries_stream(INSERT.entries), { objectMode: false })
+      const entries = INSERT.entries[0]?.[Symbol.iterator] || INSERT.entries[0]?.[Symbol.asyncIterator] || INSERT.entries[0] instanceof Readable ? INSERT.entries[0] : INSERT.entries
+      const stream = Readable.from(this.INSERT_entries_stream(entries), { objectMode: false })
       stream.type = 'json'
-      stream._raw = INSERT.entries
+      stream._raw = entries
       this.entries = [[...this.values, stream]]
     }
 
@@ -545,7 +545,7 @@ class CQN2SQLRenderer {
     let buffer = '['
 
     let sep = ''
-    for (const row of entries) {
+    for await (const row of entries) {
       buffer += `${sep}{`
       if (!sep) sep = ','
 
@@ -619,7 +619,7 @@ class CQN2SQLRenderer {
           if (val != null && elements[this.columns[key]]?.type in this.BINARY_TYPES) {
             val = Buffer.from(val, 'base64').toString(binaryEncoding)
           }
-          buffer += `${sepsub}${val === undefined ? 'null' : JSON.stringify(val)}`
+          buffer += `${sepsub}${val == null ? 'null' : JSON.stringify(val)}`
         }
 
         if (!sepsub) sepsub = ','
@@ -1143,8 +1143,8 @@ class CQN2SQLRenderer {
   managed_extract(name, element, converter) {
     const { UPSERT, INSERT } = this.cqn
     const extract = !(INSERT?.entries || UPSERT?.entries) && (INSERT?.rows || UPSERT?.rows)
-      ? `value->>'$[${this.columns.indexOf(name)}]'`
-      : `value->>'$."${name.replace(/"/g, '""')}"'`
+      ? `value->>${this.string(`$[${this.columns.indexOf(name)}]`)}`
+      : `value->>${this.string(`$.${JSON.stringify(name)}`)}`
     const sql = converter?.(extract) || extract
     return { extract, sql }
   }

package/lib/cqn4sql.js

@@ -5,7 +5,7 @@ cds.infer.target ??= q => q._target || q.target // instanceof cds.entity ? q._ta
 
 const infer = require('./infer')
 const { computeColumnsToBeSearched } = require('./search')
-const { prettyPrintRef, isCalculatedOnRead, isCalculatedElement, getImplicitAlias } = require('./utils')
+const { prettyPrintRef, isCalculatedOnRead, isCalculatedElement, getImplicitAlias, getModelUtils } = require('./utils')
 
 /**
  * For operators of <eqOps>, this is replaced by comparing all leaf elements with null, combined with and.
@@ -78,6 +78,7 @@ function cqn4sql(originalQuery, model) {
     }
   }
   inferred = infer(inferred, model)
+  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
   //       we need to infer the query even if no transformation will happen because cds.infer can't calculate the target
@@ -225,7 +226,7 @@ function cqn4sql(originalQuery, model) {
    */
   function transformQueryForInsertUpsert(kind) {
     const { as } = transformedQuery[kind].into
-    const target = cds.infer.target (inferred) // REVISIT: we should reliably use inferred._target instead
+    const target = cds.infer.target(inferred) // REVISIT: we should reliably use inferred._target instead
     transformedQuery[kind].into = { ref: [target.name] }
     if (as) transformedQuery[kind].into.as = as
     return transformedQuery
@@ -281,7 +282,7 @@ function cqn4sql(originalQuery, model) {
       const args = []
       if (r.queryArtifact.SELECT) args.push({ SELECT: transformSubquery(r.queryArtifact).SELECT, as: r.alias })
       else {
-        const id = localized(r.queryArtifact)
+        const id = getLocalizedName(r.queryArtifact)
         args.push({ ref: [r.args ? { id, args: r.args } : id], as: r.alias })
       }
       from = { join: r.join || 'left', args, on: [] }
@@ -308,7 +309,7 @@ function cqn4sql(originalQuery, model) {
         ),
       )
 
-      const id = localized(getDefinition(nextAssoc.$refLink.definition.target))
+      const id = getDefinition(nextAssoc.$refLink.definition.target).name
       const { args } = nextAssoc
       const arg = {
         ref: [args ? { id, args } : id],
@@ -801,8 +802,9 @@ function cqn4sql(originalQuery, model) {
         })
     } else {
       outerAlias = transformedQuery.SELECT.from.as
+      const getInnermostTarget = q => (q._target ? getInnermostTarget(q._target) : q)
       subqueryFromRef = [
-        ...(transformedQuery.SELECT.from.ref || /* subq in from */ transformedQuery.SELECT.from.SELECT.from.ref),
+        ...(transformedQuery.SELECT.from.ref || /* subq in from */ [getInnermostTarget(transformedQuery).name]),
         ...ref,
       ]
     }
@@ -1070,7 +1072,7 @@ function cqn4sql(originalQuery, model) {
       outerQueries.push(inferred)
       Object.defineProperty(q, 'outerQueries', { value: outerQueries })
     }
-    const target = cds.infer.target (inferred) // REVISIT: we should reliably use inferred._target instead
+    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)
@@ -1739,7 +1741,7 @@ function cqn4sql(originalQuery, model) {
            * with the main query alias. see @function expandColumn()
            * There is one exception:
            * - if current and next have the same alias, we need to assign a new alias to the next
-           *                          
+           *
            */
           if (!(inferred.SELECT?.expand === true && current.alias.toLowerCase() !== as.toLowerCase())) {
             as = getNextAvailableTableAlias(as)
@@ -1766,7 +1768,7 @@ function cqn4sql(originalQuery, model) {
         filterConditions.forEach(f => {
           transformedWhere.push('and')
           if (filterConditions.length > 1) transformedWhere.push(asXpr(f))
-          else if (f.length > 3) transformedWhere.push(asXpr(f))
+          else if (f.length > 3 || f.includes('or') || f.includes('and')) transformedWhere.push(asXpr(f))
           else transformedWhere.push(...f)
         })
       } else {
@@ -1786,7 +1788,7 @@ function cqn4sql(originalQuery, model) {
       const subquerySource =
         getDefinition(transformedFrom.$refLinks[0].definition.target) || transformedFrom.$refLinks[0].target
       if (subquerySource.params && !args) args = {}
-      const id = localized(subquerySource)
+      const id = getLocalizedName(subquerySource)
       transformedFrom.ref = [args ? { id, args } : id]
 
       return { transformedWhere, transformedFrom }
@@ -1994,9 +1996,7 @@ function cqn4sql(originalQuery, model) {
             }
             // assumption: if first step is the association itself, all following ref steps must be resolvable
             // within target `assoc.assoc.fk` -> `assoc.assoc_fk`
-            else if (
-              lhsFirstDef === getParentEntity(assocRefLink.definition).elements[assocRefLink.definition.name]
-            )
+            else if (lhsFirstDef === getParentEntity(assocRefLink.definition).elements[assocRefLink.definition.name])
               result[i].ref = [assocRefLink.alias, lhs.ref.slice(lhs.ref[0] === '$self' ? 2 : 1).join('_')]
             // naive assumption: if the path starts with an association which is not the association from
             // which the on-condition originates, it must be a foreign key and hence resolvable in the source
@@ -2077,7 +2077,7 @@ function cqn4sql(originalQuery, model) {
         // pseudo element
         return element
       if (element.kind === 'entity') return element
-      else return getDefinition(localized(getParentEntity(element.parent)))
+      else return getDefinition(getParentEntity(element.parent).name)
     }
   }
 
@@ -2164,8 +2164,8 @@ function cqn4sql(originalQuery, model) {
       on.push(...(customWhere && hasLogicalOr(unmanagedOn) ? [asXpr(unmanagedOn)] : unmanagedOn))
     }
 
-    const subquerySource = assocTarget(nextDefinition) || nextDefinition
-    const id = localized(subquerySource)
+    const subquerySource = getDefinition(nextDefinition.target) || nextDefinition
+    const id = getLocalizedName(subquerySource)
     if (subquerySource.params && !customArgs) customArgs = {}
     const SELECT = {
       from: {
@@ -2203,52 +2203,6 @@ function cqn4sql(originalQuery, model) {
     return SELECT
   }
 
-  /**
-   * If the query is `localized`, return the name of the `localized` entity for the `definition`.
-   * If there is no `localized` entity for the `definition`, return the name of the `definition`
-   *
-   * @param {CSN.definition} definition
-   * @returns the name of the localized entity for the given `definition` or `definition.name`
-   */
-  function localized(definition) {
-    if (!isLocalized(definition)) return definition.name
-    const view = getDefinition(`localized.${definition.name}`)
-    return view?.name || definition.name
-  }
-
-  /**
-   * If a given query is required to be translated, the query has
-   * the `.localized` property set to `true`. If that is the case,
-   * and the definition has not set the `@cds.localized` annotation
-   * to `false`, the given definition must be translated.
-   *
-   * @returns true if the given definition shall be localized
-   */
-  function isLocalized(definition) {
-    return (
-      inferred.SELECT?.localized &&
-      definition['@cds.localized'] !== false &&
-      !inferred.SELECT.forUpdate &&
-      !inferred.SELECT.forShareLock
-    )
-  }
-
-  /** returns the CSN definition for the given name from the model */
-  function getDefinition(name) {
-    if (!name) return null
-    return model.definitions[name]
-  }
-
-  /**
-   * Get the csn definition of the target of a given association
-   *
-   * @param assoc
-   * @returns the csn definition of the association target or null if it is not an association
-   */
-  function assocTarget(assoc) {
-    return getDefinition(assoc.target) || null
-  }
-
   /**
    * For a given search expression return a function "search" which holds the search expression
    * as well as the searchable columns as arguments.

package/lib/infer/index.js

@@ -4,7 +4,7 @@ const cds = require('@sap/cds')
 
 const JoinTree = require('./join-tree')
 const { pseudos } = require('./pseudos')
-const { isCalculatedOnRead, getImplicitAlias } = require('../utils')
+const { isCalculatedOnRead, getImplicitAlias, getModelUtils } = require('../utils')
 const cdsTypes = cds.linked({
   definitions: {
     Timestamp: { type: 'cds.Timestamp' },
@@ -27,6 +27,8 @@ function infer(originalQuery, model) {
   if (!model) throw new Error('Please specify a model')
   const inferred = originalQuery
 
+  const { getDefinition } = getModelUtils(model, originalQuery)
+
   // REVISIT: The more edge use cases we support, thes less optimized are we for the 90+% use cases
   // e.g. there's a lot of overhead for infer( SELECT.from(Books) )
   if (originalQuery.SET) throw new Error('”UNION” based queries are not supported')
@@ -111,13 +113,13 @@ function infer(originalQuery, model) {
 
       inferArg(from, null, null, { inFrom: true })
       const alias =
-      from.uniqueSubqueryAlias ||
-      from.as ||
-      (ref.length === 1
-        ? getImplicitAlias(first, useTechnicalAlias)
-        : getImplicitAlias(ref.at(-1).id || ref.at(-1), useTechnicalAlias));    
+        from.uniqueSubqueryAlias ||
+        from.as ||
+        (ref.length === 1
+          ? getImplicitAlias(first, useTechnicalAlias)
+          : getImplicitAlias(ref.at(-1).id || ref.at(-1), useTechnicalAlias))
       if (alias in querySources) throw new Error(`Duplicate alias "${alias}"`)
-      querySources[alias] = { definition: target, args }
+      querySources[alias] = { definition: getDefinition(target.name), args }
       const last = from.$refLinks.at(-1)
       last.alias = alias
     } else if (from.args) {
@@ -209,7 +211,7 @@ function infer(originalQuery, model) {
           if (col.func) {
             if (col.args) {
               // {func}.args are optional
-              applyToFunctionArgs(col.args, inferArg, [false, null, {dollarSelfRefs}])
+              applyToFunctionArgs(col.args, inferArg, [false, null, { dollarSelfRefs }])
             }
             queryElements[as] = getElementForCast(col)
           }
@@ -350,7 +352,7 @@ function infer(originalQuery, model) {
     }
 
     function handleRef(col, inXpr) {
-      inferArg(col, queryElements, null,  { inXpr })
+      inferArg(col, queryElements, null, { inXpr })
       const { definition } = col.$refLinks[col.$refLinks.length - 1]
       if (col.cast)
         // final type overwritten -> element not visible anymore
@@ -399,7 +401,8 @@ function infer(originalQuery, model) {
    */
 
   function inferArg(arg, queryElements = null, $baseLink = null, context = {}) {
-    const { inExists, inXpr, inCalcElement, baseColumn, inInfixFilter, inQueryModifier, inFrom, dollarSelfRefs } = context
+    const { inExists, inXpr, inCalcElement, baseColumn, inInfixFilter, inQueryModifier, inFrom, dollarSelfRefs } =
+      context
     if (arg.param || arg.SELECT) return // parameter references are only resolved into values on execution e.g. :val, :1 or ?
     if (arg.args) applyToFunctionArgs(arg.args, inferArg, [null, $baseLink, context])
     if (arg.list) arg.list.forEach(arg => inferArg(arg, null, $baseLink, context))
@@ -424,7 +427,7 @@ function infer(originalQuery, model) {
       firstStepIsSelf = !firstStepIsTableAlias && arg.ref.length > 1 && ['$self', '$projection'].includes(arg.ref[0])
       expandOnTableAlias = arg.ref.length === 1 && arg.ref[0] in sources && (arg.expand || arg.inline)
     }
-    if(dollarSelfRefs && firstStepIsSelf) {
+    if (dollarSelfRefs && firstStepIsSelf) {
       Object.defineProperty(arg, 'inXpr', { value: true, writable: true })
       dollarSelfRefs.push(arg)
       return
@@ -810,7 +813,8 @@ function infer(originalQuery, model) {
     else alreadySeenCalcElements.add(calcElement)
     const { ref, xpr } = calcElement.value
     if (ref || xpr) {
-      baseLink = { definition: calcElement.parent, target: calcElement.parent }
+      const parentElementDefinition = getDefinition(calcElement.parent.name)
+      baseLink = { definition: parentElementDefinition, target: parentElementDefinition }
       inferArg(calcElement.value, null, baseLink, { inCalcElement: true, ...context })
       const basePath =
         column.$refLinks?.length > 1
@@ -825,7 +829,13 @@ function infer(originalQuery, model) {
 
     if (calcElement.value.args) {
       const processArgument = (arg, calcElement, column) => {
-        inferArg(arg, null, { definition: calcElement.parent, target: calcElement.parent }, { inCalcElement: true })
+        const parentElementDefinition = getDefinition(calcElement.parent.name)
+        inferArg(
+          arg,
+          null,
+          { definition: parentElementDefinition, target: parentElementDefinition },
+          { inCalcElement: true },
+        )
         const basePath =
           column.$refLinks?.length > 1
             ? { $refLinks: column.$refLinks.slice(0, -1), ref: column.ref.slice(0, -1) }
@@ -879,8 +889,7 @@ function infer(originalQuery, model) {
             step[nestedProp].forEach(a => {
               // reset sub path for each nested argument
               // e.g. case when <path> then <otherPath> else <anotherPath> end
-              if(!a.ref)
-                subPath = { $refLinks: [...basePath.$refLinks], ref: [...basePath.ref] }
+              if (!a.ref) subPath = { $refLinks: [...basePath.$refLinks], ref: [...basePath.ref] }
               mergePathsIntoJoinTree(a, subPath)
             })
           }
@@ -891,7 +900,7 @@ function infer(originalQuery, model) {
         const calcElementIsJoinRelevant = isColumnJoinRelevant(p)
         if (calcElementIsJoinRelevant) {
           if (!calcElement.value.isJoinRelevant)
-            Object.defineProperty(step, 'isJoinRelevant', { value: true, writable: true,  })
+            Object.defineProperty(step, 'isJoinRelevant', { value: true, writable: true })
           joinTree.mergeColumn(p, originalQuery.outerQueries)
         } else {
           // we need to explicitly set the value to false in this case,
@@ -960,7 +969,7 @@ function infer(originalQuery, model) {
     if (Object.keys(queryElements).length === 0 && aliases.length === 1) {
       const { elements } = getDefinitionFromSources(sources, aliases[0])
       // only one query source and no overwritten columns
-      for (const k of Object.keys(elements)) {
+      for (const k in elements) {
         if (!exclude(k)) {
           const element = elements[k]
           if (element.type !== 'cds.LargeBinary') {
@@ -1083,12 +1092,6 @@ function infer(originalQuery, model) {
     }
   }
 
-  /** returns the CSN definition for the given name from the model */
-  function getDefinition(name) {
-    if (!name) return null
-    return model.definitions[name]
-  }
-
   function getDefinitionFromSources(sources, id) {
     return sources[id].definition
   }

package/lib/infer/join-tree.js

@@ -170,7 +170,7 @@ class JoinTree {
         // find the correct query source
         if (
           r.queryArtifact === head.target ||
-          r.queryArtifact === head.target.target /** might as well be a query for order by */
+          r.queryArtifact === head.target._target /** might as well be a query for order by */
         )
           node = r
       })

package/lib/utils.js

@@ -40,32 +40,94 @@ function isCalculatedElement(def) {
 
 /**
  * Calculates the implicit table alias for a given string.
- * 
+ *
  * Based on the last part of the string, the implicit alias is calculated
  * by taking the first character and prepending it with '$'.
  * A leading '$' is removed if the last part already starts with '$'.
- * 
+ *
  * @example
  * getImplicitAlias('Books') => '$B'
  * getImplicitAlias('bookshop.Books') => '$B'
  * getImplicitAlias('bookshop.$B') => '$B'
- * 
+ *
  * @param {string} str - The input string.
- * @returns {string} 
+ * @returns {string}
  */
 function getImplicitAlias(str, useTechnicalAlias = true) {
   const index = str.lastIndexOf('.')
-  if(useTechnicalAlias) {
+  if (useTechnicalAlias) {
     const postfix = (index != -1 ? str.substring(index + 1) : str).replace(/^\$/, '')[0] || /* str === '$' */ '$'
     return '$' + postfix
   }
   return index != -1 ? str.substring(index + 1) : str
 }
 
+/**
+ * Shared utility functions which operate dynamically on the model / query.
+ *
+ * @param {CSN.model} model
+ * @param {CQL} query
+ */
+function getModelUtils(model, query) {
+  /**
+   * Returns the name of the localized entity for the given `definition`.
+   * 
+   * If the query is `localized`, returns the name of the `localized` version of the `definition`.
+   * If there is no `localized` version of the `definition`, return the name of the `definition`
+   *
+   * @param {CSN.definition} definition
+   * @returns the name of the localized entity for the given `definition` or `definition.name`
+   */
+  function getLocalizedName(definition) {
+    if (!isLocalized(definition)) return definition.name
+    const view = getDefinition(`localized.${definition.name}`)
+    return view?.name || definition.name
+  }
+
+  /**
+   * Returns true if the definition shall be localized, in the context of the given query.
+   * 
+   * If a given query is required to be translated, the query has
+   * the `.localized` property set to `true`. If that is the case,
+   * and the definition has not set the `@cds.localized` annotation
+   * to `false`, the given definition must be translated.
+   *
+   * @returns true if the given definition shall be localized
+   */
+  function isLocalized(definition) {
+    return (
+      query.SELECT?.localized &&
+      definition?.['@cds.localized'] !== false &&
+      !query.SELECT.forUpdate &&
+      !query.SELECT.forShareLock
+    )
+  }
+
+  /**
+   * Returns the (potentially localized) CSN definition for the given name from the model.
+   *
+   * @param {string} name - The name of the definition to retrieve.
+   * @returns {Object|null} The CSN definition or null if not found. The definition may be localized.
+   */
+  function getDefinition(name) {
+    if (!name) return null
+    const def = model.definitions[name]
+    if (!def || !isLocalized(def)) return def
+    return model.definitions[`localized.${def.name}`] || def
+  }
+
+  return {
+    getLocalizedName,
+    isLocalized,
+    getDefinition,
+  }
+}
+
 // export the function to be used in other modules
 module.exports = {
   prettyPrintRef,
   isCalculatedOnRead,
   isCalculatedElement,
   getImplicitAlias,
+  getModelUtils,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/db-service",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "CDS base database service",
   "homepage": "https://github.com/cap-js/cds-dbs/tree/main/db-service#cds-base-database-service",
   "repository": {