Description

Adds a column to a query and populates its rows with the contents of a one-dimensional array. Pads query columns, if necessary, to ensure that all columns have the same number of rows.

Returns

The number of the column that was added.

Category

Query functions

Function syntax

QueryAddColumn(query, columnName [, columnType], array)

See also

QueryNewQueryAddRowQuerySetCellManaging data types for columns in Query of Queries user guide in the Developing ColdFusion Applications

History

ColdFusion (2018 release): Introduced named parameters.

ColdFusion MX 7: Added the datatype parameter.

ColdFusion MX: Changed behavior: if a user attempts to add a column whose name is invalid, ColdFusion throws an error. (In earlier releases, ColdFusion permitted the add operation, but the user could not reference the column after adding it.)

Parameters

Parameter

Description

query

Name of a query object.

columnName

Name of the new column.

columnType

(Optional) Column data type. ColdFusion generates an error if 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:

  • Object: Java Object, which is the default column type.
  • Integer: 32-bit integer
  • BigInt: 64-bit integer
  • Double: 64-bit decimal number
  • Decimal: Variable length decimal, as specified by java.math.BigDecimal
  • VarChar: String
  • Binary: Byte array
  • Bit: Boolean (1=True, 0=False)
  • Time: Time
  • Date: Date (can include time information)

array

Name of an array whose elements populate the new column.

Usage

You can add columns to query objects, such as queries retrieved with the cfquery tag or queries created with the QueryNew function. You cannot use the QueryAddColumn function on a cached query. This function is useful for generating a query object from the arrays of output parameters that Oracle stored procedures can generate.Adobe recommends that you use the optional datatype parameter. Without this parameter, ColdFusion must try to determine the column's data type when it uses the query object in a query of queries. Determining the data type requires additional processing, and can result in errors if ColdFusion does not guess the type correctly.

Example

The following example creates an empty query and populates the columns of the dataset by passing a one-dimensional array. It then adds a third column to the dataset taking values from the array.

The column values of the first two columns are empty.

<cfscript>
       myQuery=QueryNew("Country,Capital","varchar,varchar");
       /*Add array values in column*/
       myColumnValues=ArrayNew(1);
       myColumnValues[1]=320;
       myColumnValues[2]=250;
       myColumnValues[3]=200;
      QueryAddColumn(myQuery,"Population_millions","varchar",myColumnValues);// Add column Population_millions
       WriteDump(myQuery);
</cfscript>

Output

queryaddcolumn output
queryaddcolumn output

Using member function

<cfscript>
       myQuery=QueryNew("Country,Capital","varchar,varchar");
       /*Add array values in column*/
       myAreaValues=ArrayNew(1);
       myAreaValues[1]=100000;
       myAreaValues[2]=50000;
       myQuery.addColumn("Area","integer",myAreaValues);
       WriteDump(myQuery);
</cfscript>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy