Выполнение прямых SQL-запросов

Сопоставление полей запроса с полями модели

raw() автоматически сопоставляет поля в запросе с полями модели.

Порядок полей в запросе не имеет значения. Другими словами, оба следующих запроса работают одинаково:

>>> Person.objects.raw("SELECT id, first_name, last_name, birth_date FROM myapp_person")
>>> Person.objects.raw("SELECT last_name, birth_date, first_name, id FROM myapp_person")

Сопоставление выполняется по имени. Это означает, что вы можете использовать SQL-оператор AS для сопоставления полей запроса с полями модели. Таким образом, если у вас есть другая таблица, содержащая данные Person, вы можете легко отобразить их в экземпляры Person:

>>> Person.objects.raw(
...     """
...     SELECT first AS first_name,
...            last AS last_name,
...            bd AS birth_date,
...            pk AS id,
...     FROM some_other_table
...     """
... )

До тех пор, пока имена совпадают, экземпляры модели будут созданы корректно.

В качестве альтернативы вы можете сопоставить поля в запросе с полями модели, используя аргумент translations к raw(). Это словарь, сопоставляющий имена полей в запросе с именами полей модели. Например, вышеприведенный запрос также можно записать:

>>> name_map = {"first": "first_name", "last": "last_name", "bd": "birth_date", "pk": "id"}
>>> Person.objects.raw("SELECT * FROM some_other_table", translations=name_map)

Поиск по индексу

raw() поддерживает индексирование, поэтому, если вам нужен только первый результат, вы можете написать:

>>> first_person = Person.objects.raw("SELECT * FROM myapp_person")[0]

Однако, индексирование и срезы не выполняются на уровне базы данных. Если у вас большое количество Person объектов в базе данных, более эффективно ограничить запрос на уровне SQL:

>>> first_person = Person.objects.raw("SELECT * FROM myapp_person LIMIT 1")[0]

Откладывание полей модели

Поля также могут быть опущены:

>>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person")

Объекты Person, возвращаемые этим запросом, будут отложенными экземплярами моделей (см. defer()). Это означает, что поля, исключённые из запроса, будут загружаться по мере необходимости. Например:

>>> for p in Person.objects.raw("SELECT id, first_name FROM myapp_person"):
...     print(
...         p.first_name,  # This will be retrieved by the original query
...         p.last_name,  # This will be retrieved on demand
...     )
...
John Smith
Jane Jones

Внешне выглядит так, будто запрос извлёк и имя, и фамилию. Однако, на самом деле этот пример выдал 3 запроса. Только имена были извлечены в raw() запросе — фамилии были загружены по мере необходимости при их выводе.

Есть только одно поле, которое нельзя опустить — первичный ключ. Django использует первичный ключ для идентификации экземпляров модели, поэтому он всегда должен быть включён в прямой запрос. Будет поднята исключение FieldDoesNotExist, если вы забудете его включить.

Добавление аннотаций

Вы также можете выполнить запросы, содержащие поля, которые не определены в модели. Например, мы можем использовать функцию age() PostgreSQL, чтобы получить список людей с возрастом, вычисленным базой данных:

>>> people = Person.objects.raw("SELECT *, age(birth_date) AS age FROM myapp_person")
>>> for p in people:
...     print("%s is %s." % (p.first_name, p.age))
...
John is 37.
Jane is 42.
...

Часто можно избежать использования raw SQL для вычисления аннотаций, используя вместо этого выражение Func().

Передача параметров в raw()

Если вам нужно выполнить параметризованные запросы, вы можете использовать аргумент params к методу raw():

>>> lname = "Doe"
>>> Person.objects.raw("SELECT * FROM myapp_person WHERE last_name = %s", [lname])

params — список или словарь параметров. Вы будете использовать %s плейсхолдеры в строке запроса для списка или %(key)s плейсхолдеры для словаря (где key заменяется ключом словаря), независимо от вашего движка базы данных. Такие плейсхолдеры будут заменены параметрами из аргумента params.

>>> query = "SELECT * FROM myapp_person WHERE last_name = %s" % lname
>>> Person.objects.raw(query)

>>> query = "SELECT * FROM myapp_person WHERE last_name = '%s'"

Соединения и курсоры

connection и cursor в основном реализуют стандартный Python DB-API, описанный в PEP 249 — за исключением случаев обработки обработки транзакций.

Если вы не знакомы с Python DB-API, обратите внимание, что SQL-запрос в cursor.execute() использует заполнительные значения, "%s", а не добавляет параметры непосредственно в SQL. Если вы используете этот метод, базовая библиотека базы данных автоматически будет экранировать ваши параметры по мере необходимости.

Также обратите внимание, что Django ожидает заполнитель "%s", а не "?", который используется привязками Python к SQLite. Это сделано для обеспечения согласованности и разумности.

Использование курсора как контекстного менеджера:

with connection.cursor() as c:
    c.execute(...)

эквивалентно:

c = connection.cursor()
try:
    c.execute(...)
finally:
    c.close()