Creating a Search Interface

The <cfsearch> tag is used to query Verity collections. Typically, an application has a form that collects search parameters from the user; this form is submitted to an application page that invokes the <cfsearch> tag. <cfsearch> generates a query object containing records from the specified collection that match the keywords of the criteria attribute. The following snippet performs a search and returns a query named SearchResults:

 <cfsearch collection="SnailsAndPuppyDogTails"           name="SearchResults"           type="SIMPLE"           criteria="#FORM.keywords#"> 

There are two search types: simple and explicit. The criteria attribute of a simple search is commonly just a list of keywords. In an explicit search, criteria can refine the results with any number of Verity operators and modifiers, but each must be explicitly invoked.

NOTE

If you search for an all-uppercase or all-lowercase string, the search is not case-sensitive:

 criteria="COLDFUSION" criteria="coldfusion" 

If you search for a mixed-case string, the search is case-sensitive:

 criteria="ColdFusion" 

A simple query expression is simple only in that you, the developer, do not need to identify any special Verity operators. You can enter multiple words separated by commas, in which case the comma is treated like a logical or. If you omit the commas, the query expression is treated as a phrase. Wildcards can be specified for pattern matching. In addition, the simple search type packs a very powerful combination of the Verity engine stem operator and the many modifier.

A stem search automatically includes words that are derived from the ones listed in criteria. For example, a word such as view returns records that contain view, viewing, views, and so on.

The many modifier ranks search results according to a relevancy score. Relevancy is based on the density of the search term in the searched data. The more often a word appears in a document, the higher the document's score. Furthermore, if a keyword has the same frequency in two documents, the smaller document is given a higher relevancy. For example, a 500-page report that mentions the word corruption ten times is ranked with less significance than a 5-page document that also has ten instances of corruption.

An explicit query expression can include any of the Verity operators and modifiers. However, they all must be explicitly specified. You might consider assembling an explicit search expression programmatically from an advanced search form, or simply letting power users submit their own expressions.

The query object generated by <cfsearch> can be processed as usual with <cfoutput> to build a table of results. The available query results are listed in Table 38.1. Optionally, a status structure can also be returned providing additional information as listed in Table 38.2.

Table 38.1. <cfsearch> result Variables

RESULT	DESCRIPTION
author	Extracted from document (including Microsoft Office documents and PDF files) if available.
category	A list of associated categories, if present.
categoryTree	A hierarchal category tree, if categories are present.
columnlist	The list of column names for the result set.
context	A context summary highlighting the matched text (if contextpassages specified).
currentrow	The current row being processed by a loop, such as <cfoutput>.
custom1	The value of the column indicated in the custom1 attribute of the <cfindex> tag (custom).
custom2	The value of the column indicated in the custom2 attribute of the <cfindex> tag (custom).
custom3	The value of the column indicated in the custom3 attribute of the <cfindex> tag (custom).
custom4	The value of the column indicated in the custom4 attribute of the <cfindex> tag (custom).
key	The full filename of the document in a file or path collection type, or the value of the query column indicated in the key attribute of custom index.
rank	Rank within search results.
recordcount	The number of records in the result set.
recordssearched	The total number of records searched.
score	The relevancy score that Verity dynamically calculates based on the search criteria.
size	Number of bytes in matching document.
summary	The automatic summary that <cfindex> generates. The default selects the best three matching sentences, up to a maximum of 500 characters.
title	The value of the title of an HTML, PDF, or Microsoft Office document (file or path), or the value of the column indicated in the TITLE attribute (custom).
type	The MIME type of the matching document.
url	The url indicated in the <cfindex> tag used to populate the collection, plus the filename for the document matched.

Table 38.2. <cfsearch> status Variables

STATUS	DESCRIPTION
found	The number of documents that matches the search.
keywords	A structure containing alternate suggested keywords.
keywordScore	Same structure as keywords, but contains score values.
searched	The total number of records searched.
suggestedQuery	Alternate query suggestion that may return better results (for example, due to misspellings).
time	Search processing time (in milliseconds).

Dynamic URL parameters are covered in Chapter 8, "URL Variables."

For query-based collections, the primary key is usually returned in key and can be used in a where clause to return the complete record. File-based collections use a combination of the url or key columns, depending on how the collection was originally populated. For example, if the urlpath attribute of <cfindex> was used, you would use this:

 <!--- query the collection ---> <cfsearch collection="SnailsAndPuppyDogTails"           name="SearchResults"           type="SIMPLE"           criteria="#FORM.keywords#"> <!--- format and output the results ---> <table> <tr>  <td>Score</td>  <td>Document</td> </tr> <cfoutput query="SearchResults"> <tr>  <td>#Score#</td>  <td><A HREF="#URL#">#Title#</a><br>#Summary#</td> </tr> </cfoutput> </table> 

NOTE

External Verity collections (that is, collections not created in ColdFusion) can be referenced by using the external="YES" attribute of the <cfindex> and <cfsearch> tags. The collection name in the COLLECTION attribute should be set to that of the directory path where the collection resides on the hard drive.

The two fields you can reference in an external collection are key and score. These are the only fields common to all Verity collections, regardless of the interface through which the collection is created. This means you do not have access to url, title, summary, or the custom fields. Likewise, custom fields (that is, non-ColdFusion fields) in external collections cannot be referenced.

TIP

The <cfsearch> result set is limited to 64 Kbytes. Using broad search terms, coupled with a large enough collection, users might hit the limit and get an error message. The easiest way to handle the problem is to catch and trap the error and instruct the user to furnish more specific search criteria.

Error trapping is discussed in Chapter 26, "Error Handling."

Full-text searching can also be performed in SQL databases, by using the LIKE operator. SQL searches and pattern matching are covered in Chapter 44, "Basic SQL."