Docs #36391 -- Added RawSQL usage section to ORM expressions guide. #19475
Conversation
…xed :class: reference for RawSQL in SQL guide.
There was a problem hiding this comment.
The introduction on lines 7-9 needs updating.
Line 215, which has a throwaway mention to Func, should be updated to mention RawSQL.
The new entry should be a ==== heading, like the other headings “Performing raw queries” and “Executing custom SQL directly”.
In terms of order, perhaps it would make sense to mention RawSQL first.
I don’t think we need a full explainer of how to use RawSQL, since it has documentation of its own.
I am not sure the extra warning is necessary, the entire page is about Raw SQL and passing pararmeters anyway. I notice there's already one warning under “Passing parameters into raw()”, perhaps we can move that warning up to the top of the page?
|
Thank you for the thoughtful feedback! I've incorporated all your suggestions |
There was a problem hiding this comment.
The introduction on lines 7-9 needs updating.
Still needs doing.
Line 215, which has a throwaway mention to
Func, should be updated to mentionRawSQL.
The way you updated this section doesn't point out that RawSQL is covered next.
Also, I now think that maybe the Func reference could be merged into the section we're writing, since that is another way of using "raw" SQL, via a short SQL fragment. Perhaps we could call the section "Raw SQL fragments" or similar.
In terms of order, perhaps it would make sense to mention
RawSQLfirst.
This is still not actioned. I meant to put the section first in the document.
perhaps we can move that warning up to the top of the page?
Still needs doing, or at least discussing!
docs/topics/db/sql.txt
Outdated
| Using RawSQL in ORM expressions | ||
| ================================ |
There was a problem hiding this comment.
| Using RawSQL in ORM expressions | |
| ================================ | |
| Using RawSQL in ORM expressions | |
| =============================== |
Underlines need to match title length exactly in reStructuredText
docs/topics/db/sql.txt
Outdated
| Django provides a number of built-in expressions and functions for use in queries. | ||
| However, when these are not sufficient, you can use :class:`~django.db.models.expressions.RawSQL` | ||
| to include custom SQL fragments inside annotations or filters. |
There was a problem hiding this comment.
This intro to the topic doesn't really place RawSQL within the context of the surrounding page. It should highlight how RawSQL differs to the other options.
|
Thank you for the detailed and thoughtful feedback - I've now addressed all the suggestions you've mentioned. I've updated the introduction to better contextualize RawSQL in relation to the other raw query methods, revised the section ordering, and merged the Func reference into the new "Raw SQL fragments" section as advised. I’ve also adjusted the heading underline and moved the warning to the top of the page as discussed. This is my first time contributing to the Django documentation, so I may still have missed some things. I’d really appreciate any further feedback you might have. Thanks again for your guidance! |
|
Dear @adamchainz, Would you be willing to review this pull request (#19475) when you have a moment? The proposed changes aim to improve the documentation by clarifying how Your feedback would be greatly appreciated. Thank you in advance for your time and your continued contributions to the Django project. |
Trac ticket number
#36391
Branch description
This PR adds documentation for using
RawSQLin the "Performing raw SQL queries" guide (topics/db/sql.txt).It introduces
RawSQLas an ORM expression suitable for use inannotate()andfilter(), with an example and a warning about SQL injection risks. The section complements existing documentation forManager.raw()andcursor.execute().Checklist
mainbranch.Please let me know if any changes are needed — I’d appreciate suggestions for improving alignment with Django’s documentation tone and structure. Thank you!