Error initializing relations in mapper when compiled with Cython

[kevinkupski]

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

import uuid
from typing import TYPE_CHECKING, Optional

from pgvector.sqlalchemy import Vector
from sqlalchemy import ForeignKey
from sqlalchemy.dialects.postgresql import JSON
from sqlalchemy.ext.mutable import MutableDict
from sqlmodel import Column, Field, Relationship, SQLModel
from src.api.database.models import TimestampModel, UUIDModel

if TYPE_CHECKING:
    from src.api.database.collections.models import Collection

VECTOR_DIMENSIONS = 1536


class Document(UUIDModel, TimestampModel, SQLModel, table=True):
    __tablename__ = "documents"
    collection_id: Optional[uuid.UUID] = Field(
        default=None, sa_column=Column(ForeignKey("collections.id", ondelete="CASCADE"))
    )
    collection: Optional["Collection"] = Relationship(back_populates="documents")
    text: Optional[str]
    document_metadata: Optional[MutableDict] = Field(
        default={}, sa_column=Column(MutableDict.as_mutable(JSON))
    )
    embedding: list[float] = Field(
        default=None, sa_column=Column(Vector(VECTOR_DIMENSIONS))
    )

Description

When compiling and running my SQLModel Code with Cython, I get the following error: sqlalchemy.exc.InvalidRequestError: When initializing mapper Mapper[Document(documents)], expression "relationship("Optional['Collection']")" seems to be using a generic class as the argument to relationship(); please state the generic argument using an annotation, e.g. "collection: Mapped[Optional['Collection']] = relationship()"

Changing the code to the proposed collection: Mapped[Optional['Collection']] does not help.

When using the code with the Python interpreter, it just works fine.

Operating System

Linux

Operating System Details

Running this code via the Devcontainer Extension of VSCode, which means I'm running it in Docker for Mac.

SQLModel Version

0.0.14

Python Version

3.11.7

Additional Context

Cython Version: 3.0.7

[seedor87]

This seems to be a problem related to a new(er) release of sqlalchemy,

https://docs.sqlalchemy.org/en/20/changelog/migration_20.html#migration-to-2-0-step-six-add-allow-unmapped-to-explicitly-typed-orm-models

But this still did not solve the problem for me. Looking for any help.

[iamyb]

Same issue with cython and works well with cPython. any workaround here for this issue?

[krithika369]

What helped in my case was supplying the sa_relationship parameter, in addition to using Mapped. For the example in the docs, it would be:

from sqlalchemy.orm import Mapped, relationship
...
heroes: Mapped[list[Message]] = Relationship(sa_relationship=relationship(back_populates="team"))

[nickteff]

I was stuck with the same problem. Luckily, the workaround in this discussion helped me. Thanks to everyone who contributed.

[kappa-gooner]

Ran into the exact same problem. Thanks for saving the world! 🎉

[iamciro]

Turns out I ran into the same issue and this solved it.

Thanks for the workaround!

[sawyna]

I have come across this issue as well. Using sa_relationship as above works and solves the problem. However, when I have a more advanced use case like passing a link_model, it fails. Because sqlmodel converts these arguments and generates the relationship object and automatically passes to sa_relationship.

Digging into the code, I think the type annotations are being saved in cls.__annotations__ as string instead of the actual type. In the above example, 'Optional[Collection]' is the value in cls.__annotations__ dict for the key collection instead of Optional[Collection]. sqlmodel tries to go through these annotations and generates the relationship to pass to sqlalchemy. However, it doesn't understand the type if it is a string. That in turn doesn't create the right relationship for sqlalchemy and it fails with this error that's not intuitive.

Changing the code to the proposed collection: Mapped[Optional['Collection']] does not help.

This wouldn't work for the same reason as above. type annotations are probably coming in a strings.

In my case, the annotations are saved in cls.annotationsas string because I usedfrom future import annotations`. In Python 3.7+, this import defers the evaluation of type annotations, meaning they are stored as strings instead of actual types.

I think it makes sense for sqlmodel to understand the type annotations even if they come in as a string. For now, I removed the future import and everything works as expected.

[essamgouda97]

In the age of cursor ai, chatgpt and all those AI tools; this comment saved my life <3