CFINDEX  
Description

Populates a Verity collection with metadata and creates indexes for searching it. Verity is a search engine that you can integrate in a ColdFusion application to search physical files of various types or a database query. Indexing database columns that result from a query lets users search the query data much faster than they could if you used multiple SQL queries to return the same data.

You must define a Verity collection using the ColdFusion MX Administrator or the cfcollection tag before creating indexes for the collection.

You also can index a Verity collection using the ColdFusion MX Administrator or by using a native Verity indexing tool, such as Vspider or MKVDK. These options, however, limit you to indexing a collection of files in a directory path.

For more information on creating, indexing, and searching a Verity collection, see Chapter 24, "Building a Search Interface" in ColdFusion MX Developer's Guide.

 
Category

Extensibility tags

 
Syntax
<cfindex 
   collection = "collection_name"
   action = "action"
   type = "type"
   title = "title"
   key = "ID"
   body = "body"
   custom1 = "custom_value"
   custom2 = "custom_value"
custom3 = "custom_value"
custom4 = "custom_value"
   category = "category_name"
   categoryTree = "category_tree"
   URLpath = "URL"
   extensions = "file_extensions"
   query = "query_name"
   recurse = "yes" or "no"
   language = "language">
   status = "status">
 
See also

cfcollection, cfexecute, cfobject, cfreport, cfsearch, cfwddx

 
History

ColdFusion MX 7:

  • Added the status, category, and categoryTree attributes.
  • Removed reference to external collections.
  • Removed suggested cflock usage.

ColdFusion MX:

  • The action attribute value optimize is obsolete. It does not work, and might cause an error, in ColdFusion MX.
  • Changed the external attribute behavior: it is not necessary to specify the external attribute. (ColdFusion automatically detects whether a collection is internal or external.)
  • Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF files.
  • Changed thrown exceptions: this tag can throw the SEARCHENGINE exception.
  • Changed acceptable collection naming: this tag accepts collection names that include spaces.
  • Changed query result behavior: the cfindex tag can index the query results from a cfsearch tag.
 
Usage

The attributes settings that the cfindex tag requires depend on whether you set the query attribute. If you set the query attribute to a valid query name, it specifies that cfindex is to index the data in the query rather than indexing documents on a disk. If you do not set the query attribute, cfindex assumes it is indexing a file (type = file), a set of files in a directory path (type = path), or text that you provide in the body attribute (type = custom).

If you set the query attribute to a valid query name, the cfindex tag creates indexes as specified by the following attributes and their values:

   

File

The key attribute is the name of a column in the query that contains a full filename (including path).

Path

The key attribute is the name of a column in the query that contains a directory pathname.

 

The extensions and recurse attributes, if specified, elaborate on which files are included. If the action is delete, cfindex deletes keys for the collection.

Custom

The key attribute specifies a column name that contains anything you want; for example, the primary key value in the database. It must be unique because this is the primary key in the collection. If the action is delete, the key attribute is the name of a column in the query that contains the keys to delete.

 

The body attribute is required and is a comma-delimited list of the names of the columns that contain the text data to be indexed.

If you do not set the query attribute, the cfindex tag creates indexes as specified by the following attributes and their values:

   

File

The key attribute is required and is a full pathname to a file.

Path

The key attribute is required and it is a directory pathname.

 

The extensions and recurse attributes, if specified, designate which types of files are included. If the action is delete, both the keys and the document files are deleted.

Custom

The key attribute is an identifier that specifies the key. If the action is delete, the key attribute is the document key to delete.

 

The body attribute is required and is the text to be indexed.

If type is not specified but query is set, ColdFusion sets the type to the default value of custom.

If neither type nor query is set, ColdFusion sets type to the default value of file.

If type equals custom, all attributes except for key and body can specify a literal value, not only a column name. This allows you to change a field to empty in the collection.

 
Status attribute

The status attribute provides the following information and diagnostics about the result of a cfindex operation:

     

BADKEYS

Struct

A structure of keys with diagnostic messages about the indexing of these keys. If there are no bad keys, this key does not exist.

DELETED

Number

The number of keys deleted.

MESSAGES

Array

An array of diagnostic messages, including nonfatal errors and warnings, returned from the Verity K2 Index server. If there are no messages, this key does not exist.

INSERTED

Number

The number of keys inserted into the collection.

UPDATED

Number

The number of keys updated in the collection.

 
Example
<!--- EXAMPLE #1 Index a file, type = "file". ---------------------------->
<!--- Example dumps content of status variable (info). ------------------->
<cfindex collection="CodeColl" 
   action="refresh" 
   type="file"
   key="C:\blackstone\wwwroot\vw_files\cfindex.htm" 
   urlpath="http://localhost:8500/vw_files/"
   language="English"
   title="Cfindex Reference page"
   status="info">

<!--- Search for Attributes. --->
<cfsearch
   name = "mySearch"
   collection = "CodeColl"
   criteria = "Attributes"
   contextpassages = "1"
   maxrows = "100">
<cfoutput>
   key=#mySearch.key#<br />
   title=#mySearch.title#<br />
   context=#mySearch.context#<br />
   url=#mySearch.url#<br />
</cfoutput>

<cfdump var="#info#">

<!--- EXAMPLE #2 Index a path (type = "path"). ------------------------------>
<cfindex collection="CodeColl" 
   action="refresh" 
   type="path"
   key="C:\inetpub\wwwroot\vw_files\newspaper\sports" 
   urlpath="http://localhost/vw_files/newspaper/sports"
   extensions = ".htm, .html"
   recurse="no"
   language="English"
   categoryTree="vw_files/newspaper/sports"
   category="Giants">

<!--- Search for any references to criteria. --->
<cfsearch
   name = "mySearch"
   collection = "CodeColl"
   categoryTree="vw_files/newspaper/sports"
   category="Giants"
   criteria = "Williams" 
   contextpassages = "1"
   maxrows = "100">
<cfoutput>
   key=#mySearch.key#<br />
   title=#mySearch.title#<br />
   context=#mySearch.context#<br />
   url=#mySearch.url#<br />
</cfoutput>

<!---EXAMPLE #3: Index a QUERY (type = "custom") using custom1. ------------>
<!--- Retrieve data from the table. --->
<cfquery name="getCourses" datasource="cfdocexamples">
   SELECT * FROM COURSES
</cfquery>

<!--- Update the collection with the above query results. --->
<!--- key is Course_ID in the Courses table. ---->
<!--- body specifies the columns to be indexed for searching. --->
<!--- custom1 specifies the value of the Course_Number column. --->

<cfindex 
   query="getCourses"
   collection="CodeColl"
   action="Update"
   type="Custom"
   key="Course_ID"
   title="Courses"
   body="Course_ID,Descript"
   custom1="Course_Number"
>
<h2>Indexing Complete</h2>
<!--- cno supplies value for searching custom1; 
      could be form input instead. --->
<cfset cno = "540">
<cfsearch
   name = "mySearch"
   collection = "CodeColl"
   criteria = "CF_CUSTOM1 <MATCHES> #cno#"
   contextpassages = "1"
   maxrows = "100">
<!--- Returns indexed values (Course_ID and Descript) for 
      Course_Number 540. --->
<cfoutput>
   key=#mySearch.key#<br />
   title=#mySearch.title#<br />
   context=#mySearch.context#<br />
   url=#mySearch.url#<br />
</cfoutput>

<!--- EXAMPLE #4 Index a FILE within a QUERY (type= "file"). --------------->
<!--- Retrieve row with a column that contains a filename (Contract_File). --->
<cfquery name="getEmps" datasource="cfdocexamples">
   SELECT * FROM EMPLOYEE WHERE EMP_ID = 1
</cfquery>

<!--- Update the collection with the above query results. --->
<!--- key specifies the column that contains a complete filename. --->
<!--- file is indexed in same way as if no query involved. --->
<cfindex 
   query="getEmps"
   collection="CodeColl"
   action="Update"
   type="file"
   key="Contract_File"   
   title="Contract_File"
   body="Emp_ID,FirstName,LastName,Contract_File">

<h2>Indexing Complete</h2>
<cfsearch
   name = "mySearch"
   collection = "CodeColl"
   criteria = "vacation"
   contextpassages = "1"
   maxrows = "100">
<cfoutput>
   key=#mySearch.key#<br />
   title=#mySearch.title#<br />
   context=#mySearch.context#<br />
   url=#mySearch.url#<br />
</cfoutput>

<!--- EXAMPLE # 5 Index a PATH within a QUERY. ---------------------------->
<!--- Retrieve a row with a column that contains a path (Project_Docs). --->
<cfquery name="getEmps" datasource="cfdocexamples">
   SELECT * FROM EMPLOYEE WHERE Emp_ID = 15
</cfquery>

<!--- Update the collection with the above query results. --->
<!--- key specifies a column that contains a directory path. --->
<!--- path is indexed in same way as if no query involved. --->
<cfindex 
   query="getEmps"
   collection="CodeColl"
   action="update"
   type="path"
   key="Project_Docs"
   title="Project_Docs"
   body="Emp_ID,FirstName,LastName,Project_Docs">

<h2>Indexing Complete</h2>

<cfsearch
   name = "getEmps"
   collection = "CodeColl"
   criteria = "cfsetting"
   contextpassages = "1"
   maxrows = "100">
<cfoutput>
   key=#getEmps.key#<br />
   title=#getEmps.title#<br />
   context=#getEmps.context#<br />
   url=#getEmps.url#<br />
</cfoutput>

<!--- EXAMPLE #6 Deletes keys in the CodeColl collection for html files --->
<!--- in the specified directory (but not in subdirectories). ------------->

<cfindex collection="CodeColl" 
   action="delete" 
   type="path"
   key="C:\CFusionMX7\wwwroot\vw_files\newspaper" 
   urlpath="http://localhost:8500/vw_files/newspaper"
   extensions = ".htm, .html"
   recurse="no">

<!--- EXAMPLE #7 Purges all keys in the CodeColl collection --->
<!--- with recursion. ------------------------------------------------------->

<cfindex collection="CodeColl" 
   action="purge" 
   type="path"
   key="C:\CFusionMX7\wwwroot\vw_files\newspaper">
COLLECTION  
  Required
 

Name of a collection that is registered by ColdFusion; for example, "personnel".
ACTION  
  Required
 
  • update: updates a collection and adds key to the index.
  • delete: removes collection documents as specified by the key attribute.
  • purge: deletes all of the documents in a collection. Causes the collection to be taken offline, preventing searches.
  • refresh: deletes all of the documents in a collection, and then performs an update.
TYPE  
  Optional
 
Default value: "custom, if query attribute is specified. Otherwise, file. "
  • file: applies action value to filename, including path. Expects a filename in the key attribute.
  • path: applies action to files in a directory path that pass the extensions filter. Expects a directory name in the key attribute.
  • custom: applies action to custom data; for example, to data from a query.
TITLE  
  Optional
 

Provides a title for the document if one cannot be extracted from the document.
KEY  
  Required
 
Default value: "(empty string)"

The value specified for key depends on the type attribute:

  • If type = "file", the directory path and filename for the file,
  • If type = "path", the directory path for the location of the files.
  • If type = "custom", a unique identifier that specifies the location of the data, For a query, the name of the column that holds the primary key, for example. If not a query, an identifier such as the URL for a web page, for example.
BODY  
  Required if type = custom
 
  • ASCII text to index.
  • Query column names, if name is specified in query.

You can specify columns in a delimited list; for example: "emp_name, dept_name, location".

This attribute is ignored if type is file or path, and is invalid if action is delete.
CUSTOM1  
  Optional
 

Use to index discrete values in collection records, which lets you search for specific records using the Verity MATCHES operator. By contrast, values specified in the body attribute are concatenated and searched as a body of text using the specified criteria.

If type = query, a query column name. If type = custom, a data field to be indexed.

CUSTOM2  
  Optional
 

Usage is the same as for custom1.

CUSTOM3  
  Optional
 

Usage is the same as for custom1.
CUSTOM4  
  Optional
 

Usage is the same as for custom1.
CATEGORY  
  Optional
 

A string value that specifies one or more search categories for which to index the data. You can define multiple categories, separated by commas, for a single index.

CATEGORYTREE  
  Optional
 

A string value that specifies a hierarchical category or category tree for searching. It is a series of categories separated by forward slashes ("/"). You can specify only one category tree.
URLPATH  
  Optional
 

If type is file or path, specifies the URL path. During indexing, this pathname is prefixed to filenames and returned from a search as the url.
EXTENSIONS  
  Optional
 
Default value: "htm, " Default value: "html," Default value: "cfm, " Default value: "cfml, " Default value: "dbm, " Default value: "dbml"

Delimited list of file extensions that ColdFusion uses to index files, if type = "Path".

"*." returns files with no extension. ".*" returns all files.

For example, the following code returns files with a listed extension or no extension:

extensions == ".htm, .html, .cfm, .cfml, "*."
QUERY  
  Optional.
 

The name of the query against which the collection is generated.
RECURSE  
  Optional
 
Default value: "no"
  • yes: if type = "path", indexes qualified files in directories below the path specified in the key attribute.
  • no
LANGUAGE  
  Optional
 
Default value: "English"

For options, see cfcollection. Requires the appropriate Verity Locales language pack (Western Europe, Asia, Multilanguage, Eastern Europe/Middle Eastern).

STATUS  
  Optional
 

The name of the structure into which ColdFusion MX returns status information.