Merge branch 'main' into dev/aaronburtle/fix-schema-validation-no-entities

Author: souvikghosh04

schemas/dab.draft.schema.json

@@ -280,6 +280,10 @@
               "description": "Allow enabling/disabling MCP requests for all entities.",
               "default": true
             },
+            "description": {
+              "type": "string",
+              "description": "Description of the MCP server, exposed as the 'instructions' field in the MCP initialize response to provide behavioral context to MCP clients and agents."
+            },
             "dml-tools": {
               "description": "Configuration for MCP Data Manipulation Language (DML) tools. Set to true/false to enable/disable all tools, or use an object to configure individual tools.",
               "oneOf": [

src/Azure.DataApiBuilder.Mcp/BuiltInTools/AggregateRecordsTool.cs

@@ -45,13 +45,24 @@ public class AggregateRecordsTool : IMcpTool
         {
             Name = "aggregate_records",
             Description = "Computes aggregations (count, avg, sum, min, max) on entity data. "
-                + "WORKFLOW: 1) Call describe_entities first to get entity names and field names. "
-                + "2) Call this tool with entity, function, and field from step 1. "
-                + "RULES: field '*' is ONLY valid with count. "
-                + "orderby, having, first, and after ONLY apply when groupby is provided. "
-                + "RESPONSE: Result is aliased as '{function}_{field}' (e.g. avg_unitPrice). "
-                + "For count(*), the alias is 'count'. "
-                + "With groupby and first, response includes items, endCursor, and hasNextPage for pagination.",
+                + "Prerequisite: 1) Call describe_entities in the current session to discover valid entity names and field names. "
+                + "2) Call this tool using only names returned by that call. "
+                + "Do not use entity or field names from memory, prior conversations, or assumptions. "
+                + "count supports field * to count all rows. "
+                + "avg, sum, min, and max must reference a field with a numeric data type as returned by describe_entities. "
+                + "distinct removes duplicate values before aggregation and is not valid with field *. "
+                + "filter applies an OData WHERE clause before aggregation. Supported operators: eq, ne, gt, ge, lt, le, and, or, not. "
+                + "String pattern operators such as startswith, endswith, contains, and regex are NOT supported. "
+                + "Use groupby to compute aggregated rows per group. All groupby fields must exist on the entity and must be discovered through describe_entities. "
+                + "Grouped results include the groupby fields and the aggregated value. "
+                + "orderby, having, first, and after apply only when groupby is present. "
+                + "orderby controls the sort direction of groups based on the aggregation result value. Allowed values are 'asc' and 'desc'; if omitted, 'desc' is used. It cannot sort by entity fields. "
+                + "having filters groups based on the aggregated value produced by the function. Supported operators: eq, neq, gt, gte, lt, lte, in. "
+                + "When groupby and first are used together, the response includes items, endCursor, and hasNextPage. "
+                + "To retrieve the next page, pass the returned endCursor value as the after parameter in a subsequent call with the same inputs. "
+                + "Aggregated values are aliased as {function}_{field} (example: avg_unitPrice). "
+                + "count(*) is the sole exception to this pattern and returns the alias 'count', not count_*. "
+                + "If the call fails due to an unrecognized entity or field name, call describe_entities again to verify valid names, then retry with corrected inputs.",
             InputSchema = JsonSerializer.Deserialize<JsonElement>(
                 @"{
                     ""type"": ""object"",
@@ -67,32 +78,32 @@ public class AggregateRecordsTool : IMcpTool
                         },
                         ""field"": {
                             ""type"": ""string"",
-                            ""description"": ""Field name to aggregate, or '*' with count to count all rows.""
+                            ""description"": ""Field name to aggregate, or * with count to count all rows.""
                         },
                         ""distinct"": {
                             ""type"": ""boolean"",
-                            ""description"": ""Remove duplicate values before aggregating. Not valid with field '*'."",
+                            ""description"": ""Remove duplicate values before aggregating. Not valid with field *."",
                             ""default"": false
                         },
                         ""filter"": {
                             ""type"": ""string"",
-                            ""description"": ""OData WHERE clause applied before aggregating. Operators: eq, ne, gt, ge, lt, le, and, or, not. Example: 'unitPrice lt 10'."",
+                            ""description"": ""OData WHERE clause applied before aggregating. Operators: eq, ne, gt, ge, lt, le, and, or, not. String pattern operators such as startswith, endswith, contains, and regex are not supported. Example: unitPrice lt 10."",
                             ""default"": """"
                         },
                         ""groupby"": {
                             ""type"": ""array"",
                             ""items"": { ""type"": ""string"" },
-                            ""description"": ""Field names to group by. Each unique combination produces one aggregated row. Enables orderby, having, first, and after."",
+                            ""description"": ""Field names to group by. Each unique combination produces one aggregated row that includes the group fields and the aggregated value. Enables orderby, having, first, and after."",
                             ""default"": []
                         },
                         ""orderby"": {
                             ""type"": ""string"",
                             ""enum"": [""asc"", ""desc""],
-                            ""description"": ""Sort direction for grouped results by the aggregated value. Only applies when groupby is provided; ignored otherwise.""
+                            ""description"": ""Sort direction for grouped results by the aggregated value (ascending or descending). Requires groupby. Cannot sort by entity fields. If omitted, the default sort direction is used.""
                         },
                         ""having"": {
                             ""type"": ""object"",
-                            ""description"": ""Filter groups by the aggregated value (HAVING clause). Requires groupby. Multiple operators are AND-ed."",
+                            ""description"": ""Filter groups by the aggregated value (HAVING clause). Supported operators: eq, neq, gt, gte, lt, lte, in. Requires groupby. Multiple operators are AND-ed."",
                             ""properties"": {
                                 ""eq"":  { ""type"": ""number"", ""description"": ""Equals."" },
                                 ""neq"": { ""type"": ""number"", ""description"": ""Not equals."" },
@@ -109,7 +120,7 @@ public class AggregateRecordsTool : IMcpTool
                         },
                         ""first"": {
                             ""type"": ""integer"",
-                            ""description"": ""Max grouped results to return. Requires groupby. Enables paginated response with endCursor and hasNextPage."",
+                            ""description"": ""Max grouped results to return. Requires groupby. Enables cursor pagination with endCursor and hasNextPage."",
                             ""minimum"": 1
                         },
                         ""after"": {

src/Cli/ConfigGenerator.cs

@@ -3288,7 +3288,7 @@ public static bool TrySimulateAutoentities(AutoConfigSimulateOptions options, Fi
 
             if (runtimeConfig.DataSource.DatabaseType != DatabaseType.MSSQL)
             {
-                _logger.LogError("Autoentities simulation is only supported for MSSQL databases. Current database type: {DatabaseType}.", runtimeConfig.DataSource.DatabaseType);
+                _logger.LogError("The autoentities simulation is only supported for MSSQL databases. Current database type: {DatabaseType}.", runtimeConfig.DataSource.DatabaseType);
                 return false;
             }
 
@@ -3380,7 +3380,7 @@ public static bool TrySimulateAutoentities(AutoConfigSimulateOptions options, Fi
         /// <param name="results">The simulation results keyed by filter (definition) name.</param>
         private static void WriteSimulationResultsToConsole(Dictionary<string, List<(string EntityName, string SchemaName, string ObjectName)>> results)
         {
-            Console.WriteLine("AutoEntities Simulation Results");
+            Console.WriteLine("Autoentities Simulation Results");
             Console.WriteLine();
 
             foreach ((string filterName, List<(string EntityName, string SchemaName, string ObjectName)> matches) in results)

src/Config/ObjectModel/RuntimeConfig.cs

@@ -507,7 +507,7 @@ public string GetDataSourceNameFromAutoentityName(string autoentityName)
         if (!_autoentityNameToDataSourceName.TryGetValue(autoentityName, out string? autoentityDataSource))
         {
             throw new DataApiBuilderException(
-                message: $"{autoentityName} is not a valid autoentity.",
+                message: $"'{autoentityName}' is not a valid autoentities definition.",
                 statusCode: HttpStatusCode.NotFound,
                 subStatusCode: DataApiBuilderException.SubStatusCodes.EntityNotFound);
         }

src/Core/Resolvers/QueryExecutor.cs

@@ -293,8 +293,11 @@ public virtual TConnection CreateConnection(string dataSourceName)
                 TResult? result = default(TResult);
                 try
                 {
-                    using DbDataReader dbDataReader = ConfigProvider.GetConfig().MaxResponseSizeLogicEnabled() ?
-                        await cmd.ExecuteReaderAsync(CommandBehavior.SequentialAccess) : await cmd.ExecuteReaderAsync(CommandBehavior.CloseConnection);
+                    CommandBehavior commandBehavior = ConfigProvider.GetConfig().MaxResponseSizeLogicEnabled() ? CommandBehavior.SequentialAccess : CommandBehavior.CloseConnection;
+                    // CancellationToken is passed to ExecuteReaderAsync to ensure that if the client times out while the query is executing, the execution will be cancelled and resources will be freed up.
+                    CancellationToken cancellationToken = httpContext?.RequestAborted ?? CancellationToken.None;
+                    using DbDataReader dbDataReader = await cmd.ExecuteReaderAsync(commandBehavior, cancellationToken);
+
                     if (dataReaderHandler is not null && dbDataReader is not null)
                     {
                         result = await dataReaderHandler(dbDataReader, args);

src/Core/Services/MetadataProviders/MsSqlMetadataProvider.cs

@@ -305,7 +305,7 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
             foreach ((string autoentityName, Autoentity autoentity) in autoentities)
             {
                 int addedEntities = 0;
-                JsonArray? resultArray = await QueryAutoentitiesAsync(autoentity);
+                JsonArray? resultArray = await QueryAutoentitiesAsync(autoentityName, autoentity);
                 if (resultArray is null)
                 {
                     continue;
@@ -316,7 +316,7 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
                     if (resultObject is null)
                     {
                         throw new DataApiBuilderException(
-                            message: $"Cannot create new entity from autoentity pattern due to an internal error.",
+                            message: $"Cannot create new entity from autoentities definition '{autoentityName}' due to an internal error.",
                             statusCode: HttpStatusCode.InternalServerError,
                             subStatusCode: DataApiBuilderException.SubStatusCodes.ErrorInInitialization);
                     }
@@ -329,7 +329,7 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
 
                     if (string.IsNullOrWhiteSpace(entityName) || string.IsNullOrWhiteSpace(objectName) || string.IsNullOrWhiteSpace(schemaName))
                     {
-                        _logger.LogError("Skipping autoentity generation: entity_name or object is null or empty for autoentity pattern '{AutoentityName}'.", autoentityName);
+                        _logger.LogError("Skipping autoentity generation: 'entity_name', 'object', or 'schema' is null or empty for autoentities definition '{autoentityName}'.", autoentityName);
                         continue;
                     }
 
@@ -357,7 +357,7 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
                     if (!entities.TryAdd(entityName, generatedEntity) || !runtimeConfig.TryAddGeneratedAutoentityNameToDataSourceName(entityName, autoentityName))
                     {
                         throw new DataApiBuilderException(
-                            message: $"Entity with name '{entityName}' already exists. Cannot create new entity from autoentity pattern with definition-name '{autoentityName}'.",
+                            message: $"Entity with name '{entityName}' already exists. Cannot create new entity from autoentities definition '{autoentityName}'.",
                             statusCode: HttpStatusCode.BadRequest,
                             subStatusCode: DataApiBuilderException.SubStatusCodes.ErrorInInitialization);
                     }
@@ -376,14 +376,14 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
 
                 if (addedEntities == 0)
                 {
-                    _logger.LogWarning("No new entities were generated from the autoentity {autoentityName} defined in the configuration.", autoentityName);
+                    _logger.LogWarning("No new entities were generated from the autoentities definition '{autoentityName}'.", autoentityName);
                 }
             }
 
             _runtimeConfigProvider.AddMergedEntitiesToConfig(entities);
         }
 
-        public async Task<JsonArray?> QueryAutoentitiesAsync(Autoentity autoentity)
+        public async Task<JsonArray?> QueryAutoentitiesAsync(string autoentityName, Autoentity autoentity)
         {
             string include = string.Join(",", autoentity.Patterns.Include);
             string exclude = string.Join(",", autoentity.Patterns.Exclude);
@@ -396,10 +396,10 @@ protected override async Task GenerateAutoentitiesIntoEntities(IReadOnlyDictiona
                 { $"{BaseQueryStructure.PARAM_NAME_PREFIX}name_pattern", new(namePattern, null, SqlDbType.NVarChar) }
             };
 
-            _logger.LogInformation("Query for Autoentities is being executed with the following parameters.");
-            _logger.LogInformation($"Autoentities include pattern: {include}");
-            _logger.LogInformation($"Autoentities exclude pattern: {exclude}");
-            _logger.LogInformation($"Autoentities name pattern: {namePattern}");
+            _logger.LogDebug("Query for autoentities is being executed with the following parameters.");
+            _logger.LogDebug("The autoentities definition '{autoentityName}' include pattern: {include}", autoentityName, include);
+            _logger.LogDebug("The autoentities definition '{autoentityName}' exclude pattern: {exclude}", autoentityName, exclude);
+            _logger.LogDebug("The autoentities definition '{autoentityName}' name pattern: {namePattern}", autoentityName, namePattern);
 
             JsonArray? resultArray = await QueryExecutor.ExecuteQueryAsync(
                 sqltext: getAutoentitiesQuery,

src/Core/Services/MetadataProviders/SqlMetadataProvider.cs

@@ -717,7 +717,7 @@ private void GenerateDatabaseObjectForEntities()
         /// </summary>
         protected virtual Task GenerateAutoentitiesIntoEntities(IReadOnlyDictionary<string, Autoentity>? autoentities)
         {
-            throw new NotSupportedException($"{GetType().Name} does not support Autoentities yet.");
+            throw new NotSupportedException($"{GetType().Name} does not support autoentities yet.");
         }
 
         /// <summary>

src/Service.Tests/Configuration/ConfigurationTests.cs

@@ -5608,7 +5608,7 @@ public async Task TestAutoentitiesAreGeneratedIntoEntities(bool useEntities, int
         /// <returns></returns>
         [TestCategory(TestCategory.MSSQL)]
         [DataTestMethod]
-        [DataRow("publishers", "uniqueSingularPublisher", "uniquePluralPublishers", "/unique/publisher", "Entity with name 'publishers' already exists. Cannot create new entity from autoentity pattern with definition-name 'PublisherAutoEntity'.", DisplayName = "Autoentities fail due to entity name")]
+        [DataRow("publishers", "uniqueSingularPublisher", "uniquePluralPublishers", "/unique/publisher", "Entity with name 'publishers' already exists. Cannot create new entity from autoentities definition 'PublisherAutoEntity'.", DisplayName = "Autoentities fail due to entity name")]
         [DataRow("UniquePublisher", "publishers", "uniquePluralPublishers", "/unique/publisher", "Entity publishers generates queries/mutation that already exist", DisplayName = "Autoentities fail due to graphql singular type")]
         [DataRow("UniquePublisher", "uniqueSingularPublisher", "publishers", "/unique/publisher", "Entity publishers generates queries/mutation that already exist", DisplayName = "Autoentities fail due to graphql plural type")]
         [DataRow("UniquePublisher", "uniqueSingularPublisher", "uniquePluralPublishers", "/publishers", "The rest path: publishers specified for entity: publishers is already used by another entity.", DisplayName = "Autoentities fail due to rest path")]

src/Service.Tests/UnitTests/SqlMetadataProviderUnitTests.cs

@@ -634,7 +634,7 @@ public async Task CheckAutoentitiesQuery(string[] include, string[] exclude, str
 
             // Act
             MsSqlMetadataProvider metadataProvider = (MsSqlMetadataProvider)_sqlMetadataProvider;
-            JsonArray resultArray = await metadataProvider.QueryAutoentitiesAsync(autoentity);
+            JsonArray resultArray = await metadataProvider.QueryAutoentitiesAsync("autoentity", autoentity);
 
             // Assert
             Assert.IsNotNull(resultArray);