Django gives you two ways of performing raw SQL queries: you can use\nManager.raw() to perform raw queries and return model instances, or\nyou can avoid the model layer entirely and execute custom SQL directly.
raw() マネージャメソッドは素の SQL 文を処理してモデルのインスタンスを返させる場合に利用できます:
This method takes a raw SQL query, executes it, and returns a\ndjango.db.models.query.RawQuerySet instance. This RawQuerySet instance\ncan be iterated over like a normal QuerySet to\nprovide object instances.
例を示す事で最も簡単に説明できます。以下のモデルについて考えてください:
\nclass Person(models.Model):\n first_name = models.CharField(...)\n last_name = models.CharField(...)\n birth_date = models.DateField(...)\nこの時以下のように独自の SQL を実行できます:
\n>>> for p in Person.objects.raw('SELECT * FROM myapp_person'):\n... print(p)\nJohn Smith\nJane Jones\nThis example isn't very exciting -- it's exactly the same as running\nPerson.objects.all(). However, raw() has a bunch of other options that\nmake it very powerful.
raw() は自動的にクエリのフィールドをモデルのフィールドにマップします。
クエリ内で記述したフィールド名の順番は処理の結果に影響しません。つまり、以下の両方のクエリは同じように動作します:
\n>>> Person.objects.raw('SELECT id, first_name, last_name, birth_date FROM myapp_person')\n...\n>>> Person.objects.raw('SELECT last_name, birth_date, first_name, id FROM myapp_person')\n...\nマッチングはその名前によって行われます。これは SQL 文の AS 句をクエリのフィールドからモデルのフィールドにマップするのに利用できる事を意味します。そのためもし Person データを保持する別のテーブルが存在する場合でも、そのデータを Person インスタンスに容易にマップできます:
>>> Person.objects.raw('''SELECT first AS first_name,\n... last AS last_name,\n... bd AS birth_date,\n... pk AS id,\n... FROM some_other_table''')\n名称が一致している限り、そのモデルのインスタンスは適切に生成されます。
\nあるいは、raw() の translations 引数を利用する事でクエリのフィールドとモデルのフィールドをマップできます。これは直接的なクエリのフィールド名とモデルのフィールド名とのマッピングです。例として、上記のクエリは以下のように書く事もできます:
>>> name_map = {'first': 'first_name', 'last': 'last_name', 'bd': 'birth_date', 'pk': 'id'}\n>>> Person.objects.raw('SELECT * FROM some_other_table', translations=name_map)\nraw() はインデックスに対応しており、最初の結果だけが欲しい場合次のように書けます:
>>> first_person = Person.objects.raw('SELECT * FROM myapp_person')[0]\nしかしながら、そのインデックスの利用と結果の分割はデータベースの領域で行われている訳ではありません。もし Person オブジェクトがデータベース内に大量に存在する場合、SQL レベルで問い合わせの制限をした方が効果的です:
>>> first_person = Person.objects.raw('SELECT * FROM myapp_person LIMIT 1')[0]\nモデルのフィールドは省略可能です:
\n>>> people = Person.objects.raw('SELECT id, first_name FROM myapp_person')\n上記のクエリから得られる Person オブジェクトは遅延評価されるモデルのインスタンスになります(defer() を参照)。これはクエリから省かれたフィールドが要求に応じて読み出される事を意味します。以下はその例になります:
>>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'):\n... print(p.first_name, # This will be retrieved by the original query\n... p.last_name) # This will be retrieved on demand\n...\nJohn Smith\nJane Jones\n外見上は、そのクエリが名前と苗字を両方取得しているように見えます。しかし、この例は実際には 3 つのクエリを発行しています。名前だけが raw() 内のクエリによって取得され -- 苗字は両方とも表示される時点で都度取得されました。
\nThere is only one field that you can't leave out - the primary key\nfield. Django uses the primary key to identify model instances, so it\nmust always be included in a raw query. A\nFieldDoesNotExist exception will be raised if\nyou forget to include the primary key.
モデル内に定義されていないフィールドを含んだクエリを実行する事もできます。例えば、PostgreSQL の age() 関数 によってデータベース上で計算された年齢と共に人物の一覧を取得できます:
\n>>> people = Person.objects.raw('SELECT *, age(birth_date) AS age FROM myapp_person')\n>>> for p in people:\n... print("%s is %s." % (p.first_name, p.age))\nJohn is 37.\nJane is 42.\n...\nYou can often avoid using raw SQL to compute annotations by instead using a\nFunc() expression.
\nraw() にパラメータを渡すLink to this heading#パラメータを用いたクエリを使用する場合は、raw() に対して params 引数を利用できます:
>>> lname = 'Doe'\n>>> Person.objects.raw('SELECT * FROM myapp_person WHERE last_name = %s', [lname])\nparams is a list or dictionary of parameters. You'll use %s\nplaceholders in the query string for a list, or %(key)s\nplaceholders for a dictionary (where key is replaced by a\ndictionary key), regardless of your database engine. Such placeholders will be\nreplaced with parameters from the params argument.
Manager.raw() でも要求を満たせない場合があります:きれいにモデルにマップできないクエリを扱ったり、UPDATE、 INSERT あるいは DELETE を直接実行したりする必要が有るかもしれません。
こういったケースでは、モデル層を完全に迂回してデータベースにいつでも直接アクセスできます。
\ndjango.db.connection オブジェクトがデフォルトのデータベース接続に対応しています。そのデータベース接続を利用するには、カーソルオブジェクトを取得するため connection.cursor() を呼び出してください。続いて、cursor.execute(sql, [params]) を呼び出して SQL を実行した後 cursor.fetchone() もしくは cursor.fetchall() で結果の行を取得します。
例:
\nfrom django.db import connection\n\ndef my_custom_sql(self):\n with connection.cursor() as cursor:\n cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz])\n cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])\n row = cursor.fetchone()\n\n return row\nTo protect against SQL injection, you must not include quotes around the %s\nplaceholders in the SQL string.
もしリテラルなパーセント記号をクエリ中で使いたい場合、パラメータを渡す際に二重に記述する必要が有る事に注意してください:
\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%'")\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%%' AND id = %s", [self.id])\n2 つ以上のデータベース を利用している場合、特定の接続(とカーソル)を取得するのに django.db.connections を利用できます。django.db.connections はその別名を指定する事で特定の接続を得られる、辞書に似たオブジェクトです:
from django.db import connections\nwith connections['my_db_alias'].cursor() as cursor:\n # Your code here...\nデフォルトでは、Python データベース API は返す結果にフィールド名を含まず、つまり``辞書``でなく、``リスト``の値として結果を返します。処理能力とメモリを少々利用して、次のような処理を用いる事で結果を``辞書``として得られます:
\ndef dictfetchall(cursor):\n "Return all rows from a cursor as a dict"\n columns = [col[0] for col in cursor.description]\n return [\n dict(zip(columns, row))\n for row in cursor.fetchall()\n ]\n別の選択肢は Python 標準ライブラリに含まれる collections.namedtuple() を利用する事です。namedtuple は属性を指定して値へのアクセスが可能なタプルに似たオブジェクトです; 加えてインデックスが利用でき、イテレート可能でもあります。取得した結果は不変であり属性名もしくはインデックスでアクセスできて便利です:
from collections import namedtuple\n\ndef namedtuplefetchall(cursor):\n "Return all rows from a cursor as a namedtuple"\n desc = cursor.description\n nt_result = namedtuple('Result', [col[0] for col in desc])\n return [nt_result(*row) for row in cursor.fetchall()]\n以下はここまで示した三通り方法それぞれの異なる利用例です:
\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2");\n>>> cursor.fetchall()\n((54360982, None), (54360880, None))\n\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2");\n>>> dictfetchall(cursor)\n[{'parent_id': None, 'id': 54360982}, {'parent_id': None, 'id': 54360880}]\n\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2");\n>>> results = namedtuplefetchall(cursor)\n>>> results\n[Result(id=54360982, parent_id=None), Result(id=54360880, parent_id=None)]\n>>> results[0].id\n54360982\n>>> results[0][0]\n54360982\nconnection と cursor の実装は PEP 249 に規定された Python DB-API の基準にほぼ完全に準拠しています — トランザクション操作 は例外となります。
Python DB-API に精通していない場合、cursor.execute() 内の SQL 文には直接値を追加せずに、"%s" というプレースホルダーを利用する事に注意してください。この手法を用いる事で、内部で動作しているデータベースライブラリは自動的に必要に応じて値のエスケープを行ってくれます。
加えて Django はプレースホルダーとして Python に内蔵された SQLite モジュールで用いられる "?" でなく "%s" を期待して動作する事にも注意してください。これは全体の調和と健全性のためです。
コンテキストマネージャとしてのカーソルの利用:
\nwith connection.cursor() as c:\n c.execute(...)\nこれは以下と同じです:
\nc = connection.cursor()\ntry:\n c.execute(...)\nfinally:\n c.close()\nCalls a database stored procedure with the given name. A sequence\n(params) or dictionary (kparams) of input parameters may be\nprovided. Most databases don't support kparams. Of Django's built-in\nbackends, only Oracle supports it.
For example, given this stored procedure in an Oracle database:
\nCREATE PROCEDURE "TEST_PROCEDURE"(v_i INTEGER, v_text NVARCHAR2(10)) AS\n p_i INTEGER;\n p_text NVARCHAR2(10);\nBEGIN\n p_i := v_i;\n p_text := v_text;\n ...\nEND;\nThis will call it:
\nwith connection.cursor() as cursor:\n cursor.callproc('test_procedure', [1, 'test'])\n