Django gives you three ways of performing raw SQL queries: you can embed raw\nSQL fragments into ORM queries using\nRawSQL (see Raw SQL fragments),\nuse Manager.raw() to perform raw queries and return model instances,\nor avoid the model layer entirely and execute custom SQL directly.
In some cases, you may need to embed raw SQL fragments directly into ORM\nqueries — for example, in annotate() or\nfilter() calls. Use Func()\nexpressions for calling database functions across\nbackends, or\nRawSQL for arbitrary parameterized SQL\nfragments.
raw() マネージャメソッドは素の SQL 文を処理してモデルのインスタンスを返させる場合に利用できます:
このメソッドは素の SQL クエリを受け取り、実行し、 django.db.models.query.RawQuerySet インスタンスを返します。この RawQuerySet インスタンスは通常の QuerySet のようにイテレートしてオブジェクトインスタンスを生成できます。
これは例で説明するのが一番わかりやすいでしょう。次のようなモデルがあるとします:
\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)\n...\nJohn Smith\nJane Jones\nこの例はたいしてエキサイティングではありません。これは Person.objects.all() を実行したのと全く同じです。しかしながら、 raw() はその機能を極めて強力なものにする数々のオプションを備えています。
raw() は自動的にクエリのフィールドをモデルのフィールドにマップします。
クエリのフィールドの順番は重要ではありません。つまり、以下のクエリはどちらも同じように動作します:
\n>>> Person.objects.raw("SELECT id, first_name, last_name, birth_date FROM myapp_person")\n>>> Person.objects.raw("SELECT last_name, birth_date, first_name, id FROM myapp_person")\nマッチングは名前によって行われます。つまり、SQL の AS 句を使用して、クエリのフィールドをモデルのフィールドにマッピングできます。もし、他のテーブルで Person のデータがあれば、簡単に Person のインスタンスにマッピングできます:
>>> Person.objects.raw("""\n... 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...\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() はインデックスをサポートしているので、最初の結果だけが必要な場合はこう書きます:
\n>>> first_person = Person.objects.raw("SELECT * FROM myapp_person")[0]\nただし、インデックス作成とスライスはデータベースレベルでは実行されません。データベースに多数の Person オブジェクトがある場合は、SQL レベルでクエリを制限する方が効率的です:
\n>>> 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")\nThe Person objects returned by this query will be deferred model instances\n(see defer()). This means that the\nfields that are omitted from the query will be loaded on demand. For example:
>>> for p in Person.objects.raw("SELECT id, first_name FROM myapp_person"):\n... print(\n... p.first_name, # This will be retrieved by the original query\n... p.last_name, # This will be retrieved on demand\n... )\n...\nJohn Smith\nJane Jones\n見た目上は、そのクエリが名前と苗字を両方取得しているように見えます。しかし、この例は実際には 3 つのクエリを発行しています。名前だけが raw() 内のクエリによって取得され、苗字は両方とも表示される時点でその都度取得されました。
省略できないフィールドが一つだけあります。主キーのフィールドです。Django はモデルのインスタンスの識別に主キーを利用するので、素のクエリには必ず含む必要があります。もし主キーを入れ忘れると、 FieldDoesNotExist 例外が発生します。
raw() にパラメータを渡すLink to this heading#パラメータを用いたクエリを使用する場合は、raw() に対して params 引数を利用できます:
>>> lname = "Doe"\n>>> Person.objects.raw("SELECT * FROM myapp_person WHERE last_name = %s", [lname])\nparams はパラメータのリストもしくは辞書です。リストの場合は %s というプレースホルダーを使い、辞書の場合は %(key)s というプレースホルダーを使います ( key は辞書のキーに置き換えられます)、データベースエンジンを意識する必要はありません。このようなプレースホルダは params 引数のパラメータに置き換えられます。
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\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\nSQLインジェクションから保護するために、SQL文字列の %s プレースホルダの前後に引用符を含めてはいけません。
もしリテラルなパーセント記号をクエリ中で使いたい場合、パラメータを渡す際に二重に記述する必要が有る事に注意してください:
\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\n\nwith connections["my_db_alias"].cursor() as cursor:\n # Your code here\n ...\nデフォルトでは、Python データベース API は返す結果にフィールド名を含まず、つまり 辞書 でなく、 リスト の値として結果を返します。処理能力とメモリを少々利用して、次のような処理を用いる事で結果を 辞書 として得られます:
def dictfetchall(cursor):\n """\n Return all rows from a cursor as a dict.\n Assume the column names are unique.\n """\n columns = [col[0] for col in cursor.description]\n return [dict(zip(columns, row)) for row in cursor.fetchall()]\n別の選択肢は Python 標準ライブラリに含まれる collections.namedtuple() を利用する事です。namedtuple は属性を指定して値へのアクセスが可能なタプルに似たオブジェクトです; 加えてインデックスが利用でき、イテレート可能でもあります。取得した結果は不変であり属性名もしくはインデックスでアクセスできて便利です:
from collections import namedtuple\n\n\ndef namedtuplefetchall(cursor):\n """\n Return all rows from a cursor as a namedtuple.\n Assume the column names are unique.\n """\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()]\ndictfetchall() と namedtuplefetchall() の例は、異なるテーブルの列をカーソルは区別できないため、一意な列名を想定しています。
この3つの違いの例を挙げましょう:
\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()\n与えられた名前のストアドプロシージャを呼び出します。入力パラメータのシーケンス (params) または辞書 (kparams) を指定できます。ほとんどのデータベースは kparams をサポートしていません。Django の組み込みバックエンドでは、 Oracle だけがサポートしています。
たとえば、Oracleデータベースで次のようなストアドプロシージャがあるとします:
\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;\nこれは以下のコードで呼び出すことができます。:
\nwith connection.cursor() as cursor:\n cursor.callproc("test_procedure", [1, "test"])\n