Commits

Matt Chaput  committed fff1376

Docs updates.

  • Participants
  • Parent commits 38cf3bb

Comments (0)

Files changed (3)

File docs/source/recipes.rst

 Whoosh recipes
 ==============
 
+General
+=======
+
+Get the stored fields for a document from the document number
+-------------------------------------------------------------
+::
+
+    stored_fields = searcher.stored_fields(docnum)
+
+
+Searching
+=========
+
+Find every document
+-------------------
+::
+
+    myquery = query.Every()
+
+
+iTunes-style search-as-you-type
+-------------------------------
+
+Use the :class:`whoosh.analysis.NgramWordAnalyzer` as the analyzer for the
+field you want to search as the user types. You can save space in the index by
+turning off positions in the field using ``phrase=False``, since phrase
+searching on N-gram fields usually doesn't make much sense::
+
+    # For example, to search the "title" field as the user types
+    analyzer = analysis.NgramWordAnalyzer()
+    title_field = fields.TEXT(analyzer=analyzer, phrase=False)
+    schema = fields.Schema(title=title_field)
+
+See the documentation for the :class:`~whoosh.analysis.NgramWordAnalyzer` class
+for information on the available options.
+
+
 Shortcuts
 =========
 
         ...
 
 
-Queries
+Sorting
 =======
 
+See :doc:`facets`.
+
+
+Speed up sorting/grouping by QueryFacet
+---------------------------------------
+::
+
+    # Runtime query facet
+    qfacet = sorting.QueryFacet({"a-m": TermRange("name", "a", "m"),
+                                 "n-z": TermRange("name", "n", "zzzzz")})
+    results = searcher.search(myquery, sortedby=qfacet)
+    
+    # Cache the query facet in a pseudo-field
+    searcher.define_facets("nameranges", qfacet, save=True)
+    
+    # Use the pseudo-field to sort/group instead of the QueryFacet
+    results = searcher.search(myquery, sortedby="nameranges")
 
 
 Results
 Global information
 ==================
 
+How many documents are in the index?
+------------------------------------
+::
+
+    # Including documents that are deleted but not yet optimized away
+    numdocs = searcher.doc_count_all()
+    
+    # Not including deleted documents
+    numdocs = searcher.doc_count()
+
+
 What fields are in the index?
 -----------------------------
 ::
 
     return myindex.schema.names()
 
+
 Is term X in the index?
 -----------------------
 ::
 
     return ("content", "wobble") in searcher
+
+
+How many times does term X occur in the index?
+----------------------------------------------
+::
+
+    # Number of times content:wobble appears in all documents
+    freq = searcher.frequency("content", "wobble")
     
+    # Number of documents containing content:wobble
+    docfreq = searcher.doc_frequency("content", "wobble")
+
+
 Is term X in document Y?
 ------------------------
 ::

File docs/source/searching.rst

 Sorting
 -------
 
-Instead of sorting the matched documents by a score, you can sort them by the
-contents of one or more indexed field(s). These should be fields for which each
-document stores one term (i.e. an ID field type), for example "path", "id",
-"date", etc.
-
-To sort by the contents of the "path" field::
-
-    results = s.search(myquery, sortedby="path")
-    
-To sort by the contents of the "date" field, and within that the "id" field::
-
-    results = s.search(myquery, sortedby=["path", "date"])
-    
-To reverse the sort order::
-
-    results = s.search(myquery, sortedby="path", reverse=True)
-
-To do more complex sorts (with different fields sorted in different directions)
-use a Sorter object. See :doc:`api/sorting`.
-
-Sorting relies on field caches. See :doc:`fieldcaches` for information about
-field caches.
+See :doc:`facets`.
 
 
 Highlighting snippets and More Like This
 ``Results.extend(results)``
     Adds the documents in 'results' on to the end of the list of result
     documents.
-    
+
 ``Results.filter(results)``
     Removes the documents in 'results' from the list of result documents.
-    
+
 ``Results.upgrade(results)``
     Any result documents that also appear in 'results' are moved to the top of
     the list of result documents.
-    
+
 ``Results.upgrade_and_extend(results)``
     Any result documents that also appear in 'results' are moved to the top of
     the list of result documents. Then any other documents in 'results' are

File src/whoosh/searching.py

         :class:`whoosh.sorting.FieldFacet` or
         :class:`whoosh.sorting.MultiFacet` and pass it to the
         :meth:`Searcher.search` method's ``sortedby`` keyword argument.
+        
+        See :doc:`/facets`.
         """
         
         return sorting.Sorter(self, *args, **kwargs)
 
     def define_facets(self, name, qs, save=False):
+        """This is an experimental feature which may change in future versions.
+        
+        Adds a field cache for a synthetic field defined by a dictionary of
+        queries. This creates a persistent cache to speed up a
+        :class:`whoosh.sorting.QueryFacet`. You can then use the new "field"
+        for sorting and/or faceting.
+        
+        For example, sorting using a :class:`~whoosh.sorting.QueryFacet`
+        recomputes the queries at sort time, which may be slow::
+        
+            qfacet = sorting.QueryFacet({"a-z": TermRange(...
+            results = searcher.search(myquery, sortedby=qfacet)
+            
+        You can cache the results of the query facet in a field cache and use
+        the pseudo-field for sorting::
+        
+            searcher.define_facets("nameranges", qfacet, save=True)
+            
+            results = searcher.search(myquery, sortedby="nameranges")
+        
+        See :doc:`/facets`.
+        
+        :param name: a name for the pseudo-field to cache the query results in.
+        :param qs: a QueryFacet object or dictionary mapping key values to
+            :class:`whoosh.query.Query` objects.
+        :param save: if True, saves the field cache to disk so it is persistent
+            across searchers. The default is False, which only creates the
+            field cache in memory.
+        """
+        
+        if isinstance(qs, sorting.QueryFacet):
+            qs = qs.querydict
+        
         def doclists_for_searcher(s):
-            return dict((key, q.docs(s)) for key, q in iteritems(qs))
+            return dict((key, q.docs(s)) for key, q in qs.items())
         
         if self.subsearchers:
             for s in self.subsearchers:
             dls = doclists_for_searcher(self)
             self.ixreader.define_facets(name, dls, save=save)
     
-    def docs_for_query(self, q, leafs=True):
-        if self.subsearchers and leafs:
+    def docs_for_query(self, q):
+        """Returns an iterator of document numbers for documents matching the
+        given :class:`whoosh.query.Query` object.
+        """
+        
+        if self.subsearchers:
             for s, offset in self.subsearchers:
                 for docnum in q.docs(s):
                     yield docnum + offset