# Operators and Modifiers

The power of the CFSEARCH tag is in the control it gives you over the Verity search engine. The engine offers users a high degree of specificity in setting search parameters.

## Operators

An operator represents logic to be applied to a search element. This logic defines the qualifications a document must meet to be retrieved. Operators are used to refine your search or to influence the results in other ways. For example, you could construct an HTML form for conducting searches. In the form, a user could perform a search for a single term: server. You can refine your search by limiting the search scope in a number of ways. Operators are available for limiting a query to a sentence or paragraph, and you can search words based on proximity. The following operator types are available:

- Evidence operators -- Used to specify basic and intelligent word searches.
- Proximity operators -- For specifying the relative location of words in a document.
- Relational operators -- Search fields in a collection.
- Concept operators -- Used to identify a concept in a document by combining the meanings of search elements.
- Score operators -- Allow you to manipulate the score returned by a search element. The score percentage display can optionally be set to as many as four decimal places.
- Natural language operators -- Allow the use of natural language expressions in forming queries.

Ordinarily, you use operators in explicit searches. They are used in the following manner:

    "<operator>search_string"

### Evidence operators

Evidence operators can be used to specify either a basic word search or an intelligent word search. A basic word search finds documents that contain only the word or words specified in the query. An intelligent word search expands the query terms to create an expanded word list so that the search returns documents that contain variations of the query terms.

Documents retrieved using evidence operators are not ranked by relevance unless you use the MANY modifier.

Verity Evidence Operators
Operator | Description
--- | ---
STEM | Expands the search to include the word you enter and its variations. The STEM operator is automatically implied in any SIMPLE query. For example, the EXPLICIT query expression `<STEM>believe` yields matches such as, "believe," "believing," "believer".'
WILDCARD | Matches wildcard characters included in search strings. Certain characters automatically indicate a wildcard specification, such as * and?. For example, the query expression `spam*` yields matches such as, "spam," "spammer," "spamming."
WORD | Performs a basic word search, selecting documents that include one or more instances of the specific word you enter. The WORD operator is automatically implied in any SIMPLE query.

### Proximity operators

Proximity operators specify the relative location of specific words in the document. Specified words must be in the same phrase, paragraph, or sentence for a document to be retrieved. In the case of NEAR and NEAR/N operators, retrieved documents are ranked by relevance based on the proximity of the specified words. Proximity operators can be nested; phrases or words can appear within SENTENCE or PARAGRAPH operators, and SENTENCE operators can appear within PARAGRAPH operators.

The following table describes each operator.

Verity Proximity Operators
Operator | Description
--- | ---
NEAR | Selects documents containing specified search terms. The closer the search terms are to one another within a document, the higher the document's score. The document with the smallest possible region containing all search terms always receives the highest score. Documents whose search terms are not within 1000 words of each other are not selected.
NEAR/N | Selects documents containing two or more search terms within N number of words of each other, where N is an integer between 1 and 1024 where NEAR/1 searches for two words that are next to each other. The closer the search terms are within a document, the higher the document's score. You can specify multiple search terms using multiple instances of NEAR/N as long as the value of N is the same: `commute <NEAR/10> bicycle <NEAR/10>` `train <NEAR/10>`
PARAGRAPH | Selects documents that include all of the words you specify within the same paragraph. To search for three or more words or phrases, you must use the PARAGRAPH operator between each word or phrase.
PHRASE | Selects documents that include a phrase you specify. A phrase is a grouping of two or more words that occur in a specific order. Examples of phrases: `mission oak` `"mission oak"` `mission <PHRASE> oak` `<PARAGRAPH> (mission, oak)`
SENTENCE | Selects documents that include all of the words you specify within the same sentence. Examples: `jazz <SENTENCE> musician` `<SENTENCE> (jazz, musician)`

### Relational operators

Relational operators search document fields that have been defined in the collection. Documents containing specified field values are returned. Documents retrieved using relational operators are not ranked by relevance, and you cannot use the MANY modifier with relational operators.

The following operators are used for numeric and date comparisons.

Verity Numerical and Date Relational Operators
Operator | Description
--- | ---
= | Equals
> | Greater than
>= | Greater than or equal to
< | Less than
<= | Less than or equal to

Text comparison operators match words and parts of words. The following operators are used for text comparisons.

VerityText Comparison Operators
Operator | Description
--- | ---
CONTAINS | Selects documents by matching the word or phrase you specify with the values stored in a specific document field. Documents are selected only if the search elements specified appear in the same sequential and contiguous order in the field value. For example, specifying "god" will match "God in heaven," "a god among men," or "good god" but not "godliness," or "gods."
MATCHES | Selects documents by matching the query string with values stored in a specific document field. Documents are selected only if the search elements specified match the field value exactly. If a partial match is found, a document is not selected. For example, specifying "god" will match a document field containing only "god" and will not match "gods," "godliness," or "a god among men."
STARTS | Selects documents by matching the character string you specify with the starting characters of the values stored in a specific document field.
ENDS | Selects documents by matching the character string you specify with the ending characters of the values stored in a specific document field.
SUBSTRING | Selects documents by matching the query string you specify with any portion of the strings in a specific document field. For example, specifying "god" will match "godliness," "a god among men," "godforsaken," etc.

### Document fields

The values you specify for the CFINDEX attributes TITLE, KEY, URL, and CUSTOM can be specified as document fields for use with relational operators in the CRITERIA attribute. Document fields are referenced in text comparison operators. They are identified as:

- CF_TITLE
- CF_KEY
- CF_URL
- CF_CUSTOM1
- CF_CUSTOM2

For more information on this topic, see the Allaire Knowledge Base article, "Using Document Fields To Narrow Down Searches" (ID# 1082) on our Web site at http://www.allaire.com/Support/KnowledgeBase/SearchForm.cfm.

### The SUBSTRING operator

You can use the SUBSTRING operator to match a character string with data stored in a specified data source. In the following example, a data source called TEST1 contains the table YearPlaceText, which itself contains three columns: Year, Place, and Text. Year and Place make up the primary key. The following table shows the TEST1 schema.

YearPlaceText
Year | Place | Text
--- | --- | ---
1990 | Utah | Text about Utah 1990
1990 | Oregon | Text about Oregon 1990
1991 | Utah | Text about Utah 1991
1991 | Oregon | Text about Oregon 1991
1992 | Utah | Text about Utah 1992

The following application page matches records that have 1990 in the TEXT column and are in the Place Utah. The search is performed against the collection that contains the TEXT column and then is narrowed further by searching the string "Utah" in the CF_TITLE document field. Recall that document fields are defaults defined in every collection corresponding to the values you define for URL, TITLE, and KEY in the CFINDEX tag.

    <CFQUERY NAME="GetText"
        DATASOURCE="TEST1">
        SELECT Year+Place
            AS Identifier, text
            FROM YearPlaceText
    </CFQUERY>

    <CFINDEX COLLECTION="testcollection"
        ACTION="Update"
        TYPE="Custom"
        TITLE="Identifier"
        KEY="Identifier"
        BODY="TEXT"
        QUERY="GetText">

    <CFSEARCH NAME="GetText_Search"
        COLLECTION="testcollection"
        TYPE="Explicit"
        CRITERIA="1990 and CF_TITLE <SUBSTRING> Utah">
    <CFOUTPUT>
        Record Counts: <BR>
        #GetText.RecordCount# <BR>
        #GetText_Search.RecordCount# <BR>
    </CFOUTPUT>

    <CFOUTPUT>
        Query Results --- Should be 5 rows <BR>
    </CFOUTPUT>

    <CFOUTPUT QUERY="Gettext">
        #Identifier# <BR>
    </CFOUTPUT>

    <CFOUTPUT>
        Search Results -- should be 1 row <BR>
    </CFOUTPUT>

    <CFOUTPUT QUERY="GetText_Search">
        #GetText_Search.TITLE# <BR>
    </CFOUTPUT>

### Concept operators

Concept operators combine the meaning of search elements to identify a concept in a document. Documents retrieved using concept operators are ranked by relevance. The following table describes each concept operator.

Verity Concept Operators
Operator | Description
--- | ---
AND | Selects documents that contain all of the search elements you specify.
OR | Selects documents that show evidence of at least one of the search elements you specify.
ACCRUE | Selects documents that include at least one of the search elements you specify. Documents are ranked based on the number of search elements found.

### Score operators

Score operators govern how the search engine calculates scores for retrieved documents. The maximum score a returned search element can have is 1.000. The score percentage display can optionally be set to as many as four decimal places.

When a score operator is used, the search engine first calculates a separate score for each search element found in a document, and then performs a mathematical operation on the individual element scores to arrive at the final score for each document.

Note that the document's score is available as a result column. The SCORE result column can be referenced to trap the relevancy score of any document retrieved. For example:

    <CFOUTPUT>
        <A HREF="#Search1.URL#">#Search1.Title#</A><BR>
        Document Score=#Search1.SCORE#<BR>
    </CFOUTPUT>

The following table lists the score operators.

Verity Score Operators
Operator | Description
--- | ---
YESNO | Forces the score of an element to 1 if the element's score is non-zero: `<YESNO>mainframe` If the retrieval result of the search on "mainframe" is 0.75, the YESNO operator forces the result to 1. You can use YESNO to avoid relevance ranking.
PRODUCT | Multiplies the scores for documents matching a query. To arrive at a document's score, the search engine calculates a score for each search element and multiplies these scores together: `<PRODUCT>(computers, laptops)` The resulting score for each document is multiplied together.
SUM | Adds together the scores for documents matching a query, up to a maximum value of 1: `<SUM>(computers, laptops)` The resulting scores are added together.
COMPLEMENT | Calculates scores for documents matching a query by taking the complement (subtracting from 1) of the scores for the query's search elements. The new score is 1 minus the search element's original score. `<COMPLEMENT>computers` If the search element's original score is.785, the COMPLEMENT operator recalculates the score as.215.

## Modifiers

Modifiers can be used with operators to further refine query expressions. You can specify case sensitivity in a query, or force the output to be ranked by relevancy. Modifiers include:

- CASE -- Sets case sensitivity. Verity searches are case-insensitive for search text entered in all uppercase or all lowercase. Case sensitivity is turned on when mixed case characters are entered.
- MANY -- Results are ranked by relevancy, which is determined by the number of times the search value is found in a document.
- NOT -- Eliminates documents containing the specified words.
- ORDER -- Returns documents only if they contain words in the listed order.

### Search modifiers

Modifiers are combined with operators to change the standard behavior of an operator in some way. For example, you can use the CASE modifier with an operator to specify that you want to match the case of the search word.

Modifiers are as follows.

Verity Search Modifiers
Modifier | Description
--- | ---
CASE | Specifies a case-sensitive search: `<CASE>J[JAVA, java]` Searches for "JAVA" and "Java." If a search contains a mixed-case string, the search request will be case-sensitive.
MANY | Counts the density of words, stemmed variations, or phrases in a document and produces a relevance-ranked score for retrieved documents. Can be used with the following operators: WORD WILDCARD STEM PHRASE SENTENCE PARAGRAPH `<PARAGRAPH><MANY>javascript <AND> vbscript` The MANY modifier cannot be used with the following: AND OR ACCRUE Relational operators
NOT | Used to exclude documents that contain the specified word or phrase. Used only with the AND and OR operators. `Java <AND> programming <NOT> coffee`
ORDER | Used to specify that the search elements must occur on the same order in which they were specified in the query. Can be used with the following operators: PARAGRAPH SENTENCE NEAR/N Place the ORDER modifier before any operator: `<ORDER><PARAGRAPH>("server", "Java")`