<cfquery>

Passes SQL statements to a data source.

Not limited to queries.

This tag may have a body.

This tag is also supported within <cfscript>

<cfquery name=string columnkey=string result=string datasource=any dbtype=string dbserver=string dbname=string tags=any connectstring=string username=string password=string maxrows=number blockfactor=number timeout=any cachedafter=datetime cachedwithin=object provider=string providerdsn=string debug=boolean cachename=string psq=boolean unique=boolean ormoptions=struct indexname=string returntype=string timezone=timezone lazy=boolean params=object sql=string listener=any async=boolean cacheid=string ><!--- body --->[</cfquery>]
Attribute Description
name
string, optional

The name query. 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.

Alias: variable
columnkey
string, optional

Specifies the column to use as primary key when returnType is set to struct.

Alias: columnname, column, keycolumn
result
string, optional

Specifies a name for the structure in which cfquery returns the result variables.

  • SQL: The SQL statement that was executed. (string)
  • Cached: If the query was cached. (boolean)
  • SqlParameters: An ordered Array of cfqueryparam values. (array)
  • RecordCount: Total number of records in the query. (numeric)
  • ColumnList: Column list, comma separated. (string)
  • ExecutionTime: Execution time for the SQL request. (numeric)
datasource
any, optional

The name of the data source from which this query should retrieve data.
dbtype
string, optional

The following values are supported

  • query: for doing a query on an existing query object (QoQ / Query of Queries)
  • hql: for doing a query on orm
tags
any, optional

tags stored with the cache.

Alias: tag
username
string, optional

If specified, username overrides the username value specified in the data source setup.
password
string, optional

If specified, password overrides the password value specified in the data source setup.
maxrows
number, optional

Specifies the maximum number of rows to return in the record set.
blockfactor
number, 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 ORACLE native database drivers and to ODBC drivers. Certain ODBC drivers may dynamically reduce the block factor at runtime.
timeout
any, optional

The maximum number of seconds 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.
cachedafter
datetime, optional

This is the age of which the query data can be
cachedwithin
object, optional

Supported values are:

  • String "request": If original query was created within the current request, cached query data is used.
  • a timespan (created with function CreateTimeSpan()): If original query date falls within the time span, cached query data is used.

To use cached data, the current query must use the same SQL statement, params, data source, query name, user name, and password.
debug
boolean, optional

Used for debugging queries. Specifying this attribute causes the SQL statement submitted to the data source and the number of records returned from the query to be returned.
psq
boolean, optional

preserve single quote or not
unique
boolean, optional

Specifies if the object parameter is unique, used only for dbtype=orm or hql
ormoptions
struct, optional

Object parameter for the entity.
indexname
string, optional
returntype
string, optional

one of the following values:

  • query: default for all dbtype expect "hql", returns a query object
  • array_of_entity: works only with dbtype "hql" and is also the default value for dbtype "hql"
  • array: converts the query object into an array of structs
  • struct: converts the query object into a struct using the columnKey attribute as a primary key
timezone
timezone, optional

the timezone used to convert a date object to a timestamp (string), this value is needed when your database runs in another timezone and you are not using cfqueryparam to insert dates.
params
object, optional

an array or struct of params, see examples below

  • [ { value='jim', sqltype='varchar' } ]
  • [ 'jim' ]
  • [ id= { value='jim', sqltype='varchar' } ]
sql
string, optional

the SQL query to execute.
listener
any, optional
async
boolean, optional

Unimplemented Attribute(s)

Attribute Description
dbserver
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
dbname
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
connectstring
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
provider
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
providerdsn
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
cachename
string, optional

This attribute has been deprecated and is non-functional.

* deprecated *
lazy
boolean, optional

If "lazy" is set to true (default "false") Lucee does not initially load all the data from the datasource.

When "true" the data is only loaded when requested, this means the data is dependent on the datasource connection. If the datasource connection has been lost for some reason and the data has not yet been requested, Lucee throws an error if you try to access the data.

The "lazy" attribute only works if the following attributes are not used: cachewithin, cacheafter and result.

* deprecated *
cacheid
string, optional

Attribute not supported

* unimplemented *

Examples

Tags

<cfset qry= queryNew("name,age,whatever", "varchar,date,int", [
[ "Susi", CreateDate( 1970, 1, 1 ), 5 ],
[ "Urs" , CreateDate( 1995, 1, 1 ), 7 ],
[ "Fred", CreateDate( 1960, 1, 1 ), 9 ],
[ "Jim" , CreateDate( 1988, 1, 1 ), 11 ]
])>
<!-- bad example, not using a bound parameter, unsafe when using input from users -->
<cfquery name="q" dbtype="query">
	select * from qry where name = 'jim'
</cfquery>
<cfdump var="#q#" />

<!-- using a bound parameter with cfqueryparam -->
<cfquery name="q" dbtype="query">
select * from qry where name = <cfqueryparam value='jim'>
</cfquery>
<cfdump var="#q#" />


<!-- using an array of simple params -->
<cfscript>
p = [ 'jim' ];
</cfscript>
<cfquery name="q" dbtype="query" params=#p#>
select * from qry where name = ?
</cfquery>
<cfdump var="#q#" />


<!-- using an array of struct params -->
<cfscript>
p = [ { value='jim', sqltype='varchar' } ];
</cfscript>
<cfquery name="q" dbtype="query" params=#p#>
select * from qry where name = ?
</cfquery>
<cfdump var="#q#" />


<!-- using an array of named struct params -->
<cfscript>
p = [id= { value='jim', sqltype='varchar' } ];
</cfscript>
<cfquery name="q" dbtype="query" params=#p#>
select * from qry where name = :id
</cfquery>
<cfdump var="#q#" />

Script

qry= queryNew("name,age,whatever", "varchar,date,int", [
    [ "Susi", CreateDate( 1970, 1, 1 ), 5 ],
    [ "Urs" , CreateDate( 1995, 1, 1 ), 7 ],
    [ "Fred", CreateDate( 1960, 1, 1 ), 9 ],
    [ "Jim" , CreateDate( 1988, 1, 1 ), 11 ]
    ])

<span class="nv">query</span> <span class="nv">name</span><span class="o">=</span><span class="s2">&quot;q&quot;</span> <span class="nv">dbtype</span><span class="o">=</span><span class="s2">&quot;query&quot;</span> <span class="p">{</span>
<span class="nf">echo</span><span class="p">(</span><span class="s2">&quot;select * from qry where name = &#39;jim&#39;&quot;</span><span class="p">);</span>
<span class="p">}</span>
<span class="nf">writedump</span><span class="p">(</span><span class="nv">q</span><span class="p">);</span>
<span class="nv">query</span> <span class="nv">name</span><span class="o">=</span><span class="s2">&quot;q&quot;</span> <span class="nv">dbtype</span><span class="o">=</span><span class="s2">&quot;query&quot;</span> <span class="p">{</span>
<span class="nf">echo</span><span class="p">(</span><span class="s2">&quot;select * from qry where name = &quot;</span><span class="p">)</span>
<span class="nv">queryParam</span> <span class="nv">cfsqltype</span><span class="o">=</span><span class="s2">&quot;cf_sql_varchar&quot;</span> <span class="nv">value</span><span class="o">=</span><span class="s2">&quot;jim&quot;</span><span class="p">;</span>
<span class="p">}</span>
<span class="nf">writedump</span><span class="p">(</span><span class="nv">q</span><span class="p">);</span>
<span class="nv">p</span> <span class="o">=</span> <span class="p">[</span> <span class="s1">&#39;jim&#39;</span> <span class="p">];</span>
<span class="nv">query</span> <span class="nv">name</span><span class="o">=</span><span class="s2">&quot;q&quot;</span> <span class="nv">dbtype</span><span class="o">=</span><span class="s2">&quot;query&quot;</span> <span class="nv">params</span><span class="o">=</span><span class="err">#</span><span class="nv">p</span><span class="err">#</span><span class="p">{</span>
<span class="nf">echo</span><span class="p">(</span><span class="s2">&quot;select * from qry where name = ?&quot;</span><span class="p">);</span>
<span class="p">}</span>
<span class="nf">writedump</span><span class="p">(</span><span class="nv">q</span><span class="p">);</span>
<span class="nv">p</span> <span class="o">=</span> <span class="p">[</span><span class="nv">id</span><span class="o">=</span> <span class="p">{</span> <span class="nv">value</span><span class="o">=</span><span class="s1">&#39;jim&#39;</span><span class="p">,</span> <span class="nv">sqltype</span><span class="o">=</span><span class="s1">&#39;varchar&#39;</span> <span class="p">}</span> <span class="p">];</span>
<span class="nv">query</span> <span class="nv">name</span><span class="o">=</span><span class="s2">&quot;q&quot;</span> <span class="nv">dbtype</span><span class="o">=</span><span class="s2">&quot;query&quot;</span> <span class="nv">params</span><span class="o">=</span><span class="err">#</span><span class="nv">p</span><span class="err">#</span><span class="p">{</span>
<span class="nf">echo</span><span class="p">(</span><span class="s2">&quot;select * from qry where name = :id&quot;</span><span class="p">);</span>
<span class="p">}</span>
<span class="nf">writedump</span><span class="p">(</span><span class="nv">q</span><span class="p">);</span>

See also