このタグは、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 属性で構造体の名前を指定し、タグの属性名を構造体のキーとして使用します。
関連項目
cfdbinfo、cfinsert、cfprocparam、cfprocresult、cfqueryparam、cfstoredproc、cftransaction、cfupdate、『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 |
|
|
エラーが返されるようになるまでにクエリの各アクションを実行できる秒数の最大値です。累積時間はこの値を超える可能性があります。 |
username |
オプション |
|
データソースセットアップのユーザー名よりも優先されます。 |
| returnType | オプション | 有効な値は次のとおりです。
|
使用方法
このタグを使用して、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>
出力
例 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>
