CFQUERY  
説明

クエリーまたは SQL ステートメントをデータソースに渡します。

各 cfquery タグ内で cfqueryparam タグを使用して、未認可のユーザーからデータベースを保護するようにしてください。詳細については、セキュリティ情報 ASB99-04「Multiple SQL Statements in Dynamic Queries」(Macromedia Security Zone、www.macromedia.com/devnet/security/security_zone/asb99-04.html) および 『ColdFusion MX 開発ガイド』の第20章の「データへのアクセスおよび取り出し」 を参照してください。

 
カテゴリ

データベース操作タグ

 
シンタックス
<cfquery 
   name = "query_name"
   dataSource = "ds_name" 
   dbtype = "query"
   username = "username"
   password = "password"
   maxRows = "number"
   blockFactor = "blocksize"
   timeout = "seconds"
   cachedAfter = "date" 
   cachedWithin = "timespan" 

   次のいずれかを指定します。
      debug = "yes"、"no"
   または
      debug
>
result = "result_name"
</cfquery>
 
関連項目

cfinsert、cfprocparam、cfprocresult、cfqueryparam、cfstoredproc、cftransaction、cfupdate、『ColdFusion MX 開発ガイド』の第13章の「ColdFusion アプリケーションの設計と最適化」 の「データベース使用の最適化」および第 19 ~ 22 章

 
ヒストリ

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 ブリッジ) を使用します。

 
使用方法

このタグを使用して、ColdFusion データソースに対して SQL ステートメントを実行します。cfquery タグを使用して DDL (SQL 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 (あるいはこれら両方) について、一方の呼び出しの結果が他方の呼び出しの結果を上書きしないようにするための方法を提供します。

変数名 説明
result_name.sql

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

result_name.recordcount

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

result_name.cached

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

result_name.sqlparameters

cfqueryparam 値の順序配列です。

result_name.columnList

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

result_name.ExecutionTime

クエリーの処理に必要な累積時間です。

クエリー結果をキャッシュして、ストアードプロシージャを実行することができます。このことと、cfquery 出力の表示の詳細については、『ColdFusion MX 開発ガイド』を参照してください。

timeout 属性はクエリーの各サブ操作の最大時間に影響するだけであるため、累積時間はこの値を越える可能性があります。非常に大きな結果セットが返される可能性があるページのタイムアウトを設定するには、Administrator の [サーバーの設定] - [リクエストタイムアウト] オプションを適切な値に設定するか、cfsetting タグの RequestTimeout 属性を使用します (<cfsetting requestTimeout="300"> など)。

ColdFusion MX Administrator の [キャッシュ機能] ページで、キャッシュされるクエリーの最大数を指定します。この値を 0 に設定すると、クエリーのキャッシュ機能は無効になります。

ColdFusion の予約語をクエリー名に使用することはできません。

SQL の予約語は、エスケープしなければクエリーオブクエリーの変数名または列名としては使用できません。エスケープ文字は角括弧 [] で、たとえば次のように使用します。

SELECT [count] FROM MYTABLE. 

ColdFusion MX の予約キーワードのリストについては、『ColdFusion MX 開発ガイド』の第22章の「クエリーオブクエリーの使用」 の「予約されたキーワードのエスケープ」を参照してください。

 
<!--- この例では、CreateTimeSpan を CFQUERY と共に使用する方法を示します。 ------>
<!--- レコードセットをキャッシュします。開始行と最大行を定義します。 ---->
<!--- 'next N' 方式のブラウズを容易にします。 ---- ---->
<cfparam name="MaxRows" default="10">
<cfparam name="StartRow" default="1">
<!--------------------------------------------------------------------
キャッシュされたデータベース情報が過去 6 時間以内に更新されていない場合は、
データベースに情報のクエリーを実行。更新されている場合は、キャッシュされているデータを使用。
--------------------------------------------------------------------->
<cfquery
name="GetParks" datasource="cfdocexamples" 
cachedwithin="#CreateTimeSpan(0, 6, 0, 0)#">
SELECT PARKNAME, REGION, STATE
FROM Parks
ORDER BY ParkName, State
</cfquery>
<!--- クエリーを表示するための HTML テーブルを作成します。 ------------------------->
<table cellpadding="1" cellspacing="1">
   <tr>
      <td bgcolor="f0f0f0">
         &nbsp;
      </td>
      <td bgcolor="f0f0f0">
         <b><i>公園名</i></b>
      </td>
      <td bgcolor="f0f0f0">
         <b><i>地域</i></b>
      </td>
      <td bgcolor="f0f0f0">
         <b><i>州</i></b>
      </td>
   </tr>
<!--- クエリーを出力し、startrow パラメータと maxrows パラメータを定義します。 
クエリー変数 CurrentCount を使用して表示する行を
追跡します。 ------>
<cfoutput query="GetParks" startrow="#StartRow#" maxrows="#MaxRows#">
   <tr>
      <td valign="top" bgcolor="ffffed">
         <b>#GetParks.CurrentRow#</b>
      </td>
      <td valign="top">
         <font size="-1">#ParkName#</font>
      </td>
      <td valign="top">
         <font size="-1">#Region#</font>
      </td>
      <td valign="top">
         <font size="-1">#State#</font>
      </td>
   </tr>
</cfoutput>
<!--- 総レコード数が
総行数以下の場合は、同じページへの
リンクを提供。その際、startrow の値は
maxrows の指定値だけ増加。この例では、10 増えます。 --------->
   <tr>
      <td colspan="4">
      <cfif (StartRow + MaxRows) LTE GetParks.recordCount>
         <cfoutput><a href="#CGI.SCRIPT_NAME#?startrow=#Evaluate(StartRow + MaxRows)#">
         See next #MaxRows# rows</a></cfoutput> 
      </cfif>
      </td>
   </tr>
</table> 
NAME  
  必須
 

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

DATASOURCE  
  dbtype=query の場合以外は必須
 

クエリーがデータを取得するためのデータソースの名前です。dbtype または dataSource のいずれかを指定する必要があります。

DBTYPE  
  オプション
 

クエリーの結果を入力として指定するには、この値を使用します。dbtype または dataSource のいずれかを指定する必要があります。

USERNAME  
  オプション
 

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

PASSWORD  
  オプション
 

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

MAXROWS  
  オプション
 
Default value: "-1 (すべて)"

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

BLOCKFACTOR  
  オプション
 
Default value: "1"

サーバーから一度に取得する行の最大数です。1 ~ 100 の範囲を指定します。1 - 100. データベースシステムによってはサポートされない可能性があります。

TIMEOUT  
   
 

クエリーの各アクションが動作可能な最大秒数です。この秒数を越えるとエラーが返されます。累積時間はこの値を越える可能性があります。

JDBC ステートメントの場合は、この属性が設定されます。その他のドライバについては、各ドライバのマニュアルを確認してください。

CACHEDAFTER  
  オプション
 

日付の値です (たとえば、April 16, 1999、4-16-99)。元のクエリーの日付がこの日付よりも後の場合は、ColdFusion ではキャッシュされているクエリーデータが使用されます。キャッシュされているデータを使用するには、現在のクエリーで同じ SQL ステートメント、データソース、クエリー名、ユーザー名、およびパスワードを使用する必要があります。

日付時刻オブジェクトの範囲は、西暦 100 ~ 9999 年です。

日付の値を文字列として指定するときは、必ず文字列を引用符で囲んでください。

CACHEDWITHIN  
  オプション
 

期間です。CreateTimeSpan 関数を使用します。元のクエリーの日付がこの期間内の場合、キャッシュされているクエリーデータが使用されます。CreateTimeSpan では、現在からさかのぼって期間を定義します。クエリーのキャッシュ機能が Administrator 内で有効になっている場合のみ機能します。

キャッシュされているデータを使用するには、現在のクエリーで、同じ SQL 文、データソース、クエリー名、ユーザー名、およびパスワードを使用する必要があります。

DEBUG  
  オプション。値と統合が省かれます。
 
  • Yes、または値が省略された場合: デバッグがオンになっており、Administrator の [データベースアクティビティ] オプションがオフの場合、データソースに提出された SQL とクエリーによって返されたレコードの数が表示されます。
  • No: Administrator の [データベースアクティビティ] オプションがオンの場合は表示されません。
RESULT  
  オプション
 

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