feat: support aliasing fields with optimizer hint callables

RELEASE.md

@@ -0,0 +1,37 @@
+---
+release type: minor
+---
+
+Adjust the optimizer to handle when the same field is selected multiple times via aliases with different arguments and the field doesn't have a custom resolver.
+
+Also add support for aliasing custom fields with `annotate`/`prefetch_related` optimizer hint callables, together with three new public helpers:
+
+- `optimizer_hint_key(info)`: returns a unique, deterministic attribute name for the current field selection (based on the response key, i.e. the alias). It returns the same value inside an optimizer hint callable and inside the field's resolver, so it can be used to name a `Prefetch(to_attr=...)` in the hint and read the value back in the resolver.
+- `get_hint_value(source, info, default_attr=None, *, default=...)`: reads the value produced by an optimizer hint for the current selection, checking the alias-scoped attribute/label first and falling back to `default_attr`/`default`. Dict-form annotations with multiple callable labels are supported, so a resolver can combine several per-alias annotated values.
+- `get_field_arguments(info)`: resolves the argument values of the current field selection (including variables), usable both inside hint callables and resolvers.
+
+Example:
+
+```python
+@strawberry_django.type(Milestone)
+class MilestoneType:
+    @strawberry_django.field(
+        annotate=lambda info: Count(
+            "issue",
+            filter=Q(issue__name__contains=get_field_arguments(info)["nameContains"]),
+        ),
+    )
+    def issues_count_filtered(self, root, info, name_contains: str) -> int:
+        return get_hint_value(root, info, "issues_count_filtered")
+```
+
+```graphql
+{
+  milestoneList {
+    foo: issuesCountFiltered(nameContains: "foo")
+    bar: issuesCountFiltered(nameContains: "bar")
+  }
+}
+```
+
+Each alias resolves the hint callable with its own scoped `info`, and callable annotations are stored under an alias-scoped label so they don't clash with each other.

docs/guide/optimizer.md

@@ -287,6 +287,111 @@ The following options are accepted for optimizer hints:
   or a callable in the format of `Callable[[Info], BaseExpression]`
   (e.g. `annotate={"total": lambda info: Sum(...)}`)
 
+## Aliased fields with optimization hint callables
+
+A field whose hints are callables can produce argument-dependent optimizations,
+which means the same field can be selected multiple times via
+[aliases](https://graphql.org/learn/queries/#aliases) with different arguments:
+
+```graphql
+query {
+  orderItems {
+    cheap: totalFiltered(maxPrice: 10)
+    expensive: totalFiltered(maxPrice: 1000)
+  }
+}
+```
+
+Each alias resolves the hint callables with its own `info`, scoped to that
+specific selection. Since every annotation and `Prefetch(to_attr=...)` needs a
+unique name, three helpers keep the hint and the resolver in sync:
+
+- `strawberry_django.optimizer_hint_key(info)`: returns a unique attribute name
+  for the current selection, derived from its response key (the alias if the
+  field is aliased). It returns the same value inside a hint callable and
+  inside the resolver.
+- `strawberry_django.get_hint_value(source, info, default_attr=None, *, default=...)`:
+  reads the value produced by a hint for the current selection. It checks the
+  alias-scoped attribute first, then `default_attr` (e.g. the plain annotation
+  label used when the field is not aliased), then returns `default` if given
+  (useful when the optimizer is turned off), and raises `AttributeError` otherwise.
+- `strawberry_django.get_field_arguments(info)`: resolves the argument values of
+  the current selection (keyed by their GraphQL names, with variables resolved).
+
+For annotations, callable values are automatically stored under the
+alias-scoped name when the field is aliased, so the resolver only needs
+`get_hint_value`:
+
+```python title="types.py"
+@strawberry_django.type(models.Order)
+class Order:
+    @strawberry_django.field(
+        annotate=lambda info: Sum(
+            "items__price",
+            filter=Q(items__price__lte=get_field_arguments(info)["maxPrice"]),
+        ),
+    )
+    def total_filtered(self, root: models.Order, info: Info, max_price: int) -> int:
+        return get_hint_value(root, info, "total_filtered", default=0)
+```
+
+For prefetches, name the `to_attr` with `optimizer_hint_key` and read it back
+the same way:
+
+```python title="types.py"
+@strawberry_django.type(models.Order)
+class Order:
+    @strawberry_django.field(
+        prefetch_related=lambda info: Prefetch(
+            "items",
+            queryset=models.OrderItem.objects.filter(
+                price__lte=get_field_arguments(info)["maxPrice"],
+            ),
+            to_attr=optimizer_hint_key(info),
+        ),
+    )
+    def items_filtered(
+        self, root: models.Order, info: Info, max_price: int
+    ) -> list[OrderItem]:
+        value = get_hint_value(root, info, default=None)
+        if value is None:
+            # The optimizer is turned off, resolve the value directly
+            value = list(root.items.filter(price__lte=max_price))
+        return value
+```
+
+A field can also annotate multiple values and combine them in the resolver.
+Declare the annotations as a dict with custom labels and read each one back
+with `get_hint_value` passing the label as `default_attr` - when the field is
+aliased, callable annotations are stored under an alias-scoped variant of the
+label, and `get_hint_value` checks that variant first:
+
+```python title="types.py"
+@strawberry_django.type(models.Order)
+class Order:
+    @strawberry_django.field(
+        annotate={
+            "_matching_count": lambda info: Count(
+                "items",
+                filter=Q(items__price__lte=get_field_arguments(info)["maxPrice"]),
+            ),
+            "_matching_total": lambda info: Sum(
+                "items__price",
+                filter=Q(items__price__lte=get_field_arguments(info)["maxPrice"]),
+            ),
+        },
+    )
+    def items_summary(self, root: models.Order, info: Info, max_price: int) -> str:
+        count = get_hint_value(root, info, "_matching_count")
+        total = get_hint_value(root, info, "_matching_total")
+        return f"{count} items, {total} total"
+```
+
+> [!NOTE]
+> Static (non-callable) annotate expressions can't depend on the field's
+> arguments, so they keep their shared label and are annotated only once, no
+> matter how many aliases select the field.
+
 ## Optimization hints on model (ModelProperty)
 
 It is also possible to include type hints directly in the models' `@property`

strawberry_django/__init__.py

@@ -28,6 +28,7 @@
 )
 from .filters import filter_type, process_filters
 from .mutations.mutations import input_mutation, mutation
+from .optimizer import get_field_arguments, get_hint_value, optimizer_hint_key
 from .ordering import Ordering, order, order_type, process_order
 from .resolvers import django_resolver
 from .type import input, interface, partial, type  # noqa: A004
@@ -63,13 +64,16 @@
     "filter_field",
     "filter_type",
     "filters",
+    "get_field_arguments",
+    "get_hint_value",
     "input",
     "input_mutation",
     "interface",
     "mutation",
     "mutations",
     "node",
     "offset_paginated",
+    "optimizer_hint_key",
     "order",
     "order_field",
     "order_type",

strawberry_django/fields/field.py

@@ -48,7 +48,11 @@
 from strawberry_django.descriptors import ModelProperty
 from strawberry_django.fields.base import StrawberryDjangoFieldBase
 from strawberry_django.filters import FILTERS_ARG, StrawberryDjangoFieldFilters
-from strawberry_django.optimizer import OptimizerStore, is_optimized_by_prefetching
+from strawberry_django.optimizer import (
+    OptimizerStore,
+    is_optimized_by_prefetching,
+    optimizer_hint_key,
+)
 from strawberry_django.ordering import (
     ORDER_ARG,
     ORDERING_ARG,
@@ -232,6 +236,13 @@ def get_result(
             # sync_to_async context if the value is already cached, since it will not
             # hit the db anymore
             attname = self.django_name or self.python_name
+
+            # Check for to_attr-based prefetch from optimizer (aliased field with filters)
+            if info is not None:
+                alias_attr = optimizer_hint_key(info)
+                if hasattr(source, alias_attr):
+                    return getattr(source, alias_attr)
+
             attr = getattr(source.__class__, attname, None)
 
             def get_cached_result():