<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>CFQUERY</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">CFQUERY</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Passes queries or SQL statements to a data source.
</p>

<p>
Macromedia recommends that you use the cfqueryparam tag within every cfquery tag, to help secure your databases from unauthorized users. For more information, see Security Bulletin ASB99-04, &quot;Multiple SQL Statements in Dynamic Queries,&quot; in the Macromedia Security Zone, www.macromedia.com/devnet/security/security_zone/asb99-04.html</a>, and Chapter&#160;20, "Accessing and Retrieving Data" in ColdFusion MX Developer's Guide.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
Database manipulation tags
</p>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="syntax"><span class="title">Syntax</span><pre>&lt;cfquery 
   name = &quot;query_name&quot;
   dataSource = &quot;ds_name&quot;
   dbtype = &quot;query&quot;
   username = &quot;username&quot;
   password = &quot;password&quot;
   maxRows = &quot;number&quot;
   blockFactor = &quot;blocksize&quot;
   timeout = &quot;seconds&quot;
   cachedAfter = &quot;date&quot; 
   cachedWithin = &quot;timespan&quot; 

   Either of the following:
      debug = &quot;yes&quot; or &quot;no&quot;
   or:
      debug
&gt;
result = &quot;result_name&quot;
&lt;/cfquery&gt;
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
cfinsert, cfprocparam, cfprocresult, cfqueryparam, cfstoredproc, cftransaction, cfupdate; "Optimizing database use" in Chapter&#160;13, "Designing and Optimizing a ColdFusion&#160;Application," and Chapters 19-22 in ColdFusion MX Developer's Guide
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">History</span>
<p>
ColdFusion&#160;MX&#160;7:
</p>
<ul>

<li>Added the result attribute for specifying an alternate name for the structure that holds the result variables.</li>

<li>Added result variables for the SQL statement executed (sql), the number of records returned (recordcount), whether the query was cached (cached), an array of cfqueryparam values (sqlparameters), and the list of columns in the returned query (columnlist).</li>
</ul>

<p>
ColdFusion&#160;MX:
</p>
<ul>

<li>Changed Query of Queries behavior: it now supports a larger subset of standard SQL.</li>

<li>Changed dot notation support: ColdFusion now supports dot notation within a record set name. ColdFusion interprets such a name as a structure. </li>

<li>Deprecated the connectString, dbName, dbServer, provider, providerDSN, and sql attributes, and all values of the dbtype attribute except query. They do not work, and might cause an error, in releases later than ColdFusion 5. </li>

<li>New query object variable: cfquery.ExecutionTime.</li>

<li>No longer supports native drivers. It now uses JDBC (and ODBC-JDBC bridge) for database connectivity.</li>
</ul>

<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
Use this tag to execute a SQL statement against a ColdFusion data source. Although you can use the cfquery tag to execute any SQL Data Definition Language (DDL) or Data Manipulation Language (DML) statement, you typically use it to execute a SQL SELECT statement.
</p>
<table>
  <tr valign="top">
    <td width="30"><strong>Note: </strong></td>
    <td>To call a stored procedure, use the cfstoredproc tag.</td>
  </tr>
</table>
<p>
This tag creates a query object, providing this information in query variables:
</p>

<p>
</p><div align="left">
<table border="1">
  <caption></caption>
  <tr align="center">    <th>&#160;</th>
    <th>&#160;</th>
</tr>
  <tr align="left">    <td><pre>query_name.currentRow
</pre></td>
    <td>
<p>Current row of query that cfoutput is processing.</p></td>
</tr>
  <tr align="left">    <td><pre>query_name.columnList
</pre></td>
    <td>
<p>Comma-delimited list of the query columns.</p></td>
</tr>
  <tr align="left">    <td><pre>query_name.RecordCount
</pre></td>
    <td>
<p>Number of records (rows) returned from the query.</p></td>
</tr>
</table>
</div>
<p>
</p>

<p>
The cfquery tag also returns the following result variables in a structure. You can access these variables with a prefix of the name you specified in the result attribute. For example, if you assign the name myResult to the result attribute, you would retrieve the name of the SQL statement that was executed by accessing #myResult.sql#. The result attribute provides a way for functions or CFCs that are called from multiple pages, possibly at the same time, to avoid overwriting results of one call with another.
</p>

<p>
</p><div align="left">
<table border="1">
  <caption></caption>
  <tr align="center">    <th>&#160;</th>
    <th>&#160;</th>
</tr>
  <tr align="left">    <td><pre>result_name.sql
</pre></td>
    <td>
<p>The SQL statement that was executed.</p></td>
</tr>
  <tr align="left">    <td><pre>result_name.recordcount
</pre></td>
    <td>
<p>Current row of query that cfoutput is processing.</p></td>
</tr>
  <tr align="left">    <td><pre>result_name.cached
</pre></td>
    <td>
<p>True if the query was cached; False otherwise.</p></td>
</tr>
  <tr align="left">    <td><pre>result_name.sqlparameters
</pre></td>
    <td>
<p>An ordered Array of cfqueryparam values.</p></td>
</tr>
  <tr align="left">    <td><pre>result_name.columnList
</pre></td>
    <td>
<p>Comma-delimited list of the query columns.</p></td>
</tr>
  <tr align="left">    <td><pre>result_name.ExecutionTime
</pre></td>
    <td>
<p>Cumulative time required to process the query.</p></td>
</tr>
</table>
</div>
<p>
</p>

<p>
You can cache query results and execute stored procedures. For information about this and about displaying cfquery output, see ColdFusion MX Developer's Guide. 
</p>

<p>
Because the timeout attribute only affects the maximum time for each suboperation of a query, the cumulative time may exceed its value. To set a timeout for a page that might get a very large result set, set the Administrator &gt; Server Settings &gt; Timeout Requests option to an appropriate value or use the RequestTimeout attribute of the cfsetting tag (for example, &lt;cfsetting requestTimeout=&quot;300&quot;&gt;).
</p>

<p>
The Caching page of the ColdFusion MX Administrator specifies the maximum number of cached queries. Setting this value to 0 disables query caching.
</p>

<p>
You cannot use ColdFusion reserved words as query names. 
</p>

<p>
You cannot use SQL reserved words as variable or column names in a Query of Queries, unless they are escaped. The escape character is the bracket []; for example:
</p>
<pre>SELECT [count] FROM MYTABLE. 
</pre>
<p>
For a list of reserved keywords in ColdFusion MX, see "Escaping reserved keywords" in Chapter&#160;22, "Using Query of Queries" in ColdFusion MX Developer's Guide.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span><pre>&lt;!--- This example shows the use of CreateTimeSpan with CFQUERY ------&gt;
&lt;!--- to cache a record set. Define startrow and maxrows to ----&gt;
&lt;!--- facilitate &#39;next N&#39; style browsing. ----&gt;
&lt;cfparam name=&quot;MaxRows&quot; default=&quot;10&quot;&gt;
&lt;cfparam name=&quot;StartRow&quot; default=&quot;1&quot;&gt;
&lt;!--------------------------------------------------------------------
Query database for information if cached database information has
not been updated in the last six hours; otherwise, use cached data.
---------------------------------------------------------------------&gt;
&lt;cfquery 
name=&quot;GetParks&quot; datasource=&quot;cfdocexamples&quot; 
cachedwithin=&quot;#CreateTimeSpan(0, 6, 0, 0)#&quot;&gt;
SELECT PARKNAME, REGION, STATE
FROM Parks
ORDER BY ParkName, State
&lt;/cfquery&gt;
&lt;!--- Build HTML table to display query. -------------------------&gt;
&lt;table cellpadding=&quot;1&quot; cellspacing=&quot;1&quot;&gt;
   &lt;tr&gt;
      &lt;td bgcolor=&quot;f0f0f0&quot;&gt;
         &amp;nbsp;
      &lt;/td&gt;
      &lt;td bgcolor=&quot;f0f0f0&quot;&gt;
         &lt;b&gt;&lt;i&gt;Park Name&lt;/i&gt;&lt;/b&gt;
      &lt;/td&gt;
      &lt;td bgcolor=&quot;f0f0f0&quot;&gt;
         &lt;b&gt;&lt;i&gt;Region&lt;/i&gt;&lt;/b&gt;
      &lt;/td&gt;
      &lt;td bgcolor=&quot;f0f0f0&quot;&gt;
         &lt;b&gt;&lt;i&gt;State&lt;/i&gt;&lt;/b&gt;
      &lt;/td&gt;
   &lt;/tr&gt;
&lt;!--- Output the query and define the startrow and maxrows parameters. 
Use the query variable CurrentCount to keep track of the row you 
are displaying. ------&gt;
&lt;cfoutput query=&quot;GetParks&quot; startrow=&quot;#StartRow#&quot; maxrows=&quot;#MaxRows#&quot;&gt;
   &lt;tr&gt;
      &lt;td valign=&quot;top&quot; bgcolor=&quot;ffffed&quot;&gt;
         &lt;b&gt;#GetParks.CurrentRow#&lt;/b&gt;
      &lt;/td&gt;
      &lt;td valign=&quot;top&quot;&gt;
         &lt;font size=&quot;-1&quot;&gt;#ParkName#&lt;/font&gt;
      &lt;/td&gt;
      &lt;td valign=&quot;top&quot;&gt;
         &lt;font size=&quot;-1&quot;&gt;#Region#&lt;/font&gt;
      &lt;/td&gt;
      &lt;td valign=&quot;top&quot;&gt;
         &lt;font size=&quot;-1&quot;&gt;#State#&lt;/font&gt;
      &lt;/td&gt;
   &lt;/tr&gt;
&lt;/cfoutput&gt;
&lt;!--- If the total number of records is less than or equal
to the total number of rows, then offer a link to
the same page, with the startrow value incremented by
maxrows (in the case of this example, incremented by 10). ---------&gt;
   &lt;tr&gt;
      &lt;td colspan=&quot;4&quot;&gt;
      &lt;cfif (StartRow + MaxRows) LTE GetParks.RecordCount&gt;
         &lt;cfoutput&gt;&lt;a href=&quot;#CGI.SCRIPT_NAME#?startrow=#Evaluate(StartRow + 
MaxRows)#&quot;&gt;
         See next #MaxRows# rows&lt;/a&gt;&lt;/cfoutput&gt; 
      &lt;/cfif&gt;
      &lt;/td&gt;
   &lt;/tr&gt;
&lt;/table&gt; 
</pre>
         </td>
      </tr>
   </table>
   </div>
<div id="NAME">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">NAME</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Name of query. Used in page to reference query record set. Must begin with a letter. Can include letters, numbers, and underscores. </p>

  </td>
  </tr>
  </table>
</div>
<div id="DATASOURCE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">DATASOURCE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required unless dbtype=query.</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Name of data source from which query gets data. You must specify either dbtype or dataSource.</p>

  </td>
  </tr>
  </table>
</div>
<div id="DBTYPE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">DBTYPE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Use this value to specify the results of a query as input. You must specify either dbtype or dataSource.</p>

  </td>
  </tr>
  </table>
</div>
<div id="USERNAME">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">USERNAME</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Overrides username in data source setup.</p>

  </td>
  </tr>
  </table>
</div>
<div id="PASSWORD">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">PASSWORD</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Overrides password in data source setup.</p>

  </td>
  </tr>
  </table>
</div>
<div id="MAXROWS">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">MAXROWS</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "-1 (All)"


<p>Maximum number of rows to return in record set.</p>

  </td>
  </tr>
  </table>
</div>
<div id="BLOCKFACTOR">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">BLOCKFACTOR</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "1"


<p>Maximum rows to get at a time from server. Range: 1 - 100. Might not be supported by some database systems.</p>

  </td>
  </tr>
  </table>
</div>
<div id="TIMEOUT">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">TIMEOUT</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">&#160;</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Maximum number of seconds that each action of a query is permitted to execute before returning an error. The cumulative time may exceed this value.</p>
<p>For JDBC statements, ColdFusion sets this attribute. For other drivers, check driver documentation.</p>

  </td>
  </tr>
  </table>
</div>
<div id="CACHEDAFTER">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">CACHEDAFTER</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Date value (for example, April 16, 1999, 4-16-99). If date of original query is after this date, ColdFusion uses cached query data. To use cached data, current query must use same SQL statement, data source, query name, user name, password. </p>
<p>A date/time object is in the range 100 AD-9999 AD.</p>
<p>When specifying a date value as a string, you must enclose it in quotation marks.</p>

  </td>
  </tr>
  </table>
</div>
<div id="CACHEDWITHIN">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">CACHEDWITHIN</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Timespan, using the CreateTimeSpan function. If original query date falls within the time span, cached query data is used. CreateTimeSpan defines a period from the present, back. Takes effect only if query caching is enabled in the Administrator. </p>
<p>To use cached data, the current query must use the same SQL statement, data source, query name, user name, and password. </p>

  </td>
  </tr>
  </table>
</div>
<div id="DEBUG">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">DEBUG</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional; value and equals sign may be omitted</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">


<ul>

<li>Yes, or if omitted: if debugging is enabled, but the Administrator Database Activity option is not enabled, displays SQL submitted to datasource and number of records returned by query. </li>

<li>No: if the Administrator Database Activity option is enabled, suppresses display.</li>
</ul>


  </td>
  </tr>
  </table>
</div>
<div id="RESULT">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">RESULT</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Specifies a name for the structure in which cfquery returns the result variables. For more information, see the Usage section .</p>

  </td>
  </tr>
  </table>
</div>

  </body>
</html>
