cfquery

注意:

このタグは、CFFiddle ではサポートされていません。

説明

クエリまたは SQL ステートメントをデータソースに渡します。 cfqueryparam   タグを各  cfquery   タグ内で使用して、権限のないユーザーがデータベースにアクセスできないようにしてください。

カテゴリ

シンタックス

<cfquery  
name = "query name"  
blockFactor = "block size"  
cachedAfter = "date"  
cacheID = "ID"  
cacheRegion = "region"  
cachedWithin = "timespan" 
disableAutoGenKeys="true|false" 
dataSource = "data source name"  
dbtype = "query"  
debug = "yes|no"  
fetchClientInfo = "yes|no"  
maxRows = "number"  
ormoptions = #orm options structure#  
password = "password"  
result = "result name"  
timeout = "seconds"  
username = "user name" 
returnType="array | json/array | query | struct | json/struct">  
</cfquery>
注意:

このタグの属性は attributeCollection 属性で指定でき、その値は構造体になります。attributeCollection 属性で構造体の名前を指定し、タグの属性名を構造体のキーとして使用します。

関連項目

cfdbinfocfinsertcfprocparamcfprocresultcfqueryparamcfstoredproccftransactioncfupdate、『ColdFusion アプリケーションの開発』の ColdFusion アプリケーションの最適化データベース使用の最適化

履歴

ColdFusion(2021 リリース):属性 returnType が追加されました。

ColdFusion(2018 リリース):パラメーター disableAutoGenKeys が追加されました。

ColdFusion 11:次の属性が削除されました。

  • connectString
  • dbName
  • dbServer
  • provider
  • providerDSN
  • sql

さらに、次の dbType 属性値も削除されました。

  • dynamic
  • ODBC
  • Oracle73
  • Oracle80
  • Sybase11
  • OLEDB
  • DB2

ColdFusion 10:fetchClientInfo、cacheID、cacheRegion、clientInfo の各属性が追加されました。

ColdFusion 9.0.1:HQL クエリのサポートが導入され、ormoptions 属性が追加されました。

ColdFusion 9:データソース属性はオプションになりました。

ColdFusion 8:行の ID を指定する結果変数が追加されました。

ColdFusion MX 7:

  • 結果変数を保持する構造体の別名を指定するための result 属性が追加されました。
  • 実行された SQL ステートメントの結果変数( sql )、返されたレコードの数( recordcount )、クエリがキャッシュされたかどうか(cached)、 cfqueryparam   値の配列( sqlparameters )、返されたクエリ内の列のリスト( columnlist )が追加されました。
    ColdFusion MX:
  • クエリオブクエリの動作が変更されました。サポートされる標準 SQL のサブセットが拡張されました。
  • ドット表記法のサポートが変更されました。 レコードセット 名でのドット表記法をサポートするようになりました。レコードセット名は構造体として解釈されます。
  • connectString、dbName、dbServer、provider、 providerDSN 、 sql  の各属性、および query を除く  dbtype  属性のすべての値が廃止されました。これらは、 ColdFusion 5 以降のリリースでは機能せず、 エラーを引き起こす可能性があります。
  • 新しいクエリオブジェクト変数 cfquery.ExecutionTime を使用できるようになりました。
  • ネイティブドライバはサポートされなくなりました。データベース接続には JDBC(および ODBC-JDBC ブリッジ)を使用します。

属性

属性

必須/オプション

デフォルト

説明

name

必須

 

クエリ名。クエリのレコードセットを参照するためにページ内で使用します。文字で始める必要があります。文字、数字、およびアンダースコアを使用できます。

blockFactor

オプション

1

サーバーから一度に取得する行の最大数。1~100 の範囲で指定します。一部のデータベースシステムではサポートされないことがあります。

cachedAfter

オプション

 

日付の値です(例えば、April 16, 1999、4-16-99)。元のクエリの日付がこの日付よりも後の場合は、ColdFusion ではキャッシュされているクエリデータが使用されます。キャッシュされているデータを使用するには、現在のクエリで同じ SQL ステートメント、データソース、クエリ名、ユーザー名、パスワードを使用する必要があります。日付時刻オブジェクトの範囲は、西暦 100~9999 年です。
日付の値を文字列として指定するときは、文字列を引用符で囲みます。

cacheID

オプション

 

クエリ結果をキャッシュに保存する際に使用する ID です。この ID は、キャッシュのクエリの取得と削除の両方で使用できます。

cacheRegion

オプション

 

クエリ結果をキャッシュする際に使用するキャッシュ領域です。指定しない場合、デフォルトでは、クエリは QUERY 領域にキャッシュされます。

cachedWithin

オプション

 

期間です。CreateTimeSpan 関数を使用します。元のクエリの日付がこの期間内の場合、キャッシュされているクエリデータが使用されます。CreateTimeSpan では、現在からさかのぼって期間を定義します。クエリのキャッシュ機能が Administrator 内で有効になっている場合のみ機能します。キャッシュされているデータを使用するには、現在のクエリで、同じ SQL 文、データソース、クエリ名、ユーザー名、パスワードを使用する必要があります。

clientInfo

オプション

 

データベース接続で設定するクライアントのプロパティが含まれる構造体です。

dataSource

オプション

 

dataSource 属性は、オプションになりました。省略すると、アプリケーションで指定されたデータソースがクエリで使用されます。どちらにも指定されない場合は、エラーが発生します。

dbtype

オプション

 

クエリの結果を入力として指定します。dbtype か dataSource のいずれかを指定します。ColdFusion では、cfquery で HQL がサポートされます。したがって、次の例に示すように dbtype="hql" を指定できます。<cfquery dbtype="hql" name="artists" ormoptions=#{cachename=""}#>from Artists where firstname=<cfqueryparam value="Aiden"></cfquery>

debug

オプション(値と等号は省略可能)

 

·         yes、または値が省略された場合:デバッグがオンになっており、Administrator の「データベースアクティビティ」オプションがオフの場合、データソースに提出された SQL と、クエリによって返されたレコードの数が表示されます。

·         no の場合:Administrator の「データベースアクティビティ」オプションがオンの場合は表示されません。

disableAutoGenKeys オプション false

自動生成キーの取得を無効にする場合は、true を指定します。

以前のバージョンの ColdFusion では、この属性をデータソースレベルで設定することができました。ColdFusion の 2018 リリースでは、クエリレベルで設定できます。

fetchClientInfo

オプション

no

yes に設定した場合、最後のクエリによって渡された、キーと値のペアを持つ構造体が返されます。

maxRows

オプション

-1(すべて)

レコードセットで返す行の最大数です。

ormoptions

オプション

 

HQL を実行する際の orm オプションが含まれる構造体です。dbtype が hql に設定されている場合にのみ適用されます。

password

オプション

 

データソースセットアップのパスワードよりも優先されます。

result

オプション

 

cfquery が結果変数を返す構造体の名前です。詳細については、「使用方法」を参照してください。

timeout

 

 

エラーが返されるようになるまでにクエリの各アクションを実行できる秒数の最大値です。累積時間はこの値を超える可能性があります。
JDBC ステートメントの場合は、この属性が設定されます。その他のドライバについては、各ドライバーのマニュアルを参照してください。

username

オプション

 

データソースセットアップのユーザー名よりも優先されます。

returnType オプション  

有効な値は次のとおりです。

  • 配列
  • JSON/配列
  • クエリ(デフォルト)

使用方法

このタグを使用して、ColdFusion データソースに対して SQL ステートメントを実行します。cfquery タグを使用して任意の SQL DDL(Data Definition Language:データ定義言語)または DML(Data Manipulation Language:データ操作言語)ステートメントを実行できますが、通常は SQL SELECT ステートメントを実行します。

注意:

ストアドプロシージャを呼び出すには、cfstoredproc タグを使用します。

このタグではクエリオブジェクトが作成され、次の情報がクエリ変数に提供されます。

変数名

説明

query_name.currentRow

cfoutput が処理しているクエリの現在行です。

query_name.columnList

クエリ列のカンマ区切りリストです。

query_name.RecordCount

クエリで返されるレコード(行)数です。

 

cfquery タグは、構造体内の次の結果変数も返します。result 属性で指定した名前を接頭辞とするこれらの変数にアクセスできます。例えば、myResult という名前を result 属性に割り当てた場合、#myResult.sql# にアクセスすることにより、実行された SQL ステートメントの名前を取得できます。result 属性は、複数のページから同時に呼び出される可能性がある関数または CFC(あるいはこれら両方)について、一方の呼び出しの結果が他方の呼び出しの結果を上書きしないようにするための方法を提供します。INSERT クエリの結果変数には、挿入された行の自動生成 ID を示すキーと値のペアが格納されます。この結果変数は、この機能をサポートするデータベースでのみ使用できます。複数のレコードが挿入された場合の値は ID のリストになります。キー名はデータベースごとに異なります。

変数名

説明

result_name.sql

実行された SQL ステートメントです。

result_name.recordcount

クエリで返されるレコード(行)数です。

result_name.cached

クエリがキャッシュされた場合は true、それ以外の場合は false です。

result_name.sqlparameters

cfqueryparam 値の順序配列です。

result_name.columnList

クエリ列のカンマ区切りリストです。

result_name.ExecutionTime

クエリの処理に要した累積時間です。

result_name.IDENTITYCOL

(SQL Server のみ)挿入された行の ID です。

result_name.ROWID

(Oracle のみ)挿入された行の ID です。これは行のプライマリキーではありませんが、この ID に基づいて行を取得できます。

result_name.SYB_IDENTITY

(Sybase のみ)挿入された行の ID です。

result_name.SERIAL_COL

(Informix のみ)挿入された行の ID です。

result_name.GENERATED_KEY (MySQL のみ)挿入された行の ID です。MySQL 3 はこの機能をサポートしていません。
result_name.GENERATEDKEY (すべてのデータベースをサポート)挿入された行の ID です。

クエリ結果をキャッシュして、ストアドプロシージャを実行することができます。この方法と、cfquery 出力を表示する方法については、『ColdFusion アプリケーションの開発』を参照してください。timeout 属性はクエリの各サブ操作の最大時間に影響するだけなので、累積時間はこの値を超える可能性があります。非常に大きな結果セットが返される可能性があるページのタイムアウトを設定するには、Administrator の「サーバーの設定」で「リクエストタイムアウト」オプションを適切な値に設定するか、cfsetting タグの RequestTimeout 属性を使用します(<cfsetting requestTimeout="300"> など)。
ColdFusion Administrator のキャッシュ機能ページで、キャッシュされるクエリの最大数を指定します。この値を 0 に設定すると、クエリのキャッシュ機能は無効になります。
ColdFusion の予約語をクエリ名に使用することはできません。SQL の予約語は、エスケープしなければクエリオブクエリの変数名または列名としては使用できません。エスケープ文字は角括弧 [] で、例えば次のように使用します。

SELECT [count] FROM MYTABLE.

ColdFusion の予約キーワードのリストについては、『ColdFusion アプリケーションの開発』のクエリオブクエリのユーザーガイドの「予約語のエスケープ」を参照してください。

例 1:基礎知識

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples">
       SELECT FIRSTNAME,LASTNAME
       FROM EMPLOYEES
</cfquery>

<!--- Create HTML page --->
<HTML>
       <head>
             <title>
                    List of Employees
             </title>
       </head>
       <body>
             <h1>
                    Employee List
             </h1>
             <!--- List out employees--->
             <cfoutput query="getEmployees">
                    #FIRSTNAME# #LASTNAME# <br/>
             </cfoutput>
       </body>
</HTML>

例 2:テーブルの使用

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>

<!--- Create HTML page --->
<html>
 <head>
  <title>
   Table of Employees
  </title>
 </head>
 <body>
  <table border="1">
   <!--- Loop through the database --->
   <cfoutput query="getEmployees">
    <tr>
     <td>
      #FIRSTNAME# #LASTNAME#
     </td>
     <td>
      #EMAIL#
     </td>
     <td>
      #PHONE#
     </td>
    </tr>
   </cfoutput>
  </table>
 </body>
</html>

例 3:result 属性の使用

<!--- Get employee names from database --->
<cfquery name="getEmployees" datasource="cfdocexamples" result="result">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#result#" >
<cfoutput>
 <!--- Display count of records --->
 #result.RecordCount#
</cfoutput>

出力

result
result

例 4:password 属性の使用

多くのデータベース設定では、データベースに対してクエリを実行するには、(ユーザー名とパスワードを使用して)認証をおこなう必要があります。username 属性と password 属性を使用して、認証を追加することができます。

なお、ColdFusion Administrator で、データソースのユーザー名とパスワードを設定することもできます。認証に関する詳細をクエリに指定すると、ColdFusion Administrator で設定したユーザー名とパスワードより優先されます。

<cfquery datasource="cfdocexamples" username="myusername" password="mypassword">
  select *
  from Employees
</cfquery>

例 5:レコード数の制限

maxRows 属性を使用すると、返される行の数を制限できます。

<cfquery name="getEmployees" datasource="cfdocexamples" result="result" maxrows="10">
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#result#" >
<cfoutput>
 <!--- Display count of records --->
 #result.RecordCount#
</cfoutput>

例 6:timeout 属性の使用

timeout 属性を使用すると、タイムアウト制限を設定できます。  タイムアウトは、設定された制限を超える時間にわたってリクエストが実行されるのを防ぐうえで役に立ちます。

timeout 属性は、エラーが返されるようになるまでにクエリの各アクションを実行できる秒数の最大値を設定します。

<cfquery name="getEmployees" datasource="cfdocexamples" timeout="20" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

例 7:キャッシュされたクエリ

Web サイトまたはアプリケーションに送信されるトラフィックの量は、サイトまたはアプリケーションのパフォーマンスに影響を及ぼします。データベースクエリをキャッシュすると、パフォーマンスを向上させることができます。

キャッシュされたクエリでは、結果がサーバーのメモリに格納されます。結果が格納されるのは、クエリが最初に実行されたときです。その後は、クエリを実行するたびに、結果がメモリから取得されます。

cachedAfter 属性を使用して、クエリをキャッシュすることができます。

<cfquery name="getEmployees" datasource="cfdocexamples" cachedafter="10-15-2018" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

CreateTimeSpan 関数で cachedWithin 属性を使用してクエリをキャッシュすることもできます。

次の例では、クエリのデータがキャッシュされてから 60 秒以上経過すると、クエリが再実行されます。それ以外の場合は、キャッシュされたデータが使用されます。

<cfquery name="getEmployees" datasource="cfdocexamples" cachedwithin="#CreateTimespan(0,0,60,0)#" >
 SELECT FIRSTNAME,LASTNAME,EMAIL,PHONE
 FROM EMPLOYEES
</cfquery>
<cfdump var="#getEmployees#" >

例 8:戻り値の型が配列

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery" RETURNTYPE = "array"> 
        select ARTID,ARTISTID,ARTNAME  from art where ARTID < 2 
</cfquery> 
<cfoutput>#getEmployees[1].ARTID# #getEmployees[1].ARTISTID# #getEmployees[1].ARTNAME#</cfoutput> 

例 9:戻り値の型が JSON または配列

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery" RETURNTYPE = "json/array"> 
        select ARTID,ARTISTID,ARTNAME from art where ARTID < 2 
</cfquery> 
<cfset record=deserializeJSON(getEmployees)> 
<cfoutput>#record[1].ARTID# #record[1].ARTISTID# #record[1].ARTNAME# #getEmployees#</cfoutput>

例 10:戻り値の型がデフォルトクエリ

<cfquery name="getEmployees" datasource="cfArtGallery" result="myquery"> 
        select ARTID,ARTISTID,ARTNAME from art where ARTID < 2 
</cfquery> 
<cfset record=QueryGetRow(getEmployees,1)> 
<cfoutput>#record.ARTID# #record.ARTISTID# #record.ARTNAME#</cfoutput>

 Adobe

ヘルプをすばやく簡単に入手

新規ユーザーの場合

Adobe MAX 2024

Adobe MAX
クリエイティブカンファレンス

10 月 14 日~ 16 日 マイアミビーチおよびオンライン

Adobe MAX

クリエイティブカンファレンス

10 月 14 日~ 16 日 マイアミビーチおよびオンライン

Adobe MAX 2024

Adobe MAX
クリエイティブカンファレンス

10 月 14 日~ 16 日 マイアミビーチおよびオンライン

Adobe MAX

クリエイティブカンファレンス

10 月 14 日~ 16 日 マイアミビーチおよびオンライン