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.
\nAo longo deste guia ( e nas referências), nos referiremos sobre os seguintes modelos, os quais compreendem uma aplicação de blog web.
\nfrom django.db import models\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def __str__(self): # __unicode__ on Python 2\n return self.name\n\nclass Author(models.Model):\n name = models.CharField(max_length=200)\n email = models.EmailField()\n\n def __str__(self): # __unicode__ on Python 2\n return self.name\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog)\n headline = models.CharField(max_length=255)\n body_text = models.TextField()\n pub_date = models.DateField()\n mod_date = models.DateField()\n authors = models.ManyToManyField(Author)\n n_comments = models.IntegerField()\n n_pingbacks = models.IntegerField()\n rating = models.IntegerField()\n\n def __str__(self): # __unicode__ on Python 2\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.
Assumindo que os modelos estão em um arquivo mysite/blog/models.py, aqui um exemplo:
>>> 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().
Dado uma instância b5 de Blog que já tenha sido salva no banco de dados, este exemplo altera seu nome e atualiza seu registro no banco de dados:
>>> 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#Atualizar um campo do tipo ForeignKey funciona exatamente da mesma maneira que salvar um campo normal – simplesmente assinale um objeto do tipo correto para o campo em questão. Este exemplo atualiza o atributo blog de uma instância de Entry, assumindo que instâncias apropriadas de Entry``e ``Blog já estejam salvas no banco de dados (então podemos retorná-las abaixo):
>>> from blog.models import 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()\nAtualizar uma classe do tipo ManyToManyField funciona um pouco diferente – use o método add() no campo para adicionar um registro para a relação. Este exemplo adiciona a instância joe de Author ao objeto entry:
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\nPara adicionar múltiplos registros para um ManyToManyField de uma só vez, inclua múltiplos argumentos na chamada do add(), como aqui:
>>> 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.
Você chega a um QuerySet usando o Manager do modelo. Cada mdoelo tem no mínimo um Manager, e é por padrão chamado objects. Acesse ele diretamente através da classe do modelo, como aqui:
>>> 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."\nA Manager é a principal fonte de QuerySets para um modelo. Por exemplo, Blog.objects.all() retorna uma QuerySet que contém todos os objetos do tipo Blog do banco de dados.
A maneira mais simples de recuperar objeto de uma tabela é pegar todos eles. Para fazer isso, use o método all() na Manager:
>>> 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)\nO resultado de um refinamento de uma QuerySet é ela mesma uma QuerySet, tal que é possível encadear refinamentos. Por exemplo:
>>> Entry.objects.filter(\n... headline__startswith='What'\n... ).exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(\n... pub_date__gte=datetime(2005, 1, 30)\n... )\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.
Exemplo
\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())\nEstes três QuerySets são separados. O primeiro é um QuerySet básico contendo todas as entradas que contenham uma manchete iniciando com “What”. O segundo é um subconjunto do primeiro, com um critério adicional que exclui aqueles cujo o pub_date é hoje ou está no futuro. O terceiro é também um subconjunto do primeiro, com um critério adicional que seleciona somente os registros cujo o pub_date é hoje ou está no futuro. A QuerySet (q1) inicial não é afetado pelo processo de refinamento.
QuerySets são “lazy”Link para este cabeçalho#QuerySets são preguiçosos (“lazy”) – o ato de criar uma QuerySet não envolve nenhuma atividade no banco de dados. Você pode epilhar filtros o dia inteiro, e o Django não irá execuar a conssulta realmente até que a QuerySet seja interpretada. Dê uma olhada neste exemplo:
>>> 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.
Se você sabe que somente um objeto combina com sua consulta, você pode usar o método get() em uma Manager o qual retorna o objeto diretamente:
>>> 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.
Por exemplo, isso retorna os 5 primeiros objetos (LIMIT 5):
>>> Entry.objects.all()[:5]\nEste retorna o sexto até o décimo objeto (OFFSET 5 LIMIT 5):
>>> Entry.objects.all()[5:10]\nÍndice negativo (isto é Entry.objects.all()[-1]) não é suportado.
Em geral, fatiar uma QuerySet retorna uma nova QuerySet – isso não interpreta a query. Uma exceção é se você usar o parâmetro “step” da syntax de fatias do Python. Por exemplo, isso deve realmente executar a consulta para que retorne uma lista de cada segundo objeto dos primeiros 10:
>>> Entry.objects.all()[:10:2]\nPara retornar um único objeto ao invés de uma lista (ex. SELECT foo FROM bar LIMIT 1), use um índice simples ao invés de uma fatia. Por exemplo, isso retorna o primeiro Entry do banco de dados, depois de ordenar alfabeticamente pela “headline”:
>>> Entry.objects.order_by('headline')[0]\nIsso é, de maneira rudementar, equivalente a:
\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().
Argumentos nomeados para filtros básicos estão no formato field__lookuptype=value. (aquilo é um “underscore” duplo). Por exemplo:
>>> 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:
\nexactCombinação exata. Por exemplo:
\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
Por exemplo, os dois seguintes argumentos são equivalentes:
\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.
iexactUma combinação que ignora a diferença entre caixa-alta e caixa-baixa. Então a consulta:
\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.
\nO Django oferece uma maneira poderosa e intuitva de “seguir” relacionamento nos filtros, automaticamente cuidando dos JOINs SQL para você, por detrás das cenas. Para abranger um relacionamento, apenas use o nome do campo dos campos relacionados através dos modelos, separados por duplo “underscore”, até chegar ao campo que você quer.
Este exemplo devolve todos os objetos Entry com um Blog o qual o name é 'Beatles Blog':
>>> Entry.objects.filter(blog__name='Beatles Blog')\nA abrangância pode ser tão profunda quanto queira.
\nIsso funciona de trás-pra-frente. Para se referir a um relacionamento “reverso”, apenas use o nome do modelo em mínúsculo.
\nEste exemplo retorna todos os objetos Blog``os quais tem pelo menos uma ``Entry a qual o headline contém '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)\nQuando se está filtrando um objeto baseado em uma ManyToManyField ou em uma ForeignKey reversa, existem dois tipos diferentes de filtros que talvez lhe interesse. Considere o relacionamento Blog/Entry (Blog para Entry é uma relação um-para-muitos). Talvez estejamos interessados em encontrar blogs que tenham uma “entry” a qual tenha “Lennon” no “headline” e foi publicado em 2008. Ou talvez queiramos achar blogs que tenham um “entry” com “Lennon” na “headline” como também uma “entry” que foi publicada em 2008. Uma vez que tenhamos múltiplos “entry”s associados com um único Blog, ambas destas consultas são possíveis e fazem sentido em algumas situações.
O mesmo tipo de situação vêem a tona com uma ManyToManyField. Por exemplo, se um Entry tem um ManyToManyField chamado tags, talvez queiramos encontrar “entry”s conectados com “tags” chamada “music” e “bands” ou talvez queiramos uma “entry”que contém uma “tag” com o nome de “music” e status de “public”.
Para lidar com ambas as situações, o Django tem uma maneira conveniente de processar as chamadas do filter(). Tudo que está dentro de uma única chamada filter() é aplicado simultâneamente para filtrar item de combinem com todos os requerimentos. Chamadas sucessivas de filter() restrigem os conjunto de objetos, mas para relacionamentos com vários valores, eles se aplicam para qualquer objeto conectaco a chamada do primeiro modelo, não necessariamente aqueles objetos que foram selecionada por uma chamada anterior de filter().
Isso pode parecer um pouco confuso, então talvez um exemplo irá carificar. Para selecionar todas as “entries” de blogs que contém “Lennon” na manchete e que foram publicadas em 2008 (a mesma entrada satisfaz ambas as condições), nós poderíamos escrever:
\nBlog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)\nPara selecionar todos os blogs que contenham uma “entry” com “Lennon” na manchete assim como uma “entry” que foi publicada em 2008, podeíamos escrever:
\nBlog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)\nSuponha que exista somente um blog que tenha ambas as “entries” contendo “Lennon” e “entries” de 2008, mas nenhuma das “entries” de 2008 contém “Lennon”. A primeira consulta não irá retornar qualquer blog, mas a segunda consulta irá retornar aquele blog.
\nNo segundo exemplo, o primeiro filtro restringe a consulta a todos aqueles blogs ligados a “entries” com “Lennon” na manchete. O Segundo filtro restringe o conjunto de blogs e ainda aqueles que também são ligados a entradas que foram publicadas em 2008. As “entries” selecionadas por um segundo filtro talvez tehha ou não tenha as mesmas “entries” do primeiro filtro. Estamos filtrando os items Blog com cada comando de filtro, não os items Entry.
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?
\nO Django fornece a F expressions para permitir tais comparações. Instâncias de F() atuam como uma referência a um campo de modelo dentro de uma consulta. Essas referências podem então ser comparadas a valores de dois diferentes campos na mesma instância de modelo.
Por exemplo, para encontrar uma lista de todas “entries” que tenham mais comentários que “pingbacks”, construimos um objeto F() para referenciar o contados de “pingback”, e usar o objeto F() na consulta:
>>> from django.db.models import F\n>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks'))\nO Django suporta o uso de adição, subtração, multiplicação, divisão, módulo, e aritmética poderosa com objetos F(), ambos com constantes e com outros objetos F(). Para encontrar todos os “entries” de blogs com das vezes mais comentários do que “pingbacks”, modificamos a consulta:
>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks') * 2)\nPara encontrar as “entries” onde a taxa de “entry” é menor que a soma da contagem de “pingback” e contagem de comentários, poderíamos fazer a consulta:
\n>>> Entry.objects.filter(rating__lt=F('n_comments') + F('n_pingbacks'))\nPodemos também usar a anotação do duplo “underscore” para abranger relacionamento em um objeto F(). Um objeto F() com duplo “underscore” introduzirá qualquer “join” necessária para acessar objetos relacionados. Por exemplo, para receber todas as “entries” onde o nome do autor é o mesmo que o nome do blog, nós poderíamos fazer a consulta:
>>> Entry.objects.filter(authors__name=F('blog__name'))\nPara data e campos “date/time”, você pode adicionar ou subtrair um objeto do tipo timedelta object. A consulta seguinte retornaria todas as entradas que foram modificadas mais de 3 dias depois que foram publicadas:
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))\nOs objeto F() suportam operações bit a bit através do .bitand() e .bitor(), por exemplo:
>>> F('somefield').bitand(16)\npkLink para este cabeçalho#Por conveniência, o Django fornece um atalho para o filtro pk, o que representa a “chave-primária”.
No modelo Blog de exemplo model, a chave-primária é o campo ìd`, de modo que estes três exemplos são equivalentes:
>>> 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\nO uso da pk não está limitado a consultas __exact – qualquer termo de consulta pode ser combinado com pk para realizar uma consulta com a chave-primária de um modelo:
# 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)\nO filtro pk também funciona através de “joins”. Por exemplo, estes três comandos são equivalentes:
>>> 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.)
Isso significa que as coisas funcionam intuitivamente, de modo que a abstração não atrapalha. Por exemplo, para retornar todas as entradas que contenham um sinal de porcentagem, apenas use o sinal de porcentagem como qualquer outro caracter:
\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”.
Mantenha este comportamento do cache em mente, porque ele pode te pegar se você não usar seu QuerySets de maneira correta. Por exemplo irá criar dois QuerySets, interpretá-los, e jogá-los fora.
>>> 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.
Para evitar este problema, simplesmente salve a QuerySet e reuse-a:
>>> 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]) # Re-use the cache from the evaluation.\nQuerySets não são armazenados no “cache”Link para este cabeçalho#Resultados de consultas nem sempre são salvas no “cache”. Quando interpretar somente parte da consulta, o “cache” é veririficado, mas se ele não estiver populado então os itens retornados pela consulta subsequente não vão para o “cache”. Especificamente, isso significa que limitar consultas usando o fatiamento de “array” ou um índice não irá popular o cache.
\nPor exemplo, pegar um certo índice em um objeto “queryset” repetidamente irá consultar o banco de dados todas as vezes:
\n>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nPorém, se todo o queryset foi interpretado, então o “cache” será verificado:
\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\nAqui estão alguns exemplos de outras ações que irão resultar na interpretação de toda a consulta e portanto populam o “cache”:
\n>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\nQLink para este cabeçalho#Consultas com argumentos nomeados – no filter(), etc. – compõem uma “E”. Se você precisa executar consultas mais complexas (por exemplo, consultas com comandos OR), você pode usar Q objects.
Um objeto Q (django.db.models.Q) é um objeto usado para encapsular uma coleção de argumentos nomeados. Estes argumentos são especificados como um “campo de filtro” acima.
Por exemplo, este objeto Q encapsula uma única consulta LIKE:
from django.db.models import Q\nQ(question__startswith='What')\nObjetos Q podem ser combinados usando os operadores & e |. Quando um operador é usado com dois objetos Q, ele produz um novo objeto ``Q`.
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')\nIsso é o equivalente as seguintes cláusulas SQL WHERE:
WHERE question LIKE 'Who%' OR question LIKE 'What%'\nVocê pode compor comandos de uma complexidade arbitrária combinando objeto Q com os operadores & e | e usar o agrupamento entre parêntesis. Os objetos Q podem também ser negados usando o operador ~, possbilitando combinar filtros que combinem uma consulta normal e um consulta de negação (NOT):
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… grosseiramente traduzido para o 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\nPara comparar duas instâncias de modelos, apenas use o operador Pyhon padrão, o sinal duplo de igual: ==. Por de trás das cenas, compara os valores das chave-primárias dos dois modelos.
Usando o exemplo Entry acima, os comandos seguintes são equivalentes:
>>> some_entry == other_entry\n>>> some_entry.id == other_entry.id\nSe a chave-primária de um modelo não é chamada id, não tem problema. Comparações sempre irão usar a chave-primária, não importa como é chamada. Por exemplo, se a chave-primária de um modelo é chamada name, estes dois comandos são equivalentes:
>>> some_obj == other_obj\n>>> some_obj.name == other_obj.name\nO método de deleção, é convenientemente chamado delete(). Este método deleta imediatamente os objetos e retorna o número de objetos deletados e um dicionário com o número de deleções por tipo de objeto. Exemplo:
>>> e.delete()\n(1, {'weblog.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.
Por exemplo, esse deleta todas os objetos Entry com o ano do pub_date igual 2005:
>>> 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 just set pk to None. Using our blog example:
blog = Blog(name='My blog', tagline='Blogging is easy')\nblog.save() # blog.pk == 1\n\nblog.pk = None\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\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 None:
django_blog.pk = None\ndjango_blog.id = None\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.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.entry = entry\ndetail.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.all().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.select_related().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. Just loop\nover them and call save():
for item in my_queryset:\n item.save()\nCalls to update can also use F expressions to\nupdate one field based on the value of another field in the model. This is\nespecially useful for incrementing counters based upon their current value. For\nexample, to increment the pingback count for every entry in the blog:
>>> Entry.objects.all().update(n_pingbacks=F('n_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