Changes between Version 4 and Version 5 of DocPtDatabaseAPI

Timestamp:

Oct 8, 2006, 6:30:51 PM (19 years ago)

Author:

anonymous

Comment:

--

DocPtDatabaseAPI

@@ -170 +170 @@
 
 
+Recuperando objetos
+===================
+
+Para recuperar objetos de seu banco de dados, você constrói um ``QuerySet`` através de um ``Manager`` (gerente) em sua classe de modelo. 
+
+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:: 
+
+    Blog.objects  # <django.db.models.manager.Manager object at ...>
+    b = Blog(name='Foo', tagline='Bar')
+    b.objects     # AttributeError: "Manager isn't accessible via Blog instances."
+
+(``Managers`` são acessívei somente por via das classes modelos, e não pelas instâncias dos modelos, isto é para garantir a separação entre operações em níveis de tabelas ("table-level") das operações em níveis de registro ("record-level") )
+
+O ``Manager`` é a principal fonte de ``QuerySets`` para um determinado modelo (model). Ele age como uma "raiz" das ``QuerySet`` que descrevem todos os objetos em tabelas de um determinado modelo no banco de dados.
+Por exemplo, ``Blog.objects`` é a ``QuerySet`` inicial que contém todos os objetos ``Blog`` no banco de dados.
+
+
+
+Recuperando todos objetos
+-------------------------
+
+A maneira a mais simples de recuperar objetos de uma tabela é recuperá-los todos de uma vez..  Para fazer isto, use o método ``all()`` em um ``Manager``.
+
+Exemplo::
+
+    all_entries = Entry.objects.all()
+
+O método ``all()`` retorna um ``QuerySet`` de todos os objetos no banco de dados.
+
+(Já que ``Entry.objects`` é um ``QuerySet``, porque nós não podemos utilizar ``Entry.objects``?
+Isto ocorre porque ``Entry.objects``, que é a ``QuerySet`` raíz , é um caso especial que não pode ser avaliado. O método ``all()`` retorna um ``QuerySet`` que *pode* ser avaliado.)
+
+Filtrando objetos
+-----------------
+
+A``QuerySet`` raíz que é fornecida pelo ``Manager`` descreve todos os objetos de um tabela no banco de dados. Embora usualmente, você tenha que escolher somente parte (subset) do completo conjunto de objetos
+
+Para criar tal parte do conjunto, você refina a ``QuerySet`` inicial, adicionando condições como filtros. As duas maneiras mais comuns para refinar um ``QuerySet`` são: 
+
+``filter(**kwargs)``
+    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
+
+Os parâmetros de busca (``**kwargs`` nas funções definidas acima) devem estar no format descrito abaixo em `Field lookups`_.
+
+.. _`Field lookups`: http://www.djangoproject.com/documentation/db_api/#field-lookups
+
+Por exemplo, para obter um ``QuerySet`` das entradas de um blog desde o ano de 2006, use ``filter()`` dessa forma::
+
+    Entry.objects.filter(pub_date__year=2006)
+
+(Note que não temos que adicionar um ``all()`` -- ``Entry.objects.all().filter(...)``. Isto também deve funcionar, porém você somente precisa usar ``all()`` quando você quiser todos os objetos da ``QuerySet`` raíz.)
+
+Filtros encadeados
+------------------
+
+O resultado do refinamento de uma ``QuerySet`` é também um ``QuerySet``, assim é possível encadear outros refinamentos. Por exemplo::
+
+    Entry.objects.filter(
+        headline__startswith='What').exclude(
+            pub_date__gte=datetime.now()).filter(
+                pub_date__gte=datetime(2005, 1, 1))
+
+...observe o ``QuerySet`` inicial com todas entradas contidas no banco de dados, incluia um filtro, depois uma exclusão, e depois outro filtro. O resultado final é um ``QuerySet`` contendo todas as entradas que o cabeçalho (headline) começe com "What", que foram publicados entre 1 de janeiro de 2005 e a data atual.
+
+
 
 }}}