models.ForeignObject is missing documentation

[Ömer Faruk Abacı]

While trying to implement a custom multiple-column join I have spent hours to find an elegant way, at the end I have found an old issue here:

https://code.djangoproject.com/ticket/19385

Then I have realized that I can use ForeignObject for custom joins. Almost all of the solutions online suggest using raw SQLs with Manager.raw() or QuerySet.extra(), none of them mention about ForeignObject. I don't know if it was on purpose or not but I thought that it might be good to mention about the ForeignObject in the following section:

​https://docs.djangoproject.com/en/4.1/ref/models/relations/

What do you think?

[David Sanders]

ForeignObject isn't documented because it isn't earmarked for public use. That being said there's some external documentation on it in a few places to implement custom joins, one good one here: ​https://devblog.kogan.com/blog/custom-relationships-in-django

Closing as won'tfix. If you'd like to raise this topic making ForeignObject public please free to start a discussion on the DevelopersMailingList.

[Ömer Faruk Abacı]

I see your point, thank you!

[Carlton Gibson]

Simon had a proposal in his DjangoCon US 2020 keynote about documenting some of the internals in a way that would help people learn the ORM, but not make them public and so commit to API stability. I don't know how that would role out, or if this would fall under it specifically, but it seems related.

[Mariusz Felisiak]

Replying to Carlton Gibson:

Simon had a proposal in his DjangoCon US 2020 keynote about documenting some of the internals in a way that would help people learn the ORM, but not make them public and so commit to API stability. I don't know how that would role out, or if this would fall under it specifically, but it seems related.

We have a ticket for this :), see #27617.

[Carlton Gibson]

Of course we do :D