[Zope-Checkins] CVS: Zope/lib/python/Products/ZCatalog/help - ZCatalog.py:1.15

[Casey Duncan]

Update of /cvs-repository/Zope/lib/python/Products/ZCatalog/help
In directory cvs.zope.org:/tmp/cvs-serv30520/help

Modified Files:
	ZCatalog.py 
Log Message:
Major refactor of the catalog search engine centered around optimizing sort by index operations. The resulting code greatly outperforms the previous version and uses less memory.

Exposed a new ZCatalog method "search" which has a better interface for programmatic searches. Updated documentation as well.

Implemented a sort limit option which allows you to inform the catalog that you are only interested in a certain number of results. In the common case this allows the ZCatalog machinery to use a different sorting algorithm (N-Best) which scales much better then a full sort.

Also more tightly integrated the merge option which allows you to tell the catalog that you would like raw and unsorted intermediate results returned rather than sorted and lazified results. This can be used to efficiently merge search results across multiple catalogs.


=== Zope/lib/python/Products/ZCatalog/help/ZCatalog.py 1.14 => 1.15 ===
--- Zope/lib/python/Products/ZCatalog/help/ZCatalog.py:1.14	Wed Aug 14 18:25:15 2002
+++ Zope/lib/python/Products/ZCatalog/help/ZCatalog.py	Thu Dec  5 16:17:07 2002
@@ -178,6 +178,10 @@
 
           sort_order -- You can specify 'reverse' or 'descending'.
           Default behavior is to sort ascending.
+          
+          sort_limit -- An optimization hint to tell the catalog how many
+          results you are really interested in. See the limit argument
+          to the search method for more details.
 
         There are some rules to consider when querying this method:
 
@@ -210,4 +214,27 @@
     def __call__(REQUEST=None, **kw):
         """
         Search the catalog, the same way as 'searchResults'.
+        """
+
+    def search(query_request, sort_index=None, reverse=0, limit=None, merge=1):
+        """Programmatic search interface, use for searching the catalog from
+        scripts.
+            
+        query_request -- Dictionary containing catalog query. This uses the 
+        same format as searchResults.
+        
+        sort_index -- Name of sort index
+        
+        reverse -- Boolean, reverse sort order (defaults to false)
+        
+        limit -- Limit sorted result count to the n best records. This is an
+        optimization hint used in conjunction with a sort_index. If possible
+        ZCatalog will use a different sort algorithm that uses much less memory
+        and scales better then a full sort. The actual number of records
+        returned is not guaranteed to be <= limit. You still need to apply the
+        same batching to the results.
+
+        merge -- Return merged, lazy results (like searchResults) or raw 
+        results for later merging. This can be used to perform multiple
+        queries (even across catalogs) and merge and sort the combined results.
         """