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

>>> 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()