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!