Searching with AdvancedQuery

AdvancedQuery is an excellent product that overcomes several of the more cumbersome limitations otherwise present with plain ZCatalog queries. The comprehensive documentation is available here.

If you want to install it, require it in your add-on product's setup.py:

      install_requires=[
          'setuptools',
          'Products.AdvancedQuery',

AdvancedQuery is straightforward to use. In the simplest scenario, it can simply duplicate the action of running a normal ZCatalog query:

from Products.CMFCore.utils import getToolByName
cat = getToolByName(context, 'portal_catalog')
aq = cat.makeAdvancedQuery({'portal_type' : 'Event', 'review_state' : 'pending'})
brains = cat.evalAdvancedQuery(aq)

At this stage, all it looks like is a slightly more complicated way of doing things that you already know how to do. However, AdvancedQuery comes into its own by making possible things that are otherwise very hard to do with plain ZCatalog queries. For example, we want to get all published Documents sorted first by Creator, and sub-sorted by date of publication:

from Products.CMFCore.utils import getToolByName
cat = getToolByName(context, 'portal_catalog')
aq = cat.makeAdvancedQuery({'portal_type' : 'Document', 'review_state' : 'published'})
brains = cat.evalAdvancedQuery(aq, (('Creator', 'asc'), ('effective', 'asc')))

Or how about only those documents the same as above which have had related items noted against them?

from Products.AdvancedQuery import Ge
from Products.CMFCore.utils import getToolByName
cat = getToolByName(context, 'portal_catalog')
aq = cat.makeAdvancedQuery({'portal_type' : 'Document', 'review_state' : 'published'})
aq &= Ge('getRawRelatedItems', None)
brains = cat.evalAdvancedQuery(aq, (('Creator', 'asc'), ('effective', 'asc')))

As you can see, AdvancedQuery makes specifying exactly what you want from the catalog very easy, and the transition to using it is very straightforward, as it already accepts the same sort of query parameters and format that you are already familiar with. When you are ready, you can mix in more advanced criteria without disturbing your existing way of working with the Catalog Tool.

It's strongly recommended to read the AdvancedQuery documentation linked to above and playing with some of the more advanced options it details.