Memetakan bidang permintaan ke bidang model¶

raw() secara otomatis memetakan bidang-bidang dalam permintaan ke bidang pada model.

Urutan dari bidang-bidang daam permintaan anda tidak masalah. Dengan kata lain, kedua dari permintaan berikut bekerja mirip:

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

Pencocokan selesai berdasarkan nama. Ini berarti bahwa anda dapat menggunakan klausa AS SQL untuk memetakan bidang-bidang dalam permintaan ke bidang-bidang model. Jadi jika anda mempunyai beberapa tabel lain yang mempunyai data Person dalam nya, anda dapat dengan mudah memetakan itu menjadi instance Person:

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

Selama nama-nama cocok, instance model akan dibuat dengan benar.

Kalau tidak, anda dapat memetakan bidang-bidang dalam permintaan ke bidang-bidang model menggunakan argumen translations pada raw(). Ini adalah nama-nama pemetaan dictionary dalam permintaan pada nama-nama dari bidang pada model. Sebagai contoh, permintaan diatas dapat juga ditulis:

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

Pencarian indeks¶

raw() mendukung pengindeksan, jadi jika anda butuh hanya hasil pertama anda dapat menulis:

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

Bagaimanapun, pengindeksan dan pemotongan tidak dilakukan pada tingkat basisdata. Jika anda mempunyai sejumlah besar obyek Person dalam basisdata anda, itu lebih efesien membatasi permintaan pada tingkat SQL:

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

Menangguhkan bidang-bidang model¶

Bidang-bidang mungkin juga ditiadakan:

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

Obyek Person dikembalikan oleh permintaan ini akan meniadakan instance-instance model (lihat defer()). Ini berarti bahwa bidang-bidang yang dihilangkan dari permintaan akan dimuat pada permintaan. Sebagai contoh:

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

Dari penampilan luar, ini terlihat seperti permintaan telah mengambil kedua nama pertama dan nama terakhir. Bagaimanapun, contoh ini sebenarnya menerbitkan 3 permintaan. Hanya nama pertama yang diambil oleh permintaan raw() -- nama terakhir keduanya diambil pada permintaan mereka telah cetak.

Hanya ada sat bidang yang anda tidak dapat tinggalkan - bidang primary key. Django menggunakan primary key untuk mencirikan instance-instance model, jadi itu harus selalu disertakan dalam permintaan mentah. Sebuah pengecualian InvalidQuery akan dimunculkan jika anda lupa menyertakan primary key.

Menambahkan keterangan¶

Anda dapat juga menjalankan permintaan mengandung bidang-bidang yang tidak ditentukan pada model. Sebagai contoh, kami dapat menggunakan PostgreSQL's age() function untuk mendapatkan daftar orang dengan umur mereka dihitung oleh basisdata:

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

You can often avoid using raw SQL to compute annotations by instead using a Func() expression.

Melewati parameter kedalam raw()¶

Jika anda butuh melakukan permintaan gambaran parameter, anda dapat menggunakan argumen params pada raw():

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

params adalah sebuah parameter list atau dictionary. Anda akan menggunakan palceholder %s dalam string permintaan untuk daftar, atau placeholder %(key)s untuk sebuah dictionary (dimana key diganti oleh kunci dictionary, tentu saja), tidak peduli dari mesin basisdata anda. Placeholder itu akan diganti dengan parameter dari argumen params.

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

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

Hubungan dan kursor¶

connection dan cursor kebanyakan menerapkan API-DB Python standar digambarkan dalam pep:249 — kecuali ketika itu datang pada transaction handling 1.

Jika anda akrab dengan DB-API Python, catat bahwa pernyataan SQL dalam cursor.execute() menggunakan placeholder, "%s", daripada menambahkan parameter langsung dalam SQL. Jika anda menggunakan teknik ini, pustaka basisdata pokok akan otomatis meloloskan parameter anda seperlunya.

Juga catat bahwa Django mengharapkan placeholder "%s", bukan placeholder "?", yang digunakan oleh pengikatan Python SQLite. Ini adalah untuk kebaikan dari ketetapan dan kesegaran.

Menggunakan sebuah kursor sebagai pengelola konteks:

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

setara pada:

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