CFQUERY passes SQL statements for any purpose to your data source. Not limited to queries.
<CFQUERY NAME="query_name" DATASOURCE="ds_name" DBTYPE="type" USERNAME="username" PASSWORD="password" MAXROWS="number" BLOCKFACTOR="blocksize" TIMEOUT="milliseconds" DEBUG="Yes/No" CACHEDAFTER="date" CACHEDWITHIN="timespan" > SQL statements </CFQUERY>
Required. The name you assign to the query. Query names must begin with a letter and may consist of letters, numbers, and the underscore character (spaces are not allowed). The query name is used later in the page to reference the query's record set.
Required. The name of the data source from which this query should retrieve data.
Optional. The database driver type:
Optional. If specified, USERNAME overrides the username value specified in the data source setup.
Optional. If specified, PASSWORD overrides the password value specified in the data source setup.
Optional. Specifies the maximum number of rows you want returned in the record set.
Optional. Specifies the maximum number of rows to fetch at a time from the server. The range is 1 (default) to 100. This parameter applies to ODBC drivers. Certain ODBC drivers may dynamically reduce the block factor at runtime.
Optional. Lets you specify a maximum number of milliseconds for the query to execute before returning an error indicating that the query has timed-out. This attribute is not supported by most ODBC drivers. TIMEOUT is supported by the SQL Server 6.x or above driver. The minimum and maximum allowable values vary, depending on the driver.
Optional. Used for debugging queries. Specifying this attribute causes the SQL statement actually submitted to the data source and the number of records returned from the query to be output.
Optional. Specify a date value (for example,6/16/99, June 16, 1999, 6-16-99). ColdFusion uses cached query data if the date of the original query is after the date specified. Effective only if query caching has been enabled in the ColdFusion Administrator. To use cached data, the current query must use the same SQL statement, data source, query name, user name, password, and DBTYPE.
Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values.
When specifying a date value as a string, make sure it is enclosed in quotes.
Optional. Enter a timespan using the ColdFusion CreateTimeSpan function. Cached query data will be used if the original query date falls within the time span you define. The CreateTimeSpan function is used to define a period of time from the present backwards. Effective only if query caching has been enabled in the ColdFusion Administrator. To use cached data, the current query must use the same SQL statement, data source, query name, user name, password, and DBTYPE.
In addition to returning data from a ColdFusion data source, the CFQUERY tag also returns informations about the query. CFQUERY.ExecutionTime returns the time it took the query to execute in milliseconds.
CFQUERY creates a query object and provides you with information in three query variables and in the ExecutionTime variable as described in the following table.
CFQUERY Variables | |
---|---|
Variable Name | Description |
query_name.RecordCount | The total number of records returned by the query. |
query_name.CurrentRow | The current row of the query being processed by CFOUTPUT. |
query_name.ColumnList | Returns a comma-delimited list of the query columns. |
CFQUERY.ExecutionTime | Returns the time it took to execute the query. |
<!--- This example shows the use of CFQUERY ---> <HTML> <HEAD> <TITLE>CFQUERY Example</TITLE> </HEAD> <BODY> <H3>CFQUERY Example</H3> <HTML> <CFQUERY NAME="GetProducts" DATASOURCE="CFExpress"> SELECT product_name, product_description FROM products ORDER BY product_name </CFQUERY> <table cellspacing="2" cellpadding="2" border="0"> <tr> <th align="left">Product Name</th> <th align="left">Product Description</th> </tr> <CFOUTPUT QUERY="GetProducts"> <tr> <td valign="top">#product_name#</td> <td>#product_description#</td> </tr> </CFOUTPUT> </table> </BODY> </HTML>