Соответствие полей ответа и полей модели¶

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() <func-expressions>`.

Передача параметров в 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()