@cap-js/db-service 1.19.1 → 1.20.1

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [1.20.1](https://github.com/cap-js/cds-dbs/compare/db-service-v1.20.0...db-service-v1.20.1) (2025-05-27)
+
+
+### Fixed
+
+* **`search`:** do not search on non-projected elements ([#1198](https://github.com/cap-js/cds-dbs/issues/1198)) ([1461673](https://github.com/cap-js/cds-dbs/commit/14616730ba8c27e8ffa30c5962b881badfab991c))
+* current_utctimestamp as default ([#1161](https://github.com/cap-js/cds-dbs/issues/1161)) ([c0cccad](https://github.com/cap-js/cds-dbs/commit/c0cccad921c45db96e14f0e2afeced6af69da4a2))
+* exists within expression is properly detected ([#1156](https://github.com/cap-js/cds-dbs/issues/1156)) ([febe175](https://github.com/cap-js/cds-dbs/commit/febe1755186d291b92edbdf69cebbab68a53d0af))
+* resilience for query re-use scenarios ([#1175](https://github.com/cap-js/cds-dbs/issues/1175)) ([fe9abd5](https://github.com/cap-js/cds-dbs/commit/fe9abd5e4c5e9153c0afad9164f240ae2eadf581))
+
+## [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)
 
 

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 = ','
@@ -1102,7 +1102,7 @@ class CQN2SQLRenderer {
 
       let onInsert = this.managed_session_context(element[cdsOnInsert]?.['='])
         || this.managed_session_context(element.default?.ref?.[0])
-        || (element.default?.val !== undefined && { val: element.default.val, param: false })
+        || (element.default && { __proto__:  element.default, param: false })
       let onUpdate = this.managed_session_context(element[cdsOnUpdate]?.['='])
 
       if (onInsert) onInsert = this.expr(onInsert)
@@ -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, defineProperty, 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,
       ]
     }
@@ -843,10 +845,7 @@ function cqn4sql(originalQuery, model) {
     }
     const expanded = transformSubquery(subquery)
     const correlated = _correlate({ ...expanded, as: columnAlias }, outerAlias)
-    Object.defineProperty(correlated, 'elements', {
-      value: expanded.elements,
-      writable: true,
-    })
+    defineProperty(correlated, 'elements', expanded.elements)
     return correlated
 
     function _correlate(subq, outer) {
@@ -1068,9 +1067,9 @@ function cqn4sql(originalQuery, model) {
     else {
       const outerQueries = inferred.outerQueries || []
       outerQueries.push(inferred)
-      Object.defineProperty(q, 'outerQueries', { value: outerQueries })
+      defineProperty(q, 'outerQueries', 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)
@@ -1082,7 +1081,7 @@ function cqn4sql(originalQuery, model) {
         getImplicitAlias(last.id || last),
         inferred.outerQueries,
       )
-      Object.defineProperty(q.SELECT.from, 'uniqueSubqueryAlias', { value: uniqueSubqueryAlias })
+      defineProperty(q.SELECT.from, 'uniqueSubqueryAlias', uniqueSubqueryAlias)
     }
   }
 
@@ -1309,7 +1308,7 @@ function cqn4sql(originalQuery, model) {
             const flatForeignKey = getDefinition(element.parent.name)?.elements[fkBaseName]
 
             setElementOnColumns(flatColumn, flatForeignKey || fkElement)
-            Object.defineProperty(flatColumn, '_csnPath', { value: csnPath, writable: true })
+            defineProperty(flatColumn, '_csnPath', csnPath)
             flatColumns.push(flatColumn)
           }
         }
@@ -1341,7 +1340,7 @@ function cqn4sql(originalQuery, model) {
     if (column.sort) flatRef.sort = column.sort
     if (columnAlias) flatRef.as = columnAlias
     setElementOnColumns(flatRef, element)
-    Object.defineProperty(flatRef, '_csnPath', { value: csnPath, writable: true })
+    defineProperty(flatRef, '_csnPath', csnPath)
     return [flatRef]
 
     function getReplacement(from) {
@@ -1674,7 +1673,7 @@ function cqn4sql(originalQuery, model) {
     const transformedWhere = []
     let transformedFrom = copy(from) // REVISIT: too expensive!
     if (from.$refLinks)
-      Object.defineProperty(transformedFrom, '$refLinks', { value: [...from.$refLinks], writable: true })
+      defineProperty(transformedFrom, '$refLinks', [...from.$refLinks])
     if (from.args) {
       transformedFrom.args = []
       from.args.forEach(arg => {
@@ -1739,7 +1738,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)
@@ -1786,7 +1785,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 }
@@ -1922,10 +1921,7 @@ function cqn4sql(originalQuery, model) {
           const refLinkFaker = thing => {
             const { ref } = thing
             const assocHost = getParentEntity(assocRefLink.definition)
-            Object.defineProperty(thing, '$refLinks', {
-              value: [],
-              writable: true,
-            })
+            defineProperty(thing, '$refLinks', [])
             let pseudoPath = false
             ref.reduce((prev, res, i) => {
               if (res === '$self') {
@@ -1994,9 +1990,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 +2071,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 +2158,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 +2197,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.
@@ -2416,10 +2364,7 @@ function getParentEntity(element) {
  * @param {csn.Element} element
  */
 function setElementOnColumns(col, element) {
-  Object.defineProperty(col, 'element', {
-    value: element,
-    writable: true,
-  })
+  defineProperty(col, 'element', element)
 }
 
 const getName = col => col.as || col.ref?.at(-1)

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, defineProperty } = 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')
@@ -73,7 +75,7 @@ function infer(originalQuery, model) {
       joinTree: { value: joinTree, writable: true, configurable: true }, // REVISIT: eliminate
     })
     // also enrich original query -> writable because it may be inferred again
-    Object.defineProperty(originalQuery, 'elements', { value: elements, writable: true, configurable: true })
+    defineProperty(originalQuery, 'elements', elements)
   }
   return inferred
 
@@ -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) {
@@ -169,10 +171,7 @@ function infer(originalQuery, model) {
    * @param {csn.Element} element
    */
   function setElementOnColumns(col, element) {
-    Object.defineProperty(col, 'element', {
-      value: element,
-      writable: true,
-    })
+    defineProperty(col, 'element', element)
   }
 
   /**
@@ -209,7 +208,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)
           }
@@ -243,7 +242,7 @@ function infer(originalQuery, model) {
       // link $refLinks -> special name resolution rules for orderBy
       orderBy.forEach(token => {
         let $baseLink
-        let rejectJoinRelevantPath
+        let needsElementsOfQueryAsBase
         // first check if token ref is resolvable in query elements
         if (columns) {
           const firstStep = token.ref?.[0].id || token.ref?.[0]
@@ -251,14 +250,11 @@ function infer(originalQuery, model) {
             const columnName = c.as || c.flatName || c.ref?.at(-1).id || c.ref?.at(-1) || c.func
             return columnName === firstStep
           })
-          const needsElementsOfQueryAsBase =
+          needsElementsOfQueryAsBase =
             tokenPointsToQueryElements &&
-            queryElements[token.ref?.[0]] &&
-            /* expand on structure can be addressed */ !queryElements[token.ref?.[0]].$assocExpand
+            queryElements[firstStep] &&
+            /* expand on structure can be addressed */ !queryElements[firstStep].$assocExpand
 
-          // if the ref points into the query itself and follows an exposed association
-          // to a non-fk column, we must reject the ref, as we can't join with the queries own results
-          rejectJoinRelevantPath = needsElementsOfQueryAsBase
           if (needsElementsOfQueryAsBase) $baseLink = { definition: { elements: queryElements }, target: inferred }
         } else {
           // fallback to elements of query source
@@ -266,7 +262,9 @@ function infer(originalQuery, model) {
         }
 
         inferArg(token, queryElements, $baseLink, { inQueryModifier: true })
-        if (token.isJoinRelevant && rejectJoinRelevantPath) {
+        // if the ref points into the query itself and follows an exposed association
+        // to a non-fk column, we must reject the ref, as we can't join with the queries own results
+        if (token.isJoinRelevant && needsElementsOfQueryAsBase) {
           // reverse the array, find the last association and calculate the index of the association in non-reversed order
           const assocIndex =
             token.$refLinks.length - 1 - token.$refLinks.reverse().findIndex(link => link.definition.isAssociation)
@@ -350,7 +348,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,22 +397,27 @@ 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))
-    if (arg.xpr) arg.xpr.forEach(token => inferArg(token, queryElements, $baseLink, { ...context, inXpr: true })) // e.g. function in expression
+    if (arg.xpr)
+      arg.xpr.forEach((token, i) =>
+        inferArg(token, queryElements, $baseLink, { ...context, inXpr: true, inExists: arg.xpr[i - 1] === 'exists' }),
+      ) // e.g. function in expression
 
     if (!arg.ref) {
       if (arg.expand && queryElements) queryElements[arg.as] = resolveExpand(arg)
       return
     }
 
-    // initialize $refLinks
-    Object.defineProperty(arg, '$refLinks', {
-      value: [],
-      writable: true,
-    })
+    // Before the arg is linked, it's meta information should be cleaned up.
+    // This may be important if one manipulates the arg object
+    // __after__ a query has been fired and re-uses the manipulated query
+    defineProperty(arg, '$refLinks', [])
+    defineProperty(arg, 'isJoinRelevant', false)
+
     // if any path step points to an artifact with `@cds.persistence.skip`
     // we must ignore the element from the queries elements
     let isPersisted = true
@@ -424,8 +427,8 @@ 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) {
-      Object.defineProperty(arg, 'inXpr', { value: true, writable: true })
+    if (dollarSelfRefs && firstStepIsSelf) {
+      defineProperty(arg, 'inXpr', true)
       dollarSelfRefs.push(arg)
       return
     }
@@ -452,7 +455,7 @@ function infer(originalQuery, model) {
               const nextStep = arg.ref[1]?.id || arg.ref[1]
               if (isNonForeignKeyNavigation(element, nextStep)) {
                 if (inExists) {
-                  Object.defineProperty($baseLink, 'pathExpressionInsideFilter', { value: true })
+                  defineProperty($baseLink, 'pathExpressionInsideFilter', true)
                 } else {
                   rejectNonFkNavigation(element, element.on ? $baseLink.definition.name : nextStep)
                 }
@@ -516,7 +519,7 @@ function infer(originalQuery, model) {
             const nextStep = arg.ref[i + 1]?.id || arg.ref[i + 1]
             if (isNonForeignKeyNavigation(element, nextStep)) {
               if (inExists) {
-                Object.defineProperty($baseLink, 'pathExpressionInsideFilter', { value: true })
+                defineProperty($baseLink, 'pathExpressionInsideFilter', true)
               } else {
                 rejectNonFkNavigation(element, element.on ? $baseLink.definition.name : nextStep)
               }
@@ -532,7 +535,7 @@ function infer(originalQuery, model) {
         } else if (id === '$dummy') {
           // `some.known.element.$dummy` -> no error; used by cds.ql to simulate joins
           arg.$refLinks.push({ definition: { name: '$dummy', parent: arg.$refLinks[i - 1].target } })
-          Object.defineProperty(arg, 'isJoinRelevant', { value: true })
+          defineProperty(arg, 'isJoinRelevant', true)
         } else {
           const notFoundIn = pseudoPath ? arg.ref[i - 1] : getFullPathForLinkedArg(arg)
           stepNotFoundInPredecessor(id, notFoundIn)
@@ -558,7 +561,7 @@ function infer(originalQuery, model) {
         const definition = arg.$refLinks[i].definition
         if ((!definition.target && definition.kind !== 'entity') || (!inFrom && danglingFilter))
           throw new Error('A filter can only be provided when navigating along associations')
-        if (!inFrom && !arg.expand) Object.defineProperty(arg, 'isJoinRelevant', { value: true })
+        if (!inFrom && !arg.expand)defineProperty(arg, 'isJoinRelevant', true)
         let skipJoinsForFilter = false
         step.where.forEach(token => {
           if (token === 'exists') {
@@ -587,7 +590,7 @@ function infer(originalQuery, model) {
       if (getDefinition(arg.$refLinks[i].definition.target)?.['@cds.persistence.skip'] === true) isPersisted = false
       if (!arg.ref[i + 1]) {
         const flatName = nameSegments.join('_')
-        Object.defineProperty(arg, 'flatName', { value: flatName, writable: true })
+        defineProperty(arg, 'flatName', flatName)
         // if column is casted, we overwrite it's origin with the new type
         if (arg.cast) {
           const base = getElementForCast(arg)
@@ -632,7 +635,7 @@ function infer(originalQuery, model) {
     })
 
     // we need inner joins for the path expressions inside filter expressions after exists predicate
-    if ($baseLink?.pathExpressionInsideFilter) Object.defineProperty(arg, 'join', { value: 'inner' })
+    if ($baseLink?.pathExpressionInsideFilter) defineProperty(arg, 'join', 'inner')
 
     // ignore whole expand if target of assoc along path has ”@cds.persistence.skip”
     if (arg.expand) {
@@ -652,7 +655,7 @@ function infer(originalQuery, model) {
         ? { ref: [...baseColumn.ref, ...arg.ref], $refLinks: [...baseColumn.$refLinks, ...arg.$refLinks] }
         : arg
       if (isColumnJoinRelevant(colWithBase)) {
-        Object.defineProperty(arg, 'isJoinRelevant', { value: true })
+        defineProperty(arg, 'isJoinRelevant', true)
         joinTree.mergeColumn(colWithBase, originalQuery.outerQueries)
       }
     }
@@ -758,7 +761,7 @@ function infer(originalQuery, model) {
         const res = $leafLink.definition.is2one
           ? new cds.struct({ elements: inferredExpandSubquery.elements })
           : new cds.array({ items: new cds.struct({ elements: inferredExpandSubquery.elements }) })
-        return Object.defineProperty(res, '$assocExpand', { value: true })
+        return defineProperty(res, '$assocExpand', true)
       } else if ($leafLink.definition.elements) {
         let elements = {}
         expand.forEach(e => {
@@ -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,13 +900,13 @@ function infer(originalQuery, model) {
         const calcElementIsJoinRelevant = isColumnJoinRelevant(p)
         if (calcElementIsJoinRelevant) {
           if (!calcElement.value.isJoinRelevant)
-            Object.defineProperty(step, 'isJoinRelevant', { value: true, writable: true,  })
+            defineProperty(step, 'isJoinRelevant',true)
           joinTree.mergeColumn(p, originalQuery.outerQueries)
         } else {
           // we need to explicitly set the value to false in this case,
           // e.g. `SELECT from booksCalc.Books { ID, author.{name }, author {name } }`
           // --> for the inline column, the name is join relevant, while for the expand, it is not
-          Object.defineProperty(step, 'isJoinRelevant', { value: false, writable: true })
+          defineProperty(step, 'isJoinRelevant', false)
         }
       }
     }
@@ -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') {
@@ -1055,7 +1064,6 @@ function infer(originalQuery, model) {
    * @returns {object} a copy of @param base with all annotations of @param from
    * @TODO prototype based
    */
-  // REVISIT: TODO: inferred.elements should be linked
   function getCopyWithAnnos(from, base) {
     const result = { ...base }
     // REVISIT: we don't need to and hence should not handle annotations at runtime
@@ -1063,7 +1071,7 @@ function infer(originalQuery, model) {
       if (prop.startsWith('@')) result[prop] = from[prop]
     }
 
-    if (from.as && base.name !== from.as) Object.defineProperty(result, 'name', { value: from.as }) // TODO double check if this is needed
+    if (from.as && base.name !== from.as) defineProperty(result, 'name', from.as) // TODO double check if this is needed
     // in subqueries we need the linked element if an outer query accesses it
     return Object.setPrototypeOf(result, base)
   }
@@ -1083,12 +1091,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/search.js

@@ -79,7 +79,7 @@ const _getSearchableColumns = entity => {
     const column = entity.elements[columnName]
     if (column?.isAssociation || columnName.includes('.')) {
       deepSearchCandidates.push({ ref: columnName.split('.') })
-      continue;
+      continue
     }
     cdsSearchColumnMap.set(columnName, annotationValue)
   }
@@ -93,8 +93,8 @@ const _getSearchableColumns = entity => {
     // `@cds.search { element1: true }` or `@cds.search { element1 }`
     if (annotatedColumnValue) return true
 
-    // calculated elements are only searchable if requested through `@cds.search` 
-    if(column.value) return false
+    // calculated elements are only searchable if requested through `@cds.search`
+    if (column.value) return false
 
     // if at least one element is explicitly annotated as searchable, e.g.:
     // `@cds.search { element1: true }` or `@cds.search { element1 }`
@@ -112,16 +112,23 @@ const _getSearchableColumns = entity => {
 
   if (deepSearchCandidates.length) {
     deepSearchCandidates.forEach(c => {
-      const element = c.ref.reduce((resolveIn, curr, i) => {
-        const next = resolveIn.elements?.[curr] || resolveIn._target.elements[curr]
-        if (next?.isAssociation && !c.ref[i + 1]) {
-          const searchInTarget = _getSearchableColumns(next._target)
-          searchInTarget.forEach(elementRefInTarget => {
-            searchableColumns.push({ ref: c.ref.concat(...elementRefInTarget.ref) })
-          })
+      let element = entity
+      for (let i = 0; i < c.ref.length; ++i) {
+        const curr = c.ref[i]
+        const next = element.elements?.[curr] ?? element._target?.elements?.[curr]
+
+        if (!next) { // e.g. if a search element is not part of a projection
+          element = undefined
+          break
         }
-        return next
-      }, entity)
+
+        if (next.isAssociation && i === c.ref.length - 1) {
+          _getSearchableColumns(next._target).forEach(r => searchableColumns.push({ ref: c.ref.concat(...r.ref) }))
+        }
+
+        element = next
+      }
+
       if (element?.type === DEFAULT_SEARCHABLE_TYPE) {
         searchableColumns.push({ ref: c.ref })
       }
@@ -129,9 +136,8 @@ const _getSearchableColumns = entity => {
   }
 
   return searchableColumns.map(column => {
-    if(column.ref)
-      return column
-    return { ref: [ column.name ] }
+    if (column.ref) return column
+    return { ref: [column.name] }
   })
 }
 
@@ -183,15 +189,16 @@ const computeColumnsToBeSearched = (cqn, entity = { __searchableColumns: [] }) =
       }
     })
   } else {
-    if(entity.kind === 'entity') {
+    if (entity.kind === 'entity') {
       // first check cache
-      toBeSearched = entity.own('__searchableColumns') || entity.set('__searchableColumns', _getSearchableColumns(entity))
+      toBeSearched =
+        entity.own('__searchableColumns') || entity.set('__searchableColumns', _getSearchableColumns(entity))
     } else {
       // if we search on a subquery, we don't have a cache
       toBeSearched = _getSearchableColumns(entity)
     }
     toBeSearched = toBeSearched.map(c => {
-      const column = {ref: [...c.ref]}
+      const column = { ref: [...c.ref] }
       return column
     })
   }

package/lib/utils.js

@@ -40,32 +40,103 @@ 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
 }
 
+function defineProperty(obj, prop, value) {
+  return Object.defineProperty(obj, prop, {
+    value,
+    writable: true,
+    configurable: true,
+  })
+}
+
+/**
+ * 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,
+  defineProperty,
+  getModelUtils,
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cap-js/db-service",
-  "version": "1.19.1",
+  "version": "1.20.1",
   "description": "CDS base database service",
   "homepage": "https://github.com/cap-js/cds-dbs/tree/main/db-service#cds-base-database-service",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cap-js/cds-dbs"
+    "url": "git+https://github.com/cap-js/cds-dbs.git"
   },
   "bugs": {
     "url": "https://github.com/cap-js/cds-dbs/issues"