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