@cap-js/change-tracking 1.1.4 → 2.0.0-beta.2

package/lib/h2/register.js

@@ -0,0 +1,27 @@
+const cds = require('@sap/cds');
+
+const { prepareCSNForTriggers, generateTriggersForEntities, writeLabelsCSV } = require('../utils/trigger-utils.js');
+
+function registerH2CompilerHook() {
+	const _sql_original = cds.compile.to.sql;
+	cds.compile.to.sql = function (csn, options) {
+		let ret = _sql_original.call(this, csn, options);
+		const kind = options?.kind ?? options?.to;
+		if (kind !== 'h2') return ret;
+
+		const { runtimeCSN, hierarchy, entities } = prepareCSNForTriggers(csn, true);
+		const { generateH2Triggers } = require('./triggers.js');
+		const triggers = generateTriggersForEntities(runtimeCSN, hierarchy, entities, generateH2Triggers);
+
+		if (triggers.length > 0) {
+			writeLabelsCSV(entities, runtimeCSN);
+		}
+		// Add semicolon at the end of each DDL statement if not already present
+		ret = ret.map((s) => (s.endsWith(';') ? s : s + ';'));
+
+		return ret.concat(triggers);
+	};
+	Object.assign(cds.compile.to.sql, _sql_original);
+}
+
+module.exports = { registerH2CompilerHook };

package/lib/h2/triggers.js

@@ -0,0 +1,41 @@
+const utils = require('../utils/change-tracking.js');
+const config = require('@sap/cds').env.requires['change-tracking'];
+const { getCompositionParentInfo, getGrandParentCompositionInfo } = require('../utils/composition-helpers.js');
+const { _generateJavaMethod, _generateCreateBody, _generateUpdateBody, _generateDeleteBody, _generateDeleteBodyPreserve } = require('./java-codegen.js');
+
+function generateH2Trigger(csn, entity, rootEntity, mergedAnnotations = null, rootMergedAnnotations = null, grandParentContext = {}) {
+	const { columns: trackedColumns } = utils.extractTrackedColumns(entity, csn, mergedAnnotations);
+	const objectIDs = utils.getObjectIDs(entity, csn, mergedAnnotations?.entityAnnotation);
+	const rootObjectIDs = utils.getObjectIDs(rootEntity, csn, rootMergedAnnotations?.entityAnnotation);
+
+	// Check if this entity is a tracked composition target (composition-of-many)
+	const compositionParentInfo = getCompositionParentInfo(entity, rootEntity, rootMergedAnnotations);
+
+	// Get grandparent info for deep linking (e.g., OrderItemNote -> OrderItem.notes -> Order.orderItems)
+	const { grandParentEntity, grandParentMergedAnnotations, grandParentCompositionField } = grandParentContext;
+	const grandParentCompositionInfo = getGrandParentCompositionInfo(rootEntity, grandParentEntity, grandParentMergedAnnotations, grandParentCompositionField);
+
+	// Generate triggers if we have tracked columns OR if this is a composition target
+	const shouldGenerateTriggers = trackedColumns.length > 0 || compositionParentInfo;
+	if (!shouldGenerateTriggers) return null;
+
+	// Generate the Java code for each section
+	const createBody = !config?.disableCreateTracking ? _generateCreateBody(entity, trackedColumns, objectIDs, rootEntity, rootObjectIDs, csn, compositionParentInfo, grandParentCompositionInfo) : '';
+	const updateBody = !config?.disableUpdateTracking ? _generateUpdateBody(entity, trackedColumns, objectIDs, rootEntity, rootObjectIDs, csn, compositionParentInfo, grandParentCompositionInfo) : '';
+	let deleteBody = '';
+	if (!config?.disableDeleteTracking) {
+		deleteBody = config?.preserveDeletes
+			? _generateDeleteBodyPreserve(entity, trackedColumns, objectIDs, rootEntity, rootObjectIDs, csn, compositionParentInfo, grandParentCompositionInfo)
+			: _generateDeleteBody(entity, trackedColumns, objectIDs, rootEntity, rootObjectIDs, csn, compositionParentInfo, grandParentCompositionInfo);
+	}
+
+	// Define the full Create Trigger SQL
+	return `CREATE TRIGGER ${utils.transformName(entity.name)}_ct
+            AFTER INSERT, UPDATE, DELETE ON ${utils.transformName(entity.name)}
+            FOR EACH ROW
+            AS $$
+            ${_generateJavaMethod(createBody, updateBody, deleteBody, entity.name, compositionParentInfo, grandParentCompositionInfo)}
+            $$;;`;
+}
+
+module.exports = { generateH2Trigger };

package/lib/hana/composition.js

@@ -0,0 +1,248 @@
+const utils = require('../utils/change-tracking.js');
+const { toSQL, compositeKeyExpr, buildGrandParentObjectIDExpr } = require('./sql-expressions.js');
+
+/**
+ * Builds rootObjectID select for composition of many
+ */
+function buildCompOfManyRootObjectIDSelect(rootEntity, rootObjectIDs, binding, refRow, model) {
+	const rootEntityKeyExpr = compositeKeyExpr(binding.map((k) => `:${refRow}.${k}`));
+
+	if (!rootObjectIDs || rootObjectIDs.length === 0) return rootEntityKeyExpr;
+
+	const rootKeys = utils.extractKeys(rootEntity.keys);
+	if (rootKeys.length !== binding.length) return rootEntityKeyExpr;
+
+	const where = {};
+	for (let i = 0; i < rootKeys.length; i++) {
+		where[rootKeys[i]] = { val: `:${refRow}.${binding[i]}` };
+	}
+
+	const parts = [];
+	for (const oid of rootObjectIDs) {
+		const query = SELECT.one.from(rootEntity.name).columns(oid.name).where(where);
+		parts.push(`COALESCE(TO_NVARCHAR((${toSQL(query, model)})), '')`);
+	}
+
+	const concatLogic = parts.join(" || ', ' || ");
+
+	return `COALESCE(NULLIF(${concatLogic}, ''), ${rootEntityKeyExpr})`;
+}
+
+/**
+ * Builds context for composition of one parent changelog entry.
+ * In composition of one, the parent entity has FK to the child (e.g., BookStores.registry_ID -> BookStoreRegistry.ID)
+ * So we need to do a reverse lookup: find the parent record that has FK pointing to this child.
+ */
+function buildCompositionOfOneParentContext(compositionParentInfo, rootObjectIDs, modification, rowRef, model) {
+	const { parentEntityName, compositionFieldName, parentKeyBinding } = compositionParentInfo;
+	const { compositionName, childKeys } = parentKeyBinding;
+
+	// Build the FK field names on the parent that point to this child
+	// For composition of one, CAP generates <compositionName>_<childKey> fields
+	const parentFKFields = childKeys.map((k) => `${compositionName}_${k}`);
+
+	// Build WHERE clause to find the parent entity that has this child
+	const parentEntity = model.definitions[parentEntityName];
+	const parentKeys = utils.extractKeys(parentEntity.keys);
+	const parentWhereClause = parentFKFields.map((fk, i) => `${fk} = :${rowRef}.${childKeys[i]}`).join(' AND ');
+
+	// Build the parent key expression via subquery (reverse lookup)
+	const parentKeyExpr = compositeKeyExpr(parentKeys.map((pk) => `(SELECT ${pk} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause})`));
+
+	// Build rootObjectID expression for the parent entity
+	let rootObjectIDExpr;
+	if (rootObjectIDs?.length > 0) {
+		const oidSelects = rootObjectIDs.map((oid) => `(SELECT ${oid.name} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause})`);
+		rootObjectIDExpr = oidSelects.length > 1 ? oidSelects.join(" || ', ' || ") : oidSelects[0];
+	} else {
+		rootObjectIDExpr = parentKeyExpr;
+	}
+
+	// Add parent_modification to declares for dynamic determination
+	const declares = 'DECLARE parent_id NVARCHAR(36); DECLARE parent_modification NVARCHAR(10);';
+
+	// Determine modification dynamically: 'create' if parent was just created, 'update' otherwise
+	// Note: For composition of one, we check if a composition entry already exists for this transaction
+	// to avoid duplicates when both parent UPDATE and child DELETE triggers fire
+	const insertSQL = `
+		SELECT CASE WHEN COUNT(*) > 0 THEN 'create' ELSE 'update' END INTO parent_modification
+			FROM SAP_CHANGELOG_CHANGES
+			WHERE entity = '${parentEntityName}'
+			AND entityKey = ${parentKeyExpr}
+			AND modification = 'create'
+			AND transactionID = CURRENT_UPDATE_TRANSACTION();
+		INSERT INTO SAP_CHANGELOG_CHANGES
+			(ID, parent_ID, attribute, entity, entityKey, objectID, createdAt, createdBy, valueDataType, modification, transactionID)
+			SELECT
+				parent_id,
+				NULL,
+				'${compositionFieldName}',
+				'${parentEntityName}',
+				${parentKeyExpr},
+				${rootObjectIDExpr},
+				CURRENT_TIMESTAMP,
+				SESSION_CONTEXT('APPLICATIONUSER'),
+				'cds.Composition',
+				parent_modification,
+				CURRENT_UPDATE_TRANSACTION()
+			FROM SAP_CHANGELOG_CHANGE_TRACKING_DUMMY
+			WHERE EXISTS (
+				SELECT 1 FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause}
+			)
+			AND NOT EXISTS (
+				SELECT 1 FROM SAP_CHANGELOG_CHANGES
+				WHERE entity = '${parentEntityName}'
+				AND entityKey = ${parentKeyExpr}
+				AND attribute = '${compositionFieldName}'
+				AND valueDataType = 'cds.Composition'
+				AND transactionID = CURRENT_UPDATE_TRANSACTION()
+			);`;
+
+	return { declares, insertSQL, parentEntityName, compositionFieldName, parentKeyExpr };
+}
+
+function buildCompositionParentContext(compositionParentInfo, rootObjectIDs, modification, rowRef, model, grandParentCompositionInfo = null) {
+	const { parentEntityName, compositionFieldName, parentKeyBinding } = compositionParentInfo;
+
+	// Handle composition of one (parent has FK to child - need reverse lookup)
+	if (parentKeyBinding.type === 'compositionOfOne') {
+		return buildCompositionOfOneParentContext(compositionParentInfo, rootObjectIDs, modification, rowRef, model);
+	}
+
+	const parentKeyExpr = compositeKeyExpr(parentKeyBinding.map((k) => `:${rowRef}.${k}`));
+
+	// Build rootObjectID expression for the parent entity
+	const rootEntity = model.definitions[parentEntityName];
+	const rootObjectIDExpr = buildCompOfManyRootObjectIDSelect(rootEntity, rootObjectIDs, parentKeyBinding, rowRef, model);
+
+	let declares, insertSQL;
+
+	if (grandParentCompositionInfo) {
+		// When we have grandparent info, we need to:
+		// 1. Create grandparent entry (Order.orderItems) for current transaction if not exists
+		// 2. Create parent entry (OrderItem.notes) linking to the grandparent entry
+		const { grandParentEntityName, grandParentCompositionFieldName, grandParentKeyBinding } = grandParentCompositionInfo;
+
+		// Build grandparent key expression by looking up from parent entity
+		const parentEntity = model.definitions[parentEntityName];
+		const parentKeys = utils.extractKeys(parentEntity.keys);
+		const parentWhere = parentKeys.map((pk, i) => `${pk} = :${rowRef}.${parentKeyBinding[i]}`).join(' AND ');
+		const grandParentKeyExpr = compositeKeyExpr(grandParentKeyBinding.map((k) => `(SELECT ${k} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhere})`));
+
+		// Build grandparent objectID expression
+		const grandParentEntity = model.definitions[grandParentEntityName];
+		const grandParentObjectIDs = utils.getObjectIDs(grandParentEntity, model);
+		const grandParentObjectIDExpr = grandParentObjectIDs?.length > 0 ? buildGrandParentObjectIDExpr(grandParentObjectIDs, grandParentEntity, parentEntityName, parentKeyBinding, grandParentKeyBinding, rowRef, model) : grandParentKeyExpr;
+
+		// Add grandparent_id to declares
+		declares = 'DECLARE parent_id NVARCHAR(36);\n\tDECLARE grandparent_id NVARCHAR(36);';
+
+		insertSQL = `SELECT MAX(ID) INTO grandparent_id FROM SAP_CHANGELOG_CHANGES
+			WHERE entity = '${grandParentEntityName}'
+			AND entityKey = ${grandParentKeyExpr}
+			AND attribute = '${grandParentCompositionFieldName}'
+			AND valueDataType = 'cds.Composition'
+			AND transactionID = CURRENT_UPDATE_TRANSACTION();
+		IF grandparent_id IS NULL THEN
+			grandparent_id := SYSUUID;
+			INSERT INTO SAP_CHANGELOG_CHANGES
+				(ID, parent_ID, attribute, entity, entityKey, objectID, createdAt, createdBy, valueDataType, modification, transactionID)
+				VALUES (
+					grandparent_id,
+					NULL,
+					'${grandParentCompositionFieldName}',
+					'${grandParentEntityName}',
+					${grandParentKeyExpr},
+					${grandParentObjectIDExpr},
+					CURRENT_TIMESTAMP,
+					SESSION_CONTEXT('APPLICATIONUSER'),
+					'cds.Composition',
+					'update',
+					CURRENT_UPDATE_TRANSACTION()
+				);
+		END IF;
+		
+		INSERT INTO SAP_CHANGELOG_CHANGES
+			(ID, parent_ID, attribute, entity, entityKey, objectID, createdAt, createdBy, valueDataType, modification, transactionID)
+			VALUES (
+				parent_id,
+				grandparent_id,
+				'${compositionFieldName}',
+				'${parentEntityName}',
+				${parentKeyExpr},
+				${rootObjectIDExpr},
+				CURRENT_TIMESTAMP,
+				SESSION_CONTEXT('APPLICATIONUSER'),
+				'cds.Composition',
+				'${modification}',
+				CURRENT_UPDATE_TRANSACTION()
+			);`;
+	} else {
+		// Add parent_modification to declares for dynamic determination
+		declares = 'DECLARE parent_id NVARCHAR(36);\n\tDECLARE parent_modification NVARCHAR(10);';
+
+		// Determine modification dynamically: 'create' if parent was just created, 'update' otherwise
+		// This handles both deep insert (parent created in same tx) and independent insert (parent already existed)
+		insertSQL = `
+		SELECT CASE WHEN COUNT(*) > 0 THEN 'create' ELSE 'update' END INTO parent_modification
+			FROM SAP_CHANGELOG_CHANGES
+			WHERE entity = '${parentEntityName}'
+			AND entityKey = ${parentKeyExpr}
+			AND modification = 'create'
+			AND transactionID = CURRENT_UPDATE_TRANSACTION();
+		INSERT INTO SAP_CHANGELOG_CHANGES
+			(ID, parent_ID, attribute, entity, entityKey, objectID, createdAt, createdBy, valueDataType, modification, transactionID)
+			VALUES (
+				parent_id,
+				NULL,
+				'${compositionFieldName}',
+				'${parentEntityName}',
+				${parentKeyExpr},
+				${rootObjectIDExpr},
+				CURRENT_TIMESTAMP,
+				SESSION_CONTEXT('APPLICATIONUSER'),
+				'cds.Composition',
+				parent_modification,
+				CURRENT_UPDATE_TRANSACTION()
+			);`;
+	}
+
+	return { declares, insertSQL, parentEntityName, compositionFieldName, parentKeyExpr };
+}
+
+function buildParentLookupSQL(parentEntityName, parentKeyExpr, compositionFieldName) {
+	return `SELECT MAX(ID) INTO parent_id FROM SAP_CHANGELOG_CHANGES
+			WHERE entity = '${parentEntityName}'
+			AND entityKey = ${parentKeyExpr}
+			AND attribute = '${compositionFieldName}'
+			AND valueDataType = 'cds.Composition'
+			AND transactionID = CURRENT_UPDATE_TRANSACTION();`;
+}
+
+function buildParentLookupOrCreateSQL(compositionParentContext) {
+	const { insertSQL: compInsertSQL, parentEntityName, compositionFieldName, parentKeyExpr } = compositionParentContext;
+	return `${buildParentLookupSQL(parentEntityName, parentKeyExpr, compositionFieldName)}
+		IF parent_id IS NULL THEN
+			parent_id := SYSUUID;
+			${compInsertSQL}
+		END IF;`;
+}
+
+function buildCompositionOnlyBody(entityName, compositionParentContext, prefixSQL = '') {
+	const { getSkipCheckCondition } = require('./sql-expressions.js');
+	const { declares } = compositionParentContext;
+	const prefix = prefixSQL ? `\n\t\t${prefixSQL}` : '';
+	return `${declares}
+	IF ${getSkipCheckCondition(entityName)} THEN${prefix}
+		${buildParentLookupOrCreateSQL(compositionParentContext)}
+	END IF;`;
+}
+
+module.exports = {
+	buildCompOfManyRootObjectIDSelect,
+	buildCompositionOfOneParentContext,
+	buildCompositionParentContext,
+	buildParentLookupSQL,
+	buildParentLookupOrCreateSQL,
+	buildCompositionOnlyBody
+};

package/lib/hana/register.js

@@ -0,0 +1,28 @@
+const cds = require('@sap/cds');
+const { fs } = cds.utils;
+
+const { prepareCSNForTriggers, generateTriggersForEntities, writeLabelsCSV, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
+
+function registerHDICompilerHook() {
+	const _hdi_migration = cds.compiler.to.hdi.migration;
+	cds.compiler.to.hdi.migration = function (csn, options, beforeImage) {
+		const { generateHANATriggers } = require('./triggers.js');
+		const { runtimeCSN, hierarchy, entities } = prepareCSNForTriggers(csn, true);
+
+		const triggers = generateTriggersForEntities(runtimeCSN, hierarchy, entities, generateHANATriggers);
+
+		if (triggers.length > 0) {
+			delete csn.definitions['sap.changelog.CHANGE_TRACKING_DUMMY']['@cds.persistence.skip'];
+			writeLabelsCSV(entities, runtimeCSN);
+			const dir = 'db/src/gen/data/';
+			fs.writeFileSync(`${dir}/sap.changelog-CHANGE_TRACKING_DUMMY.csv`, `X\n1`);
+			ensureUndeployJsonHasTriggerPattern();
+		}
+
+		const ret = _hdi_migration(csn, options, beforeImage);
+		ret.definitions = [...ret.definitions, ...triggers];
+		return ret;
+	};
+}
+
+module.exports = { registerHDICompilerHook };

package/lib/hana/sql-expressions.js

@@ -0,0 +1,213 @@
+const utils = require('../utils/change-tracking.js');
+const { CT_SKIP_VAR, getEntitySkipVarName, getElementSkipVarName } = require('../utils/session-variables.js');
+
+const HANAService = require('@cap-js/hana');
+const cqn4sql = require('@cap-js/db-service/lib/cqn4sql');
+const { createTriggerCQN2SQL } = require('../TriggerCQN2SQL.js');
+
+const TriggerCQN2SQL = createTriggerCQN2SQL(HANAService.CQN2SQL);
+let HANACQN2SQL;
+
+function toSQL(query, model) {
+	if (!HANACQN2SQL) {
+		HANACQN2SQL = new TriggerCQN2SQL();
+	}
+	const sqlCQN = cqn4sql(query, model);
+	return HANACQN2SQL.SELECT(sqlCQN);
+}
+
+function getSkipCheckCondition(entityName) {
+	const entitySkipVar = getEntitySkipVarName(entityName);
+	return `(COALESCE(SESSION_CONTEXT('${CT_SKIP_VAR}'), 'false') != 'true' AND COALESCE(SESSION_CONTEXT('${entitySkipVar}'), 'false') != 'true')`;
+}
+
+function getElementSkipCondition(entityName, elementName) {
+	const varName = getElementSkipVarName(entityName, elementName);
+	return `COALESCE(SESSION_CONTEXT('${varName}'), 'false') != 'true'`;
+}
+
+function compositeKeyExpr(parts) {
+	if (parts.length <= 1) return parts[0];
+	return `HIERARCHY_COMPOSITE_ID(${parts.join(', ')})`;
+}
+
+/**
+ * Truncates large strings: CASE WHEN LENGTH(val) > 5000 THEN LEFT(val, 4997) || '...' ELSE val END
+ */
+function wrapLargeString(val, isLob = false) {
+	if (val === 'NULL') return 'NULL';
+	// For LOB types, we need to convert to NVARCHAR first
+	const expr = isLob ? `TO_NVARCHAR(${val})` : val;
+	return `CASE WHEN LENGTH(${expr}) > 5000 THEN LEFT(${expr}, 4997) || '...' ELSE ${expr} END`;
+}
+
+/**
+ * Returns SQL expression for a column's raw value
+ */
+function getValueExpr(col, refRow) {
+	if (col.type === 'cds.Boolean') {
+		return `:${refRow}.${col.name}`;
+	}
+	if (col.target && col.foreignKeys) {
+		return col.foreignKeys.map((fk) => `TO_NVARCHAR(:${refRow}.${col.name}_${fk})`).join(" || ' ' || ");
+	}
+	if (col.target && col.on) {
+		return col.on.map((m) => `TO_NVARCHAR(:${refRow}.${m.foreignKeyField})`).join(" || ' ' || ");
+	}
+	// Scalar value
+	let raw = `:${refRow}.${col.name}`;
+	if (col.type === 'cds.LargeString') {
+		return wrapLargeString(raw, true);
+	}
+	if (col.type === 'cds.String') {
+		return wrapLargeString(raw, false);
+	}
+	return `TO_NVARCHAR(${raw})`;
+}
+
+/**
+ * Null-safe change detection: (old <> new OR old IS NULL OR new IS NULL) AND NOT (old IS NULL AND new IS NULL)
+ */
+function nullSafeChanged(column, isLob = false) {
+	// For LOB types, convert to NVARCHAR before comparison
+	const o = isLob ? `TO_NVARCHAR(:old.${column})` : `:old.${column}`;
+	const n = isLob ? `TO_NVARCHAR(:new.${column})` : `:new.${column}`;
+	return `(${o} <> ${n} OR ${o} IS NULL OR ${n} IS NULL) AND NOT (${o} IS NULL AND ${n} IS NULL)`;
+}
+
+/**
+ * Returns SQL WHERE condition for detecting column changes (null-safe comparison)
+ */
+function getWhereCondition(col, modification) {
+	const isLob = col.type === 'cds.LargeString';
+	if (modification === 'update') {
+		const checkCols = col.foreignKeys ? col.foreignKeys.map((fk) => `${col.name}_${fk}`) : col.on ? col.on.map((m) => m.foreignKeyField) : [col.name];
+		return checkCols.map((k) => nullSafeChanged(k, isLob)).join(' OR ');
+	}
+	// CREATE or DELETE: check value is not null
+	const rowRef = modification === 'create' ? 'new' : 'old';
+	if (col.target && col.foreignKeys) {
+		return col.foreignKeys.map((fk) => `:${rowRef}.${col.name}_${fk} IS NOT NULL`).join(' OR ');
+	}
+	if (col.target && col.on) {
+		return col.on.map((m) => `:${rowRef}.${m.foreignKeyField} IS NOT NULL`).join(' OR ');
+	}
+	// For LOB types, convert to NVARCHAR before null check
+	if (isLob) {
+		return `TO_NVARCHAR(:${rowRef}.${col.name}) IS NOT NULL`;
+	}
+	return `:${rowRef}.${col.name} IS NOT NULL`;
+}
+
+/**
+ * Returns SQL expression for a column's label (looked-up value for associations)
+ */
+function getLabelExpr(col, refRow, model) {
+	if (!(col.target && col.alt)) {
+		return `NULL`;
+	}
+
+	// Builds inline SELECT expression for association label lookup with locale support
+	let where = {};
+	if (col.foreignKeys) {
+		where = col.foreignKeys.reduce((acc, k) => {
+			acc[k] = { val: `:${refRow}.${col.name}_${k}` };
+			return acc;
+		}, {});
+	} else if (col.on) {
+		where = col.on.reduce((acc, mapping) => {
+			acc[mapping.targetKey] = { val: `:${refRow}.${mapping.foreignKeyField}` };
+			return acc;
+		}, {});
+	}
+
+	const alt = col.alt.map((s) => s.split('.').slice(1).join('.'));
+	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
+
+	// Check for localization
+	const localizedInfo = utils.getLocalizedLookupInfo(col.target, col.alt, model);
+	if (localizedInfo) {
+		const textsWhere = { ...where, locale: { func: 'SESSION_CONTEXT', args: [{ val: 'LOCALE' }] } };
+		const textsQuery = SELECT.one.from(localizedInfo.textsEntity).columns(columns).where(textsWhere);
+		const baseQuery = SELECT.one.from(col.target).columns(columns).where(where);
+		return `COALESCE((${toSQL(textsQuery, model)}), (${toSQL(baseQuery, model)}))`;
+	}
+
+	const query = SELECT.one.from(col.target).columns(columns).where(where);
+	return `(${toSQL(query, model)})`;
+}
+
+/**
+ * Builds SQL expression for objectID (entity display name)
+ * Uses @changelog annotation fields, falling back to entity name
+ */
+function buildObjectIDExpr(objectIDs, entity, rowRef, model) {
+	const keys = utils.extractKeys(entity.keys);
+	const entityKeyExpr = compositeKeyExpr(keys.map((k) => `:${rowRef}.${k}`));
+
+	if (!objectIDs || objectIDs.length === 0) {
+		return entityKeyExpr;
+	}
+
+	const parts = [];
+	for (const oid of objectIDs) {
+		if (oid.included) {
+			parts.push(`TO_NVARCHAR(:${rowRef}.${oid.name})`);
+		} else {
+			const where = keys.reduce((acc, k) => {
+				acc[k] = { val: `:${rowRef}.${k}` };
+				return acc;
+			}, {});
+			const query = SELECT.one.from(entity.name).columns(oid.name).where(where);
+			parts.push(`COALESCE(TO_NVARCHAR((${toSQL(query, model)})), '')`);
+		}
+	}
+
+	const concatLogic = parts.join(" || ', ' || ");
+	return `COALESCE(NULLIF(${concatLogic}, ''), ${entityKeyExpr})`;
+}
+
+/**
+ * Builds SQL expression for grandparent entity's objectID
+ * Used when creating grandparent composition entries for deep linking
+ */
+function buildGrandParentObjectIDExpr(grandParentObjectIDs, grandParentEntity, parentEntityName, parentKeyBinding, grandParentKeyBinding, rowRef, model) {
+	// Build WHERE clause to find the parent entity record (e.g., OrderItem from OrderItemNote's FK)
+	const parentEntity = model.definitions[parentEntityName];
+	const parentKeys = utils.extractKeys(parentEntity.keys);
+	const parentWhere = parentKeys.map((pk, i) => `${pk} = :${rowRef}.${parentKeyBinding[i]}`).join(' AND ');
+
+	// Build WHERE clause to find the grandparent entity record from parent
+	const grandParentKeys = utils.extractKeys(grandParentEntity.keys);
+	const grandParentWhereSubquery = grandParentKeys
+		.map((gk, i) => {
+			const fkField = grandParentKeyBinding[i];
+			return `${gk} = (SELECT ${fkField} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhere})`;
+		})
+		.join(' AND ');
+
+	const parts = [];
+	for (const oid of grandParentObjectIDs) {
+		// Since we're using a raw WHERE string, we need to construct this manually
+		const selectSQL = `SELECT ${oid.name} FROM ${utils.transformName(grandParentEntity.name)} WHERE ${grandParentWhereSubquery}`;
+		parts.push(`COALESCE(TO_NVARCHAR((${selectSQL})), '')`);
+	}
+
+	const concatLogic = parts.join(" || ', ' || ");
+	const grandParentKeyExpr = compositeKeyExpr(grandParentKeyBinding.map((k) => `(SELECT ${k} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhere})`));
+
+	return `COALESCE(NULLIF(${concatLogic}, ''), ${grandParentKeyExpr})`;
+}
+
+module.exports = {
+	toSQL,
+	getSkipCheckCondition,
+	getElementSkipCondition,
+	compositeKeyExpr,
+	wrapLargeString,
+	getValueExpr,
+	getWhereCondition,
+	getLabelExpr,
+	buildObjectIDExpr,
+	buildGrandParentObjectIDExpr
+};