Improve handling of polymorphism in the optimizer

docs/guide/optimizer.md

@@ -293,3 +293,193 @@ class OrderItem:
 
 `total` now will be properly optimized since it points to a `@model_property`
 decorated attribute, which contains the required information for optimizing it.
+
+## Optimizing polymorphic queries
+
+The optimizer has dedicated support for polymorphic queries, that is, fields which return an interface.
+The optimizer will handle optimizing any subtypes of the interface as necessary. This is supported on top level queries
+as well as relations between models.
+See the following sections for how this interacts with your models.
+
+### Using Django Polymorphic
+
+If you are already using the [Django Polymorphic](https://django-polymorphic.readthedocs.io/en/stable/) library,
+polymorphic queries work out of the box.
+
+```python title="models.py"
+from django.db import models
+from polymorphic.models import PolymorphicModel
+
+class Project(PolymorphicModel):
+    topic = models.CharField(max_length=255)
+
+class ResearchProject(Project):
+    supervisor = models.CharField(max_length=30)
+
+class ArtProject(Project):
+    artist = models.CharField(max_length=30)
+```
+
+```python title="types.py"
+import strawberry
+import strawberry_django
+from . import models
+
+
+@strawberry_django.interface(models.Project)
+class ProjectType:
+    topic: strawberry.auto
+
+
+@strawberry_django.type(models.ResearchProject)
+class ResearchProjectType(ProjectType):
+    supervisor: strawberry.auto
+
+
+@strawberry_django.type(models.ArtProject)
+class ArtProjectType(ProjectType):
+    artist: strawberry.auto
+
+
+@strawberry.type
+class Query:
+    projects: list[ProjectType] = strawberry_django.field()
+```
+
+The `projects` field will return either ResearchProjectType or ArtProjectType, matching on whether it is a
+ResearchProject or ArtProject. The optimizer will make sure to only select those fields from subclasses which are
+requested in the GraphQL query in the same way that it does normally.
+
+> [!WARNING]
+> The optimizer does not filter your QuerySet and Django will return
+> all instances of your model, regardless of whether their type exists in your GraphQL schema or not.
+> Make sure you have a corresponding type for every model subclass or add a `get_queryset` method to your
+> GraphQL interface type to filter out unwanted subtypes.
+> Otherwise you might receive an error like
+> `Abstract type 'ProjectType' must resolve to an Object type at runtime for field 'Query.projects'.`
+
+### Using Model-Utils InheritanceManager
+
+Models using `InheritanceManager` from [django-model-utils](https://django-model-utils.readthedocs.io/en/latest/)
+are also supported.
+
+```python title="models.py"
+from django.db import models
+from model_utils.managers import InheritanceManager
+
+class Project(models.Model):
+    topic = models.CharField(max_length=255)
+
+    objects = InheritanceManager()
+
+class ResearchProject(Project):
+    supervisor = models.CharField(max_length=30)
+
+class ArtProject(Project):
+    artist = models.CharField(max_length=30)
+```
+
+```python title="types.py"
+import strawberry
+import strawberry_django
+from . import models
+
+
+@strawberry_django.interface(models.Project)
+class ProjectType:
+    topic: strawberry.auto
+
+
+@strawberry_django.type(models.ResearchProject)
+class ResearchProjectType(ProjectType):
+    supervisor: strawberry.auto
+
+
+@strawberry_django.type(models.ArtProject)
+class ArtProjectType(ProjectType):
+    artist: strawberry.auto
+
+
+@strawberry.type
+class Query:
+    projects: list[ProjectType] = strawberry_django.field()
+```
+
+The `projects` field will return either ResearchProjectType or ArtProjectType, matching on whether it is a
+ResearchProject or ArtProject. The optimizer automatically calls `select_subclasses`, passing in any subtypes present
+in your schema.
+
+> [!WARNING]
+> The optimizer does not filter your QuerySet and Django will return
+> all instances of your model, regardless of whether their type exists in your GraphQL schema or not.
+> Make sure you have a corresponding type for every model subclass or add a `get_queryset` method to your
+> GraphQL interface type to filter out unwanted subtypes.
+> Otherwise you might receive an error like
+> `Abstract type 'ProjectType' must resolve to an Object type at runtime for field 'Query.projects'.`
+
+> [!NOTE]
+> If you have polymorphic relations (as in: a field that points to a model with subclasses), you need to make sure
+> the manager being used to look up the related model is an `InheritanceManager`.
+> Strawberry Django uses the model's [base manager](https://docs.djangoproject.com/en/5.1/topics/db/managers/#base-managers)
+> by default, which is different from the standard `objects`.
+> Either change your base manager to also be an `InheritanceManager` or set Strawberry Django to use the default
+> manager: `DjangoOptimizerExtension(prefetch_custom_queryset=True)`.
+
+### Custom polymorphic solution
+
+The optimizer also supports polymorphism even if your models are not polymorphic.
+`resolve_type` in the GraphQL interface type is used to tell GraphQL the actual type that should be used.
+
+```python title="models.py"
+from django.db import models
+
+class Project(models.Model):
+    topic = models.CharField(max_length=255)
+    supervisor = models.CharField(max_length=30)
+    artist = models.CharField(max_length=30)
+
+```
+
+```python title="types.py"
+import strawberry
+import strawberry_django
+from . import models
+
+
+@strawberry_django.interface(models.Project)
+class ProjectType:
+    topic: strawberry.auto
+
+    @classmethod
+    def resolve_type(cls, value, info, parent_type) -> str:
+        if not isinstance(value, models.Project):
+            raise TypeError()
+        if value.artist:
+            return 'ArtProjectType'
+        if value.supervisor:
+            return 'ResearchProjectType'
+        raise TypeError()
+
+    @classmethod
+    def get_queryset(cls, qs, info):
+        return qs
+
+
+@strawberry_django.type(models.ResearchProject)
+class ResearchProjectType(ProjectType):
+    supervisor: strawberry.auto
+
+
+@strawberry_django.type(models.ArtProject)
+class ArtProjectType(ProjectType):
+    artist: strawberry.auto
+
+
+@strawberry.type
+class Query:
+    projects: list[ProjectType] = strawberry_django.field()
+```
+
+> [!WARNING]
+> Make sure to add `get_queryset` to your interface type, to force the optimizer to use
+> `prefetch_related`, otherwise this technique will not work for relation fields.

pyproject.toml

@@ -59,6 +59,7 @@ setuptools = "^77.0.3"
 psycopg2 = "^2.9.9"
 psycopg2-binary = "^2.9.9"
 django-tree-queries = "^0.19.0"
+django-model-utils = "^5.0.0"
 
 [tool.poetry.extras]
 debug-toolbar = ["django-debug-toolbar"]