rawsql-ts 0.11.1-beta → 0.11.2-beta

package/dist/src/transformers/PostgresArrayEntityCteBuilder.d.ts

@@ -1,104 +1,77 @@
 import { CommonTable } from '../models/Clause';
 import { JsonMapping } from './PostgresJsonQueryBuilder';
-import { ProcessableEntity } from './PostgresObjectEntityCteBuilder';
+import { ProcessableEntity, JsonColumnMapping } from './PostgresObjectEntityCteBuilder';
 /**
- * PostgreSQL-specific builder for creating CTEs for array entities (array relationships).
- * This class handles the creation of CTEs that build JSON/JSONB arrays for child entities,
- * processing them from the deepest level up to ensure proper dependency ordering.
+ * Builds CTEs for array entities using depth-first processing and row compression.
  *
- * Features:
- * - Depth-based CTE naming (cte_array_depth_N)
- * - Row compression using GROUP BY operations
- * - JSONB/JSON array aggregation
- * - Hierarchical processing of nested arrays
- * - Column exclusion to avoid duplication
- *
- * Why depth calculation is critical:
- * 1. Array entities can be nested at multiple levels. We must process the deepest
- *    (most distant) arrays first to ensure their JSON representations are available
- *    when building their parent arrays.
- * 2. Array entity processing is essentially a row compression operation using GROUP BY.
- *    Unlike parent entities which use column compression, arrays require grouping
- *    to aggregate multiple rows into JSON arrays.
- *
- * Example hierarchy:
- * Order (root, depth 0)
- *   └─ Items (array, depth 1)
- *       └─ Details (array, depth 2)
- *
- * Processing order: depth 2 → depth 1 → depth 0
+ * Core concepts:
+ * - Column Compression: OBJECT relationships (user_id, user_name → user_json)
+ * - Row Compression: ARRAY relationships (multiple rows → JSON array via GROUP BY)
+ * - Depth-First: Process deepest arrays first for dependency ordering
+ * - GROUP BY Exclusion: Exclude array-internal columns to prevent over-grouping
  */
 export declare class PostgresArrayEntityCteBuilder {
     private static readonly CTE_ARRAY_PREFIX;
+    private static readonly JSON_FUNCTIONS;
     /**
-     * Build CTEs for all array entities in the correct dependency order
-     * @param ctesSoFar Array of CTEs built so far (starts with the initial CTE)
-     * @param aliasOfCteToBuildUpon Alias of the CTE from which the current array CTE will select
+     * Builds CTEs for all array entities using depth-first processing.
+     * Collects arrays by depth, processes deepest first, chains CTEs.
+     *
+     * @param ctesSoFar Array of CTEs built so far
+     * @param aliasOfCteToBuildUpon Alias of the CTE to build upon
      * @param allEntities Map of all entities in the mapping
      * @param mapping The JSON mapping configuration
-     * @returns Object containing the updated list of all CTEs and the alias of the last CTE created
+     * @param columnMappings Optional mappings from object entity IDs to generated JSON column names
+     * @returns Object containing updated CTEs and last CTE alias
      */
-    buildArrayEntityCtes(ctesSoFar: CommonTable[], aliasOfCteToBuildUpon: string, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping): {
+    buildArrayEntityCtes(ctesSoFar: CommonTable[], aliasOfCteToBuildUpon: string, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping, columnMappings?: JsonColumnMapping[]): {
         updatedCtes: CommonTable[];
         lastCteAlias: string;
     };
     /**
-     * Collect all array entities and calculate their depth from root.
-     *
-     * Depth calculation ensures proper processing order where deeper nested
-     * arrays are processed first, making their aggregated data available
-     * for parent array processing.
+     * Collects array entities and calculates depth for dependency ordering.
+     * Depth = distance from root. Deeper arrays processed first.
      *
      * @param mapping The JSON mapping configuration
      * @param allEntities Map of all entities in the mapping
-     * @returns Array of array entity information with calculated depths, sorted deepest first
+     * @returns Array of array entity information with depths, sorted deepest first
      */
     private collectAndSortArrayEntities;
     /**
-     * Group array entities by their depth level.
-     *
-     * Grouping by depth allows us to:
-     * - Process all entities at the same level in a single CTE
-     * - Optimize query performance by reducing the number of CTEs
-     * - Maintain clear dependency ordering
+     * Groups array entities by depth level for batch processing.
      *
      * @param arrayInfos Array of array entity information with depths
      * @returns Map of depth level to entities at that depth
      */
     private groupEntitiesByDepth;
     /**
-     * Build a CTE that processes all array entities at a specific depth level.
-     *
-     * This method creates a single CTE that aggregates multiple array entities
-     * at the same depth, using GROUP BY to compress rows into JSON arrays.
+     * Builds CTE for specific depth level using row compression.
+     * Uses GROUP BY to aggregate multiple rows into JSON arrays.
+     * Excludes array-internal columns from GROUP BY to prevent over-grouping.
      *
      * @param infos Array entities at this depth level
      * @param currentCteAlias Alias of the CTE to build upon
      * @param currentCtes All CTEs built so far
      * @param depth Current depth level being processed
      * @param mapping JSON mapping configuration
+     * @param columnMappings Optional mappings from object entity IDs to generated JSON column names
      * @returns The new CTE and its alias
      */
     private buildDepthCte;
     /**
-     * Build JSON aggregation function for an array entity.
-     *
-     * This method creates a jsonb_agg or json_agg function call that aggregates
-     * the entity's columns into a JSON array. It also handles nested relationships
-     * by including child entity properties in the JSON object.
+     * Creates jsonb_agg function for array entity.
+     * Handles entity columns and nested child relationships.
+     * Uses originalPropertyName to avoid sequential numbering.
      *
      * @param entity The array entity being processed
      * @param nestedEntities All nested entities from the mapping
      * @param allEntities Map of all entities (not used in current implementation)
+     * @param columnMappings Mappings from object entity IDs to generated JSON column names
      * @returns Object containing the JSON aggregation function
      */
     private buildAggregationDetailsForArrayEntity;
     /**
-     * Collects array entity columns organized by depth for the GROUP BY exclusion strategy.
-     *
-     * This method creates a mapping from depth levels to sets of column names that belong to
-     * array entities at each depth. This is used to determine which columns should be excluded
-     * from GROUP BY clauses when performing array aggregation at specific depths.
+     * Collects array entity columns by depth for GROUP BY exclusion strategy.
      *
      * @param mapping The JSON mapping configuration containing all entities
      * @param currentDepth The current aggregation depth being processed
@@ -106,7 +79,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private collectArrayEntityColumnsByDepth;
     /**
-     * Calculates the depth of an entity in the hierarchy by traversing up to the root.
+     * Calculates entity depth by traversing up to root.
      *
      * @param entity The entity to calculate depth for
      * @param mapping The JSON mapping containing all entities
@@ -114,7 +87,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private calculateEntityDepth;
     /**
-     * Adds all columns from an entity to the specified depth set.
+     * Adds entity columns to depth set.
      *
      * @param entity The entity whose columns should be added
      * @param depth The depth level to add columns to
@@ -122,10 +95,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private addEntityColumnsToDepthSet;
     /**
-     * Recursively collects columns from all descendant entities under a parent entity.
-     *
-     * This method ensures that all nested entities (at any depth) under an array entity
-     * have their columns properly categorized by the array entity's depth level.
+     * Recursively collects columns from descendant entities.
      *
      * @param parentEntityId The ID of the parent entity
      * @param targetDepth The depth level to assign collected columns to
@@ -134,11 +104,8 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private collectDescendantColumns;
     /**
-     * Processes SELECT variables to determine which should be included in GROUP BY clauses.
-     *
-     * This method implements the core logic for deciding which columns from previous CTEs
-     * should be included in the GROUP BY clause when performing array aggregation. It handles
-     * special cases for JSON columns and applies depth-based filtering to prevent over-grouping.
+     * Implements GROUP BY exclusion strategy for array aggregation.
+     * Excludes current array columns and array-internal object JSON columns.
      *
      * @param prevSelects SELECT variables from the previous CTE
      * @param arrayColumns Columns that are being aggregated (should be excluded from GROUP BY)
@@ -146,14 +113,12 @@ export declare class PostgresArrayEntityCteBuilder {
      * @param currentDepth The current aggregation depth being processed
      * @param selectItems Output array for SELECT items
      * @param groupByItems Output array for GROUP BY items
+     * @param arrayInternalObjectColumns JSON columns from objects within arrays being processed
      */
     private processSelectVariablesForGroupBy;
     /**
-     * Determines whether a column should be included in the GROUP BY clause.
-     *
-     * This method applies depth-based filtering and special handling for JSON columns
-     * to prevent over-grouping during array aggregation. It implements heuristics for
-     * excluding columns that belong to nested entities within array contexts.
+     * Determines if column should be included in GROUP BY clause.
+     * Applies depth-based filtering and special handling for JSON columns.
      *
      * @param columnName The name of the column to evaluate
      * @param arrayEntitiesByDepth Map of depth levels to their column sets
@@ -162,11 +127,8 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private shouldIncludeColumnInGroupBy;
     /**
-     * Applies heuristics to determine if an entity JSON column should be included in GROUP BY.
-     *
-     * This method uses entity numbering patterns to identify deeply nested entities
-     * that should be excluded from GROUP BY when processing array aggregations.
-     * This is a simplified heuristic approach that works for current use cases.
+     * Applies heuristics for entity JSON column inclusion in GROUP BY.
+     * Uses entity numbering patterns to identify deeply nested entities.
      *
      * @param columnName The JSON column name (expected format: entity_N_json)
      * @param currentDepth The current aggregation depth

package/dist/src/transformers/PostgresArrayEntityCteBuilder.js

@@ -6,42 +6,27 @@ const SimpleSelectQuery_1 = require("../models/SimpleSelectQuery");
 const ValueComponent_1 = require("../models/ValueComponent");
 const SelectValueCollector_1 = require("./SelectValueCollector");
 /**
- * PostgreSQL-specific builder for creating CTEs for array entities (array relationships).
- * This class handles the creation of CTEs that build JSON/JSONB arrays for child entities,
- * processing them from the deepest level up to ensure proper dependency ordering.
+ * Builds CTEs for array entities using depth-first processing and row compression.
  *
- * Features:
- * - Depth-based CTE naming (cte_array_depth_N)
- * - Row compression using GROUP BY operations
- * - JSONB/JSON array aggregation
- * - Hierarchical processing of nested arrays
- * - Column exclusion to avoid duplication
- *
- * Why depth calculation is critical:
- * 1. Array entities can be nested at multiple levels. We must process the deepest
- *    (most distant) arrays first to ensure their JSON representations are available
- *    when building their parent arrays.
- * 2. Array entity processing is essentially a row compression operation using GROUP BY.
- *    Unlike parent entities which use column compression, arrays require grouping
- *    to aggregate multiple rows into JSON arrays.
- *
- * Example hierarchy:
- * Order (root, depth 0)
- *   └─ Items (array, depth 1)
- *       └─ Details (array, depth 2)
- *
- * Processing order: depth 2 → depth 1 → depth 0
+ * Core concepts:
+ * - Column Compression: OBJECT relationships (user_id, user_name → user_json)
+ * - Row Compression: ARRAY relationships (multiple rows → JSON array via GROUP BY)
+ * - Depth-First: Process deepest arrays first for dependency ordering
+ * - GROUP BY Exclusion: Exclude array-internal columns to prevent over-grouping
  */
 class PostgresArrayEntityCteBuilder {
     /**
-     * Build CTEs for all array entities in the correct dependency order
-     * @param ctesSoFar Array of CTEs built so far (starts with the initial CTE)
-     * @param aliasOfCteToBuildUpon Alias of the CTE from which the current array CTE will select
+     * Builds CTEs for all array entities using depth-first processing.
+     * Collects arrays by depth, processes deepest first, chains CTEs.
+     *
+     * @param ctesSoFar Array of CTEs built so far
+     * @param aliasOfCteToBuildUpon Alias of the CTE to build upon
      * @param allEntities Map of all entities in the mapping
      * @param mapping The JSON mapping configuration
-     * @returns Object containing the updated list of all CTEs and the alias of the last CTE created
+     * @param columnMappings Optional mappings from object entity IDs to generated JSON column names
+     * @returns Object containing updated CTEs and last CTE alias
      */
-    buildArrayEntityCtes(ctesSoFar, aliasOfCteToBuildUpon, allEntities, mapping) {
+    buildArrayEntityCtes(ctesSoFar, aliasOfCteToBuildUpon, allEntities, mapping, columnMappings) {
         let currentCtes = [...ctesSoFar];
         let currentCteAlias = aliasOfCteToBuildUpon;
         // Collect and sort array entities by depth
@@ -56,22 +41,19 @@ class PostgresArrayEntityCteBuilder {
         for (const depth of depths) {
             const infos = entitiesByDepth.get(depth);
             // Build CTE for all entities at this depth
-            const { cte, newCteAlias } = this.buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping);
+            const { cte, newCteAlias } = this.buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping, columnMappings);
             currentCtes.push(cte);
             currentCteAlias = newCteAlias;
         }
         return { updatedCtes: currentCtes, lastCteAlias: currentCteAlias };
     }
     /**
-     * Collect all array entities and calculate their depth from root.
-     *
-     * Depth calculation ensures proper processing order where deeper nested
-     * arrays are processed first, making their aggregated data available
-     * for parent array processing.
+     * Collects array entities and calculates depth for dependency ordering.
+     * Depth = distance from root. Deeper arrays processed first.
      *
      * @param mapping The JSON mapping configuration
      * @param allEntities Map of all entities in the mapping
-     * @returns Array of array entity information with calculated depths, sorted deepest first
+     * @returns Array of array entity information with depths, sorted deepest first
      */
     collectAndSortArrayEntities(mapping, allEntities) {
         const arrayEntityInfos = [];
@@ -113,12 +95,7 @@ class PostgresArrayEntityCteBuilder {
         return arrayEntityInfos;
     }
     /**
-     * Group array entities by their depth level.
-     *
-     * Grouping by depth allows us to:
-     * - Process all entities at the same level in a single CTE
-     * - Optimize query performance by reducing the number of CTEs
-     * - Maintain clear dependency ordering
+     * Groups array entities by depth level for batch processing.
      *
      * @param arrayInfos Array of array entity information with depths
      * @returns Map of depth level to entities at that depth
@@ -135,19 +112,19 @@ class PostgresArrayEntityCteBuilder {
         return entitiesByDepth;
     }
     /**
-     * Build a CTE that processes all array entities at a specific depth level.
-     *
-     * This method creates a single CTE that aggregates multiple array entities
-     * at the same depth, using GROUP BY to compress rows into JSON arrays.
+     * Builds CTE for specific depth level using row compression.
+     * Uses GROUP BY to aggregate multiple rows into JSON arrays.
+     * Excludes array-internal columns from GROUP BY to prevent over-grouping.
      *
      * @param infos Array entities at this depth level
      * @param currentCteAlias Alias of the CTE to build upon
      * @param currentCtes All CTEs built so far
      * @param depth Current depth level being processed
      * @param mapping JSON mapping configuration
+     * @param columnMappings Optional mappings from object entity IDs to generated JSON column names
      * @returns The new CTE and its alias
      */
-    buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping) {
+    buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping, columnMappings) {
         var _a;
         // Collect columns that will be compressed into arrays
         // This includes both direct columns and columns from nested entities within the array
@@ -186,12 +163,28 @@ class PostgresArrayEntityCteBuilder {
         });
         // Collect array entity columns organized by depth for GROUP BY exclusion strategy
         const arrayEntityColumns = this.collectArrayEntityColumnsByDepth(mapping, depth);
+        // Identify JSON columns from objects within the arrays being processed at this depth
+        const arrayInternalObjectColumns = new Set();
+        if (columnMappings) {
+            infos.forEach(info => {
+                // Find all object-type nested entities within this array entity
+                mapping.nestedEntities
+                    .filter(ne => ne.parentId === info.entity.id && ne.relationshipType === "object")
+                    .forEach(objectEntity => {
+                    // Find the corresponding JSON column mapping for this object entity
+                    const columnMapping = columnMappings.find(cm => cm.entityId === objectEntity.id);
+                    if (columnMapping) {
+                        arrayInternalObjectColumns.add(columnMapping.generatedColumnName);
+                    }
+                });
+            });
+        }
         // Process existing SELECT variables to determine which should be included in GROUP BY
-        this.processSelectVariablesForGroupBy(prevSelects, arrayColumns, arrayEntityColumns, depth, selectItems, groupByItems);
+        this.processSelectVariablesForGroupBy(prevSelects, arrayColumns, arrayEntityColumns, depth, selectItems, groupByItems, arrayInternalObjectColumns);
         // Add JSON aggregation columns for each array entity at this depth
         for (const info of infos) {
-            const agg = this.buildAggregationDetailsForArrayEntity(info.entity, mapping.nestedEntities, new Map() // allEntities - not needed for array aggregation
-            );
+            const agg = this.buildAggregationDetailsForArrayEntity(info.entity, mapping.nestedEntities, new Map(), // allEntities - not needed for array aggregation
+            columnMappings);
             selectItems.push(new Clause_1.SelectItem(agg.jsonAgg, info.entity.propertyName));
         }
         // Create the new CTE
@@ -205,20 +198,19 @@ class PostgresArrayEntityCteBuilder {
         return { cte, newCteAlias: cteAlias };
     }
     /**
-     * Build JSON aggregation function for an array entity.
-     *
-     * This method creates a jsonb_agg or json_agg function call that aggregates
-     * the entity's columns into a JSON array. It also handles nested relationships
-     * by including child entity properties in the JSON object.
+     * Creates jsonb_agg function for array entity.
+     * Handles entity columns and nested child relationships.
+     * Uses originalPropertyName to avoid sequential numbering.
      *
      * @param entity The array entity being processed
      * @param nestedEntities All nested entities from the mapping
      * @param allEntities Map of all entities (not used in current implementation)
+     * @param columnMappings Mappings from object entity IDs to generated JSON column names
      * @returns Object containing the JSON aggregation function
      */
-    buildAggregationDetailsForArrayEntity(entity, nestedEntities, allEntities) {
+    buildAggregationDetailsForArrayEntity(entity, nestedEntities, allEntities, columnMappings) {
         // Build JSON object for array elements using JSONB functions
-        const jsonBuildFunction = "jsonb_build_object";
+        const jsonBuildFunction = PostgresArrayEntityCteBuilder.JSON_FUNCTIONS.BUILD_OBJECT;
         const args = [];
         // Add the entity's own columns
         Object.entries(entity.columns).forEach(([jsonKey, sqlColumn]) => {
@@ -228,12 +220,54 @@ class PostgresArrayEntityCteBuilder {
         // Find and process child entities (both object and array types)
         const childEntities = nestedEntities.filter((ne) => ne.parentId === entity.id);
         childEntities.forEach((childEntity) => {
-            args.push(new ValueComponent_1.LiteralValue(childEntity.propertyName));
+            // Use originalPropertyName if available to avoid sequential numbering in final JSON
+            const propertyNameForJson = childEntity.originalPropertyName || childEntity.propertyName;
+            args.push(new ValueComponent_1.LiteralValue(propertyNameForJson));
             if (childEntity.relationshipType === "object") {
-                // For object relationships, use pre-computed JSON column
-                // Use entity ID instead of name to avoid naming conflicts
-                const jsonColumnName = `${childEntity.id.toLowerCase()}_json`;
-                args.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(jsonColumnName)));
+                // For object relationships, use pre-computed JSON column from column mappings
+                if (!columnMappings) {
+                    throw new Error(`❌ PostgresArrayEntityCteBuilder Error: Column mappings not provided\n` +
+                        `\n` +
+                        `🔍 Details:\n` +
+                        `  - Entity ID: ${childEntity.id}\n` +
+                        `  - Entity Name: ${childEntity.name || 'unknown'}\n` +
+                        `  - Property Name: ${childEntity.propertyName}\n` +
+                        `  - Relationship Type: ${childEntity.relationshipType}\n` +
+                        `\n` +
+                        `💡 Solution:\n` +
+                        `  Column mappings are required for hybrid JSON column naming.\n` +
+                        `  This error indicates that PostgresObjectEntityCteBuilder did not\n` +
+                        `  pass column mappings to PostgresArrayEntityCteBuilder.\n` +
+                        `\n` +
+                        `🔧 Check:\n` +
+                        `  1. Ensure PostgresJsonQueryBuilder.buildJsonWithCteStrategy() passes columnMappings\n` +
+                        `  2. Verify PostgresObjectEntityCteBuilder.buildObjectEntityCtes() returns columnMappings\n` +
+                        `  3. Check that Model-driven mapping conversion generates unique entity IDs`);
+                }
+                const mapping = columnMappings.find(m => m.entityId === childEntity.id);
+                if (!mapping) {
+                    const availableMappings = columnMappings.map(m => `${m.entityId} → ${m.generatedColumnName}`).join(', ');
+                    throw new Error(`❌ PostgresArrayEntityCteBuilder Error: Column mapping not found\n` +
+                        `\n` +
+                        `🔍 Details:\n` +
+                        `  - Looking for Entity ID: ${childEntity.id}\n` +
+                        `  - Entity Name: ${childEntity.name || 'unknown'}\n` +
+                        `  - Property Name: ${childEntity.propertyName}\n` +
+                        `  - Relationship Type: ${childEntity.relationshipType}\n` +
+                        `\n` +
+                        `📋 Available Mappings:\n` +
+                        `  ${availableMappings || 'None'}\n` +
+                        `\n` +
+                        `💡 Solution:\n` +
+                        `  Entity IDs must match between mapping generation and usage.\n` +
+                        `  This suggests a mismatch in entity ID generation or processing.\n` +
+                        `\n` +
+                        `🔧 Check:\n` +
+                        `  1. Model-driven mapping conversion generates consistent entity IDs\n` +
+                        `  2. PostgresObjectEntityCteBuilder processes all entities correctly\n` +
+                        `  3. Entity hierarchy and parentId relationships are correct`);
+                }
+                args.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(mapping.generatedColumnName)));
             }
             else if (childEntity.relationshipType === "array") {
                 // For array relationships, use the column directly
@@ -244,7 +278,7 @@ class PostgresArrayEntityCteBuilder {
         const jsonObject = new ValueComponent_1.FunctionCall(null, new ValueComponent_1.RawString(jsonBuildFunction), new ValueComponent_1.ValueList(args), null);
         // Create JSON aggregation using JSONB with NULL filtering
         // Use FILTER clause to exclude rows where primary key is NULL (no actual data)
-        const jsonAggFunction = "jsonb_agg";
+        const jsonAggFunction = PostgresArrayEntityCteBuilder.JSON_FUNCTIONS.AGGREGATE;
         // Find the primary column (typically the first column) to use for NULL filtering
         const primaryColumn = Object.values(entity.columns)[0];
         // For now, create standard jsonb_agg and handle NULL filtering in post-processing
@@ -253,11 +287,7 @@ class PostgresArrayEntityCteBuilder {
         return { jsonAgg };
     }
     /**
-     * Collects array entity columns organized by depth for the GROUP BY exclusion strategy.
-     *
-     * This method creates a mapping from depth levels to sets of column names that belong to
-     * array entities at each depth. This is used to determine which columns should be excluded
-     * from GROUP BY clauses when performing array aggregation at specific depths.
+     * Collects array entity columns by depth for GROUP BY exclusion strategy.
      *
      * @param mapping The JSON mapping configuration containing all entities
      * @param currentDepth The current aggregation depth being processed
@@ -266,7 +296,7 @@ class PostgresArrayEntityCteBuilder {
     collectArrayEntityColumnsByDepth(mapping, currentDepth) {
         const arrayEntitiesByDepth = new Map(); // Initialize depth maps for current and deeper levels
         // Use a reasonable maximum depth limit to avoid infinite loops
-        const maxDepth = Math.max(currentDepth + 3, 5); // Allow up to 3 additional levels or minimum 5 levels
+        const maxDepth = Math.max(currentDepth + 3, 5);
         for (let d = currentDepth; d <= maxDepth; d++) {
             arrayEntitiesByDepth.set(d, new Set());
         }
@@ -287,7 +317,7 @@ class PostgresArrayEntityCteBuilder {
         return arrayEntitiesByDepth;
     }
     /**
-     * Calculates the depth of an entity in the hierarchy by traversing up to the root.
+     * Calculates entity depth by traversing up to root.
      *
      * @param entity The entity to calculate depth for
      * @param mapping The JSON mapping containing all entities
@@ -303,7 +333,7 @@ class PostgresArrayEntityCteBuilder {
         return entityDepth;
     }
     /**
-     * Adds all columns from an entity to the specified depth set.
+     * Adds entity columns to depth set.
      *
      * @param entity The entity whose columns should be added
      * @param depth The depth level to add columns to
@@ -316,10 +346,7 @@ class PostgresArrayEntityCteBuilder {
         });
     }
     /**
-     * Recursively collects columns from all descendant entities under a parent entity.
-     *
-     * This method ensures that all nested entities (at any depth) under an array entity
-     * have their columns properly categorized by the array entity's depth level.
+     * Recursively collects columns from descendant entities.
      *
      * @param parentEntityId The ID of the parent entity
      * @param targetDepth The depth level to assign collected columns to
@@ -337,11 +364,8 @@ class PostgresArrayEntityCteBuilder {
         });
     }
     /**
-     * Processes SELECT variables to determine which should be included in GROUP BY clauses.
-     *
-     * This method implements the core logic for deciding which columns from previous CTEs
-     * should be included in the GROUP BY clause when performing array aggregation. It handles
-     * special cases for JSON columns and applies depth-based filtering to prevent over-grouping.
+     * Implements GROUP BY exclusion strategy for array aggregation.
+     * Excludes current array columns and array-internal object JSON columns.
      *
      * @param prevSelects SELECT variables from the previous CTE
      * @param arrayColumns Columns that are being aggregated (should be excluded from GROUP BY)
@@ -349,24 +373,30 @@ class PostgresArrayEntityCteBuilder {
      * @param currentDepth The current aggregation depth being processed
      * @param selectItems Output array for SELECT items
      * @param groupByItems Output array for GROUP BY items
+     * @param arrayInternalObjectColumns JSON columns from objects within arrays being processed
      */
-    processSelectVariablesForGroupBy(prevSelects, arrayColumns, arrayEntitiesByDepth, currentDepth, selectItems, groupByItems) {
+    processSelectVariablesForGroupBy(prevSelects, arrayColumns, arrayEntitiesByDepth, currentDepth, selectItems, groupByItems, arrayInternalObjectColumns) {
         prevSelects.forEach(sv => {
             if (!arrayColumns.has(sv.name)) {
+                // Exclude JSON columns from objects within arrays being processed
+                if (arrayInternalObjectColumns && arrayInternalObjectColumns.has(sv.name)) {
+                    // Skip this column - it's an object within the array being aggregated
+                    return;
+                }
                 const shouldInclude = this.shouldIncludeColumnInGroupBy(sv.name, arrayEntitiesByDepth, currentDepth);
                 if (shouldInclude) {
                     selectItems.push(new Clause_1.SelectItem(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sv.name)), sv.name));
-                    groupByItems.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sv.name)));
+                    // Exclude JSON columns from GROUP BY as PostgreSQL doesn't support equality operators for JSON type
+                    if (!sv.name.endsWith('_json')) {
+                        groupByItems.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sv.name)));
+                    }
                 }
             }
         });
     }
     /**
-     * Determines whether a column should be included in the GROUP BY clause.
-     *
-     * This method applies depth-based filtering and special handling for JSON columns
-     * to prevent over-grouping during array aggregation. It implements heuristics for
-     * excluding columns that belong to nested entities within array contexts.
+     * Determines if column should be included in GROUP BY clause.
+     * Applies depth-based filtering and special handling for JSON columns.
      *
      * @param columnName The name of the column to evaluate
      * @param arrayEntitiesByDepth Map of depth levels to their column sets
@@ -384,19 +414,19 @@ class PostgresArrayEntityCteBuilder {
                 break;
             }
         }
-        // Special handling for JSON columns to prevent over-grouping
-        if (isJsonColumn && columnName.startsWith('entity_')) {
-            shouldInclude = this.shouldIncludeJsonColumn(columnName, currentDepth);
+        // Critical: JSON columns from objects within arrays being processed 
+        // must be excluded from GROUP BY as they are aggregated within the array
+        if (isJsonColumn) {
+            // Legacy handling for entity_ prefixed JSON columns
+            if (columnName.startsWith('entity_')) {
+                shouldInclude = this.shouldIncludeJsonColumn(columnName, currentDepth);
+            }
         }
-        // Always include non-entity JSON columns (e.g., computed columns)
-        return shouldInclude || (isJsonColumn && !columnName.startsWith('entity_'));
+        return shouldInclude;
     }
     /**
-     * Applies heuristics to determine if an entity JSON column should be included in GROUP BY.
-     *
-     * This method uses entity numbering patterns to identify deeply nested entities
-     * that should be excluded from GROUP BY when processing array aggregations.
-     * This is a simplified heuristic approach that works for current use cases.
+     * Applies heuristics for entity JSON column inclusion in GROUP BY.
+     * Uses entity numbering patterns to identify deeply nested entities.
      *
      * @param columnName The JSON column name (expected format: entity_N_json)
      * @param currentDepth The current aggregation depth
@@ -420,4 +450,9 @@ class PostgresArrayEntityCteBuilder {
 exports.PostgresArrayEntityCteBuilder = PostgresArrayEntityCteBuilder;
 // Constants for consistent naming conventions
 PostgresArrayEntityCteBuilder.CTE_ARRAY_PREFIX = 'cte_array_depth_';
+// JSON function names for PostgreSQL aggregation
+PostgresArrayEntityCteBuilder.JSON_FUNCTIONS = {
+    BUILD_OBJECT: 'jsonb_build_object',
+    AGGREGATE: 'jsonb_agg'
+};
 //# sourceMappingURL=PostgresArrayEntityCteBuilder.js.map