AlierTable: get()

対象のテーブルからレコードを取得します。

この関数は非同期関数です。

構文

alierTable.get() => Promise<object>
alierTable.get({ filter }) => Promise<object>
alierTable.get({ sort }) => Promise<object>
alierTable.get({ sort, limit }) => Promise<object>
alierTable.get({ sort, offset }) => Promise<object>
alierTable.get({ sort, limit, offset }) => Promise<object>
alierTable.get({ aggregate }) => Promise<object>
alierTable.get({ aggregate, aggregateAs }) => Promise<object>
alierTable.get({ final }) => Promise<object>
alierTable.get({ aggregate, final }) => Promise<object>
alierTable.get({ aggregate, aggregateAs, final }) => Promise<object>
alierTable.get({ filter, sort }) => Promise<object>
alierTable.get({ filter, sort, limit }) => Promise<object>
alierTable.get({ filter, sort, offset }) => Promise<object>
alierTable.get({ filter, sort, limit, offset }) => Promise<object>
alierTable.get({ filter, aggregate }) => Promise<object>
alierTable.get({ filter, aggregate, aggregateAs }) => Promise<object>
alierTable.get({ filter, final }) => Promise<object>
alierTable.get({ filter, aggregate, final }) => Promise<object>
alierTable.get({ filter, aggregate, aggregateAs, final }) => Promise<object>

引数

単一の、以下のプロパティを持つオブジェクトです。 このオブジェクトの指定は任意です。指定がない場合、以下のすべてのプロパティについて既定の値が使われます。

  • filter: string | undefined （省略可）

    取得するレコードの条件式です（WHERE）。 指定した場合、対象のテーブルから条件式を満たすレコードだけが取得できます。

    WHERE 句の条件を表すSQL式を、文字列として指定します。 条件式の記法についてはSQL 式のスクリプト上での表現を参照してください。

    このプロパティの指定は任意です。指定がない場合、すべてのレコードを取得します（WHERE 句を指定しません）。

  • sort: string | Array<string> | undefined （省略可）

    レコードの並べ替えのキーとして用いるカラム名のリストです（ORDER BY）。

    カラム名のリストは、カラム名の配列またはカンマ区切り文字列として指定します。

    特殊な記法として、カラム名の先頭に ! をつけることで、そのカラムに対して降順で並べ替えが行われます（先頭に ! がない場合、昇順で並べ替えが行われます）。

    このプロパティの指定は任意です。指定がない場合、並べ替えを行いません。

  • aggregate: function | object | undefined （省略可）

    関数または組み込みの集計関数を利用するためのオブジェクトです。

    aggregate に関数が指定された場合、取得した各レコードに対して呼び出されます。 また、指定された関数は以下の引数を受け取ります：

    • record: object
      • index 番目のレコードを表すオブジェクトです。
    • index: number
      • 取得したレコード配列の 0 始まりの添え字です。

    aggregate に指定された関数が Promise を返す場合、取得したすべてのレコードに対する呼び出しが行われた後、すべての Promise に対して待ち合わせをします。ただし、いずれかの Promise が棄却された場合、他の Promise を待たずに get() の呼び出しは失敗します。

    aggregate にオブジェクトが指定された場合、そのオブジェクトは以下のプロパティを持たなければなりません：

    • aggregate: string

      組み込みの集計関数とその引数の組です。

    • group: string | string[] | undefined （省略可）

      レコードのグループ化に使うカラム名のリストです（GROUP BY）。

      カラム名のリストには、カラム名の配列、またはカンマ区切り文字列が指定できます。 リストが空の場合、レコードはグループ化されません。

      get() の引数にプロパティ filter が指定されている場合、filter に指定した条件を満たすレコードに対してグループ化が行われます。

      このプロパティの指定は任意です。指定がない場合、レコードはグループ化されません。

    • having: string | undefined （省略可）

      グループ化されたレコードに対する条件式です（HAVING）。

      get() の引数にプロパティ filter が指定されている場合、filter に指定した条件を満たすレコードに対してグループ化が行われ、その後に having に指定した条件でグループ化されたレコードがフィルタされます。

      このプロパティの指定は任意です。指定がない場合、すべてのグループ化されたレコードを取得します。

    aggregate に指定するオブジェクトは以下の関数から生成できます：

    • $count()
      • COUNT 集計関数を使用する際に使います。
    • $sum()
      • SUM 集計関数を使用する際に使います。
    • $avg()
      • AVG 集計関数を使用する際に使います。
    • $max()
      • MAX 集計関数を使用する際に使います。
    • $min() を参照。
      • MIN 集計関数を使用する際に使います。

    このプロパティの指定は任意です。指定がない場合、集計処理は行われません。

  • aggregateAs: string | undefined （省略可）

    引数のプロパティ aggregate で指定した集計操作の結果に与える別名です。

    このプロパティは引数のプロパティ aggregate にオブジェクトを指定した場合にのみ意味を持ちます。それ以外の場合には単に無視されます。

    このプロパティの指定は任意です。指定がない場合、組み込みの集計関数の名前が使用されます。

  • final: function （省略可）

    レコード取得と集計操作が完了した後に呼ばれるコールバック関数です。

    コールバック関数には以下の引数が与えられます。

    • count: number

      取得したレコードの個数です。

    コールバック関数が Promise を返した場合、その履行を待ち合わせます。

    レコードの取得や集計操作に失敗した場合、このコールバック関数は呼び出されません。

  • limit: number （省略可）

    取得するレコード数の上限です。

    レコード数の上限として、0 以上の整数を指定できます（0, 1, 2, ...）。

    0 以上の整数以外の数値を与えた場合、以下のように動作します：

    • 無限大（Infinity / -Infinity）、非数 (NaN) または負の値を指定した場合、それは無視されます（レコード数は制限されません）。

    • 小数部が 0 でない数値を与えた場合、小数部を切り捨てた結果がレコード数の上限となります。

      特に 0 から 1 未満の値を指定した場合（0 <= limit && limit < 1）、レコードは取得されません。

    プロパティ limit は必ず sort とともに指定する必要があります。sort によりソートキーが与えられていない場合、limit は効果を持ちません（無視されます）。

    Array の最大長（32ビット符号なし整数の最大値）を超える値を指定した場合、limit の値は Array の最大長に丸められます。これは limit を指定しなかった場合と同じ結果を与えます。

    このプロパティの指定は任意です。指定がない場合、limit の値は Array の最大長（32ビット符号なし整数の最大値）として扱われます。

  • offset: number （省略可）

    取得する先頭レコードの位置です。 条件に一致したレコードのうち、先頭の offset 個のレコードは結果に含まれません。

    レコードの先頭位置として、0 以上の整数を指定できます（0, 1, 2, ...）。

    0 以上の整数以外の数値を与えた場合、以下のように動作します：

    • 無限大（Infinity / -Infinity）、非数 (NaN) 、負の値または 0 を指定した場合（offset <= 0）、それは無視されます（条件に一致した最初のレコードから取得します）。

    • 小数部が 0 でない数値を与えた場合、小数部を切り捨てた結果がレコードの先頭位置となります。

      特に 0 から 1 未満の値を指定した場合（0 <= offset && offset < 1）、条件に一致した最初のレコードから取得します。

    offset として Number.MAX_SAFE_INTEGER を超える値を指定した場合、offset の値は Number.MAX_SAFE_INTEGER に丸められます。

    offset は必ず sort とともに指定する必要があります。sort によりソートキーが与えられていない場合、offset は効果を持ちません（無視されます）。

    このプロパティの指定は任意です。指定がなかった場合、offset の値は 0 として扱われます。

sortの必要性
  • sort の指定がない限り、レコードの順序は不定です。そのため、limit および offset は sort の指定がない場合、効果を持ちません。
limit および offset の値に関する制約事項
  • limit および offset を指定に関する挙動はバックエンドのデータベースの仕様とは必ずしも一致しません。
    • 例えば SQLite において OFFSET を単独で使用することはできず、常に LIMIT <limit> OFFSET <offset> の形で使用なければなりませんが、 AlierTable から生成されるSQL文はこの制約を回避するように行われます（<limit> に有効な値が指定できない場合、JavaScript の Array クラスで扱える配列の最大長が代わりに指定されます。<offset> に関しても同様に、有効な値が指定できない場合には 0 が代わりに指定されます）。
  • limit の最大値は JavaScript の Array クラスで扱える配列の最大長に起因します。
  • offset の最大値は以下の理由により指定されます：
    • JavaScript において Number 型では 53 ビットを超える長さの整数を精確に扱えないため
    • 対向のデータベースが扱える数値型の制約に違反しないため

返値: Promise<object>

実行結果 のオブジェクトを与える Promise です。

成功時には実行結果オブジェクトのプロパティ records として、取得したレコードの配列が設定されます。

レコードはカラム名と同名のプロパティを持つオブジェクトとして与えられます。

対象が単一のテーブルである場合、レコードのプロパティ名は対象のテーブルのカラム名が使われます。 対象が複数のテーブルの結合である場合、各テーブル名またはその別名とカラム名を下線（_）でつなげた名前（tablename_columname）がプロパティ名に使われます。

また引数のプロパティ aggregate として集計用オブジェクトを与えた場合、その集計結果は引数のプロパティ aggregateAs で指定した名前か、aggregateAs が指定されていない場合、集計用オブジェクトによって実行される組み込みの集計関数の名前がレコードのプロパティ名に使われます。

解説

対象のテーブルからレコードを取得します。

使用例は実行例を参照してください。