cfquery

説明

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

cfquery タグ内で cfqueryparam タグを使用して、権限のないユーザーがデータベースにアクセスできないようにしてください。詳細については、セキュリティ情報 ASB99-04「Multiple SQL Statements in Dynamic Queries」(Security Zone、www.adobe.com/go/sn_asb99-04_jp) および『ColdFusion アプリケーションの開発』のAccessing and Retrieving Dataを参照してください。

シンタックス

<cfquery  
    name = "query name" 
    blockFactor = "block size" 
    cachedAfter = "date"  
    cacheID = "ID" 
    cacheRegion = "region" 
    cachedWithin = "timespan" 
    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"> 
</cfquery>
注意: このタグの属性は attributeCollection 属性で指定でき、その値は構造体になります。attributeCollection 属性で構造体の名前を指定し、タグの属性名を構造体のキーとして使用します。

関連項目

cfdbinfocfinsertcfprocparamcfprocresultcfqueryparamcfstoredproccftransactioncfupdate、『ColdFusion アプリケーションの開発』のOptimizing database use

履歴

ColdFusion 10 Beta:fetchClientInfocacheIDcacheRegion の各属性が追加されました。

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 のサブセットが拡張されました。

  • ドット表記法のサポートが変更されました。レコードセット名でのドット表記法をサポートするようになりました。レコードセット名は構造体として解釈されます。

  • connectStringdbNamedbServerproviderproviderDSN、および 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 文、データソース、クエリー名、ユーザー名、およびパスワードを使用する必要があります。

dataSource

オプション

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

dbtype

オプション

クエリーの結果を入力として指定します。dbtype または dataSource を指定します。

ColdFusion 9.0.1 では、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 の [データベースアクティビティ] オプションがオンの場合は表示されません。

fetchClientInfo

オプション

no

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

maxRows

オプション

-1 (すべて)

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

ormoptions

オプション

 

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

password

オプション

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

result

オプション

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

timeout

 

エラーが返されるようになるまでにクエリーの各アクションを実行できる秒数の最大値です。累積時間はこの値を超える可能性があります。

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

username

オプション

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

使用方法

このタグを使用して、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 はこの機能をサポートしていません。

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

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

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

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

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

SELECT [count] FROM MYTABLE. 

ColdFusion の予約キーワードのリストについては、『ColdFusion アプリケーションの開発』のEscaping reserved keywordsを参照してください。

<!--- This example shows the use of CreateTimeSpan with CFQUERY ------> 
<!--- to cache a record set. Define startrow and maxrows to ----> 
<!--- facilitate 'next N' style browsing. ----> 
<cfparam name="MaxRows" default="10"> 
<cfparam name="StartRow" default="1"> 
<!-------------------------------------------------------------------- 
Query database for information if cached database information has 
not been updated in the last six hours; otherwise, use cached data. 
---------------------------------------------------------------------> 
<cfquery  
    name="GetParks" datasource="cfdocexamples"  
    cachedwithin="#CreateTimeSpan(0, 6, 0, 0)#"> 
    SELECT PARKNAME, REGION, STATE 
    FROM Parks 
    ORDER BY ParkName, State 
</cfquery> 
<!--- Build HTML table to display query. -------------------------> 
<table cellpadding="1" cellspacing="1"> 
    <tr> 
        <td bgcolor="f0f0f0"> 
            &nbsp; 
        </td> 
        <td bgcolor="f0f0f0"> 
            <b><i>Park Name</i></b> 
        </td> 
        <td bgcolor="f0f0f0"> 
            <b><i>Region</i></b> 
        </td> 
        <td bgcolor="f0f0f0"> 
            <b><i>State</i></b> 
        </td> 
    </tr> 
<!--- Output the query and define the startrow and maxrows parameters.  
Use the query variable CurrentCount to keep track of the row you are displaying. ------> 
<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> 
<!--- If the total number of records is less than or equal to the total number of rows,  
then offer a link to the same page, with the startrow value incremented by maxrows  
(in the case of this example, incremented by 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>