returnFormat
refers to the transformation your executed query makes (if any) before being returned to you. You can choose one of three return formats:
"array"
"query"
"none"
A custom function
By default, qb returns an array of structs as the result of your query. This is the same as specifying array
as your returnFormat
:
You can get the original query object that CFML generates by setting the returnFormat
to query
:
This setting can be overridden on a per-instance basis by calling setReturnFormat()
:
If you want complete control over your return result, you can provide a function as a returnFormat
. The results of the function will be returned as the results of the builder.
Available as an advanced option for framework authors, qb will call out to a column formatter prior to processing a column as part of the SQL query. This allows frameworks like Quick to define queries using aliases and transform them to columns during execution.
You can provide your own column formatter function to qb through the init
method or by calling setColumnFormatter
. It is a function that takes a column string and returns a string
Two interception points are available from QB: preQBExecute
and postQBExecute
. These fire before and after the queryExecute
call, respectively.
The following information is available in the interceptData
struct:
The following information is available in the interceptData
struct:
Each query execution method allows for the passing of an options struct. This is the same struct you would pass to .
qb allows you to specify default options when creating the QueryBuilder instance using the defaultOptions
argument.
You can set defaultOptions
for the default QueryBuilder (QueryBuilder@qb
) in your config/ColdBox.cfc
file under moduleSettings
.
You can also combine this with WireBox to create custom QueryBuilder instances pointing to different datasources and even different grammars.
When mapping to components provided by modules, such as qb, use the interception point inside your config/WireBox.cfc
to ensure all modules are fully loaded and available.
In Application.cfc
you can specify your default datasource which will be used by qb. If you want to retrieve data from other datasources you can specify this in all retrieval functions by using the extra options parameter such as:
If you also want to use a non-default SQL Grammar you have to specify this when creating your QueryBuilder
.
Replace the question marks (?) in a sql string with the bindings provided.
qb can inline the query bindings into the SQL string that it has built up. This is used by other tools like or to provide a richer debugging experience. It is also publicly available for other libraries to use, such as .
Name | Type | Required | Default Value | Description |
---|
Name | Type | Description |
sql | String | The SQL string to execute. |
bindings | Struct | The struct of bindings (keys and values) for the query. |
options | Struct | Any options to pass along to |
returnObject | String | The type to return: |
Name | Type | Description |
sql | String | The SQL string to execute. |
bindings | Struct | The struct of bindings (keys and values) for the query. |
options | Struct | Any options to pass along to |
returnObject | String | The type to return: |
query | Query | null | The query object or |
result | Struct | The query result struct. |
sql |
| true | The SQL with question marks ( |
bindings |
| true | The bindings to use when replacing the question marks ( |
inline |
| false |
| Flag to inline the bindings value or not. If |