TOP

返す行数を指定する SELECT 節です。

Synopsis

SELECT  [DISTINCT clause] 
  [TOP {[((]int[))] | ALL}]
  select-item {,select-item2}

引数

int

返す行数を指定された整数値に制限します。int 引数には、正の整数、ダイナミック SQL の入力パラメータ (?)、または正の整数に解決される、埋め込み SQL のホスト変数 (:var) を指定できます。

ダイナミック SQL では、int 値はオプションで一重または二重の括弧で囲むことができます (推奨される構文は二重括弧です)。これらの括弧により、対応するクエリ・キャッシュの int 値のリテラル置換を抑制できます。

ALL

TOP ALL は、サブクエリまたは CREATE VIEW 文に使用したときにのみ意味を持ちます。ORDER BY 節をこれらの状況で使用することがサポートされるように使用すると、CREATE VIEW で使用するクエリやサブクエリで TOP 節と ORDER BY 節を組み合わせる必要がある要件が満たされます。TOP ALL では、返される行数に制限はありません。

説明

オプションの TOP 節は、SELECT キーワードとオプションの DISTINCT 節の後、最初の select-item の前に記述します。

TOP キーワードは、ダイナミック SQL とカーソル・ベースの埋め込み SQL で使用されます。非カーソルの埋め込み SQL では、TOP キーワードの意味のある使い方は TOP 0 のみとなります。他のすべての TOP int (int はゼロ以外の任意の整数) は有効ではありますが、意味はありません。なぜなら、非カーソルの埋め込み SQL 内の SELECT は常に、最大 1 行のデータを返すからです。

SELECT 文の TOP 節は、返される行数を int で指定された数に制限します。TOP 節が指定されない場合、既定では SELECT 条件を満たすすべての行を表示します。TOP 節が指定された場合、表示される行数は、int か、クエリ述語の要件を満たすすべての行のいずれか少ない方になります。ALL を指定した場合、SELECT は、クエリ述語の要件を満足するテーブル内のすべての行を返します。

クエリで ORDER BY 節が指定されていない場合、どのレコードが “上位“ 行として返されるかは予想できません。ORDER BY 節を指定すれば、上位行は節で指定された順序に一致します。

DISTINCT 節は (指定された場合)、TOP の前に適用され、一意の値が (最大で) int 個返されるように指定します。

すべての行が送信されている場合、TOP は簡略化されます。このようにして、SQLCODE 100 を取得するまで選択する場合に、SQLCODE 100 を設定する FETCH では結果が即座に得られます。

ビューを介して、または FROM 節サブクエリを介してデータにアクセスする場合に、TOP 節ではなく (または TOP 節への追加として)、%vid ビュー ID を使用することで、返される行の数を制限できます。%vid の使用の詳細は、"Caché SQL の使用法" の "ビューの定義と使用" の章を参照してください。

TOP の int 値

int 数値には、整数、数値文字列、ダイナミック SQL の入力パラメータ (?)、または整数値に解決される入力ホスト変数 (:var) を指定できます。

int 値は、返される行数を指定します。許可される値は、0 および正の数値です。小数または数字文字列は、整数値として解析されます。ゼロ (0) は有効な int 値です。TOP 0 を指定するとクエリは実行されますが、データは返されません。

クエリのキーワードとして TOP ALL を指定する必要があります。? 入力パラメータまたは :var ホスト変数値として ALL を指定することはできません。クエリ・パーサは、このように指定された文字列 "ALL" を値が 0 の数値文字列として解釈します。

TOP int は数値文字列または整数として指定できるため、TOP 引数メタデータは、xDBC データ型 4 (INTEGER) ではなく 12 (VARCHAR) として返されることに注意してください。

TOP とクエリ・キャッシュ

int 値は、括弧を付けて指定することも、付けないで指定することもできます。これらの括弧は、ダイナミック SQL クエリのキャッシュ方法に影響します (非カーソルの埋め込み SQL クエリはキャッシュされません)。括弧なしの int 値は、クエリ・キャッシュでは ? パラメータ値に変換されます。これは、同じクエリを異なる TOP の int 値で呼び出すことは、毎回クエリを準備および最適化するのではなく、同じクエリ・キャッシュを呼び出すことを意味します。

括弧で囲むと、リテラル置換を抑制します。例えば、TOP ((7)) です。int が括弧で囲まれている場合、クエリ・キャッシュは特定の int 値を保持します。同じ TOP int 値のクエリを再呼び出しする場合、同じクエリ・キャッシュを使用します。別の TOP int 値でクエリを呼び出すと、SQL は新しいクエリを準備し、最適化し、キャッシュします。

TOP ALL は、? パラメータ変数としてはキャッシュされません。ALL はリテラルではなくキーワードとして解析されます。したがって、同じクエリに TOP 7 を指定した場合と TOP ALL を指定した場合で、異なる 2 つのクエリ・キャッシュが生成されます。

TOP と ORDER BY

TOP は、通常、SELECT で ORDER BY 節と共に使用されます。既定の昇順の ORDER BY 照合シーケンスでは、NULL が最小 (“上位“) の値と見なされ、次に空文字列 ('') が続きます。

サブクエリの SELECT または CREATE VIEW の SELECT で ORDER BY 節を指定する場合は、TOP が必要です。このような場合、TOP int (返す行数を制限する) または TOP ALL を使用できます。

TOP ALL はサブクエリまたは CREATE VIEW 文でのみ使用できます。サブクエリで使用する ORDER BY 節または CREATE VIEW クエリで使用する ORDER BY 節は TOP 節と組み合わせる必要がありますが、TOP ALL を指定することでその要件を満たすことができます。TOP ALL では、返される行数に制限はありません。TOP ALL ...ORDER BY では、既定の SELECT の最適化は変更されません。ALL キーワードを括弧で囲むことはできません。

TOP の最適化

既定では、SELECT はすべてのデータを返す時間が最速になるように最適化されます。TOP int 節と ORDER BY 節の両方を追加すると、最初の行を返す時間が最速になるように最適化されます (最適化を変更するには両方の節が必要です)。%SYS.PTools.SQLStatsOpens in a new tab クラスの TimeToFirstRow プロパティを使用すると、最初の行を返すために必要な時間を返すことができます。

以下に特殊な最適化のケースを示します。

返される行数を制限せずに TOP および ORDER BY の最適化方法を使用する必要がある場合があります (ページ単位で表示されるデータを返す場合など)。そのような場合、int 値を全行数より大きく指定して TOP 節を発行することができます。
既定の SELECT の最適化を変更せずに、返される行数を制限してその順序を指定する必要がある場合があります。そのような場合、TOP 節、ORDER BY 節、および %NOTOPOPT キーワードを指定すると、すべてのデータを最速で返す最適化が保持されます。詳細は、"FROM" 節を参照してください。

TOP と集約および関数

集約関数またはスカラ関数は、単独の値のみを返せます。クエリの select-item リストに、集約と関数のみが含まれている場合の TOP 節が適用されるかどうかについては、以下に示します。

select-item リストに COUNT(*) や AVG(Age) などの集約関数が含まれており、フィールド参照が含まれていない場合、TOP の int 値や ORDER BY 節の存在に関係なく、複数の行は返されません。これらの節は検証されますが、無視されます。詳細は、以下の例を参照してください。
```
SELECT TOP 5 AVG(Age),CURRENT_TIMESTAMP(3) FROM Sample.Person
  /* returns 1 row */
```
```
SELECT TOP 1 AVG(Age),CURRENT_TIMESTAMP(3) FROM Sample.Person ORDER BY Age
  /* returns 1 row */
```
select-item リストに、1 つ以上のスカラ関数、式、リテラル (%TABLENAME など)、サブクエリ、またはホスト変数が含まれており、フィールド参照および集約は含まれていない場合、TOP 節が適用されます。詳細は、以下の例を参照してください。
```
SELECT TOP 5 ROUND(678.987,2),CURRENT_TIMESTAMP(3) FROM Sample.Person
  /* returns 5 identical rows */
```
実際に返される行数は、テーブル・フィールドを参照していない場合でも、テーブル内の行数が影響します。以下に例を示します。
```
SELECT TOP 300 CURRENT_TIMESTAMP(3) FROM Sample.Person
  /* returns either the number of rows in Sample.Person
     or 300 rows, whichever is smaller */
```
クエリが述語の条件によって制限されている場合、テーブル・フィールドが select-item リストで参照されていない場合でも、返される行数はその条件によって制限されます。以下に例を示します。
```
SELECT TOP 300 CURRENT_TIMESTAMP(3) FROM Sample.Person WHERE Home_State = 'MA'
  /* returns either the number of rows in Sample.Person
     where Home_State = 'MA'
     or 300 rows, whichever is smaller */
```
SELECT 文に FROM 節が含まれていない場合には、TOP 値に関係なく、返される行は最大でも 1 つです。以下に例を示します。
```
SELECT TOP 5 ROUND(678.987,2),CURRENT_TIMESTAMP(3)
  /* returns 1 row */
```
DISTINCT 節は、TOP 節をさらに制限します。個別値の数が TOP 値より少ない場合は、個別値を持つ行のみが返されます。スカラ関数のみが参照される場合は、1 行のみが返されます。以下に例を示します。
```
SELECT DISTINCT TOP 15 CURRENT_TIMESTAMP(3) FROM Sample.Person
  /* returns 1 row */
```
TOP 0 と指定すると、select-item リストの内容や、SELECT 文に FROM 節や DISTINCT 節が含まれているかどうかに関係なく、常に行はまったく返されません。
非カーソルの埋め込み SQL では、TOP 0 と指定したクエリでは行は返されず、SQLCODE=100 に設定されます。非カーソルの埋め込み SQL クエリで TOP 1 (または他の任意の TOP int 値) と指定すると、1 行が返され、SQLCODE=0 に設定されます。カーソル・ベースの埋め込み SQL では、フェッチ・ループが完了すると、TOP int 値に関係なく、常に SQLCODE=100 に設定されます。

例

以下のクエリは、データベースに格納される順番で Sample.Person から取得する最初の 20 行を返します。通常、このレコードの順序は予測できません。

SELECT TOP 20 Home_State,Name FROM Sample.Person

以下のクエリは、Sample.Person から取得した最初の 20 個の異なる Home_State 値を照合順の昇順で返します。

SELECT DISTINCT TOP 20 Home_State FROM Sample.Person ORDER BY Home_State

以下のクエリでは、非重複 FavoriteColor 値のうち最初の 40 個が返されます。“上位“ の行は ORDER BY 節を反映し、Sample.Person 内のすべての行を照合順の降順 (DESC) に並べ替えます。FavoriteColors フィールドには NULL があることがわかっており、照合順の昇順では最初に表示されるので、既定の照合順の昇順より降順を使用します。

SELECT DISTINCT TOP 40 FavoriteColors FROM Sample.Person 
      ORDER BY FavoriteColors DESC

また、上記の例では FavoriteColors はリスト・フィールドなので、照合順序には要素のバイト長も加味されます。そのため、6 文字の要素 (YELLOW、PURPLE、ORANGE) は共に照合され、その後に 5 文字の要素 (WHITE、GREENなど) がリストされます。

ダイナミック SQL では、int 値を入力パラメータ (“?”) として指定できます。以下の例では、%Execute メソッドで TOP ? の入力パラメータを 10 に設定しています。

  SET myquery = "SELECT TOP ? Name,Age FROM Sample.Person"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(myquery)
    IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute(10)
  DO rset.%Display()

以下のカーソル・ベースの埋め込み SQL の例は、同じ操作を実行しています。

  SET topnum=10
  &sql(DECLARE pCursor CURSOR FOR
       SELECT TOP :topnum Name,Age INTO :name,:years FROM Sample.Person
      )
  &sql(OPEN pCursor)
  FOR { &sql(FETCH pCursor)
        QUIT:SQLCODE
        WRITE "Name=",name," Age=",years,!
      }
  &sql(CLOSE pCursor)

TOP