@an5/orm 1.3.5 → 1.3.6

package/dist/generator/src/dotnet-generator.js

@@ -723,6 +723,14 @@ namespace An5Orm
             return FindFirst("Id = @id", new Dictionary<string, object> { { "id", id } });
         }
 
+        private static bool IsScalarColumn(PropertyInfo prop)
+        {
+            var t = Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType;
+            if (t.IsPrimitive || t.IsEnum || t.IsValueType) return true;
+            if (t == typeof(string) || t == typeof(byte[]) || t == typeof(float[]) || t == typeof(double[])) return true;
+            return false;
+        }
+
         public T Create(T entity)
         {
             var properties = typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance);
@@ -734,6 +742,7 @@ namespace An5Orm
 
             foreach (var prop in properties)
             {
+                if (!IsScalarColumn(prop)) continue;
                 var val = prop.GetValue(entity);
                 if (val != null)
                 {
@@ -775,6 +784,7 @@ namespace An5Orm
 
             foreach (var prop in properties)
             {
+                if (!IsScalarColumn(prop)) continue;
                 var val = prop.GetValue(entity);
                 if (prop.Name.Equals("Id", StringComparison.OrdinalIgnoreCase))
                 {
@@ -1053,6 +1063,98 @@ namespace An5Orm
             return output;
         }
 
+        public Dictionary<string, object> Aggregate(
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            bool count = false,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+        {
+            var selectParts = new List<string>();
+            if (count) selectParts.Add("COUNT(*) AS _count");
+            if (sum != null) foreach (var col in sum) selectParts.Add($"SUM({An5Provider.Quote(col, Dialect)}) AS _sum_{col}");
+            if (avg != null) foreach (var col in avg) selectParts.Add($"AVG({An5Provider.Quote(col, Dialect)}) AS _avg_{col}");
+            if (min != null) foreach (var col in min) selectParts.Add($"MIN({An5Provider.Quote(col, Dialect)}) AS _min_{col}");
+            if (max != null) foreach (var col in max) selectParts.Add($"MAX({An5Provider.Quote(col, Dialect)}) AS _max_{col}");
+            if (selectParts.Count == 0) selectParts.Add("COUNT(*) AS _count");
+
+            var query = $"SELECT {string.Join(", ", selectParts)} FROM {TableName}";
+            if (!string.IsNullOrEmpty(whereClause)) query += $" WHERE {whereClause}";
+
+            var conn = An5DbContext.GetActiveConnection(ConnectionString, out bool isTx);
+            try
+            {
+                using var cmd = CreateCommand(conn, query);
+                if (parameters != null)
+                {
+                    foreach (var kvp in parameters) An5Provider.Bind(cmd, kvp.Key, kvp.Value);
+                }
+                using var reader = cmd.ExecuteReader();
+                var result = new Dictionary<string, object>();
+                if (reader.Read())
+                {
+                    for (int i = 0; i < reader.FieldCount; i++)
+                    {
+                        var name = reader.GetName(i);
+                        var val = reader[i];
+                        result[name] = val != DBNull.Value ? val : null;
+                    }
+                }
+                return result;
+            }
+            finally { if (!isTx) conn.Dispose(); }
+        }
+
+        public List<Dictionary<string, object>> GroupBy(
+            List<string> by,
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+        {
+            if (by == null || by.Count == 0) throw new ArgumentException("GroupBy requires at least one column in 'by'");
+            var byCols = by.Select(c => An5Provider.Quote(c, Dialect)).ToList();
+            var selectParts = new List<string>(byCols);
+            selectParts.Add("COUNT(*) AS _count");
+            if (sum != null) foreach (var col in sum) selectParts.Add($"SUM({An5Provider.Quote(col, Dialect)}) AS _sum_{col}");
+            if (avg != null) foreach (var col in avg) selectParts.Add($"AVG({An5Provider.Quote(col, Dialect)}) AS _avg_{col}");
+            if (min != null) foreach (var col in min) selectParts.Add($"MIN({An5Provider.Quote(col, Dialect)}) AS _min_{col}");
+            if (max != null) foreach (var col in max) selectParts.Add($"MAX({An5Provider.Quote(col, Dialect)}) AS _max_{col}");
+
+            var query = $"SELECT {string.Join(", ", selectParts)} FROM {TableName}";
+            if (!string.IsNullOrEmpty(whereClause)) query += $" WHERE {whereClause}";
+            query += $" GROUP BY {string.Join(", ", byCols)}";
+
+            var conn = An5DbContext.GetActiveConnection(ConnectionString, out bool isTx);
+            try
+            {
+                using var cmd = CreateCommand(conn, query);
+                if (parameters != null)
+                {
+                    foreach (var kvp in parameters) An5Provider.Bind(cmd, kvp.Key, kvp.Value);
+                }
+                using var reader = cmd.ExecuteReader();
+                var rows = new List<Dictionary<string, object>>();
+                while (reader.Read())
+                {
+                    var row = new Dictionary<string, object>();
+                    for (int i = 0; i < reader.FieldCount; i++)
+                    {
+                        var name = reader.GetName(i);
+                        var val = reader[i];
+                        row[name] = val != DBNull.Value ? val : null;
+                    }
+                    rows.Add(row);
+                }
+                return rows;
+            }
+            finally { if (!isTx) conn.Dispose(); }
+        }
+
         private static List<double> ParseDoubleArray(string json)
         {
             var clean = json.Trim('[', ']');
@@ -1253,6 +1355,26 @@ namespace An5Orm
 
         public List<T> VectorSearch(List<double> vector, int take = 10, string whereClause = null, Dictionary<string, object> parameters = null, string vectorField = "Embedding", string distanceMetric = "cosine")
             => _table.VectorSearch(vector, take, whereClause, parameters, vectorField, distanceMetric);
+
+        public Dictionary<string, object> Aggregate(
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            bool count = false,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+            => _table.Aggregate(whereClause, parameters, count, sum, avg, min, max);
+
+        public List<Dictionary<string, object>> GroupBy(
+            List<string> by,
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+            => _table.GroupBy(by, whereClause, parameters, sum, avg, min, max);
     }
 }
 `;

package/dist/generator/src/golang-generator.js

@@ -266,14 +266,34 @@ type BoolFilter struct {
 
 // DateTimeFilter provides type-safe datetime field filtering options.
 type DateTimeFilter struct {
-\tEquals *time.Time
-\tNot    *time.Time
-\tIn     []time.Time
-\tNotIn  []time.Time
-\tGt     *time.Time
-\tGte    *time.Time
-\tLt     *time.Time
-\tLte    *time.Time
+	Equals *time.Time
+	Not    *time.Time
+	In     []time.Time
+	NotIn  []time.Time
+	Gt     *time.Time
+	Gte    *time.Time
+	Lt     *time.Time
+	Lte    *time.Time
+}
+
+// AggregateArgs configures an aggregate query.
+type AggregateArgs struct {
+	Where interface{}
+	Count bool
+	Sum   []string
+	Avg   []string
+	Min   []string
+	Max   []string
+}
+
+// GroupByArgs configures a GroupBy query.
+type GroupByArgs struct {
+	By    []string
+	Where interface{}
+	Sum   []string
+	Avg   []string
+	Min   []string
+	Max   []string
 }
 
 // Dialect identifies the database engine in use.
@@ -442,6 +462,16 @@ func (c *ViewClient[T]) VectorSearch(ctx context.Context, vector []float64, opts
 \treturn c.table.VectorSearch(ctx, vector, opts...)
 }
 
+// Aggregate returns aggregate calculations on the view.
+func (c *ViewClient[T]) Aggregate(ctx context.Context, args AggregateArgs) (map[string]interface{}, error) {
+\treturn c.table.Aggregate(ctx, args)
+}
+
+// GroupBy groups view rows by specified columns and computes aggregates.
+func (c *ViewClient[T]) GroupBy(ctx context.Context, args GroupByArgs) ([]map[string]interface{}, error) {
+\treturn c.table.GroupBy(ctx, args)
+}
+
 `;
     }
     // ─── queryAndScan ──────────────────────────────────────────────────────────
@@ -953,7 +983,7 @@ func (c *TableClient[T]) UpdateMany(ctx context.Context, whereArgs interface{},
 \t\tsets = append(sets, c.quoteName(col)+" = "+c.ph(len(execArgs)))
 \t}
 
-\tclause, _, _, _, _, whereQueryArgs := c.parseArgs(whereArgs)
+\tclause, _, _, _, _, whereQueryArgs := c.parseArgsWithOffset(whereArgs, len(execArgs)+1)
 \texecArgs = append(execArgs, whereQueryArgs...)
 \tquery := fmt.Sprintf("UPDATE %s SET %s", c.quoteTable(), strings.Join(sets, ", "))
 \tif clause != "" {
@@ -1038,9 +1068,129 @@ func (c *TableClient[T]) Transaction(ctx context.Context, fn func(tx *sql.Tx) er
 \treturn tx.Commit()
 }
 
+// Aggregate returns aggregate calculations (count, sum, avg, min, max).
+func (c *TableClient[T]) Aggregate(ctx context.Context, args AggregateArgs) (map[string]interface{}, error) {
+\tclause, _, _, _, _, queryArgs := c.parseArgs(args.Where)
+\tvar selectParts []string
+\tif args.Count || (len(args.Sum) == 0 && len(args.Avg) == 0 && len(args.Min) == 0 && len(args.Max) == 0) {
+\t\tselectParts = append(selectParts, "COUNT(*) AS _count")
+\t}
+\tfor _, col := range args.Sum {
+\t\tselectParts = append(selectParts, fmt.Sprintf("SUM(%s) AS _sum_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Avg {
+\t\tselectParts = append(selectParts, fmt.Sprintf("AVG(%s) AS _avg_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Min {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MIN(%s) AS _min_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Max {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MAX(%s) AS _max_%s", c.quoteName(col), col))
+\t}
+
+\tquery := fmt.Sprintf("SELECT %s FROM %s", strings.Join(selectParts, ", "), c.quoteTable())
+\tif clause != "" {
+\t\tquery += " WHERE " + clause
+\t}
+
+\trows, err := c.DB.QueryContext(ctx, query, queryArgs...)
+\tif err != nil {
+\t\treturn nil, err
+\t}
+\tdefer rows.Close()
+
+\tcols, err := rows.Columns()
+\tif err != nil {
+\t\treturn nil, err
+\t}
+
+\tres := make(map[string]interface{})
+\tif rows.Next() {
+\t\tcolVals := make([]interface{}, len(cols))
+\t\tcolPtrs := make([]interface{}, len(cols))
+\t\tfor i := range colVals {
+\t\t\tcolPtrs[i] = &colVals[i]
+\t\t}
+\t\tif err := rows.Scan(colPtrs...); err != nil {
+\t\t\treturn nil, err
+\t\t}
+\t\tfor i, name := range cols {
+\t\t\tres[name] = colVals[i]
+\t\t}
+\t}
+\treturn res, nil
+}
+
+// GroupBy groups records by specified columns and computes aggregates.
+func (c *TableClient[T]) GroupBy(ctx context.Context, args GroupByArgs) ([]map[string]interface{}, error) {
+\tif len(args.By) == 0 {
+\t\treturn nil, fmt.Errorf("GroupBy requires at least one column in 'By'")
+\t}
+\tclause, _, _, _, _, queryArgs := c.parseArgs(args.Where)
+\tbyCols := make([]string, len(args.By))
+\tfor i, col := range args.By {
+\t\tbyCols[i] = c.quoteName(col)
+\t}
+
+\tselectParts := make([]string, len(byCols))
+\tcopy(selectParts, byCols)
+\tselectParts = append(selectParts, "COUNT(*) AS _count")
+\tfor _, col := range args.Sum {
+\t\tselectParts = append(selectParts, fmt.Sprintf("SUM(%s) AS _sum_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Avg {
+\t\tselectParts = append(selectParts, fmt.Sprintf("AVG(%s) AS _avg_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Min {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MIN(%s) AS _min_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Max {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MAX(%s) AS _max_%s", c.quoteName(col), col))
+\t}
+
+\tquery := fmt.Sprintf("SELECT %s FROM %s", strings.Join(selectParts, ", "), c.quoteTable())
+\tif clause != "" {
+\t\tquery += " WHERE " + clause
+\t}
+\tquery += " GROUP BY " + strings.Join(byCols, ", ")
+
+\trows, err := c.DB.QueryContext(ctx, query, queryArgs...)
+\tif err != nil {
+\t\treturn nil, err
+\t}
+\tdefer rows.Close()
+
+\tcols, err := rows.Columns()
+\tif err != nil {
+\t\treturn nil, err
+\t}
+
+\tvar results []map[string]interface{}
+\tfor rows.Next() {
+\t\tcolVals := make([]interface{}, len(cols))
+\t\tcolPtrs := make([]interface{}, len(cols))
+\t\tfor i := range colVals {
+\t\t\tcolPtrs[i] = &colVals[i]
+\t\t}
+\t\tif err := rows.Scan(colPtrs...); err != nil {
+\t\t\treturn nil, err
+\t\t}
+\t\trowMap := make(map[string]interface{})
+\t\tfor i, name := range cols {
+\t\t\trowMap[name] = colVals[i]
+\t\t}
+\t\tresults = append(results, rowMap)
+\t}
+\treturn results, nil
+}
+
 // parseArgs is the generic where/orderBy/take/skip extractor.
 // It uses reflection to read WhereClause, OrderBy, Take, Skip, Select from any args struct.
 func (c *TableClient[T]) parseArgs(args interface{}) (whereClause string, orderBy string, take int, skip int, selectCols []string, queryArgs []interface{}) {
+\treturn c.parseArgsWithOffset(args, 1)
+}
+
+func (c *TableClient[T]) parseArgsWithOffset(args interface{}, offset int) (whereClause string, orderBy string, take int, skip int, selectCols []string, queryArgs []interface{}) {
 \tif args == nil {
 \t\treturn
 \t}
@@ -1057,10 +1207,18 @@ func (c *TableClient[T]) parseArgs(args interface{}) (whereClause string, orderB
 
 \t// Where
 \twhereField := v.FieldByName("Where")
-\tif whereField.IsValid() && !whereField.IsNil() {
-\t\t// where is a pointer to a model-specific WhereInput struct
-\t\t// Delegate to buildWhereFromStruct
-\t\twc, wa := c.buildWhereFromStruct(whereField.Elem(), 1)
+\tif whereField.IsValid() {
+\t\tif !whereField.IsNil() {
+\t\t\telem := whereField
+\t\t\tif elem.Kind() == reflect.Ptr {
+\t\t\t\telem = elem.Elem()
+\t\t\t}
+\t\t\twc, wa := c.buildWhereFromStruct(elem, offset)
+\t\t\twhereClause = wc
+\t\t\tqueryArgs = wa
+\t\t}
+\t} else {
+\t\twc, wa := c.buildWhereFromStruct(v, offset)
 \t\twhereClause = wc
 \t\tqueryArgs = wa
 \t}

package/dist/generator/src/python-generator.js

@@ -238,27 +238,24 @@ class PythonGenerator {
             content += '\n';
             // TypedDict row shape: mirrors what the runtime actually returns
             // (plain dicts), so `AdapterTableClient["<Model>Row"]` delegates
-            // type-check. Required keys stay required via a total=True base;
-            // everything else is optional (total=False), keeping partial
-            // selects valid without extra dependencies.
-            const rowRequired = model.fields.filter(f => !f.isOptional && !f.hasDefault);
-            const rowOptional = model.fields.filter(f => f.isOptional || f.hasDefault);
+            // type-check. All table columns are guaranteed keys in fetched rows
+            // (nullable columns take Optional[...] values); relations stay
+            // optional keys (total=False) because they are only present when
+            // joined/included.
             content += `class _${model.name}Required(TypedDict):\n`;
             content += `    """Required keys of a ${model.name} row."""\n`;
-            if (rowRequired.length === 0) {
+            if (model.fields.length === 0) {
                 content += '    pass\n';
             }
-            for (const f of rowRequired) {
-                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
+            for (const f of model.fields) {
+                const pyType = f.isOptional ? `Optional[${this.mapPyType(f)}]` : this.mapPyType(f);
+                content += `    ${this.toSnakeCase(f.name)}: ${pyType}\n`;
             }
             content += `\nclass ${model.name}Row(_${model.name}Required, total=False):\n`;
             content += `    """Row shape returned for ${model.name} queries."""\n`;
-            if (rowOptional.length === 0 && model.relations.length === 0) {
+            if (model.relations.length === 0) {
                 content += '    pass\n';
             }
-            for (const f of rowOptional) {
-                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
-            }
             for (const rel of model.relations) {
                 const relName = this.toSnakeCase(rel.name);
                 content += rel.isArray ? `    ${relName}: List[Any]\n` : `    ${relName}: Any\n`;
@@ -305,9 +302,9 @@ class PythonGenerator {
         content += `from an5_adapter import An5Adapter, AdapterTableClient${hasViews ? ', ViewClient' : ''}, create_an5_adapter, set_adapter_metadata\n\n`;
         const metadataModule = this.metadataModule();
         content += 'try:\n';
-        content += `    from .${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n`;
+        content += `    from .${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS, RELATION_MAP\n`;
         content += 'except ImportError:\n';
-        content += `    from ${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n\n`;
+        content += `    from ${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS, RELATION_MAP\n\n`;
         if (models.length > 0) {
             content += 'if TYPE_CHECKING:\n';
             for (const m of models) {
@@ -332,7 +329,7 @@ class PythonGenerator {
         content += '        conn_str = (connection_string or \n';
         content += '                    os.getenv("DATABASE_URL") or \n';
         content += '                    "Server=localhost;Database=master;Trusted_Connection=True;TrustServerCertificate=True;")\n';
-        content += '        set_adapter_metadata({"model_to_table": MODEL_TO_TABLE, "model_fields": MODEL_FIELDS})\n';
+        content += '        set_adapter_metadata({"model_to_table": MODEL_TO_TABLE, "model_fields": MODEL_FIELDS, "relation_map": RELATION_MAP})\n';
         content += '        self.adapter: An5Adapter = create_an5_adapter(conn_str)\n\n';
         for (const model of models) {
             const propName = this.toSnakeCase(model.name) + 's';

package/generator/src/dotnet-generator.ts

@@ -741,6 +741,14 @@ namespace An5Orm
             return FindFirst("Id = @id", new Dictionary<string, object> { { "id", id } });
         }
 
+        private static bool IsScalarColumn(PropertyInfo prop)
+        {
+            var t = Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType;
+            if (t.IsPrimitive || t.IsEnum || t.IsValueType) return true;
+            if (t == typeof(string) || t == typeof(byte[]) || t == typeof(float[]) || t == typeof(double[])) return true;
+            return false;
+        }
+
         public T Create(T entity)
         {
             var properties = typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance);
@@ -752,6 +760,7 @@ namespace An5Orm
 
             foreach (var prop in properties)
             {
+                if (!IsScalarColumn(prop)) continue;
                 var val = prop.GetValue(entity);
                 if (val != null)
                 {
@@ -793,6 +802,7 @@ namespace An5Orm
 
             foreach (var prop in properties)
             {
+                if (!IsScalarColumn(prop)) continue;
                 var val = prop.GetValue(entity);
                 if (prop.Name.Equals("Id", StringComparison.OrdinalIgnoreCase))
                 {
@@ -1071,6 +1081,98 @@ namespace An5Orm
             return output;
         }
 
+        public Dictionary<string, object> Aggregate(
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            bool count = false,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+        {
+            var selectParts = new List<string>();
+            if (count) selectParts.Add("COUNT(*) AS _count");
+            if (sum != null) foreach (var col in sum) selectParts.Add($"SUM({An5Provider.Quote(col, Dialect)}) AS _sum_{col}");
+            if (avg != null) foreach (var col in avg) selectParts.Add($"AVG({An5Provider.Quote(col, Dialect)}) AS _avg_{col}");
+            if (min != null) foreach (var col in min) selectParts.Add($"MIN({An5Provider.Quote(col, Dialect)}) AS _min_{col}");
+            if (max != null) foreach (var col in max) selectParts.Add($"MAX({An5Provider.Quote(col, Dialect)}) AS _max_{col}");
+            if (selectParts.Count == 0) selectParts.Add("COUNT(*) AS _count");
+
+            var query = $"SELECT {string.Join(", ", selectParts)} FROM {TableName}";
+            if (!string.IsNullOrEmpty(whereClause)) query += $" WHERE {whereClause}";
+
+            var conn = An5DbContext.GetActiveConnection(ConnectionString, out bool isTx);
+            try
+            {
+                using var cmd = CreateCommand(conn, query);
+                if (parameters != null)
+                {
+                    foreach (var kvp in parameters) An5Provider.Bind(cmd, kvp.Key, kvp.Value);
+                }
+                using var reader = cmd.ExecuteReader();
+                var result = new Dictionary<string, object>();
+                if (reader.Read())
+                {
+                    for (int i = 0; i < reader.FieldCount; i++)
+                    {
+                        var name = reader.GetName(i);
+                        var val = reader[i];
+                        result[name] = val != DBNull.Value ? val : null;
+                    }
+                }
+                return result;
+            }
+            finally { if (!isTx) conn.Dispose(); }
+        }
+
+        public List<Dictionary<string, object>> GroupBy(
+            List<string> by,
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+        {
+            if (by == null || by.Count == 0) throw new ArgumentException("GroupBy requires at least one column in 'by'");
+            var byCols = by.Select(c => An5Provider.Quote(c, Dialect)).ToList();
+            var selectParts = new List<string>(byCols);
+            selectParts.Add("COUNT(*) AS _count");
+            if (sum != null) foreach (var col in sum) selectParts.Add($"SUM({An5Provider.Quote(col, Dialect)}) AS _sum_{col}");
+            if (avg != null) foreach (var col in avg) selectParts.Add($"AVG({An5Provider.Quote(col, Dialect)}) AS _avg_{col}");
+            if (min != null) foreach (var col in min) selectParts.Add($"MIN({An5Provider.Quote(col, Dialect)}) AS _min_{col}");
+            if (max != null) foreach (var col in max) selectParts.Add($"MAX({An5Provider.Quote(col, Dialect)}) AS _max_{col}");
+
+            var query = $"SELECT {string.Join(", ", selectParts)} FROM {TableName}";
+            if (!string.IsNullOrEmpty(whereClause)) query += $" WHERE {whereClause}";
+            query += $" GROUP BY {string.Join(", ", byCols)}";
+
+            var conn = An5DbContext.GetActiveConnection(ConnectionString, out bool isTx);
+            try
+            {
+                using var cmd = CreateCommand(conn, query);
+                if (parameters != null)
+                {
+                    foreach (var kvp in parameters) An5Provider.Bind(cmd, kvp.Key, kvp.Value);
+                }
+                using var reader = cmd.ExecuteReader();
+                var rows = new List<Dictionary<string, object>>();
+                while (reader.Read())
+                {
+                    var row = new Dictionary<string, object>();
+                    for (int i = 0; i < reader.FieldCount; i++)
+                    {
+                        var name = reader.GetName(i);
+                        var val = reader[i];
+                        row[name] = val != DBNull.Value ? val : null;
+                    }
+                    rows.Add(row);
+                }
+                return rows;
+            }
+            finally { if (!isTx) conn.Dispose(); }
+        }
+
         private static List<double> ParseDoubleArray(string json)
         {
             var clean = json.Trim('[', ']');
@@ -1271,6 +1373,26 @@ namespace An5Orm
 
         public List<T> VectorSearch(List<double> vector, int take = 10, string whereClause = null, Dictionary<string, object> parameters = null, string vectorField = "Embedding", string distanceMetric = "cosine")
             => _table.VectorSearch(vector, take, whereClause, parameters, vectorField, distanceMetric);
+
+        public Dictionary<string, object> Aggregate(
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            bool count = false,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+            => _table.Aggregate(whereClause, parameters, count, sum, avg, min, max);
+
+        public List<Dictionary<string, object>> GroupBy(
+            List<string> by,
+            string whereClause = null,
+            Dictionary<string, object> parameters = null,
+            List<string> sum = null,
+            List<string> avg = null,
+            List<string> min = null,
+            List<string> max = null)
+            => _table.GroupBy(by, whereClause, parameters, sum, avg, min, max);
     }
 }
 `;

package/generator/src/golang-generator.ts

@@ -273,14 +273,34 @@ type BoolFilter struct {
 
 // DateTimeFilter provides type-safe datetime field filtering options.
 type DateTimeFilter struct {
-\tEquals *time.Time
-\tNot    *time.Time
-\tIn     []time.Time
-\tNotIn  []time.Time
-\tGt     *time.Time
-\tGte    *time.Time
-\tLt     *time.Time
-\tLte    *time.Time
+	Equals *time.Time
+	Not    *time.Time
+	In     []time.Time
+	NotIn  []time.Time
+	Gt     *time.Time
+	Gte    *time.Time
+	Lt     *time.Time
+	Lte    *time.Time
+}
+
+// AggregateArgs configures an aggregate query.
+type AggregateArgs struct {
+	Where interface{}
+	Count bool
+	Sum   []string
+	Avg   []string
+	Min   []string
+	Max   []string
+}
+
+// GroupByArgs configures a GroupBy query.
+type GroupByArgs struct {
+	By    []string
+	Where interface{}
+	Sum   []string
+	Avg   []string
+	Min   []string
+	Max   []string
 }
 
 // Dialect identifies the database engine in use.
@@ -458,6 +478,16 @@ func (c *ViewClient[T]) VectorSearch(ctx context.Context, vector []float64, opts
 \treturn c.table.VectorSearch(ctx, vector, opts...)
 }
 
+// Aggregate returns aggregate calculations on the view.
+func (c *ViewClient[T]) Aggregate(ctx context.Context, args AggregateArgs) (map[string]interface{}, error) {
+\treturn c.table.Aggregate(ctx, args)
+}
+
+// GroupBy groups view rows by specified columns and computes aggregates.
+func (c *ViewClient[T]) GroupBy(ctx context.Context, args GroupByArgs) ([]map[string]interface{}, error) {
+\treturn c.table.GroupBy(ctx, args)
+}
+
 `;
   }
 
@@ -976,7 +1006,7 @@ func (c *TableClient[T]) UpdateMany(ctx context.Context, whereArgs interface{},
 \t\tsets = append(sets, c.quoteName(col)+" = "+c.ph(len(execArgs)))
 \t}
 
-\tclause, _, _, _, _, whereQueryArgs := c.parseArgs(whereArgs)
+\tclause, _, _, _, _, whereQueryArgs := c.parseArgsWithOffset(whereArgs, len(execArgs)+1)
 \texecArgs = append(execArgs, whereQueryArgs...)
 \tquery := fmt.Sprintf("UPDATE %s SET %s", c.quoteTable(), strings.Join(sets, ", "))
 \tif clause != "" {
@@ -1061,9 +1091,129 @@ func (c *TableClient[T]) Transaction(ctx context.Context, fn func(tx *sql.Tx) er
 \treturn tx.Commit()
 }
 
+// Aggregate returns aggregate calculations (count, sum, avg, min, max).
+func (c *TableClient[T]) Aggregate(ctx context.Context, args AggregateArgs) (map[string]interface{}, error) {
+\tclause, _, _, _, _, queryArgs := c.parseArgs(args.Where)
+\tvar selectParts []string
+\tif args.Count || (len(args.Sum) == 0 && len(args.Avg) == 0 && len(args.Min) == 0 && len(args.Max) == 0) {
+\t\tselectParts = append(selectParts, "COUNT(*) AS _count")
+\t}
+\tfor _, col := range args.Sum {
+\t\tselectParts = append(selectParts, fmt.Sprintf("SUM(%s) AS _sum_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Avg {
+\t\tselectParts = append(selectParts, fmt.Sprintf("AVG(%s) AS _avg_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Min {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MIN(%s) AS _min_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Max {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MAX(%s) AS _max_%s", c.quoteName(col), col))
+\t}
+
+\tquery := fmt.Sprintf("SELECT %s FROM %s", strings.Join(selectParts, ", "), c.quoteTable())
+\tif clause != "" {
+\t\tquery += " WHERE " + clause
+\t}
+
+\trows, err := c.DB.QueryContext(ctx, query, queryArgs...)
+\tif err != nil {
+\t\treturn nil, err
+\t}
+\tdefer rows.Close()
+
+\tcols, err := rows.Columns()
+\tif err != nil {
+\t\treturn nil, err
+\t}
+
+\tres := make(map[string]interface{})
+\tif rows.Next() {
+\t\tcolVals := make([]interface{}, len(cols))
+\t\tcolPtrs := make([]interface{}, len(cols))
+\t\tfor i := range colVals {
+\t\t\tcolPtrs[i] = &colVals[i]
+\t\t}
+\t\tif err := rows.Scan(colPtrs...); err != nil {
+\t\t\treturn nil, err
+\t\t}
+\t\tfor i, name := range cols {
+\t\t\tres[name] = colVals[i]
+\t\t}
+\t}
+\treturn res, nil
+}
+
+// GroupBy groups records by specified columns and computes aggregates.
+func (c *TableClient[T]) GroupBy(ctx context.Context, args GroupByArgs) ([]map[string]interface{}, error) {
+\tif len(args.By) == 0 {
+\t\treturn nil, fmt.Errorf("GroupBy requires at least one column in 'By'")
+\t}
+\tclause, _, _, _, _, queryArgs := c.parseArgs(args.Where)
+\tbyCols := make([]string, len(args.By))
+\tfor i, col := range args.By {
+\t\tbyCols[i] = c.quoteName(col)
+\t}
+
+\tselectParts := make([]string, len(byCols))
+\tcopy(selectParts, byCols)
+\tselectParts = append(selectParts, "COUNT(*) AS _count")
+\tfor _, col := range args.Sum {
+\t\tselectParts = append(selectParts, fmt.Sprintf("SUM(%s) AS _sum_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Avg {
+\t\tselectParts = append(selectParts, fmt.Sprintf("AVG(%s) AS _avg_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Min {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MIN(%s) AS _min_%s", c.quoteName(col), col))
+\t}
+\tfor _, col := range args.Max {
+\t\tselectParts = append(selectParts, fmt.Sprintf("MAX(%s) AS _max_%s", c.quoteName(col), col))
+\t}
+
+\tquery := fmt.Sprintf("SELECT %s FROM %s", strings.Join(selectParts, ", "), c.quoteTable())
+\tif clause != "" {
+\t\tquery += " WHERE " + clause
+\t}
+\tquery += " GROUP BY " + strings.Join(byCols, ", ")
+
+\trows, err := c.DB.QueryContext(ctx, query, queryArgs...)
+\tif err != nil {
+\t\treturn nil, err
+\t}
+\tdefer rows.Close()
+
+\tcols, err := rows.Columns()
+\tif err != nil {
+\t\treturn nil, err
+\t}
+
+\tvar results []map[string]interface{}
+\tfor rows.Next() {
+\t\tcolVals := make([]interface{}, len(cols))
+\t\tcolPtrs := make([]interface{}, len(cols))
+\t\tfor i := range colVals {
+\t\t\tcolPtrs[i] = &colVals[i]
+\t\t}
+\t\tif err := rows.Scan(colPtrs...); err != nil {
+\t\t\treturn nil, err
+\t\t}
+\t\trowMap := make(map[string]interface{})
+\t\tfor i, name := range cols {
+\t\t\trowMap[name] = colVals[i]
+\t\t}
+\t\tresults = append(results, rowMap)
+\t}
+\treturn results, nil
+}
+
 // parseArgs is the generic where/orderBy/take/skip extractor.
 // It uses reflection to read WhereClause, OrderBy, Take, Skip, Select from any args struct.
 func (c *TableClient[T]) parseArgs(args interface{}) (whereClause string, orderBy string, take int, skip int, selectCols []string, queryArgs []interface{}) {
+\treturn c.parseArgsWithOffset(args, 1)
+}
+
+func (c *TableClient[T]) parseArgsWithOffset(args interface{}, offset int) (whereClause string, orderBy string, take int, skip int, selectCols []string, queryArgs []interface{}) {
 \tif args == nil {
 \t\treturn
 \t}
@@ -1080,10 +1230,18 @@ func (c *TableClient[T]) parseArgs(args interface{}) (whereClause string, orderB
 
 \t// Where
 \twhereField := v.FieldByName("Where")
-\tif whereField.IsValid() && !whereField.IsNil() {
-\t\t// where is a pointer to a model-specific WhereInput struct
-\t\t// Delegate to buildWhereFromStruct
-\t\twc, wa := c.buildWhereFromStruct(whereField.Elem(), 1)
+\tif whereField.IsValid() {
+\t\tif !whereField.IsNil() {
+\t\t\telem := whereField
+\t\t\tif elem.Kind() == reflect.Ptr {
+\t\t\t\telem = elem.Elem()
+\t\t\t}
+\t\t\twc, wa := c.buildWhereFromStruct(elem, offset)
+\t\t\twhereClause = wc
+\t\t\tqueryArgs = wa
+\t\t}
+\t} else {
+\t\twc, wa := c.buildWhereFromStruct(v, offset)
 \t\twhereClause = wc
 \t\tqueryArgs = wa
 \t}

package/generator/src/python-generator.ts

@@ -271,27 +271,24 @@ export class PythonGenerator {
 
       // TypedDict row shape: mirrors what the runtime actually returns
       // (plain dicts), so `AdapterTableClient["<Model>Row"]` delegates
-      // type-check. Required keys stay required via a total=True base;
-      // everything else is optional (total=False), keeping partial
-      // selects valid without extra dependencies.
-      const rowRequired = model.fields.filter(f => !f.isOptional && !f.hasDefault);
-      const rowOptional = model.fields.filter(f => f.isOptional || f.hasDefault);
+      // type-check. All table columns are guaranteed keys in fetched rows
+      // (nullable columns take Optional[...] values); relations stay
+      // optional keys (total=False) because they are only present when
+      // joined/included.
       content += `class _${model.name}Required(TypedDict):\n`;
       content += `    """Required keys of a ${model.name} row."""\n`;
-      if (rowRequired.length === 0) {
+      if (model.fields.length === 0) {
         content += '    pass\n';
       }
-      for (const f of rowRequired) {
-        content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
+      for (const f of model.fields) {
+        const pyType = f.isOptional ? `Optional[${this.mapPyType(f)}]` : this.mapPyType(f);
+        content += `    ${this.toSnakeCase(f.name)}: ${pyType}\n`;
       }
       content += `\nclass ${model.name}Row(_${model.name}Required, total=False):\n`;
       content += `    """Row shape returned for ${model.name} queries."""\n`;
-      if (rowOptional.length === 0 && model.relations.length === 0) {
+      if (model.relations.length === 0) {
         content += '    pass\n';
       }
-      for (const f of rowOptional) {
-        content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
-      }
       for (const rel of model.relations) {
         const relName = this.toSnakeCase(rel.name);
         content += rel.isArray ? `    ${relName}: List[Any]\n` : `    ${relName}: Any\n`;
@@ -343,9 +340,9 @@ export class PythonGenerator {
 
     const metadataModule = this.metadataModule();
     content += 'try:\n';
-    content += `    from .${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n`;
+    content += `    from .${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS, RELATION_MAP\n`;
     content += 'except ImportError:\n';
-    content += `    from ${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n\n`;
+    content += `    from ${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS, RELATION_MAP\n\n`;
 
     if (models.length > 0) {
       content += 'if TYPE_CHECKING:\n';
@@ -372,7 +369,7 @@ export class PythonGenerator {
     content += '        conn_str = (connection_string or \n';
     content += '                    os.getenv("DATABASE_URL") or \n';
     content += '                    "Server=localhost;Database=master;Trusted_Connection=True;TrustServerCertificate=True;")\n';
-    content += '        set_adapter_metadata({"model_to_table": MODEL_TO_TABLE, "model_fields": MODEL_FIELDS})\n';
+    content += '        set_adapter_metadata({"model_to_table": MODEL_TO_TABLE, "model_fields": MODEL_FIELDS, "relation_map": RELATION_MAP})\n';
     content += '        self.adapter: An5Adapter = create_an5_adapter(conn_str)\n\n';
 
     for (const model of models) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@an5/orm",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "The lightweight ORM for SQL Server with support for TypeScript, Python, .NET (C#), Go, Rust, Java, Kotlin, and Swift.",
   "license": "MIT",
   "bin": {