Utföra SQL-frågor i råformatLink to this heading#

Mappning av frågefält till modellfältLink to this heading#

raw() mappar automatiskt fält i frågan till fält i modellen.

Ordningen på fälten i din fråga spelar ingen roll. Med andra ord fungerar båda följande frågor på samma sätt:

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

Matchningen görs med hjälp av namn. Det innebär att du kan använda SQL:s AS-klausuler för att mappa fält i frågan till modellfält. Så om du hade någon annan tabell som hade Person-data i den, kan du enkelt mappa den till Person-instanser:

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

Så länge namnen stämmer överens kommer modellinstanserna att skapas på rätt sätt.

Alternativt kan du mappa fält i frågan till modellfält med hjälp av argumentet translations till raw(). Detta är en ordbok som mappar namn på fält i frågan till namn på fält i modellen. Till exempel kan ovanstående fråga också skrivas:

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

IndexuppslagningarLink to this heading#

raw() stöder indexering, så om du bara behöver det första resultatet kan du skriva:

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

Indexeringen och skivningen utförs dock inte på databasnivå. Om du har ett stort antal Person-objekt i din databas är det mer effektivt att begränsa frågan på SQL-nivå:

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

Uppskjutande av modellfältLink to this heading#

Fält kan också utelämnas:

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

Objekten Person som returneras av denna fråga kommer att vara uppskjutna modellinstanser (se defer()). Detta innebär att de fält som utelämnas från frågan kommer att laddas på begäran. Till exempel:

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

Utåt sett ser det ut som om frågan har hämtat både förnamnet och efternamnet. Men i det här exemplet ställdes faktiskt tre frågor. Endast förnamnen hämtades av raw()-frågan - efternamnen hämtades båda på begäran när de skrevs ut.

Det finns bara ett fält som du inte kan utelämna - fältet för primärnyckeln. Django använder primärnyckeln för att identifiera modellinstanser, så den måste alltid inkluderas i en rå fråga. Ett FieldDoesNotExist undantag kommer att uppstå om du glömmer att inkludera den primära nyckeln.

Lägga till anteckningarLink to this heading#

Du kan också köra frågor som innehåller fält som inte är definierade i modellen. Vi kan till exempel använda PostgreSQL’s age() function för att få en lista över personer med deras åldrar beräknade av databasen:

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

Du kan ofta undvika att använda rå SQL för att beräkna annoteringar genom att istället använda ett Func()-uttryck.

Överföra parametrar till raw()Link to this heading#

Om du behöver utföra parametriserade frågor kan du använda argumentet params till raw():

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

params är en lista eller en ordbok med parametrar. Du använder %s platshållare i frågesträngen för en lista, eller %(key)s platshållare för en ordbok (där key ersätts av en ordboksnyckel), oavsett vilken databasmotor du använder. Sådana platshållare kommer att ersättas med parametrar från argumentet params.

Anslutningar och markörerLink to this heading#

connection och cursor implementerar mestadels standard Python DB-API som beskrivs i PEP 249 - förutom när det gäller transaktionshantering.

Om du inte är bekant med Python DB-API, notera att SQL-satsen i cursor.execute() använder platshållare, "%s", snarare än att lägga till parametrar direkt i SQL. Om du använder den här tekniken kommer det underliggande databasbiblioteket automatiskt att escape dina parametrar vid behov.

Observera också att Django förväntar sig platshållaren "%s", inte platshållaren "?", som används av SQLite Python-bindningar. Detta är för konsekvensens och sanitetens skull.

Använda en markör som kontexthanterare:

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

är likvärdig med:

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