Changes between Version 7 and Version 8 of DocPtDatabaseAPI

Timestamp:

Oct 12, 2006, 2:22:35 PM (18 years ago)

Author:

mario.caseiro at gmail.com

Comment:

--

DocPtDatabaseAPI

@@ -37 +37 @@
 
 Este documento cobre a versão 0.95 de Django e a versão do desenvolvimento. Docs anteriores: `0.90`_, `0.91`_
-----------------------------------------------------------------------------------------------------------------
+
 
 .. _0.90: http://www.djangoproject.com/documentation/0_90/ 
@@ -89 +89 @@
     from mysite.blog.models import Blog
     b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.')
+
     b.save()
 
@@ -119 +120 @@
 
 Especificando explicitamente valores  auto-primary-key 
-------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 
 Caso tenha um modelo com um campo ``AutoField`` mas você queira definir o ID de um objeto explicitamente quando o salvar, é só defini-lo explicitamente antes de salvá-lo, ao invés de deixar a auto atribuição do ID.
@@ -149 +151 @@
 Para salvar alterações em um objeto que já exista no banco de dados, use ``save()``. 
 
+
 Dado a instância ``b5`` do ``Blog``, que já tenha sido salva no banco de dados, demonstramos no exemplo abaixo, como alterar seu nome e atualizar tal registro no banco de dados:: 
 
@@ -177 +180 @@
 Um ``QuerySet`` representa uma coleção dos objetos em seu banco de dados. Pode ter zero, um ou muitos *filtros* (filters) --critérios que reduzem, estreitam a coleção baseando-se em parâmetros fornecidos. Em termos SQL, um ``QuerySet`` equivale a uma declaração ``SELECT``, e um filtro uma cláusula condicional como ``WHERE`` ou ``LIMIT``. 
 
+
 Você obtém um ``QuerySet`` usando o ``Manager`` dos seus modelos (models class). Cada modelo tem pelo menos um ``Manager``, e é chamado ``objects`` por padrão. Acesse-o diretamente através das classes modelos (models classes), dessa maneira:: 
 
@@ -214 +218 @@
     Retorna um novo ``QuerySet`` contendo objetos que casam com o determinado parâmetro de busca
 
+
 ``exclude(**kwargs)``
     Retorna um novo ``QuerySet`` contendo objetos que *não* casam com o determinado parâmetro de busca
@@ -228 +233 @@
 
 Filtros encadeados
-------------------
+~~~~~~~~~~~~~~~~~~
 
 O resultado do refinamento de uma ``QuerySet`` é também um ``QuerySet``, assim é possível encadear outros refinamentos. Por exemplo::
@@ -252 +257 @@
 Estes três ``QuerySets`` estão separados. O primeiro é um ``QuerySet`` base contendo todas as entradas que possuem um cabeçalho (headline) que começa com ?What?. O segundo é um subconjunto do primeiro, com critérios adicionais que exclui os registros cujo ``pub_date`` são maiores do que a data atual. O terceiro é um subconjunto do primeiro, com critérios adicionais que selecionam somente os registros cujo ``pub_date`` são maiores que a data atual. O ``QuerySet`` inicial  (``q1``) não é afetado pelo processo do refinamento. 
 
+
 QuerySets são preguiçosas
 -------------------------
@@ -258 +264 @@
 
 
-Quando QuerySets são avaliados
-------------------------------
+Quando QuerySets são assímilados
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Você pode avaliar um ``QuerySet`` nas seguintes situações: 
 
     * **Iteration.** O ``QuerySet`` é iterativo, e executa sua query no banco de dados na primeira vez que você itera sobre ele. Por exemplo, isto imprimirá o cabeçalho (headline) de todas as entradas no banco de dados:: 
+
 
           for e in Entry.objects.all():
@@ -285 +292 @@
 -------------------
 
+Use a syntax de extração de parcelas de arrays do  Python para limitar o seu ``QuerySet`` para um certo número de resultados. Isto é o equivalente das cláusulas SQL ``LIMIT`` e ``OFFSET``.
+
+Por exemplo, isto retorna os 5 primeiros objetos(``LIMIT 5``)::
+
+    Entry.objects.all()[:5]
+
+Isto retorna do quinto ao decimo objeto(``OFFSET 5 LIMIT 5``)::
+
+    Entry.objects.all()[5:10]
+
+Geralmente, extrair parcelas de um ``QuerySet`` retorna um ``QuerySet``  novo -- não avalía (executa) a query. Uma exceção é se você usar o parâmetro de ?step? da sintaxe da extração de parcelas do Python. Por exemplo, isto executaria realmente a query a fim de retornar uma lista de cada *segundo* objeto dos primeiros 10:: 
+
+    Entry.objects.all()[:10:2]
+
+
+Para recuperar um *único* objeto ao invés de uma lista  (por exemplo ``SELECT foo FROM bar LIMIT 1``), use simplismente um índice em vez de uma parcela (sclice). Por exemplo, isto retorna a primeira ``Entry`` no banco de dados, após ordenar entradas alfabeticamente pelo cabeçalho (headline):: 
+
+    Entry.objects.order_by('headline')[0]
+
+Isto é aproximadamente equivalente a:: 
+
+    Entry.objects.order_by('headline')[0:1].get()
+
+Note, entretanto, que o primeiro destes levantará ``IndexError`` equanto o segundo levantará ``DoesNotExist`` se nenhum objeto combinar os critérios dados. 
+
+Método de QuerySet que retornam novos QuerySets
+-----------------------------------------------
+
+Django fornece uma gama de métodos para refinamento de ``QuerySet`` que modificam ou os tipos de resultados retornados pelo ``QuerySet`` ou a maneira sua query SQL é executada. 
+
+``filter(**kwargs)``
+~~~~~~~~~~~~~~~~~~~~
+
+Retorna um novo``QuerySet`` contendo objetos que casam com o determinado parâmetro de busca
+
+Os parâmetros de busca (``**kwargs``) devem estar no formato descrito em `Field lookups`_ logo abaixo. Múltiplos parametros são juntados via ``AND`` na declaração SQL subjacente.
+
+``exclude(**kwargs)``
+~~~~~~~~~~~~~~~~~~~~~
+
+Retorna um novo``QuerySet`` contendo objetos que *não* casam com o determinado parâmetro de busca
+
+Os parâmetros de busca (``**kwargs``) devem estar no formato descrito em `Field lookups`_ logo abaixo. Múltiplos parâmetros são juntados via ``AND`` na declaração SQL subjacente, e tudo isto  delimitado por ``NOT()``.
+
+
+
+
+Este exemplo exclue todas entradas que ``pub_date`` é a date/time corrente  E (AND) aqueles que o cabeçalho (``headline``) é  "Hello"::
+
+    Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')
+
+em termos SQL, isto é assimilado como::
+
+    SELECT ...
+    WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')
+
+Este exemplo excluí todas entradas que ``pub_date`` é a date/time corrente OU (OR) aqueles que o cabeçalho (``headline``) é  "Hello"::
+
+    Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello')
+
+
+em termos SQL, isto é assimilado como::
+
+    SELECT ...
+
+    WHERE NOT pub_date > '2005-1-3' AND NOT headline = 'Hello'
+
+Note que o segundo exemplo é mais restritivo.
+
+
+``order_by(*fields)``
+~~~~~~~~~~~~~~~~~~~~~
+
+Por padrão, os resultados retornados por um ``QuerySet`` são ordenados pela tupla dada na opção ``ordering`` no ``Meta`` do modelo. Você pode sobrescrever isto em  um ``QuerySet`` usando o método ``order_by``. 
+
+Exemplo::
+
+    Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')
+
+O resultado acima será ordenado por ``pub_date`` decresente, então por ``headline`` crescente. O sinal negativo na frente de ``"-pub_date"`` indica a ordem *decrescente*. A ordem Crescente é implícita. Para requisitar aleatòria, use ``"?"``, como assim:: 
+
+    Entry.objects.order_by('?')
+
+Para ordenar por um campo de uma tabela diferente, adicione o nome da outra tabela e um ponto , assim como:: 
+
+    Entry.objects.order_by('blogs_blog.name', 'headline')
+
+Não há nenhuma maneira de especificar se a Ordenação deve ser "case sensitive". Com respeito à "case sensitive", Django ordenará os resultados apesar do backend de que seu banco de dados normalmente já os ordene . 
+
+
+``distinct()``
+~~~~~~~~~~~~~~
+
+Retorna um novo ``QuerySet`` que utiliza ``SELECT DISTINCT`` na query SQL. Isto elimina linhas duplicadas dos resultados da query.
+
+Por padrão, um``QuerySet`` não irá eliminar linhas duplicadas. Na prática, isto  raramente é um problema, porque as querys simples tais como ``Blog.objects.all()`` não introduzem no resultado a possibilidade de linhas duplicadas. 
+
+Entretanto, se sua query refere-se a múltiplas tabelas , é possível obter resultados duplicados quando um ``QuerySet`` é assimilado. Este é o caso de quando você deveria usar ``distinct()``. 
+
+``values(*fields)``
+~~~~~~~~~~~~~~~~~~~
+
+Retorna um ``ValuesQuerySet`` -- um ``QuerySet`` que assimila uma lista de dicionários ao invés do modelo-instância de objetos. 
+
+Cada um daqueles dicionários representa um objeto, com as chaves que correspondem aos nomes dos atributos dos objetos de modelo. 
+
+Este exemplo compara os dicionários de ``values()`` com os objetos de modelo normais:: 
+
+    # Esta lista contem um objeto de Blog .
+    >>> Blog.objects.filter(name__startswith='Beatles')
+    [Beatles Blog]
+
+    # Esta lista contem um dicionário.
+    >>> Blog.objects.filter(name__startswith='Beatles').values()
+    [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]
+
+``values()`` leva argumentos de posições opcionais, os ``*fields``, que especifica  nomes dos campos a que  ``SELETO`` deve se limitar. Se você especificar os campos, cada dicionário conterá somente as chaves/valores dos campos  que você especificou. Se você não especificar os campos, cada dicionário conterá uma chave e um valor para cada campo na tabela do banco de dados. 
+
+Exemplo::
+
+    >>> Blog.objects.values()
+    [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
+    >>> Blog.objects.values('id', 'name')
+    [{'id': 1, 'name': 'Beatles Blog'}]
+
+Um ``ValuesQuerySet`` é útil quando você sabe que você necessitará somente valores de um pequeno número de campos disponíveis e você não necessitará  a funcionalidade da instância de um objeto de modelo. É mais eficiente selecionar somente os campos que você necessita usar. 
+
+Finalmente, note que um ``ValuesQuerySet`` é uma subclasse de ``QuerySet``, assim possui todos os métodos de ``QuerySet``. Você pode chamar ``filter()`` nele, ou ``order_by()``, ou outro método qualquer. Sim, isso significa que estas duas chamadas são idênticas:: 
+
+    Blog.objects.values().order_by('id')
+    Blog.objects.order_by('id').values()
+
+As pessoas que fizeram Django preferem pôr todos os métodos SQL de alterações primeiro, seguido (opcionalmente) por quaisquer métodos de manipulem saída (tais como ``values()``), mas isso não importa realmente. Esta é sua oportunidade de realmente "flaunt" seu individualismo. 
+
+``dates(field, kind, order='ASC')``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retorna um ``DateQuerySet`` -- um ``QuerySet`` que assimila uma lista de  ``datetime.datetime`` objetos representando todas as datas disponíveis de um tipo particular dentro dos conteúdos do ``QuerySet``. 
+
+``field`` deve ser o nome de um ``DateField`` ou ``DateTimeField`` de seu modelo
+
+``tipo`` (kind) deve ser tanto ``"year"``, ``"month"`` ou ``"day"``. Cada ``datetime.datetime`` objeto na lista resultante é truncado ("truncated") ao tipo (``type``) fornecido.
+
+    * ``"year"`` retorna uma lista de todos os valores distintos de ANOS para o campo.
+    * ``"month"`` retorna uma lista de todos os valores distintos de MESES para o campo.
+    * ``"day"`` retorna uma lista de todos os valores distintos de DIAS para o campo.
+
+``order``, que por padrão é ``'ASC'``, deve ser tanto ``'ASC'`` (crescente) ou ``'DESC'`` (decrescente). Isto especifica a ordem dos resultados.
+
+Exemplos::
+
+    >>> Entry.objects.dates('pub_date', 'year')
+    [datetime.datetime(2005, 1, 1)]
+    >>> Entry.objects.dates('pub_date', 'month')
+    [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
+    >>> Entry.objects.dates('pub_date', 'day')
+    [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
+    >>> Entry.objects.dates('pub_date', 'day', order='DESC')
+    [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
+    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
+    [datetime.datetime(2005, 3, 20)]
+
+``select_related()``
+~~~~~~~~~~~~~~~~~~~~
+Retorna um ``QuerySet`` que automaticamente "segue"  os relacionamentos de chave-estrangeira, selecionando os dados adicionais do objeto-relacionado quando executa a query. Este é um impulsionador de desempenho que resulta  em querys (às vezes, muito)maiores mas o uso posterior dos relacionamentos de chave-estrangeiras não requerem novas queries no banco de dados. 
+
+Os seguintes exemplos ilustram a diferença entre buscas simples e buscas ``select_related()``. Está aqui a busca padrão:: 
+
+    # Aciona o banco de dados.
+    e = Entry.objects.get(id=5)
+
+    # Aciona o banco de dados novamente para obter o objeto Blog relacionado.
+    b = e.blog
+
+Agora a busca ``select_related`` ::
+
+    # Aciona o banco de dados.
+    e = Entry.objects.select_related().get(id=5)
+
+    # Não aciona o banco de dados, porque e.blog já foi previamente populado na query anterior.
+    b = e.blog
+
+``select_related()`` segue as chaves-estrangeiras tão longe quanto possível. Se você tiver os seguintes modelos:
+
+    class City(models.Model):
+        # ...
+
+    class Person(models.Model):
+        # ...
+        hometown = models.ForeignKey(City)
+
+    class Book(models.Model):
+        # ...
+        author = models.ForeignKey(Person)
+
+...então chamar ``Book.objects.select_related().get(id=4)`` irá fazer um cache da pessoa (``Person``) relacionada *e* da cidade (``City``) relacionada::
+
+    b = Book.objects.select_related().get(id=4)
+    p = b.author         # Não aciona o banco de dados.
+    c = p.hometown       # Não aciona o banco de dados..
+
+    sv = Book.objects.get(id=4) # Sem select_related() neste exemplo.
+    p = b.author         # Aciona o banco de dados.
+    c = p.hometown       # Aciona o banco de dados.
+
+Note que ``select_related()`` não segue chaves-estrangeiras que tenham ``null=True``.
+
+``extra(select=None, where=None, params=None, tables=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Às vezes, a sintaxe de query do Django por sí não pode fàcilmente expressar uma cláusula ``WHERE`` complexa. Para estes casos limitados, Django fornece o modificador de ``QuerySet`` ``extra()``-- uma brecha para injetar cláusulas específicas no SQL gerado pelo ``QuerySet``. 
+
+Por definição, estas buscas extras podem não ser portáveis aos diferentes engines de banco de dados (porque você está escrevendo explicitamente um código SQL) e viola o princípio DRY, assim você deve evitá-los sempre que possível. 
+
+
+
 }}}