Spec-Zone.ru › ColdFusion

cfquery

Передаёт запросы или инструкции SQL источнику данных. Рекомендуется использовать тег cfqueryparam внутри каждого тега cfquery, чтобы защитить базы данных от несанкционированного доступа

<cfquery>SQL</cfquery>

queryExecute(sql, params, options);

  • CF
  • Lucee
  • BL 1.0.0+
  • См. также: cfqueryparam queryExecute

    Справочник атрибутов

    name string

    Имя запроса. Используется на странице для обращения к набору записей запроса. Должно начинаться с буквы. Может содержать буквы, цифры и символы подчёркивания.

    datasource string

    Имя источника данных, из которого запрос получает данные. Начиная с CF 9+, можно указать источник данных по умолчанию в Application.cfc с помощью переменной this.datasource

    timezone string

    Lucee 4+ часовой пояс, используемый для преобразования объекта даты в метку времени (строку); это значение необходимо, если база данных работает в другом часовом поясе и вы не используете cfqueryparam для вставки дат.

    dbtype string

    Тип исходного запроса, для которого будет выполнена инструкция SQL. Укажите либо dbtype, либо dataSource, но не оба атрибута. Поддерживаются следующие значения: query: для запроса к существующему объекту запроса (то есть Query of Queries); hql: для запроса к ORM. ПРИМЕЧАНИЕ: поддерживаемый синтаксис SQL зависит от этого значения.
    Значения:
    • query
    • hql

    username string

    Переопределяет имя пользователя, заданное в настройках источника данных.

    password string

    Переопределяет пароль, заданный в настройках источника данных.

    maxrows numeric
    По умолчанию: -1

    Максимальное количество строк, возвращаемых в наборе записей. Значение -1 возвращает все записи.

    blockfactor numeric

    Максимальное количество строк, получаемых с сервера за один раз. Диапазон: 1–100. Некоторые системы баз данных могут не поддерживать этот атрибут.

    timeout numeric

    Максимальное количество секунд, в течение которых разрешено выполнение каждого действия запроса, прежде чем будет возвращена ошибка. Совокупное время может превышать это значение. Для инструкций JDBC CFML задаёт этот атрибут. Для других драйверов см. документацию к драйверу.

    cachedafter date

    Значение даты (например, 16 апреля 1999 г. или 4-16-99). Если дата исходного запроса позже указанной даты, CFML использует данные из кэша запроса. Чтобы использовать данные из кэша, текущий запрос должен использовать ту же инструкцию SQL, источник данных, имя запроса, имя пользователя и пароль. Объект даты/времени должен находиться в диапазоне от 100 до 9999 года н. э. При указании даты в виде строки её необходимо заключить в кавычки.

    cachedwithin numeric

    Интервал времени, заданный с помощью функции CreateTimeSpan. Если дата исходного запроса попадает в этот интервал, используются данные из кэша запроса. Функция CreateTimeSpan задаёт период, отсчитываемый назад от текущего момента. Атрибут действует, только если кэширование запросов включено в Administrator. Чтобы использовать данные из кэша, текущий запрос должен использовать ту же инструкцию SQL, источник данных, имя запроса, имя пользователя и пароль.

    debug boolean
    По умолчанию: false

    Yes: если отладка включена, но параметр Database Activity в Administrator выключен, отображает SQL, отправленный источнику данных, и количество записей, возвращённых запросом. No: если параметр Database Activity в Administrator включён, отображение подавляется.
    Значения:
    • true
    • false

    result string

    CF 8+ Задаёт имя структуры, в которую cfquery возвращает переменные результата. * SQL: выполненная инструкция SQL. (string) * Cached: признак того, что запрос был взят из кэша. (boolean) * SqlParameters: упорядоченный массив значений cfqueryparam. (array) * RecordCount: общее количество записей в запросе. (numeric) * ColumnList: список столбцов, разделённых запятыми. (string) * ExecutionTime: время выполнения запроса SQL. (numeric) * GENERATEDKEY: CF 9+ если запрос был инструкцией INSERT со столбцом идентификатора или автоинкрементным значением, значение этого идентификатора помещается в эту переменную.

    ormoptions struct

    CF 9+ Структура параметров ORM, используемых для запросов HQL (9.0.1+).

    cacheID string

    CF 10+ Значение, используемое в качестве идентификатора кэша, если заданы cachedWithin или cachedAfter.

    cacheRegion string

    CF 10+ Имя области кэша, используемой, если заданы cachedWithin или cachedAfter.

    clientInfo struct

    CF 10+ Структура со свойствами, которые необходимо задать для подключения к базе данных.

    fetchClientInfo boolean
    По умолчанию: false

    CF 10+ Если значение равно true, возвращает структуру со значением аргумента clientInfo, переданным последним запросом.

    lazy boolean
    По умолчанию: false

    Lucee 4+ Если для "lazy" задано значение true, Lucee не загружает сразу все данные из источника данных. При значении "true" данные загружаются только по запросу, то есть их доступность зависит от подключения к источнику данных. Если подключение к источнику данных по какой-либо причине потеряно, а данные ещё не были запрошены, Lucee выдаст ошибку при попытке доступа к ним. Атрибут "lazy" работает только при условии, что не используются следующие атрибуты: cachewithin, cacheafter и result.

    psq boolean
    По умолчанию: false

    Lucee 4+ Если значение равно true, сохраняет одинарные кавычки в инструкции SQL.

    returntype string
    По умолчанию: query

    Lucee 5+ Тип возвращаемого результата запроса. Допустимы следующие значения: "query": возвращает объект запроса; "array_of_entity": возвращает массив сущностей ORM (для этого dbtype должен иметь значение "hql"); "array": возвращает массив структур; "struct": возвращает структуру структур (для этого необходимо задать columnkey).

    columnkey string

    Lucee 5+ Ключ структуры, используемый для каждого результата, если returntype имеет значение "struct".

    Совместимость

    BoxLang:

    Версия 1.0.0+ <bx:query> в BoxLang

    Ссылки дополнительная информация о cfquery

    • Руководство пользователя Adobe по Query of Queries — в документации Adobe можно узнать, какие инструкции SQL поддерживаются.

    Примеры
    Примеры кода с использованием тега cfquery

    Пример CFQuery с CFQueryParam

    Показывает, как использовать тег cfqueryparam внутри cfquery.

    <cfquery name="news">
        SELECT id,title,story
        FROM news
        WHERE id = <cfqueryparam value="#url.id#" cfsqltype="cf_sql_integer">
    </cfquery>

    Синтаксис скрипта с использованием QueryExecute

    CF 11+ См. также раздел «Теги, реализованные как компоненты», где описан другой способ использования в скрипте.

    myQuery = queryExecute(
     "SELECT myCol1, myCol2 FROM myTable 
      WHERE myCol1 = :myid 
      ORDER BY myCol1 ASC ", 
      {myid: 5}, 
      {datasource = "myDSN"} 
    );
    writeDump(myQuery);

    Простой пример Query of Query

    Сначала с нуля создаётся фиктивный запрос с помощью queryNew, а затем выполняется сортировка. Для выполнения Query of Query указывается dbtype="query", а в инструкции FROM используется имя переменной объекта запроса.

    <!--- create a dummy query using queryNew --->
    <cfset news = queryNew("id,title", "integer,varchar")>
    <cfset queryAddRow(news)>
    <cfset querySetCell(news, "id", "1")>
    <cfset querySetCell(news, "title", "Dewey defeats Truman")>
    <cfset queryAddRow(news)>
    <cfset querySetCell(news, "id", "2")>
    <cfset querySetCell(news, "title", "Men walk on Moon")>
    <cfset writeDump(news)>
    
    <!--- run QofQ (query of query) --->
    <cfquery name="sortedNews" dbtype="query">
        SELECT id, title FROM news
        ORDER BY title DESC
    </cfquery>
    <cfset writeDump(sortedNews)>

    Синтаксис скрипта с использованием new Query()

    Этот синтаксис был реализован в компонентах на основе скриптов в CF 9 и 10. Устарел в ColdFusion 2018. Удалён в ColdFusion 2025. В CF11 его заменил queryExecute().

    queryObj = new Query(
     name="qryDemo",
     datasource="mydatasourcename",
     sql = "SELECT col1, col2
     FROM myTable
     WHERE id=:id"
    ); 
    queryObj.addParam(name="id",value=arguments.id, cfsqltype="cf_sql_integer");
    resultset=queryObj.execute().getResult();

    Возврат запроса в виде массива структур

    Lucee 5+ Возвращает объект запроса, преобразованный в массив структур.

    <!--- create a dummy query using queryNew --->
    <cfset users = queryNew("firstname", "varchar", [{"firstname":"Han"}])>
    <cfset writeDump(users)>
    
    <!--- run QofQ (query of query) --->
    <cfquery name="subUsers" dbtype="query" returntype="array">
        SELECT * FROM users
    </cfquery>
    <cfset writeDump(subUsers)>

    Ожидаемый результат: [ { firstname: "Han" } ]

    Возврат запроса в виде структуры структур

    Lucee 5+ Возвращает объект запроса, преобразованный в структуру структур. (Ключ структуры задаётся параметром "columnkey".)

    <!--- create a dummy query using queryNew --->
    <cfset users = queryNew("id, firstname", "integer, varchar", [{"id":1, "firstname":"Han"}])>
    <cfset writeDump(users)>
    
    <!--- run QofQ (query of query) --->
    <cfquery name="subUsers" dbtype="query" returntype="struct" columnkey="id">
        SELECT * FROM users
    </cfquery>
    <cfset writeDump(subUsers)>

    Ожидаемый результат: { 1: { id: 1, firstname: "Han" } }

    Вставка записи и получение сгенерированного ключа

    Вставляет новую запись в таблицу с именем myTable. Столбец "ID" — это столбец первичного ключа с автоинкрементом.

    <!--- insert the new record --->
    <cfquery datasource="myDatasource" result="result">
    INSERT INTO myTable ( name, email ) VALUES ( 'Joe', 'joe@domain.com' )
    </cfquery>
    
    <!--- output the new primary key --->
    <cfdump var="#result.generatedKey#" />

    © 2012–present Foundeo, Inc. and the CFDocs contributors.
    Licensed under the MIT License.
    ColdFusion is a trademark of Adobe Systems Incorporated.
    https://cfdocs.org/cfquery

    Spec-Zone.ru

    Настройки Оффлайн Что нового Помощь О нас
    Spec-Zone .ru
    спецификации, руководства, описания, API