feat: Introduce metrics attributes for aggregate properties and enhance validation

Author: mpartipilo

docs/AGGREGATE_RESULT_ACCESSORS.md

@@ -599,6 +599,74 @@ public class PriceAnalysis
 var metrics = MetricsExtractor.FromType<PriceAnalysis>();
 ```
 
+#### Selective Metrics with Type-Specific Attributes
+
+When using full `Aggregate.*` types, you can specify which metrics to query using type-specific attributes. This provides excellent IntelliSense guidance and reduces network traffic by querying only the metrics you need:
+
+```csharp
+using Weaviate.Client.Models.Typed;
+
+public class ProductStats
+{
+    // Query only Min, Max, Mean (not Sum, Median, Mode, Count)
+    [NumberMetrics(Minimum = true, Maximum = true, Mean = true)]
+    public Aggregate.Number? Price { get; set; }
+
+    // Query all Integer metrics (no attribute)
+    public Aggregate.Integer? Quantity { get; set; }
+
+    // Query Count and TopOccurrences with minimum threshold
+    [TextMetrics(Count = true, TopOccurrences = true, MinOccurrences = 5)]
+    public Aggregate.Text? Category { get; set; }
+
+    // Query only specific Boolean metrics
+    [BooleanMetrics(TotalTrue = true, PercentageTrue = true)]
+    public Aggregate.Boolean? Featured { get; set; }
+}
+
+var metrics = MetricsExtractor.FromType<ProductStats>();
+var result = await collection.Aggregate.OverAll(returnMetrics: metrics);
+var typed = result.ToTyped<ProductStats>();
+```
+
+**Available attributes:**
+
+| Attribute | Applicable Type | Available Properties |
+|-----------|----------------|---------------------|
+| `[TextMetrics]` | `Aggregate.Text` | `Count`, `TopOccurrences`, `MinOccurrences` |
+| `[IntegerMetrics]` | `Aggregate.Integer` | `Count`, `Sum`, `Mean`, `Minimum`, `Maximum`, `Median`, `Mode` |
+| `[NumberMetrics]` | `Aggregate.Number` | `Count`, `Sum`, `Mean`, `Minimum`, `Maximum`, `Median`, `Mode` |
+| `[BooleanMetrics]` | `Aggregate.Boolean` | `Count`, `TotalTrue`, `TotalFalse`, `PercentageTrue`, `PercentageFalse` |
+| `[DateMetrics]` | `Aggregate.Date` | `Count`, `Minimum`, `Maximum`, `Median`, `Mode` |
+
+**Benefits:**
+- Excellent IntelliSense showing available metrics for each type
+- Compile-time safety - C# compiler prevents mismatches
+- Reduces network traffic by querying only needed metrics
+- Clean, readable syntax with named boolean properties
+- Properties without attributes query all metrics (backward compatible)
+
+**Example with IntelliSense:**
+
+When you type `[NumberMetrics(` in your IDE, IntelliSense will show exactly which properties are available (Minimum, Maximum, Mean, Sum, Count, Median, Mode), making it clear what metrics can be queried for Number types.
+
+**MinOccurrences parameter:**
+
+The `TextMetrics` attribute includes a special `MinOccurrences` parameter that sets the minimum occurrence threshold for top occurrences:
+
+```csharp
+public class CategoryAnalysis
+{
+    // Only show categories that appear at least 10 times
+    [TextMetrics(TopOccurrences = true, MinOccurrences = 10)]
+    public Aggregate.Text? Category { get; set; }
+}
+```
+
+**Analyzer validation:**
+
+If you use the wrong attribute type (e.g., `[NumberMetrics]` on an `Aggregate.Text` property), you'll get a **WEAVIATE004** warning at compile time pointing out the mismatch.
+
 ### GroupBy with Typed Results
 
 Typed mapping also works with grouped aggregations using `ToTyped<T>()`:

src/Weaviate.Client.Analyzers/AggregatePropertySuffixAnalyzer.cs

@@ -18,6 +18,7 @@ public class AggregatePropertySuffixAnalyzer : DiagnosticAnalyzer
 {
     public const string MissingSuffixDiagnosticId = "WEAVIATE002";
     public const string InvalidSuffixTypeDiagnosticId = "WEAVIATE003";
+    public const string WrongAttributeTypeDiagnosticId = "WEAVIATE004";
     private const string Category = "Usage";
 
     private static readonly LocalizableString MissingSuffixTitle =
@@ -54,6 +55,23 @@ public class AggregatePropertySuffixAnalyzer : DiagnosticAnalyzer
         description: InvalidSuffixTypeDescription
     );
 
+    private static readonly LocalizableString WrongAttributeTypeTitle =
+        "Wrong metrics attribute for aggregate type";
+    private static readonly LocalizableString WrongAttributeTypeMessageFormat =
+        "Property '{0}' is Aggregate.{1} but has [{2}Metrics] attribute";
+    private static readonly LocalizableString WrongAttributeTypeDescription =
+        "Use the metrics attribute that matches the aggregate property type.";
+
+    private static readonly DiagnosticDescriptor WrongAttributeTypeRule = new DiagnosticDescriptor(
+        WrongAttributeTypeDiagnosticId,
+        WrongAttributeTypeTitle,
+        WrongAttributeTypeMessageFormat,
+        Category,
+        DiagnosticSeverity.Warning,
+        isEnabledByDefault: true,
+        description: WrongAttributeTypeDescription
+    );
+
     /// <summary>
     /// Recognized suffixes and their expected types.
     /// </summary>
@@ -228,7 +246,7 @@ public class AggregatePropertySuffixAnalyzer : DiagnosticAnalyzer
     private const string MetricsExtractorFullName = "Weaviate.Client.Models.Typed.MetricsExtractor";
 
     public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics =>
-        ImmutableArray.Create(MissingSuffixRule, InvalidSuffixTypeRule);
+        ImmutableArray.Create(MissingSuffixRule, InvalidSuffixTypeRule, WrongAttributeTypeRule);
 
     public override void Initialize(AnalysisContext context)
     {
@@ -357,9 +375,12 @@ INamedTypeSymbol typeSymbol
         {
             var propertyType = property.Type;
 
-            // Skip if this is a full Aggregate.* type
+            // Check for wrong metrics attribute on Aggregate.* types
             if (IsAggregateType(propertyType))
+            {
+                ValidateMetricsAttribute(context, property, propertyType, typeArgumentSyntax);
                 continue;
+            }
 
             // Only analyze primitive/value types and string
             if (!IsPrimitiveOrValueType(propertyType))
@@ -525,4 +546,60 @@ private static string GetSimpleTypeName(ITypeSymbol type)
             _ => type.ToDisplayString(),
         };
     }
+
+    private static void ValidateMetricsAttribute(
+        SyntaxNodeAnalysisContext context,
+        IPropertySymbol property,
+        ITypeSymbol aggregateType,
+        TypeSyntax typeArgumentSyntax
+    )
+    {
+        var aggregateTypeName = GetAggregateTypeName(aggregateType);
+        if (aggregateTypeName == null)
+            return;
+
+        // Check if they're using the wrong attribute type
+        var attributes = property.GetAttributes();
+        var metricsAttrs = attributes
+            .Where(a => a.AttributeClass?.Name?.EndsWith("MetricsAttribute") == true)
+            .ToList();
+
+        if (metricsAttrs.Count == 0)
+            return; // No attribute is fine
+
+        var expectedAttrName = $"{aggregateTypeName}MetricsAttribute";
+        var wrongAttr = metricsAttrs.FirstOrDefault(a =>
+            a.AttributeClass?.Name != expectedAttrName
+        );
+
+        if (wrongAttr != null)
+        {
+            var wrongTypeName =
+                wrongAttr.AttributeClass?.Name?.Replace("MetricsAttribute", "") ?? "Unknown";
+            var diagnostic = Diagnostic.Create(
+                WrongAttributeTypeRule,
+                typeArgumentSyntax.GetLocation(),
+                property.Name,
+                aggregateTypeName,
+                wrongTypeName
+            );
+            context.ReportDiagnostic(diagnostic);
+        }
+    }
+
+    private static string? GetAggregateTypeName(ITypeSymbol type)
+    {
+        var displayName = type.ToDisplayString();
+        if (displayName == "Weaviate.Client.Models.Aggregate.Text")
+            return "Text";
+        if (displayName == "Weaviate.Client.Models.Aggregate.Integer")
+            return "Integer";
+        if (displayName == "Weaviate.Client.Models.Aggregate.Number")
+            return "Number";
+        if (displayName == "Weaviate.Client.Models.Aggregate.Boolean")
+            return "Boolean";
+        if (displayName == "Weaviate.Client.Models.Aggregate.Date")
+            return "Date";
+        return null;
+    }
 }

src/Weaviate.Client.Analyzers/AnalyzerReleases.Unshipped.md

@@ -5,3 +5,4 @@ Rule ID | Category | Severity | Notes
 --------|----------|----------|-------
 WEAVIATE002 | Usage | Warning | Aggregate property missing suffix. Triggers when ToTyped<T>() or MetricsExtractor.FromType<T>() is called with the type.
 WEAVIATE003 | Usage | Warning | Invalid type for aggregate suffix. Triggers when ToTyped<T>() or MetricsExtractor.FromType<T>() is called with the type.
+WEAVIATE004 | Usage | Warning | Wrong metrics attribute for aggregate type. Triggers when using mismatched attribute (e.g., NumberMetrics on Aggregate.Text).

src/Weaviate.Client.Tests/Unit/TestTypedAggregateResults.cs

@@ -992,4 +992,162 @@ public void FromType_NonGenericOverload_Works()
     }
 
     #endregion
+
+    #region MetricsExtractor Attribute Tests
+
+    private class SelectiveMetrics
+    {
+        [NumberMetrics(Minimum = true, Maximum = true, Mean = true)]
+        public Aggregate.Number? Price { get; set; }
+
+        [TextMetrics(Count = true, TopOccurrences = true, MinOccurrences = 5)]
+        public Aggregate.Text? Category { get; set; }
+
+        [BooleanMetrics(TotalTrue = true, PercentageTrue = true)]
+        public Aggregate.Boolean? InStock { get; set; }
+    }
+
+    [Fact]
+    public void FromType_WithAttributes_EnablesOnlySpecifiedMetrics()
+    {
+        var metrics = MetricsExtractor.FromType<SelectiveMetrics>();
+
+        Assert.Equal(3, metrics.Length);
+
+        // Price: Only Min, Max, Mean
+        var price = metrics.OfType<Aggregate.Metric.Number>().First(m => m.Name == "price");
+        Assert.True(price.Minimum);
+        Assert.True(price.Maximum);
+        Assert.True(price.Mean);
+        Assert.False(price.Sum);
+        Assert.False(price.Count);
+        Assert.False(price.Median);
+
+        // Category: Count + TopOccurrences with MinOccurrences
+        var category = metrics.OfType<Aggregate.Metric.Text>().First(m => m.Name == "category");
+        Assert.True(category.Count);
+        Assert.True(category.TopOccurrencesCount);
+        Assert.True(category.TopOccurrencesValue);
+        Assert.Equal(5u, category.MinOccurrences);
+
+        // InStock: Only TotalTrue, PercentageTrue
+        var inStock = metrics.OfType<Aggregate.Metric.Boolean>().First(m => m.Name == "inStock");
+        Assert.True(inStock.TotalTrue);
+        Assert.True(inStock.PercentageTrue);
+        Assert.False(inStock.TotalFalse);
+        Assert.False(inStock.PercentageFalse);
+        Assert.False(inStock.Count);
+    }
+
+    [Fact]
+    public void FromType_NoAttribute_EnablesAll()
+    {
+        var metrics = MetricsExtractor.FromType<NoAttributeMetrics>();
+
+        var quantity = metrics.OfType<Aggregate.Metric.Integer>().First(m => m.Name == "quantity");
+        Assert.True(quantity.Count);
+        Assert.True(quantity.Sum);
+        Assert.True(quantity.Mean);
+        Assert.True(quantity.Minimum);
+        Assert.True(quantity.Maximum);
+        Assert.True(quantity.Median);
+        Assert.True(quantity.Mode);
+    }
+
+    private class NoAttributeMetrics
+    {
+        public Aggregate.Integer? Quantity { get; set; }
+    }
+
+    [Fact]
+    public void FromType_MixedAttributes_WorksCorrectly()
+    {
+        var metrics = MetricsExtractor.FromType<MixedAttributes>();
+
+        Assert.Equal(2, metrics.Length);
+
+        // Price has attribute - only specified metrics
+        var price = metrics.OfType<Aggregate.Metric.Number>().First(m => m.Name == "price");
+        Assert.True(price.Minimum);
+        Assert.True(price.Maximum);
+        Assert.False(price.Mean);
+        Assert.False(price.Sum);
+
+        // Quantity has no attribute - all metrics
+        var quantity = metrics.OfType<Aggregate.Metric.Integer>().First(m => m.Name == "quantity");
+        Assert.True(quantity.Count);
+        Assert.True(quantity.Sum);
+        Assert.True(quantity.Mean);
+    }
+
+    private class MixedAttributes
+    {
+        [NumberMetrics(Minimum = true, Maximum = true)]
+        public Aggregate.Number? Price { get; set; }
+
+        public Aggregate.Integer? Quantity { get; set; }
+    }
+
+    [Fact]
+    public void FromType_EmptyAttribute_EnablesAll()
+    {
+        var metrics = MetricsExtractor.FromType<EmptyAttributeMetrics>();
+
+        var price = metrics.OfType<Aggregate.Metric.Number>().First(m => m.Name == "price");
+
+        // Empty attribute with no true values - enables all
+        Assert.True(price.Count);
+        Assert.True(price.Sum);
+        Assert.True(price.Mean);
+        Assert.True(price.Minimum);
+        Assert.True(price.Maximum);
+        Assert.True(price.Median);
+        Assert.True(price.Mode);
+    }
+
+    private class EmptyAttributeMetrics
+    {
+        [NumberMetrics] // All properties default to false - enables all
+        public Aggregate.Number? Price { get; set; }
+    }
+
+    [Fact]
+    public void FromType_IntegerMetricsAttribute_EnablesOnlySpecifiedMetrics()
+    {
+        var metrics = MetricsExtractor.FromType<IntegerAttributeMetrics>();
+
+        var quantity = metrics.OfType<Aggregate.Metric.Integer>().First(m => m.Name == "quantity");
+        Assert.True(quantity.Sum);
+        Assert.True(quantity.Count);
+        Assert.False(quantity.Mean);
+        Assert.False(quantity.Minimum);
+        Assert.False(quantity.Maximum);
+    }
+
+    private class IntegerAttributeMetrics
+    {
+        [IntegerMetrics(Sum = true, Count = true)]
+        public Aggregate.Integer? Quantity { get; set; }
+    }
+
+    [Fact]
+    public void FromType_DateMetricsAttribute_EnablesOnlySpecifiedMetrics()
+    {
+        var metrics = MetricsExtractor.FromType<DateAttributeMetrics>();
+
+        var createdAt = metrics.OfType<Aggregate.Metric.Date>().First(m => m.Name == "createdAt");
+        Assert.True(createdAt.Minimum);
+        Assert.True(createdAt.Maximum);
+        Assert.False(createdAt.Median);
+        Assert.False(createdAt.Mode);
+        Assert.False(createdAt.Count);
+    }
+
+    private class DateAttributeMetrics
+    {
+        [DateMetrics(Minimum = true, Maximum = true)]
+        public Aggregate.Date? CreatedAt { get; set; }
+    }
+
+    #endregion
 }