Выполнение необработанных 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 будет вызвано, если вы забудете включить первичный ключ.

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

Можно также выполнять запросы, содержащие поля, которые не определены в модели. Например, мы можем использовать `PostgreSQL's age() function`__ для получения списка людей с их возрастом, вычисленным базой данных:

>>> 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.
...

Часто можно избежать использования необработанного 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", не заполнитель "?", который используется привязками SQLite Python. Это сделано для последовательности и здравомыслия.

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

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

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

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