Uma vez que tenha criado seu modelos de dados, o Django automaticamente lhe dá uma API de abstração do banco de dados que deixa que crie, retorne, edite e delete objetos. Este documento explica como usar essa API. Refira-se a Referência de modelo de dados para detalhes completos de todos os vários modelos de opções de filtros.
\nThroughout this guide (and in the reference), we’ll refer to the following\nmodels, which comprise a blog application:
\nfrom datetime import date\n\nfrom django.db import models\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def __str__(self):\n return self.name\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=200)\n email = models.EmailField()\n\n def __str__(self):\n return self.name\n\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n headline = models.CharField(max_length=255)\n body_text = models.TextField()\n pub_date = models.DateField()\n mod_date = models.DateField(default=date.today)\n authors = models.ManyToManyField(Author)\n number_of_comments = models.IntegerField(default=0)\n number_of_pingbacks = models.IntegerField(default=0)\n rating = models.IntegerField(default=5)\n\n def __str__(self):\n return self.headline\nPara representar uma tabela de banco de dados em objetos Python, o Django usa um sistema intuitivo: Uma classe de modelo que representa uma tabela de banco de dados, e uma intância desta classe representa um registro particular em uma tabela de banco de dados.
\nPara criar um objeto, instancie-o usando argumentos nomeados para a classe de modelo, então chame o save() para persistí-lo no banco de dados.
Assuming models live in a models.py file inside a blog Django app, here\nis an example:
>>> from blog.models import Blog\n>>> b = Blog(name="Beatles Blog", tagline="All the latest Beatles news.")\n>>> b.save()\nEste executa um comando SQL INSERT por detrás dos panos. O Django não acessa o banco de dados até que você chame explicitamente o save().
O método save() não retorna um valor .
Para salvar as alerações para um objeto que já existe no banco de dados, use o save().
Given a Blog instance b5 that has already been saved to the database,\nthis example changes its name and updates its record in the database:
>>> b5.name = "New name"\n>>> b5.save()\nIsso executa um comando SQL UPDATE por detras dos panos. o Django não acessa o banco de dados até que você explicitamente chame o save().
ForeignKey e ManyToManyFieldLink para este cabeçalho#Updating a ForeignKey field works exactly the same\nway as saving a normal field – assign an object of the right type to the field\nin question. This example updates the blog attribute of an Entry\ninstance entry, assuming appropriate instances of Entry and Blog\nare already saved to the database (so we can retrieve them below):
>>> from blog.models import Blog, Entry\n>>> entry = Entry.objects.get(pk=1)\n>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")\n>>> entry.blog = cheese_blog\n>>> entry.save()\nUpdating a ManyToManyField works a little\ndifferently – use the\nadd() method on the field\nto add a record to the relation. This example adds the Author instance\njoe to the entry object:
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\nTo add multiple records to a ManyToManyField in one\ngo, include multiple arguments in the call to\nadd(), like this:
>>> john = Author.objects.create(name="John")\n>>> paul = Author.objects.create(name="Paul")\n>>> george = Author.objects.create(name="George")\n>>> ringo = Author.objects.create(name="Ringo")\n>>> entry.authors.add(john, paul, george, ringo)\nO Django irá reclamar se você tentar assinalar ou adicionar um objeto do tipo errado.
\nPara recuperar objetos do seu banco de dados, construa uma QuerySet através da Manager na sua classe de modelo.
A QuerySet representa uma coleção de objetos do seu banco de dados. Ele pode ter zero, um ou muitos * filtros*. Filtros limitam os resultados baseado nos parâmetros dados. Em termos de SQL, um QuerySet equivale a um comando SELECT, e um filtro é um clásula limitante tal como WHERE or LIMIT.
You get a QuerySet by using your model’s\nManager. Each model has at least one\nManager, and it’s called\nobjects by default. Access it directly via the\nmodel class, like so:
>>> Blog.objects\n<django.db.models.manager.Manager object at ...>\n>>> b = Blog(name="Foo", tagline="Bar")\n>>> b.objects\nTraceback:\n ...\nAttributeError: "Manager isn't accessible via Blog instances."\nThe Manager is the main source of querysets for\na model. For example, Blog.objects.all() returns a\nQuerySet that contains all Blog objects in\nthe database.
The simplest way to retrieve objects from a table is to get all of them. To do\nthis, use the all() method on a\nManager:
>>> all_entries = Entry.objects.all()\nO método all() retorna uma QuerySet de todos os objetos do banco de dados.
A QuerySet retornada pelo all() descreve todos os objetos da tabela do banco de dados. Em geral, porém, você precisa selecionar somente um subconjunto de todo o conjunto de objetos.
Para criar o subconjunto, você refina o QuerySet inicial, adicionando filtros de condições. As duas maneiras mais comuns de refinar um QuerySet são:
filter(**kwargs)Retorna uma nova QuerySet contendo objetos que combinem com os parâmetros de filtros dados.
exclude(**kwargs)Retornam uma nova QuerySet contendo objetos que não combinem com os parâmetros de filtros dados.
Os parâmetros de filtros (**kwargs nas definições da função acima) devem estar no formato descrito em Filtros de campo abaixo.
Prr exemplo, para ter um QuerySet de entradas de blog do ano 2006, use o filter() como aqui:
Entry.objects.filter(pub_date__year=2006)\nCom a classe “manager” padrão, é o mesmo que:
\nEntry.objects.all().filter(pub_date__year=2006)\nThe result of refining a QuerySet is itself a\nQuerySet, so it’s possible to chain\nrefinements together. For example:
>>> Entry.objects.filter(headline__startswith="What").exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(pub_date__gte=datetime.date(2005, 1, 30))\nEle pega o QuerySet inicial com todas as entradas do banco de dados, adiciona um filtro, então adiciona uma exclusão, então outro filtro. O resultado final é um QuerySet contendo todas as entradas com uma manchete que comece com “What”, que foi publicada entre 30 de janeiro de 2005 e o dia de hoje.
QuerySets filtradas são únicasLink para este cabeçalho#Cada vez que refine um QuerySet, você tem uma nova QuerySet que não está de forma alguma vinculada ao anterior QuerySet. Cada refinamento cria uma QuerySet separada e distinta que pode ser armazenada, usada e resusada.
Example:
\n>>> q1 = Entry.objects.filter(headline__startswith="What")\n>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())\n>>> q3 = q1.filter(pub_date__gte=datetime.date.today())\nThese three querysets are separate. The first is a base\nQuerySet containing all entries that contain a\nheadline starting with “What”. The second is a subset of the first, with an\nadditional criteria that excludes records whose pub_date is today or in the\nfuture. The third is a subset of the first, with an additional criteria that\nselects only the records whose pub_date is today or in the future. The\ninitial QuerySet (q1) is unaffected by the\nrefinement process.
QuerySets são “lazy”Link para este cabeçalho#QuerySet objects are lazy – the act of creating a\nQuerySet doesn’t involve any database\nactivity. You can stack filters together all day long, and Django won’t\nactually run the query until the QuerySet is\nevaluated. Take a look at this example:
>>> q = Entry.objects.filter(headline__startswith="What")\n>>> q = q.filter(pub_date__lte=datetime.date.today())\n>>> q = q.exclude(body_text__icontains="food")\n>>> print(q)\nApesar de parece que isso seja três acessos ao banco de dados, de fato ele acessa o banco de dados somente um vez, na última linha (print(q)). Em geral, os resultados de uma QuerySet não são buscados no banco de dados até que você “peça” por eles. Quando fizer, a QuerySet é interpretada acessando o banco de dados. Para mais detalhes de quando exatamente a interpretação ocorre, veja When QuerySets are evaluated.
get()Link para este cabeçalho#O filter() sempre lhe dará um QuerySet, mesmo se um único objeto combina com a consulta - neste caso, ele será uma QuerySet que contém um único elemento.
If you know there is only one object that matches your query, you can use the\nget() method on a\nManager which returns the object directly:
>>> one_entry = Entry.objects.get(pk=1)\nVocê pode usar qualquer expressão de consulta com get(), tal como com filter() - denovo, veja o Campos de consulta abaixo.
Note que existe uma diferença entre usar o get(), e usar o filter() com uma fatia de [0]. Se não houver resultados que combinem com a consulta, o get() irá emitir uma exceção DoesNotExist. Esta exceção é um atributo da classe de modelo na qual a consulta está sendo realizada - no código acima, se não houver objeto Entry com a chave-primária de 1, o Django irá emitir um Entry.DoesNotExist.
De maneira similar, o Django irá reclamar se mais de um item combinar com a consulta get(). Neste caso, ele emitirá um MultipleObjectsReturned, o qual denovo é ele próprio um atributo da classe de modelo.
QuerySet métodosLink para este cabeçalho#Na maioria das vezes você usará o all(), get(), filter() e o exclude() quando precisar buscar objetos no banco de dados. Porém, está longe do todo que existe; veja the a Refrêcia da API de QuerySet para uma lista completa das vários métodos da QuerySet.
QuerySetsLink para este cabeçalho#Use um subconjunto da syntax de fatias de array Python para limitar seu QuerySet para um certo número de resultados. Este é o equivalente às cláusulas SQL Limit e OFFSET.
For example, this returns the first 5 objects (LIMIT 5):
>>> Entry.objects.all()[:5]\nThis returns the sixth through tenth objects (OFFSET 5 LIMIT 5):
>>> Entry.objects.all()[5:10]\nÍndice negativo (isto é Entry.objects.all()[-1]) não é suportado.
Generally, slicing a QuerySet returns a new\nQuerySet – it doesn’t evaluate the query. An\nexception is if you use the “step” parameter of Python slice syntax. For\nexample, this would actually execute the query in order to return a list of\nevery second object of the first 10:
>>> Entry.objects.all()[:10:2]\nFurther filtering or ordering of a sliced queryset is prohibited due to the\nambiguous nature of how that might work.
\nTo retrieve a single object rather than a list\n(e.g. SELECT foo FROM bar LIMIT 1), use an index instead of a slice. For\nexample, this returns the first Entry in the database, after ordering\nentries alphabetically by headline:
>>> Entry.objects.order_by("headline")[0]\nThis is roughly equivalent to:
\n>>> Entry.objects.order_by("headline")[0:1].get()\nNote, porém, que o primeiro irá emitir um IndexError enquanto o segundo emitirá um DoesNotExist se nenhum objeto combinar com o critério dado. Veja o get() para mais detalhes.
Filtros de campo é o que você usa para especiíicar os parâmetros da cláusula WHERE. Eles são especificados como argumentos nomeados para os métodos da QuerySet: filter(), exclude() e get().
Basic lookups keyword arguments take the form field__lookuptype=value.\n(That’s a double-underscore). For example:
>>> Entry.objects.filter(pub_date__lte="2006-01-01")\nTraduzido (groseiramente) no seguinte SQL:
\nSELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';\nO campo especificado em um filtro tem que ser um nome de campoo do modelo. Existe uma exceção porém, no caso de uma ForeignKey você pode especificar o nome do campo com um sufixo _id. Neste caso, é esperado que o valor do parâmetro contenha literalmente o valor da chave-primária do modelo estrageiro. Por exemplo:
>>> Entry.objects.filter(blog_id=4)\nSe você passar um argumento nomeado inválido, a funçao do filtro irá emitir um TypeError.
The database API supports about two dozen lookup types; a complete reference\ncan be found in the field lookup reference. To give you\na taste of what’s available, here’s some of the more common lookups you’ll\nprobably use:
\nexactAn “exact” match. For example:
\n>>> Entry.objects.get(headline__exact="Cat bites dog")\nGeraria SQL ao longo destas linhas:
\nSELECT ... WHERE headline = 'Cat bites dog';\nSe você não fornecer um tipo de filtro – isto é, se o seu argumento nomeado não contiver um “underscore” duplo – o tipo de filtro é assumido como sendo exact
For example, the following two statements are equivalent:
\n>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\nIsso se dá por conveniência, porque os filtros exact são casos comuns.
iexactA case-insensitive match. So, the query:
\n>>> Blog.objects.get(name__iexact="beatles blog")\nDeveria encontrar um Blog entitulado "Beatles Blog", "beatles blog", ou mesmo "BeAtlES blOG".
containsTeste de contenção sensíveis ao tipo de caixa. Por exemplo:
\nEntry.objects.get(headline__contains="Lennon")\nMais ou menos traduzido para este SQL:
\nSELECT ... WHERE headline LIKE '%Lennon%';\nNote que este irá encontrar o “headline” 'Today Lennon honored' mas não o 'today lennon honored'.
Existe também uma versão que ignora o tipo de caixa, icontains.
startswith, endswithBusca começa-com e termina-com, respectivamente. Existe também a versão que ignora o tipo de caixa chamada istartswith e iendswith.
Denovo, isso aqui somente arranha a superfície. Uma refrência completa pode ser achada na Referência de filtros de campo.
\nDjango offers a powerful and intuitive way to “follow” relationships in\nlookups, taking care of the SQL JOINs for you automatically, behind the\nscenes. To span a relationship, use the field name of related fields\nacross models, separated by double underscores, until you get to the field you\nwant.
This example retrieves all Entry objects with a Blog whose name\nis 'Beatles Blog':
>>> Entry.objects.filter(blog__name="Beatles Blog")\nA abrangância pode ser tão profunda quanto queira.
\nIt works backwards, too. While it can be customized by setting\nrelated_query_name, by default you\nrefer to a “reverse” relationship in a lookup using the lowercase name of the\nmodel.
This example retrieves all Blog objects which have at least one Entry\nwhose headline contains 'Lennon':
>>> Blog.objects.filter(entry__headline__contains="Lennon")\nSe você estiver filtrando através de múltiplos relacionamentos e um dos modelos intermediários não tiver um valor que vá de encontro com a condição do filtro, o Django irá tratá-lo como se houvesse um objeto vazio (todos os valores são NULL), mas válido. Tudo isso significa que nenhum erro será emitido. Por exemplo, neste filtro:
Blog.objects.filter(entry__authors__name="Lennon")\n(se houvesse um modelo Author relacionado), se não houvesse author associado com uma “entry”, seria tratado como se também não houvesse um name anexo, ao invés de emitir um erro por causa do author faltante.
Blog.objects.filter(entry__authors__name__isnull=True)\nirá retornar objeto do tipo Blog que tenham um name vazio no author a também aqueles os quais tem um author vazio no entry. Se você não que estes últimos objetos, você poderia escrever:
Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)\nWhen spanning a ManyToManyField or a reverse\nForeignKey (such as from Blog to Entry),\nfiltering on multiple attributes raises the question of whether to require each\nattribute to coincide in the same related object. We might seek blogs that have\nan entry from 2008 with “Lennon” in its headline, or we might seek blogs that\nmerely have any entry from 2008 as well as some newer or older entry with\n“Lennon” in its headline.
To select all blogs containing at least one entry from 2008 having “Lennon”\nin its headline (the same entry satisfying both conditions), we would write:
\nBlog.objects.filter(entry__headline__contains="Lennon", entry__pub_date__year=2008)\nOtherwise, to perform a more permissive query selecting any blogs with merely\nsome entry with “Lennon” in its headline and some entry from 2008, we\nwould write:
\nBlog.objects.filter(entry__headline__contains="Lennon").filter(\n entry__pub_date__year=2008\n)\nSuppose there is only one blog that has both entries containing “Lennon” and\nentries from 2008, but that none of the entries from 2008 contained “Lennon”.\nThe first query would not return any blogs, but the second query would return\nthat one blog. (This is because the entries selected by the second filter may\nor may not be the same as the entries in the first filter. We are filtering the\nBlog items with each filter statement, not the Entry items.) In short,\nif each condition needs to match the same related object, then each should be\ncontained in a single filter() call.
Nos exemplos dados até agora, construímos filtros que comparam o valor de um campo de modelo com uma constante. Mas e se você quiser comparar o valor de um modelo com outro campo no mesmo modelo?
\nDjango provides F() expressions to allow such comparisons. Instances of\nF() act as a reference to a model field within a query. These references\ncan then be used in query filters to compare the values of two different fields\non the same model instance.
For example, to find a list of all blog entries that have had more comments\nthan pingbacks, we construct an F() object to reference the pingback count,\nand use that F() object in the query:
>>> from django.db.models import F\n>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks"))\nDjango supports the use of addition, subtraction, multiplication, division,\nmodulo, and power arithmetic with F() objects, both with constants and with\nother F() objects. To find all the blog entries with more than twice as\nmany comments as pingbacks, we modify the query:
>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks") * 2)\nTo find all the entries where the rating of the entry is less than the\nsum of the pingback count and comment count, we would issue the\nquery:
\n>>> Entry.objects.filter(rating__lt=F("number_of_comments") + F("number_of_pingbacks"))\nYou can also use the double underscore notation to span relationships in\nan F() object. An F() object with a double underscore will introduce\nany joins needed to access the related object. For example, to retrieve all\nthe entries where the author’s name is the same as the blog name, we could\nissue the query:
>>> Entry.objects.filter(authors__name=F("blog__name"))\nFor date and date/time fields, you can add or subtract a\ntimedelta object. The following would return all entries\nthat were modified more than 3 days after they were published:
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F("pub_date") + timedelta(days=3))\nThe F() objects support bitwise operations by .bitand(), .bitor(),\n.bitxor(), .bitrightshift(), and .bitleftshift(). For example:
>>> F("somefield").bitand(16)\nDjango supports using transforms in expressions.
\nFor example, to find all Entry objects published in the same year as they\nwere last modified:
>>> from django.db.models import F\n>>> Entry.objects.filter(pub_date__year=F("mod_date__year"))\nTo find the earliest year an entry was published, we can issue the query:
\n>>> from django.db.models import Min\n>>> Entry.objects.aggregate(first_published_year=Min("pub_date__year"))\nThis example finds the value of the highest rated entry and the total number\nof comments on all entries for each year:
\n>>> from django.db.models import OuterRef, Subquery, Sum\n>>> Entry.objects.values("pub_date__year").annotate(\n... top_rating=Subquery(\n... Entry.objects.filter(\n... pub_date__year=OuterRef("pub_date__year"),\n... )\n... .order_by("-rating")\n... .values("rating")[:1]\n... ),\n... total_comments=Sum("number_of_comments"),\n... )\npkLink para este cabeçalho#Por conveniência, o Django fornece um atalho para o filtro pk, o que representa a “chave-primária”.
In the example Blog model, the primary key is the id field, so these\nthree statements are equivalent:
>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\n>>> Blog.objects.get(pk=14) # pk implies id__exact\nThe use of pk isn’t limited to __exact queries – any query term\ncan be combined with pk to perform a query on the primary key of a model:
# Get blogs entries with id 1, 4 and 7\n>>> Blog.objects.filter(pk__in=[1, 4, 7])\n\n# Get all blog entries with id > 14\n>>> Blog.objects.filter(pk__gt=14)\npk lookups also work across joins. For example, these three statements are\nequivalent:
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form\n>>> Entry.objects.filter(blog__id=3) # __exact is implied\n>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact\nLikeLink para este cabeçalho#Os campos filtros que equivalem ao comando SQL LIKE (iexact, contains, icontains, startswith, istartswith, endswith and iendswith) irão automaticamente substituir os dois caracteres especiais usados em comandos LIKE – o sinal de porcentagem e o “underscore”. (Em um comando LIKE, o sinal de porcentagem significa múltiplos-caracteres curingas e o “underscore” siginifica um único caracter curinga.)
This means things should work intuitively, so the abstraction doesn’t leak.\nFor example, to retrieve all the entries that contain a percent sign, use the\npercent sign as any other character:
\n>>> Entry.objects.filter(headline__contains="%")\nO Django irá cuidar da citação por você; o SQL resultante se parecerá com algo como:
\nSELECT ... WHERE headline LIKE '%\\%%';\nO mesmo vale para os “underscores”. Ambos os sinais, porcentagem e “underscores”, são manipulados para você de maneira transparente.
\nQuerySetssLink para este cabeçalho#Cada QuerySet contém um “cache” para minimizar o acesso ao banco de dados. Entendendo como isso funciona lhe permitirá escrever código mais eficiente.
Em uma classe QuerySet que acaba de ser criada, o “cache” está vazio. A primeira vez que a QuerySet é interpretada – e portanto, uma consulta ao banco acontece – o Django salva o resultado da consulta no “cache” da QuerySet’s e retorna o resultado que foi requerido explicitamente (exemplo, o próximo elemento, se o QuerySet está sendo iterado). Execuçãoes subsequentes do QuerySet reusam os resultados que estão no “cache”.
Keep this caching behavior in mind, because it may bite you if you don’t use\nyour QuerySets correctly. For example, the\nfollowing will create two QuerySets, evaluate\nthem, and throw them away:
>>> print([e.headline for e in Entry.objects.all()])\n>>> print([e.pub_date for e in Entry.objects.all()])\nIsso significa que a mesma consulta de banco de dados será executada duas vezes, efetivamente dobrando a carga no banco de dados. Também existe a posibilidade das duas listas não incluírem os mesmos registros de banco de dados, porque uma Entry talvez tenha sido adicionada ou deletada durante a fração de segundo entre as duas requisições.
To avoid this problem, save the QuerySet and\nreuse it:
>>> queryset = Entry.objects.all()\n>>> print([p.headline for p in queryset]) # Evaluate the query set.\n>>> print([p.pub_date for p in queryset]) # Reuse the cache from the evaluation.\nQuerySets não são armazenados no “cache”Link para este cabeçalho#Querysets do not always cache their results. When evaluating only part of\nthe queryset, the cache is checked, but if it is not populated then the items\nreturned by the subsequent query are not cached. Specifically, this means that\nlimiting the queryset using an array slice or an\nindex will not populate the cache.
\nFor example, repeatedly getting a certain index in a queryset object will query\nthe database each time:
\n>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nHowever, if the entire queryset has already been evaluated, the cache will be\nchecked instead:
\n>>> queryset = Entry.objects.all()\n>>> [entry for entry in queryset] # Queries the database\n>>> print(queryset[5]) # Uses cache\n>>> print(queryset[5]) # Uses cache\nHere are some examples of other actions that will result in the entire queryset\nbeing evaluated and therefore populate the cache:
\n>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\nIf you are writing asynchronous views or code, you cannot use the ORM for\nqueries in quite the way we have described above, as you cannot call blocking\nsynchronous code from asynchronous code - it will block up the event loop\n(or, more likely, Django will notice and raise a SynchronousOnlyOperation\nto stop that from happening).
Fortunately, you can do many queries using Django’s asynchronous query APIs.\nEvery method that might block - such as get() or delete() - has an\nasynchronous variant (aget() or adelete()), and when you iterate over\nresults, you can use asynchronous iteration (async for) instead.
The default way of iterating over a query - with for - will result in a\nblocking database query behind the scenes as Django loads the results at\niteration time. To fix this, you can swap to async for:
async for entry in Authors.objects.filter(name__startswith="A"):\n ...\nBe aware that you also can’t do other things that might iterate over the\nqueryset, such as wrapping list() around it to force its evaluation (you\ncan use async for in a comprehension, if you want it).
Because QuerySet methods like filter() and exclude() do not\nactually run the query - they set up the queryset to run when it’s iterated\nover - you can use those freely in asynchronous code. For a guide to which\nmethods can keep being used like this, and which have asynchronous versions,\nread the next section.
QuerySet and manager methodsLink para este cabeçalho#Some methods on managers and querysets - like get() and first() - force\nexecution of the queryset and are blocking. Some, like filter() and\nexclude(), don’t force execution and so are safe to run from asynchronous\ncode. But how are you supposed to tell the difference?
While you could poke around and see if there is an a-prefixed version of\nthe method (for example, we have aget() but not afilter()), there is a\nmore logical way - look up what kind of method it is in the\nQuerySet reference.
In there, you’ll find the methods on QuerySets grouped into two sections:
\nMethods that return new querysets: These are the non-blocking ones,\nand don’t have asynchronous versions. You’re free to use these in any\nsituation, but understand the constraint of no deferred queries before\nusing defer(),\nonly(), or\nfetch_mode().
Methods that do not return querysets: These are the blocking ones, and\nhave asynchronous versions - the asynchronous name for each is noted in its\ndocumentation, though our standard pattern is to add an a prefix.
Using this distinction, you can work out when you need to use asynchronous\nversions, and when you don’t. For example, here’s a valid asynchronous query:
\nuser = await User.objects.filter(username=my_input).afirst()\nfilter() returns a queryset, and so it’s fine to keep chaining it inside an\nasynchronous environment, whereas first() evaluates and returns a model\ninstance - thus, we change to afirst(), and use await at the front of\nthe whole expression in order to call it in an asynchronous-friendly way.
Relations are deferred by default. If the blog relation is not prefetched,\naccessing entry.blog during asynchronous evaluation of a queryset attempts\na blocking database query, raising SynchronousOnlyOperation. (A similar\nlimitation applies to fields deferred via defer() or only().) To avoid\nthis, see the advice on prefetching in Objetos relacionados.
Transactions are not currently supported with asynchronous queries and\nupdates. You will find that trying to use one raises\nSynchronousOnlyOperation.
If you wish to use a transaction, we suggest you write your ORM code inside a\nseparate, synchronous function and then call that using sync_to_async - see\nSuporte assíncrono for more.
JSONFieldLink para este cabeçalho#Lookups implementation is different in JSONField,\nmainly due to the existence of key transformations. To demonstrate, we will use\nthe following example model:
from django.db import models\n\n\nclass Dog(models.Model):\n name = models.CharField(max_length=200)\n data = models.JSONField(null=True)\n\n def __str__(self):\n return self.name\nNoneLink para este cabeçalho#As with other fields, storing None as the field’s value will store it as\nSQL NULL. While not recommended, it is possible to store JSON scalar\nnull instead of SQL NULL by using the JSONNull() expression.
Whichever of the values is stored, when retrieved from the database, the Python\nrepresentation of the JSON scalar null is the same as SQL NULL, i.e.\nNone. Therefore, it can be hard to distinguish between them.
This only applies to None as the top-level value of the field. If None\nis inside a list or dict, it will always be interpreted\nas JSON null.
When querying, isnull=True is used to match SQL NULL,\nwhile exact-matching JSONNull() is used to match JSON null.
>>> from django.db.models import JSONNull\n>>> Dog.objects.create(name="Max", data=None) # SQL NULL.\n<Dog: Max>\n>>> Dog.objects.create(name="Archie", data=JSONNull()) # JSON null.\n<Dog: Archie>\n>>> Dog.objects.filter(data=None)\n...: RemovedInDjango70Warning: Using None as the right-hand side of an\nexact lookup on JSONField to mean JSON scalar 'null' is deprecated. Use\nJSONNull() instead (or use the __isnull lookup if you meant SQL NULL).\n...\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data=JSONNull())\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data__isnull=True)\n<QuerySet [<Dog: Max>]>\n>>> Dog.objects.filter(data__isnull=False)\n<QuerySet [<Dog: Archie>]>\nUnless you are sure you wish to work with SQL NULL values, consider setting\nnull=False and providing a suitable default for empty values, such as\ndefault=dict.
To query based on a given dictionary key, use that key as the lookup name:
\n>>> Dog.objects.create(\n... name="Rufus",\n... data={\n... "breed": "labrador",\n... "owner": {\n... "name": "Bob",\n... "other_pets": [\n... {\n... "name": "Fishy",\n... }\n... ],\n... },\n... },\n... )\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": None})\n<Dog: Meg>\n>>> Dog.objects.filter(data__breed="collie")\n<QuerySet [<Dog: Meg>]>\nTo query a key for JSON null, None or JSONNull() can be used.
>>> Dog.objects.filter(data__owner=None)\n<Dog: Meg>\n>>> Dog.objects.filter(data__owner=JSONNull())\n<Dog: Meg>\nMultiple keys can be chained together to form a path lookup:
\n>>> Dog.objects.filter(data__owner__name="Bob")\n<QuerySet [<Dog: Rufus>]>\nIf the key is an integer, it will be interpreted as an index transform in an\narray:
\n>>> Dog.objects.filter(data__owner__other_pets__0__name="Fishy")\n<QuerySet [<Dog: Rufus>]>\nIf the key is a negative integer, it cannot be used in a filter keyword\ndirectly, but you can still use dictionary unpacking to use it in a query:
\n>>> Dog.objects.filter(**{"data__owner__other_pets__-1__name": "Fishy"})\n<QuerySet [<Dog: Rufus>]>\nIf the key you wish to query by clashes with the name of another lookup, use\nthe contains lookup instead.
To query for missing keys, use the isnull lookup:
>>> Dog.objects.create(name="Shep", data={"breed": "collie"})\n<Dog: Shep>\n>>> Dog.objects.filter(data__owner__isnull=True)\n<QuerySet [<Dog: Shep>]>\nKT() expressionsLink para este cabeçalho#Represents the text value of a key, index, or path transform of\nJSONField. You can use the double underscore\nnotation in lookup to chain dictionary key and index transforms.
Por exemplo:
\n>>> from django.db.models.fields.json import KT\n>>> Dog.objects.create(\n... name="Shep",\n... data={\n... "owner": {"name": "Bob"},\n... "breed": ["collie", "lhasa apso"],\n... },\n... )\n<Dog: Shep>\n>>> Dog.objects.annotate(\n... first_breed=KT("data__breed__1"), owner_name=KT("data__owner__name")\n... ).filter(first_breed__startswith="lhasa", owner_name="Bob")\n<QuerySet [<Dog: Shep>]>\ncontainsLink para este cabeçalho#The contains lookup is overridden on JSONField. The returned\nobjects are those where the given dict of key-value pairs are all\ncontained in the top-level of the field. For example:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contains={"owner": "Bob"})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"breed": "collie"})\n<QuerySet [<Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"tricks": ["dance"]})\n<QuerySet [<Dog: Merry>]>\ncontained_byLink para este cabeçalho#This is the inverse of the contains lookup - the\nobjects returned will be those where the key-value pairs on the object are a\nsubset of those in the value passed. For example:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})\n<QuerySet [<Dog: Meg>, <Dog: Fred>]>\n>>> Dog.objects.filter(data__contained_by={"breed": "collie"})\n<QuerySet [<Dog: Fred>]>\n>>> Dog.objects.filter(\n... data__contained_by={"breed": "pekingese", "tricks": ["dance", "fetch", "hug"]}\n... )\n<QuerySet [<Dog: Merry>, <Dog: Fred>]>\nhas_keyLink para este cabeçalho#Returns objects where the given key is in the top-level of the data. For\nexample:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_key="owner")\n<QuerySet [<Dog: Meg>]>\nhas_keysLink para este cabeçalho#Returns objects where all of the given keys are in the top-level of the data.\nFor example:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_keys=["breed", "owner"])\n<QuerySet [<Dog: Meg>]>\nhas_any_keysLink para este cabeçalho#Returns objects where any of the given keys are in the top-level of the data.\nFor example:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nQLink para este cabeçalho#Keyword argument queries – in filter(),\netc. – are “AND”ed together. If you need to execute more complex queries (for\nexample, queries with OR statements), you can use Q() objects.
A Q object (django.db.models.Q) is an object used to\nencapsulate a collection of keyword arguments. These keyword arguments are\nspecified as in “Field lookups” above.
Por exemplo, este objeto Q encapsula uma única consulta LIKE:
from django.db.models import Q\n\nQ(question__startswith="What")\nQ objects can be combined using the &, |, and ^ operators. When\nan operator is used on two Q objects, it yields a new Q object.
Por exemplo, este comando produz um único objeto Q que representa o OR de duas consultas "question__startswith":
Q(question__startswith="Who") | Q(question__startswith="What")\nThis is equivalent to the following SQL WHERE clause:
WHERE question LIKE 'Who%' OR question LIKE 'What%'\nYou can compose statements of arbitrary complexity by combining Q objects\nwith the &, |, and ^ operators and use parenthetical grouping.\nAlso, Q objects can be negated using the ~ operator, allowing for\ncombined lookups that combine both a normal query and a negated (NOT)\nquery:
Q(question__startswith="Who") | ~Q(pub_date__year=2005)\nPara cada função de filtro que recebe argumentos nominados (ex.: filter(), exclude(), get()) pode também se passado um ou mais objetos ``Q``como argumentos posicionais (not-named). Se você prover múltiplos objetos ``Q``para uma função filtro, os argumentos serão interpolados com lógicas “E”. Por exemplo:
Poll.objects.get(\n Q(question__startswith="Who"),\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n… roughly translates into the SQL:
\nSELECT * from polls WHERE question LIKE 'Who%'\n AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')\nFunções de filtro podem misturar o uso de objetos Q e argumentos nomeados. Todos os argumentos fornecidos para uma função filtro (sejam eles argumentos nomeados ou objetos Q) são interpolados com “E”. Porém, se um objeto Q é fornecido, é necessário que este preceda qualquer argumento nomeado. Por exemplo:
Poll.objects.get(\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n question__startswith="Who",\n)\n… seria uma consulta válida, equivalente ao exemplo anterior; mas:
\n# INVALID QUERY\nPoll.objects.get(\n question__startswith="Who",\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n… não seria válido.
\n\nTo compare two model instances, use the standard Python comparison operator,\nthe double equals sign: ==. Behind the scenes, that compares the primary\nkey values of two models.
Using the Entry example above, the following two statements are equivalent:
>>> some_entry == other_entry\n>>> some_entry.id == other_entry.id\nIf a model’s primary key isn’t called id, no problem. Comparisons will\nalways use the primary key, whatever it’s called. For example, if a model’s\nprimary key field is called name, these two statements are equivalent:
>>> some_obj == other_obj\n>>> some_obj.name == other_obj.name\nThe delete method, conveniently, is named\ndelete(). This method immediately deletes the\nobject and returns the number of objects deleted and a dictionary with\nthe number of deletions per object type. Example:
>>> e.delete()\n(1, {'blog.Entry': 1})\nVocê também pode deletar objetos em massa. Cada QuerySet tem um método delete(), o qual deleta todos os membros daquele QuerySet.
For example, this deletes all Entry objects with a pub_date year of\n2005:
>>> Entry.objects.filter(pub_date__year=2005).delete()\n(5, {'webapp.Entry': 5})\nKeep in mind that this will, whenever possible, be executed purely in SQL, and\nso the delete() methods of individual object instances will not necessarily\nbe called during the process. If you’ve provided a custom delete() method\non a model class and want to ensure that it is called, you will need to\n“manually” delete instances of that model (e.g., by iterating over a\nQuerySet and calling delete() on each\nobject individually) rather than using the bulk\ndelete() method of a\nQuerySet.
When Django deletes an object, by default it emulates the behavior of the SQL\nconstraint ON DELETE CASCADE – in other words, any objects which had\nforeign keys pointing at the object to be deleted will be deleted along with\nit. For example:
b = Blog.objects.get(pk=1)\n# This will delete the Blog and all of its Entry objects.\nb.delete()\nThis cascade behavior is customizable via the\non_delete argument to the\nForeignKey.
Note that delete() is the only\nQuerySet method that is not exposed on a\nManager itself. This is a safety mechanism to\nprevent you from accidentally requesting Entry.objects.delete(), and\ndeleting all the entries. If you do want to delete all the objects, then\nyou have to explicitly request a complete query set:
Entry.objects.all().delete()\nAlthough there is no built-in method for copying model instances, it is\npossible to easily create new instance with all fields’ values copied. In the\nsimplest case, you can set pk to None and\n_state.adding to True. Using our\nblog example:
blog = Blog(name="My blog", tagline="Blogging is easy")\nblog.save() # blog.pk == 1\n\nblog.pk = None\nblog._state.adding = True\nblog.save() # blog.pk == 2\nThings get more complicated if you use inheritance. Consider a subclass of\nBlog:
class ThemeBlog(Blog):\n theme = models.CharField(max_length=200)\n\n\ndjango_blog = ThemeBlog(name="Django", tagline="Django is easy", theme="python")\ndjango_blog.save() # django_blog.pk == 3\nDue to how inheritance works, you have to set both pk and id to\nNone, and _state.adding to True:
django_blog.pk = None\ndjango_blog.id = None\ndjango_blog._state.adding = True\ndjango_blog.save() # django_blog.pk == 4\nThis process doesn’t copy relations that aren’t part of the model’s database\ntable. For example, Entry has a ManyToManyField to Author. After\nduplicating an entry, you must set the many-to-many relations for the new\nentry:
entry = Entry.objects.all()[0] # some previous entry\nold_authors = entry.authors.all()\nentry.pk = None\nentry._state.adding = True\nentry.save()\nentry.authors.set(old_authors)\nFor a OneToOneField, you must duplicate the related object and assign it\nto the new object’s field to avoid violating the one-to-one unique constraint.\nFor example, assuming entry is already duplicated as above:
detail = EntryDetail.objects.all()[0]\ndetail.pk = None\ndetail._state.adding = True\ndetail.entry = entry\ndetail.save()\nNote that it is not possible to copy instances of models with deferred fields\nusing this pattern unless values are assigned to them:
\n>>> blog = Blog.objects.defer("name")[0]\n>>> blog.pk = None\n>>> blog._state.adding = True\n>>> blog.save()\nTraceback (most recent call last):\n ...\nAttributeError: Cannot retrieve deferred field 'name' from an unsaved model.\n>>> blog.name = "Another Blog"\n>>> blog.save()\nAlgumas vezes você querer definir um campo para um particular valor para todos os objetos em uma :classe:`~django.db.models.query.QuerySet`. Você pode fazer isto com o :método:`~django.db.models.query.QuerySet.update` método. Por exemplo:
\n# Update all the headlines with pub_date in 2007.\nEntry.objects.filter(pub_date__year=2007).update(headline="Everything is the same")\nYou can only set non-relation fields and ForeignKey\nfields using this method. To update a non-relation field, provide the new value\nas a constant. To update ForeignKey fields, set the\nnew value to be the new model instance you want to point to. For example:
>>> b = Blog.objects.get(pk=1)\n\n# Change every Entry so that it belongs to this Blog.\n>>> Entry.objects.update(blog=b)\nThe update() method is applied instantly and returns the number of rows\nmatched by the query (which may not be equal to the number of rows updated if\nsome rows already have the new value). The only restriction on the\nQuerySet being updated is that it can only\naccess one database table: the model’s main table. You can filter based on\nrelated fields, but you can only update columns in the model’s main\ntable. Example:
>>> b = Blog.objects.get(pk=1)\n\n# Update all the headlines belonging to this Blog.\n>>> Entry.objects.filter(blog=b).update(headline="Everything is the same")\nBe aware that the update() method is converted directly to an SQL\nstatement. It is a bulk operation for direct updates. It doesn’t run any\nsave() methods on your models, or emit the\npre_save or post_save signals (which are a consequence of calling\nsave()), or honor the\nauto_now field option.\nIf you want to save every item in a QuerySet\nand make sure that the save() method is called on\neach instance, you don’t need any special function to handle that. Loop over\nthem and call save():
for item in my_queryset:\n item.save()\nCalls to update can also use F() expressions to update one field based on\nthe value of another field in the model. This is especially useful for\nincrementing counters based upon their current value. For example, to increment\nthe pingback count for every entry in the blog:
\n>>> Entry.objects.update(number_of_pingbacks=F("number_of_pingbacks") + 1)\nHowever, unlike F() objects in filter and exclude clauses, you can’t\nintroduce joins when you use F() objects in an update – you can only\nreference fields local to the model being updated. If you attempt to introduce\na join with an F() object, a FieldError will be raised:
# This will raise a FieldError\n>>> Entry.objects.update(headline=F("blog__name"))\nIf you find yourself needing to write an SQL query that is too complex for\nDjango’s database-mapper to handle, you can fall back on writing SQL by hand.\nDjango has a couple of options for writing raw SQL queries; see\nPerforming raw SQL queries.
\nFinally, it’s important to note that the Django database layer is merely an\ninterface to your database. You can access your database via other tools,\nprogramming languages or database frameworks; there’s nothing Django-specific\nabout your database.
\n