joinedload() fails static type checking (Pyright/Pylance) when using SQLModel relationships

[Raymondo97]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from sqlmodel import SQLModel, Field, Relationship, select
from sqlalchemy.orm import joinedload
from sqlalchemy.ext.asyncio import AsyncSession

class CallCenter(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    timezone: str

class Employee(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    call_center_id: int | None = Field(default=None, foreign_key="callcenter.id")
    
    call_center: CallCenter | None = Relationship()

async def get_employee(session: AsyncSession):
    stmt = select(Employee).options(
        # Static type error here:
        # Argument of type "CallCenter | None" cannot be assigned to parameter "keys" 
        # Type "CallCenter" is not assignable to "QueryableAttribute[Any]"
        joinedload(Employee.call_center)
    )
    return await session.exec(stmt)

Description

When using SQLAlchemy's eager loading options like joinedload(), passing a SQLModel relationship directly (e.g., joinedload(Model.relationship)) results in static type checking errors in Pyright/Pylance.

The static analyzer reads the relationship as the associated Model type (or Model | None), but joinedload() expects a QueryableAttribute. While this works perfectly at runtime due to SQLModel's metaclass swapping the attributes, the developer experience suffers due to the static analyzer throwing errors.

Current Workaround:
Currently, the only way to satisfy the static type checker without using # pyright: ignore is to cast the relationship using typing.cast:

from typing import Any, cast
from sqlalchemy.orm import QueryableAttribute

def rel(attr: Any) -> QueryableAttribute[Any]:
    return cast(QueryableAttribute[Any], attr)

# This passes static analysis:
stmt = select(Employee).options(joinedload(rel(Employee.call_center)))

Expected Behavior:
Ideally, SQLModel could provide a built-in typing utility (similar to the col() function used for .where() clauses, but compatible with loader options) or type the Relationship in a way that static analyzers recognize it as a valid argument for SQLAlchemy loader options.

Operating System

Linux, Windows, macOS

Operating System Details

No response

SQLModel Version

0.0.38

Python Version

3.14

Additional Context

Pyright Version: 1.1.408
FastAPI Version: 0.135.1
Pydantic Version: 2.12.5
SQLAlchemy Version: 2.0.48

[A00474880]

This is more of an SQLAlchemy issue. A lot of syntaxes are not type supported yet. If you don't want to turn type checking off for the whole project, one option is to isolate sqlalchemy code and turn off type checking for the those modules or packages only (i.e repository pattern)

[Raymondo97]

You're right. I think I assumed that because the select function was coming from SQLModel, it was more of a problem for this repo. But the load strategy imports are still coming from sqlalchemy.orm.

I tried switching back and forth between SQLModel and SQLAlchemy's select functions, and the behavior didn't really change. So it is indeed more of a SQLAlchemy issue. Thanks for pointing it out!

[Raymondo97]

Actually, I'm reviewing this again, and I overlooked something. Before I had refactored to SQLModel classes from SQLAlchemy, I had code such as this in a repository class:

def get_by_entra_oid(self, db: Session, *, oid: str) -> EmployeeV2 | None:
        """
        Fetches an employee by their Entra ID Object ID (oid).

        Eagerly loads related Person data.
        """
        # Convert the incoming string OID to a UUID object to match the model type
        try:
            target_uuid = uuid.UUID(oid)
        except ValueError:
            return None

        statement = (
            select(self.model)
            .join(LookupEmployeeV2Entra)
            .where(LookupEmployeeV2Entra.entra_object_id == target_uuid)
            .options(
                # Eagerly load the person, and then the person's user
                joinedload(self.model.person),
                selectinload(self.model.roles).selectinload(Role.permissions),
            )
        )
        return db.scalars(statement).first()

But now I have to do use the methods I described in my original comment, in order to satisfy the type checker. This is due to how SQLModel is using the SQLModelMetaclass at runtime, to evaluate the relationship.

[Raymondo97]

Update/Clarification on the Typing Issue:

After digging deeper and comparing this to pure SQLAlchemy 2.0, I realized this is definitely a SQLModel typing limitation, not a SQLAlchemy issue.

The error happens because of how Pyright handles class-level vs. instance-level types for relationships.

In pure SQLAlchemy 2.0, we use Mapped[T]. The Mapped generic explicitly tells the static type checker that class-level access (Model.relationship) yields a QueryableAttribute, while instance-level access yields T. Because joinedload() expects a QueryableAttribute, everything passes perfectly:

# Pure SQLAlchemy 2.0 (Passes Static Analysis)
class Employee(Base):
    call_center: Mapped["CallCenter"] = relationship()

# Pyright reads Employee.call_center as QueryableAttribute["CallCenter"]
stmt = select(Employee).options(joinedload(Employee.call_center)) 

However, SQLModel requires us to type the relationship using standard Pydantic-compatible hints:

# SQLModel
class Employee(SQLModel, table=True):
    call_center: CallCenter | None = Relationship()

Because static type checkers (like Pyright/mypy) do not execute SQLModel's metaclass at analysis time, they interpret Employee.call_center literally as CallCenter | None rather than QueryableAttribute.

So when we pass Employee.call_center to joinedload(), Pyright throws an error because CallCenter | None is not a QueryableAttribute.

Potential Solutions for SQLModel:

1. A built-in casting utility (similar to how col(Model.field) works for where() clauses) specifically typed for loader options, e.g., rel(Model.relationship).
2. A way to support Mapped[T] in SQLModel relationship annotations without breaking Pydantic validation.
3. A Pyright/Mypy plugin specifically for SQLModel that understands Relationship() implies an InstrumentedAttribute on class access.