Search Scope

  • Article

Search Scope

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

The Search Scope is used to issue a search query on a folder scope. This process is similar to how you might query a table in a database. You define the scope of a search by using the Structured Query Language (SQL) SCOPE Element. Within the SCOPE Element, you define the depth and a URL for the folders to be searched. For shallow searches, you specify 'shallow traversal of'; for deep searches, you specify 'deep traversal of'; for hierarchical searches, you specify 'hierarchical traversal of'. After specifying the depth, you specify the URL for each folder. The syntax for these statements is as follows:

SCOPE('shallow traversal of "http://myserver/public"')     'shallow traversal of "http://myserver/public"
SCOPE('deep traversal of "http://myserver/public2"')       'deep traversal of "http://myserver/public2"
SCOPE('hierarchical traversal of "http://myserver/public"')  'hierarchical traversal of "http://myserver/public"

Use of the SCOPE Element is optional. If the element is not used, the search depth defaults to a shallow traversal. If you specify a SCOPE Element but do not specify a depth for a folder, the search defaults to a deep traversal. For example, the following statement defaults to a shallow traversal:

SELECT "DAV:href" FROM "http://myserver/public"

This statement defaults to a deep traversal:

SELECT "DAV:href" FROM SCOPE('"URL"')

Shallow Traversal

A shallow traversal search examines the resources in the specified folder, but not in any of the subfolders. To find all child folders contained within a particular folder, you would execute the following SQL statement:

SELECT "DAV:href", "DAV:displayname"
FROM SCOPE('shallow traversal of "http://myserver/public"')
WHERE "DAV:isfolder" = True and "DAV:ishidden" = False

This query returns all visible folders in the folder specified by a URL. The traversal is shallow, so subfolders are not searched.

Deep Traversal

Specifying a deep traversal in the SCOPE Element executes a search against any and all subfolders of the given folder, all the way to the bottom of the folder hierarchy. This means that every item in the folder structure of every subfolder is opened and examined during the search. Thus, deep traversal searches against large folder hierarchies that contain many resources can be very expensive to execute. A deep traversal search will also lock off the hierarchy to prevent the hierarchy from being modified while the search is in progress.

To find every item with property 'MyNamespace:MyProp' of value 'thisvalue' within a particular folder hierarchy, you would execute the following SQL statement:

SELECT "DAV:displayname"
FROM SCOPE('deep traversal of "http://myserver/mystore"')
WHERE "MyNamespace:MyProp" = 'thisvalue'

In some cases, it may be better to use Exchange Store Search Folders than repeated deep traversal searches, which provide a way to cache the results of frequently executed deep traversal searches. It is also more efficient to use shallow traversal searches over multiple folders than to do one deep traversal search over the same folders. When you are only searching against folder information, for instance, trying to determine the folder hierarchy of a public store or a mailbox store, it is much more efficient to use hierarchical traversal searches than a deep traversal search.

You cannot perform a deep traversal in the MAPI client public store installed by Microsoft® Exchange Server 2003, but you can perform deep traversals of private stores or of any other public folder trees. Only a shallow traversal search against a single folder is supported in the public folder tree designated for MAPI clients. If you specify a deep traversal or multiple folders, an error is returned.

Hierarchical Traversal

A hierarchical traversal search is executed only against folder resources in a specified folder. A hierarchical traversal search can be used for a task such as determining the folder hierarchy of a specified folder. For example, the following search returns the names of all subfolders in the publicinfo folder.

SELECT "DAV:displayname"
FROM SCOPE('hierarchical traversal of "http://myserver/publicinfo"')

Searching Multiple Folders

To search multiple folders you can specify multiple scopes in the query, as in the following shallow traversal search example:

SELECT "DAV:displayname"
FROM SCOPE('shallow traversal of "http://myserver/public"',
           'shallow traversal of "http://myserver/public/userinfo"',
           'shallow traversal of "http://myserver/public/userinfo/phonenumber"')

When specifying multiple folders in your SCOPE Element, you must use the same depth for each folder. You cannot mix deep and shallow searches within the same SQL command.

Note  Searching multiple folders by specifying multiple scopes in the query is not supported on a MAPI enabled public store.

To increase efficiency, multiple shallow traversal searches can be used in place of a single deep traversal search. Shallow traversal searches against multiple folders do not have the constraint of locking the folder hierarchy, as do deep traversal searches.

Send us your feedback about the Microsoft Exchange Server 2003 SDK.

Build: June 2007 (2007.618.1)

© 2003-2006 Microsoft Corporation. All rights reserved. Terms of use.