User Guide Cancel

cfindex

Last updated on Aug 1, 2024 | Also applies to ColdFusion

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Description

Populates a search engine collection with metadata and creates indexes for searching it. The engine (Solr) can 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 collection using the ColdFusion Administrator or the cfcollection tag before creating indexes for the collection.

You also can index a collection using the ColdFusion Administrator. For more information on creating, indexing, and searching a collection, see Solr search examples in Developing ColdFusion Applications.

Syntax

cfindex supports script style syntax: 

new index(collection="<collection_name>"); 

<cfindex 
action = "update|delete|purge|refresh|fullimport|deltaimport|status|abort|optimize" 
autoCommit = "yes|no" 
collection = "collection name" 
collectionNames= "comma-separated values of collection names"
body = "body" 
category = "category name" 
categoryTree = "category tree" 
custom1 = "custom value" 
custom2 = "custom value" 
custom3 = "custom value" 
custom4 = "custom value" 
extensions = "file extensions" 
key = "ID" 
language = "{{language}}" 
prefix = "location of documents" 
query = "query name" 
recurse = "yes|no" 
status = "status"
throwOnError="true|false"
title = "title" 
type = "type" 
URLpath = "URL">

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion (2016 release): Added the parameter throwOnError.

ColdFusion 10:

Added new actions fullimport , deltaimport , status, abort.
Added the attributes autoCommit, fieldBoost , docBoost.
Added support for dynamic custom fields.

ColdFusion 9: Added Solr search engine support.

ColdFusion MX 7.0.1: Added the prefix attribute.

ColdFusion MX 7:

Added the category, categoryTree , custom3, and custom4 attributes for the update and refresh actions.
Added the status attribute for the update, refresh, delete, and purge actions.
Removed reference to external collections.
Removed suggested cflock usage.

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.

Attributes

Attribute	Req/Opt	Default	Description
action	Required	Null	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. fullImport : To index full database. For instance, when you index the database for the first time. deltaImport: For partial indexing. For instance, for any updates in the database, instead of a full import, you can perform delta import to update your collection. status: Provides the status of indexing, such as the total number of documents processed and status such as idle or running. abort: Aborts an ongoing indexing task. commit: Changes to the search server. For instance, you can use autocommit="false" while indexing many documents. Then, use action="commit" to commit all the changes at once. merge: Given multiple collections, merge them into a single collection. optimize: Re-organizes all segments in a core to a single segment. Optimization is operationally time consuming, and is not advisable if the index changes frequently. Solr reads a copy of the entire index and restructures the copy into a single Segment, resulting in a much slower operation. For more information, see Optimizing Solr Performance.
autoCommit	Optional	True	If yes, automatically commit the changes to the search server. If no, indexed documents are not committed unless you specifically commit using cfindex action="commit". By default, the value is set to true.
collection	Required	Null	Name of a collection that is registered by ColdFusion; for example, " personnel ".
collectionNames	Optional	Null	Comma-separated values of collection names. Note: This attribute is required when action="merge".
body	Required if type=custom	Null	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 .
category	Optional	(empty string)	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. If you use a query for your indexed data, this value can be the name of a column.
categoryTree	Optional	(empty string)	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.
custom1	Optional	Null	Use to index discrete values in collection records, which lets you search for specific records. By contrast, values specified in the body attribute are concatenated and searched as a body of text using the specified criteria. If type = custom, a query column name. If type is file or path, a string. Additionally, ColdFusion 10 added support for dynamic custom fields.
custom2	Optional	Null	Usage is the same as for custom1.
custom3	Optional	Null	Usage is the same as for custom1.
custom4	Optional	Null	Usage is the same as for custom1.
extensions	Optional	htm , html , cfm , cfml , dbm , 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, *."
fieldBoost	Optional	htm , html , cfm , cfml , dbm , dbml	Boost specific fields while indexing. fieldBoost enhances the score of the fields and thereby the ranking in the search results. Multiple fields can be boosted by specifying the values as a comma-separated list.
key	Required	(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.
language	Optional	Null	For options, see cfcollection .
prefix	Optional	Null	Specifies the location of files to index when the computer that contains the K2 Search Service is not the computer on which you installed ColdFusion, and when you index files with the type attribute set to path .
query	Optional.	Null	The name of the query against which the collection is generated.
recurse	Optional	no	yes: if type = "path", indexes qualified files in directories below the path specified in the key attribute. no
status	Optional	Null	The name of the structure into which ColdFusion returns status information.
throwOnError	Oprtional	false	If true, then cfindex tag throws an error while indexing documents.
title	Optional	(empty string)	Provides a title for the document if one cannot be extracted from the document.
type	Optional	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. dih : Used for Data Import Handler. custom: applies action to custom data; for example, to data from a query. When type=" dih ", these actions are used: abort: Aborts an ongoing indexing task. deltaimport : For partial indexing. For instance, for any updates in the database, instead of a full import, you can perform delta import to update your collection. fullimport : To index full database. For instance, when you index the database for the first time. status: Provides the status of indexing, such as the total number of documents processed and status such as idle or running.
URLpath	Optional	(empty string)	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 .

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 that 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:

Type	Attribute 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:

Type	Attribute 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:

Key	Type	Description
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. 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:\ColdFusion\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:\ColdFusion\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:\ColdFusion\wwwroot\vw_files\newspaper">

Get help faster and easier

New user?