Partager via

Using the ISearchQueryHelper Interface

  • Article

You can develop a component or helper class to query the index by using the ISearchQueryHelper interface. This interface is implemented as a helper class to ICatalogSearchManager and is obtained by calling ISearchCatalogManager::GetQueryHelper. This interface helps you:

  • Obtain an OLE DB connection string to connect to the Windows Search database.
  • Convert user queries to Microsoft Structured Query Language (SQL).

This topic contains the following subjects:

  • Using the GenerateSqlFromUserQuery Method
  • Working with Locale Identifiers
  • Working with Properties and Columns
  • Working with Query Term Expansion
  • Working with Other ISearchQueryHelper Methods
  • Preparing to Use ISearchQueryhelper
  • Related Topics

 

Using the GenerateSqlFromUserQuery Method

The GenerateSQLFromUserQuery method transforms user input into a SQL query string, which can then be submitted to the OLE DB provider for Windows Search. This method translates the Advanced Query Syntax (AQS) or Natural Query Syntax (NQS) query entered by the user into SQL, and lets you add other SQL fragments as needed.

The SQL query string is returned in the following form:

SELECT <QuerySelectColumns> 
FROM <CatalogName that created query helper>
WHERE <Result of interpreting the user query passed into this function according to QuerySyntax>
      [ AND|OR <QueryWhereRestrictions> ]

The following is an example of the SQL string returned from the call GenerateSQLFromUserQuery("comput"):

SELECT "System.ItemUrl" 
FROM "SystemIndex" 
WHERE ((CONTAINS(*,'"comput*"',1033) RANK BY COERCION(Absolute, 1)) OR 
       (FREETEXT(("System.ItemNameDisplay":0.9, *:0.1), 'comput', 1033) AND CONTAINS(*,'"comput"',1033)))
ORDER BY "System.ItemUrl"

Note  The method generates both the FREETEXT and the CONTAINS predicates because CONTAINS alone does not generate meaningful ranking.

 

Working with Locale Identifiers

Method Description
get_QueryContentLocale/put_QueryContentLocale Gets/Puts the language code identifier (LCID) of the query. This helps get the correct wordbreaker and stemmer to compare query terms against the catalog/inverted index. The default is the current input locale.
get_QueryKeywordLocale/put_QueryKeywordLocale Gets/Puts the LCID for the language to use when parsing Advanced Query Syntax (AQS) keywords. The default is the default user locale.

The content locale and keyword locale are locale code identifiers (LCID) that help the search engine use the correct word breakers by identifying the language of the query terms and the language the AQS keywords. These are not always the same LCIDs because Windows Search is offered in a number of international versions and also includes Multilingual User Interface (MUI) packs for more languages. The content locale identifies the LCID for the language users input their search query in, while the keyword locale identifies the LCID the search engine uses when parsing Advanced Query Syntax (AQS) keywords.

For example, if you have the English-US version with no MUI packs, both the content locale and keyword locale are 1033. If you have the German version with no MUI packs, then both the content locale and keyword locale are 1031 (gr-gr). However, if you have the English version with the Romanian MUI pack, the content locale is 2072 (ro) and the keyword locale is 1033 (en-us).

 

Working with Properties and Columns

Methods Description
get_QueryContentProperties/put_QueryContentProperties Gets/Sets the content properties for the search (property column listed in the CONTAINS or FREETEXT clauses).
get_QuerySelectColumns/put_QuerySelectColumns Gets/Sets the columns (or properties) requested in the SELECT statement. The default is System.ItemUrl and properties used in the WHERE clause.

Items are represented in the property store as a row. Each row contains a number of columns that represent properties for that item. Not all items will have a value for a given property. For example, an audio file would typically not contain a value for the System.FromName property but may contain information regarding the System.Music.Artist.

With these methods, you access or modify the property with a comma delimited, null-terminated, Unicode string that specifies one or more column names of the property store: "System.Document.Author, System.Document.Title".

 

Working with Query Term Expansion

Methods Description
get_QueryTermExpansion
put_QueryTermExpansion		 Gets/Sets the search term expansion flag.

This method enables the expansion of some query terms with wild card characters, similar to regular expression expansion. Stem expansion searches for words with the same linguistic root as the query term (man/men, or swim/swam/swimming) while prefix expansion searches for words with the same prefix (fun/funnel). If not set, the default value is SEARCH_TERM_PREFIX_ALL. The values of this flag are as follows:

  • SEARCH_TERM_PREFIX_ALL - All search terms are expanded
  • SEARCH_TERM_NO_EXPANSION - No search terms are expanded
  • SEARCH_TERM_STEM_ALL - All search terms are stem expanded

 

Working with Other ISearchQueryHelper Methods

Many of the methods in the ISearchQueryHelper interface are used to set query arguments or define the properties returned.

Methods Description
get_ConnectionString Returns the OLE DB connection string. This is the preferred method of getting a properly formatted and correct connection string.
get_QueryMaxResults
put_QueryMaxResults		 Gets/Sets the maximum number of results to be returned by a query (i.e., SELECT TOP n). The default is -1, meaning that no maximum results clause is generated.
get_QuerySorting
put_QuerySorting		 Gets/Sets the sort order for the query result set (ORDER BY). If no ORDER BY clause exists, the results are returned in non-deterministic order.
get_QuerySyntax
put_QuerySyntax		 Gets/Sets the syntax of the query: Advanced Query Syntax or Natural Query Syntax.
get_QueryWhereRestrictions
put_QueryWhereRestrictions		 Gets/Sets the restrictions appended via WHERE clauses.

 

Preparing to Use ISearchQueryhelper

There are a few key interfaces and methods you should be aware of before you can start programmatically querying Windows Search using the ISearchQueryHelper interface. At a high level, you need to follow these steps:

  1. Instantiate an ISearchManager instance.

    // Create ISearchManager instance
ISearchManager* pSearchManager;

hr = CoCreateInstance(CLSID_CSearchManager, NULL, CLSCTX_LOCAL_SERVER, IID_PPV_ARGS(&pSearchManager));

  2. Obtain an instance of ISearchCatalogManager using ISearchManager::GetCatalog. The name of the system catalog for Windows Search is SYSTEMINDEX.

    // Create ISearchCatalogManager instance 
ISearchCatalogManager* pSearchCatalogManager;

// Call ISearchManager::GetCatalog for "SystemIndex" to access the catalog to the ISearchCatalogManager
hr = pSearchManager->GetCatalog(L"SystemIndex", &pSearchCatalogManager);

  3. Obtain an instance of ISearchQueryHelper using ISearchCatalogManager::GetQueryHelper.

    // Call ISearchCatalogManager::GetQueryHelper to get the ISearchQueryHelper interface
ISearchQueryHelper* pQueryHelper;

hr = pSearchCatalogManager->GetQueryHelper(&pQueryHelper);

  4. Once you have an instance of ISearchQueryHelper you must then receive the connection string used to connect to the Windows Search index OLE DB connector.

    // Call get_ConnectionString to get the OLE DB connection string
LPWSTR pszConnectionString=NULL;

hr = pQueryHelper->get_ConnectionString(&pszConnectionString);
// NOTE: YOU MUST call CoTaskMemFree() on the string