cfquery

Notă:

This tag is unsupported in CFFiddle.

Description

Passes queries or SQL statements to a data source.Adobe recommends that you use the  cfqueryparam  tag within every  cfquery  tag, to help secure your databases from unauthorized users.

Category

Syntax

<cfquery  
name = "query name"  
blockFactor = "block size"  
cachedAfter = "date"  
cacheID = "ID"  
cacheRegion = "region"  
cachedWithin = "timespan" 
disableAutoGenKeys="true|false" 
dataSource = "data source name"  
dbtype = "query"  
debug = "yes|no"  
fetchClientInfo = "yes|no"  
maxRows = "number"  
ormoptions = #orm options structure#  
password = "password"  
result = "result name"  
timeout = "seconds"  
username = "user name" 
returnType="array | json/array | query | struct | json/struct">  
</cfquery>
Notă:

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

See also

cfdbinfocfinsertcfprocparamcfprocresultcfqueryparamcfstoredproccftransactioncfupdateOptimizing database use in Optimizing ColdFusion applications in the Developing ColdFusion Applications

History

ColdFusion (2021 release): Added the attribute returnType.

ColdFusion (2018 release): Added the parameter disableAutoGenKeys.

ColdFusion 11: Removed the following attributes:

  • connectString
  • dbName
  • dbServer
  • provider
  • providerDSN
  • sql

In addition, the following dbType attribute values have been removed:

  • dynamic
  • ODBC
  • Oracle73
  • Oracle80
  • Sybase11
  • OLEDB
  • DB2

ColdFusion 10: Added the following attributes: fetchClientInfo, cacheID, cacheRegion, clientInfo}}

ColdFusion 9.0.1: Introduced support for HQL queries; added the attribute {{ormoptions.

ColdFusion 9: Datasource attribute is optional now.

ColdFusion 8: Added the result variable that specifies the ID of a row.

ColdFusion MX 7:

  • Added the result attribute for specifying an alternate name for the structure that holds the result variables.
  • 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 ).
    ColdFusion MX:
  • Changed Query of Queries behavior: it now supports a larger subset of standard SQL.
  • Changed dot notation support: ColdFusion now supports dot notation within a record set name. ColdFusion interprets such a name as a structure.
  • 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.
  • New query object variable: cfquery.ExecutionTime.
  • No longer supports native drivers. It now uses JDBC (and ODBC-JDBC bridge) for database connectivity.

Attributes

Attribute

Req/Opt

Default

Description

name

Required

 

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

blockFactor

Optional

1

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

cachedAfter

Optional

 

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. A date/time object is in the range 100 AD-9999 AD.
When specifying a date value as a string, enclose it in quotation marks.

cacheID

Optional

 

ID to be used to store query result in cache. This ID can be used to either retrieve or remove query from cache

cacheRegion

Optional

 

Cache region to be used to cache query result. If not specified, by default query is cached in the QUERY region.

cachedWithin

Optional

 

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. To use cached data, the current query must use the same SQL statement, data source, query name, user name, and password.

clientInfo

Optional

 

Structure containing properties of the client to be set on the database connection.

dataSource

Optional

 

The Datasource attribute is now optional. If omitted, the query uses the datasourcespecified in the application. If it is not specified in either places, then the error will be thrown.

dbtype

Optional

 

Results of a query as input. Specify either dbtype or dataSource.ColdFusion supports HQL in cfquery. Therefore, you can specify dbtype="hql" as shown in the following example:<cfquery dbtype="hql" name="artists" ormoptions=#{cachename=""}#>from Artists where firstname=<cfqueryparam value="Aiden"></cfquery>

debug

Optional; value and equals sign may be omitted

 

·         yes, or if omitted: if debugging is enabled, but the Administrator Database Activity option is not enabled, displays SQL submitted to the data source and number of records returned by query.

·         no: if the Administrator Database Activity option is enabled, suppresses display.

disableAutoGenKeys Optional false

Specify true to disable retrieval of autogenerated keys.

In previous versions of ColdFusion, you could set this attribute at the datasource lavel. In the 2018 release of ColdFusion, you can set it at the query level.

fetchClientInfo

Optional

no

If set yes, returns a struct with the key-value pair passed by the last query.

maxRows

Optional

-1 (All)

Maximum number of rows to return in record set.

ormoptions

Optional

 

A struct that takes orm options for executing HQL. Applies only if dbtype is set to hql.

password

Optional

 

Overrides the password in the data source setup.

result

Optional

 

Name for the structure in which cfquery returns the result variables. For more information, see Usage.

timeout

 

 

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.
For JDBC statements, ColdFusion sets this attribute. For other drivers, see the driver documentation.

username

Optional

 

Overrides user name in the data source setup.

returnType Optional  

Values are:

  • Array
  • JSON/Array
  • Query (default)

Usage

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.

Notă:

To call a stored procedure, use the cfstoredproc tag.

This tag creates a query object, providing this information in query variables:

Variable name

Description

query_name.currentRow

Current row of query that cfoutput is processing.

query_name.columnList

Comma-separated list of the query columns.

query_name.RecordCount

Number of records (rows) returned from the query.

 

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. The result variable of INSERT queries contains a key-value pair that is the automatically generated ID of the inserted row; this is available only for databases that support this feature. If more than one record was inserted, the value can be a list of IDs. The key name is database-specific.

Variable name

Description

result_name.sql

The SQL statement that was executed.

result_name.recordcount

Number of records (rows) returned from the query.

result_name.cached

True if the query was cached; False otherwise.

result_name.sqlparameters

An ordered Array of cfqueryparam values.

result_name.columnList

Comma-separated list of the query columns.

result_name.ExecutionTime

Cumulative time required to process the query.

result_name.IDENTITYCOL

SQL Server only. The ID of an inserted row.

result_name.ROWID

Oracle only. The ID of an inserted row. This is not the primary key of the row, although you can retrieve rows based on this ID.

result_name.SYB_IDENTITY

Sybase only. The ID of an inserted row.

result_name.SERIAL_COL

Informix only. The ID of an inserted row.

result_name.GENERATED_KEY MySQL only. The ID of an inserted row. MySQL 3 does not support this feature.
result_name.GENERATEDKEY Supports all databases. The ID of an inserted row.

You can cache query results and execute stored procedures. For information about this and about displaying cfquery output, see the Developing ColdFusion Applications. 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 > Server Settings > Timeout Requests option to an appropriate value or use the RequestTimeout attribute of the cfsetting tag (for example, <cfsetting requestTimeout="300">).
The Caching page of the ColdFusion Administrator specifies the maximum number of cached queries. Setting this value to 0 disables query caching.
You cannot use ColdFusion reserved words as query names. 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:

SELECT [count] FROM MYTABLE.

For a list of reserved keywords in ColdFusion, see Escaping reserved keywords in Query of Queries user guide in the Developing ColdFusion Applications.

Example 1: Getting started

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples">
       SELECT FIRSTNAME,LASTNAME
       FROM EMPLOYEES
</cfquery>

<!--- Create HTML page --->
<HTML>
       <head>
             <title>
                    List of Employees
             </title>
       </head>
       <body>
             <h1>
                    Employee List
             </h1>
             <!--- List out employees--->
             <cfoutput query="getEmployees">
                    #FIRSTNAME# #LASTNAME# <br/>
             </cfoutput>
       </body>
</HTML>

Example 2: Using tables

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>

<!--- Create HTML page --->
<html>
 <head>
  <title>
   Table of Employees
  </title>
 </head>
 <body>
  <table border="1">
   <!--- Loop through the database --->
   <cfoutput query="getEmployees">
    <tr>
     <td>
      #FIRSTNAME# #LASTNAME#
     </td>
     <td>
      #EMAIL#
     </td>
     <td>
      #PHONE#
     </td>
    </tr>
   </cfoutput>
  </table>
 </body>
</html>

Example 3: Using the result attribute

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples" result="result">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#result#" >
<cfoutput>
 <!--- Display count of records --->
 #result.RecordCount#
</cfoutput>

Output

result
result

Example 4: Using the password attribute

Many database configurations require authentication (in the form of a username and password) before you can query the database. You can add authentication using the username and password attributes.

Note that You can also configure the user name and password in the datasource in the ColdFusion Administrator. Specifying the authentication details in your query overrides the username and password in the ColdFusion Administrator.

<cfquery datasource="cfdocexamples" username="myusername" password="mypassword">
  select *
  from Employees
</cfquery>

Example 5: Limiting the number of records

You can limit the number of rows to be returned by using the maxrows attribute.

<cfquery name="getEmployees" datasource="cfdocexamples" result="result" maxrows="10">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#result#" >
<cfoutput>
 <!--- Display count of records --->
 #result.RecordCount#
</cfoutput>

Example 6: Using the timeout attribute

You can set a timeout limit using the timeout attribute.  A timeout is useful in preventing requests that are running for more than the limit set.

The timeout attribute sets the maximum number of seconds that each action of a query is allowed to execute before returning an error.

<cfquery name="getEmployees" datasource="cfdocexamples" timeout="20" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

Example 7: Cached queries

The volume of traffic to your web site or applications impacts the performance of your site or application. To enhance the performance, you can cache your database queries.

A cached query is a query that has its results stored in the server's memory. The results are stored when the query is first run. Whenever you run the query thereafter, ColdFusion retrieves the results from memory.

You can cache a query using the cachedAfter attribute.

<cfquery name="getEmployees" datasource="cfdocexamples" cachedafter="10-15-2018" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

You can also cache a query using the cachedWithin attribute with the CreateTimeSpan function.

In the example below, if the query's cached data is older than 60 seconds, the query is re-run. Otherwise, the cached data is used.

<cfquery name="getEmployees" datasource="cfdocexamples" cachedwithin="#CreateTimespan(0,0,60,0)#" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

Example 8- Return type is array

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery" RETURNTYPE = "array"> 
        select ARTID,ARTISTID,ARTNAME  from art where ARTID < 2 
</cfquery> 
<cfoutput>#getEmployees[1].ARTID# #getEmployees[1].ARTISTID# #getEmployees[1].ARTNAME#</cfoutput> 

Example 9- Return type is json/array

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery" RETURNTYPE = "json/array"> 
        select ARTID,ARTISTID,ARTNAME from art where ARTID < 2 
</cfquery> 
<cfset record=deserializeJSON(getEmployees)> 
<cfoutput>#record[1].ARTID# #record[1].ARTISTID# #record[1].ARTNAME# #getEmployees#</cfoutput>

Example 10- Return type is default query

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery"> 
        select ARTID,ARTISTID,ARTNAME from art where ARTID < 2 
</cfquery> 
<cfset record=QueryGetRow(getEmployees,1)> 
<cfoutput>#record.ARTID# #record.ARTISTID# #record.ARTNAME#</cfoutput>

 Adobe

Obțineți ajutor mai rapid și mai ușor

Utilizator nou?

Adobe MAX 2024

Adobe MAX
Conferința despre creativitate

14 – 16 octombrie, Miami Beach și online

Adobe MAX

Conferința despre creativitate

14 – 16 octombrie, Miami Beach și online

Adobe MAX 2024

Adobe MAX
Conferința despre creativitate

14 – 16 octombrie, Miami Beach și online

Adobe MAX

Conferința despre creativitate

14 – 16 octombrie, Miami Beach și online