Whatever message this page gives is out now! Go check it out!
QueryNew
Last update:
May 18, 2026
Description
Creates an empty query (query object).
Returns
An empty query with a set of named columns, or an empty query.
Category
Function syntax
QueryNew(columnlist [, columntypelist[, rowData]])History
ColdFusion (2025.0.08): The rowData parameter now accepts an ArgumentCollection, such as the arguments scope, when initializing query rows.
ColdFusion (2018 release) Update 5: You can insert rows in a query object as array of structs. For more information, see Enhancements in QueryNew function .
ColdFusion MX 7: Added columntypelist parameter.
ColdFusion 10: Added rowData parameter.
See also
QueryAddColumn , QueryAddRow , QuerySetCell ; Managing data types for columns in Query of Queries user guide in the Developing ColdFusion Applications
Parameters
| Parameter | Description |
columnlist | Comma-delimited list of column names, or an empty string. |
columntypelist | (Optional) Comma-delimited list specifying column data types. ColdFusion generates an error if the data you add to the column is not of this type, or if it cannot convert the data to this type. The following data types are valid:
|
| rowData | (Optional) Specifies data to add to the new query. Can be one of:
See "Usage" for examples. |
Usage
If you specify an empty string in the columnlist parameter, use the QueryAddColumn function to add columns to the query .Adobe recommends that you use the optional columntypelist parameter. Without this parameter, ColdFusion must try to determine data types when it uses the query object in a query of queries. Determining data types requires additional processing, and can result in errors if ColdFusion does not guess a type correctly .Enhancements in ColdFusion 10 lets you initialize the query data. You can specify a struct, an array of structs, or arrays with single or multiple dimensions to initialize the query as shown in the following example:
myQuery1 = queryNew("id,name","Integer,Varchar", {id=1,name="One"});
myQuery2 = queryNew("id,name","Integer,Varchar",
[
{id=1,name="One"},
{id=2,name="Two"},
{id=3,name="Three"}
]);
myQuery3 = queryNew("id,name","Integer,Varchar", [ [1,"One"], [2,"Two"], [3,"Three"] ]);You can use rowData to initialize query data from a struct, the arguments scope, an array of structs, or an array of arrays. Passing the arguments scope directly is useful when the function arguments map to query column names. ColdFusion treats the arguments scope as a single-row data source for the query.
Example
The following example creates a query object.
<cfscript>
myQuery = queryNew("id,name,amount","Integer,Varchar,Integer",
[
{id=1,name="One",amount=15},
{id=2,name="Two",amount=18},
{id=3,name="Three",amount=32}
]);
writeOutput("The new query is:")
writeDump(myQuery)
</cfscript>Output
Example
The following example uses the QueryNew function to create an empty query with three columns. It populates two rows of the query and displays the contents of the query object and its metadata.
<!--- Create a new three-column query, specifying the column data types --->
<cfset myQuery = QueryNew("Name, Time, Advanced", "VarChar, Time, Bit")>
<!--- Make two rows in the query --->
<cfset QueryAddRow(MyQuery, 2)>
<!--- Set the values of the cells in the query --->
<cfset QuerySetCell(myQuery, "Name", "The Wonderful World of CMFL", 1)>
<cfset QuerySetCell(myQuery, "Time", "9:15 AM", 1)>
<cfset QuerySetCell(myQuery, "Advanced", False, 1)>
<cfset QuerySetCell(myQuery, "Name", "CFCs for Enterprise Applications", 2)>
<cfset QuerySetCell(myQuery, "Time", "12:15 PM", 2)>
<cfset QuerySetCell(myQuery, "Advanced", True, 2)>
<h4>The query object contents</h4>
<cfoutput query = "myQuery">
#Name# #Time# #Advanced#<br>
</cfoutput><br>
<br>
<h4>Using individual query data values</h4>
<cfoutput>
#MyQuery.name[2]# is at #MyQuery.Time[2]#<br>
</cfoutput><br>
<br>
<h4>The query metadata</h4>
<cfset querymetadata=getMetaData(myQuery)>
<cfdump var="#querymetadata#">Example - using arguments scope as rowData
<cfscript>
// Example - using arguments scope as rowData
function test(arg1) {
return queryNew(
structKeyList(arguments), // "arg1"
"varchar",
arguments // accepted now
);
}
q = test(arg1 = "ABC");
writeDump(q);
</cfscript>Enhancements in QueryNew function
ArgumentCollection support in rowData
In ColdFusion (2025.0.08), QueryNew accepts an ArgumentCollection for the rowData parameter. This means that you can pass the arguments scope directly when creating a query row, without first copying it to a separate struct. For example
<cfscript>
// Example - using arguments scope as rowData
function test(arg1) {
return queryNew(
structKeyList(arguments), // "arg1"
"varchar",
arguments // accepted now
);
}
q = test(arg1 = "ABC");
writeDump(q);
</cfscript>In ColdFusion (2018 release) Update 5, there is an enhancement in the function QueryNew, related to how a query object is populated.
In previous versions of ColdFusion, while defining the parameters in the QueryNew function, you had to first define the columns of the query object, the data types of the columns, and finally, the row data.
For example,
<cfscript>
q=queryNew("foo,bar", "", [{foo="foo"},{bar="bar"},{foo="foo1",bar="bar1"}])
writedump(q)
</cfscript>In this update, you can insert rows in a query object as array of structs. The query object interprets the struct keys as column names and assumes the appropriate data type.
For example,
<cfscript>
myquery=QueryNew([
{"Id":101,"Name":"John Adams","Paid":FALSE},
{"Id":102,"Name":"Samuel Jackson","Paid":TRUE},
{"Id":103,"Name":"Gal Gadot","Paid":TRUE},
{"Id":104,"Name":"Margot Robbie","Paid":FALSE}
])
writedump(myquery)
</cfscript>In the snippet above, you can see that the struct keys Id, Name, and Paid are the columns of the query object and the values are the row values of the query object.
You can also create the query object by using named parameters.
For examples,
Use the parameter data to populate the query object with values as array of structs.
<cfscript>
mydata = queryNew(data=[
{"id":1,"title":"Hello World"},
{"id":2,"title":"How are you"}
]);
writeDump(mydata);
</cfscript>Use the parameter columnNames to create the columns for the query object.
<cfscript>
data = queryNew(columnNames="Year,Salary")
writeDump(data);
</cfscript>
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
