Lucee Tag Reference

<cfqueryparam>

Checks the data type of a query parameter. The cfqueryparam tag is nested within a cfquery tag and embedded within the SQL statement. This tag: - Improves security by preventing SQL injection attacks - Provides data validation for parameter values - Enhances performance by enabling database query caching - Correctly handles type conversion between CFML and database types

Body

This tag can't have a body.

Example

<cfqueryparam
	[cfsqltype=string]
	[charset=string]
	[list=boolean]
	[maxlength=number]
	[null=boolean]
	[scale=number]
	[separator=string]
	[sqltype=string]
	[value=any]>

This tag is also supported within cfscript

<cfscript>
	queryparam
		[cfsqltype=string]
		[charset=string]
		[list=boolean]
		[maxlength=number]
		[null=boolean]
		[scale=number]
		[separator=string]
		[sqltype=string]
		[value=any];
</cfscript>

Attributes

The attributes for this tag are fixed. Except for the following attributes no other attributes are allowed.

Name	Type	Required	Description
cfsqltype	string	No	This Attribute is deprecated
charset	string	No	Specifies the character encoding for string validation. This attribute serves two purposes: 1. It validates that the given value is compatible with the specified charset 2. It determines how byte length is calculated for `maxLength` validation Common values include `UTF-8`, `ISO-8859-1`, or other valid Java charset names.
list	boolean	No	Controls how the parameter value is handled: `true`: The parameter value is treated as a list of values (typically used with SQL's `IN` operator) `false`: The parameter is handled as a simple value Not set: Lucee automatically detects if the value is an array and treats it as a list if it is (but not for byte arrays) When working with lists/arrays: Empty Arrays: When an empty array is provided with `list=true` (or auto-detected as a list), Lucee will handle this correctly by effectively omitting the parameter from the query Usage with IN: Typically used with SQL's `IN` operator Array Elements: Each element in the array will be properly typed according to the specified `sqlType`
maxlength	number	No	Maximum allowed length of the parameter value (validation check). For string values: The maximum number of characters allowed For binary values: The maximum number of bytes allowed If the value exceeds this length, Lucee will throw an exception If not specified, defaults to the actual length of the provided value If the attribute `charset` is defined, string length comparison will be byte-based for that encoding
null	boolean	No	Indicates whether the parameter should be treated as NULL. `true`: The parameter is passed as NULL to the database (ignores the `value` attribute) `false`: The parameter uses the value provided in the `value` attribute Default is `false` SQL comparison with NULL requires special syntax in most databases (using `IS NULL` rather than `= NULL`).
scale	number	No	Number of decimal places to allow for numeric parameters. Only applies to decimal data types (decimal, numeric, money, etc.) Values with more decimal places than specified will be rounded Particularly important for financial calculations to control precision Default value is zero if not specified
separator	string	No	Specifies the character that separates values in string lists. Only used when `list="true"` and the value is a string (not an array) Default separator is a comma (`,`) Common alternatives include semicolon (`;`), pipe (`\|`), or tab Example: For a string like "red;green;blue" with `list="true" separator=";"`, the values would be treated as three separate items Note: For best results with complex separators or values that might contain the separator character, consider using an array instead of a delimited string.
sqltype	string	No	The SQL data type that the parameter will be bound to. Common types include: `varchar`: For strings (default) `integer`, `bigint`, `smallint`, `tinyint`: For various sized integers `double`, `decimal`, `money`: For floating point/decimal values `bit`, `boolean`: For boolean values `date`, `time`, `timestamp`: For date/time values `binary`, `blob`: For binary data Using the correct type improves security, enables proper type checking, and optimizes query execution.
value	any	No	Specifies the actual value that Lucee passes to the database. For standard parameters: The single value used in the query For list parameters: Can be an array, list string, or other collection type For null values: Set the `null` attribute to true and this attribute is ignored The value will be automatically escaped to prevent SQL injection.