すべてのプロダクト
Search

このプロダクト

    :組み込み TVF

    ドキュメントセンター

    :組み込み TVF

    最終更新日:Mar 04, 2025

    rankTvf

    rankTvf は、SQL 文の rank ウィンドウ関数に似ています。この関数は、データが分散された後にデータをフィルタリングするために使用されます。次のサンプルコードは、関数のプロトタイプを示しています。

    rankTvf("group_key", "sort_key", "reserved_count", (sql))

    group_key: データの分散に使用するフィールド。複数のフィールドを指定することも、パラメーターを空のままにすることもできます。複数のフィールドはコンマ (,) で区切ります。

    sort_key: データのソートに使用するフィールド。複数のフィールドを指定できます。プラス記号 (+) は、システムがデータを昇順でソートすることを指定します。マイナス記号 (-) は、システムがデータを降順でソートすることを指定します。デフォルトでは、システムはデータを昇順でソートします。このフィールドを空にすることはできません。

    reserved_count: 各グループで保持する返されるレコードの数。負の数は、返されるすべてのレコードが各グループで保持されることを指定します。

    sql: クエリ結果を分散する必要がある SQL 文。

    rankTvf を使用して SQL 文の結果を分散およびフィルタリングした後も、出力結果は SQL 文の元の結果がソートされた順序でソートされます。フィルタリングされた行は出力結果から削除されます。

    例:

    select * from table (
  rankTvf('brand','-size','1', (SELECT brand, size FROM phone))
) 
order by brand 
limit 100

    sortTvf

    sortTvf は、ローカルのトップ K 機能を提供するために使用されます。たとえば、sortTvf 関数を使用して、サーチャーによって返された上位 K 個の結果をソートし、その結果に対して結合操作を実行できます。ORDER BY 句を使用する場合、句は結合操作のためにクエリレコードサーチャー (QRS) にプッシュされます。ORDER BY 句は、グローバルソート操作に使用されます。

    次のサンプルコードは、関数のプロトタイプを示しています。

    sortTvf("sort_key", "reserved_count", (sql))

    sort_key: データのソートに使用するフィールド。複数のフィールドを指定できます。プラス記号 (+) は、システムがデータを昇順でソートすることを指定します。マイナス記号 (-) は、システムがデータを降順でソートすることを指定します。デフォルトでは、システムはデータを昇順でソートします。このフィールドを空にすることはできません。

    reserved_count: 各グループで保持されるフィールドの数。

    sql: クエリ結果をソートする必要がある SQL 文。

    sortTvf と rankTvf の違い: sortTvf は、テーブル内の SQL 文の元の結果の行の順序を変更します。

    例:

    select * from table (
  sortTvf('-size','3', (SELECT brand, size FROM phone))
)

    unpackMultiValue

    unpackMultiValue 関数は、複数値フィールドを展開するために使用されます。この関数は、GROUP BY 句に複数値フィールドが含まれており、複数値フィールドのグループベースの結果を展開する場合に使用されます。

    次のサンプルコードは、関数のプロトタイプを示しています。

    unpackMultiValue("unpack_keys", (sql))

    unpack_keys: 展開するフィールドの名前。複数のフィールドを指定できます。複数のフィールドはコンマ (,) で区切ります。

    sql: クエリ結果を展開する必要がある SQL 文。

    使用上の注意:

    1. 展開された複数値フィールドの型は変更されません。展開された各複数値フィールドには 1 つの値のみが含まれるか、展開されたフィールドは空になります。

    2. 少数の複数値フィールドを展開することをお勧めします。多数の複数値フィールドを展開すると、フィールド間のデカルト積の関係により、システムが過負荷になる可能性があります。

    例:

    select * from table (
  unpackMultiValue('desc,price,size', (SELECT desc, price, size FROM phone where size > 5.5))
)

    graphSearchTvf

    graphSearchTvf 関数は、サーチャーと同じプロセスでテーブル値関数 (TVF) に基づくディープラーニングモデルを使用します。このモデルは、ドキュメントのスコアリングに使用されます。次のサンプルコードは、関数のプロトタイプを示しています。

    graphSearchTvf("biz_name", "pk_name", "qinfo_kv", (sql))

    biz_name: スコアリングモデルが属する biz 構成の名前。biz 構成は、SQL 文を実行するサーチャーと同じプロセスにある必要があります。

    pk_name: スコアリングモデルのプライマリキーの名前。入力テーブルのフィールドをプライマリキーとして指定できます。

    qinfo_kv: qinfo プロトコルに準拠して指定されたキーと値のペア。

    sql: 詳細なスコアリングが必要な SQL 文。

    graphSearchTvf 関数を実行した後も、出力結果は SQL 文の元の結果がソートされた順序でソートされます。スコアリング結果を格納するために、FLOAT 型の __buildin_score__ フィールドが追加されます。

    例:

    select * from table (
  graphSearchTvf('model','store_id','fg_encode:abc', (SELECT brand, size FROM phone))
) 
order by __buildin_score__ 
limit 100

    enableShuffleTvf

    enableShuffleTvf 関数は、SQL 文を TVF から QRS に切り替えるために使用されます。たとえば、rankTvf 関数で処理する必要がある SQL 文は、デフォルトでサーチャーにプッシュダウンできます。rankTvf 関数の SQL 文に enableShuffleTvf が含まれている場合、rankTvf 関数は QRS 上でのみ実行されます。次のサンプルコードは、関数のプロトタイプを示しています。

    enableShuffleTvf((sql))

    次のサンプルコードは、enableShuffleTvf 関数の使用方法の例を示しています。

    select * from table (
 enableShuffleTvf((SELECT brand, size FROM phone))
)

    inputTableTvf

    InputTableTvf 関数は、複数の行のデータを構築するために使用されます。ほとんどの場合、この関数は論理テーブルで使用されます。次のサンプルコードは、関数のプロトタイプを示しています。

    inputTableTvf('data', (sql))

    data は複数の行のデータを記述します。複数の行はセミコロン (;) で区切ります。行内の複数の列はコンマ (,) で区切ります。例: 100,0.1;200,0.2.

    sql: 構築されたデータのスキーマを指定します。たとえば、sql パラメーターの応答でテーブルの最初の列が INT64 型で、テーブルの 2 番目の列が FLOAT 型の場合、データはこのスキーマに基づいて解析されます。

    distinctTopNTvf

    distinctTopNTvf 関数は、データの分散とソートに使用されます。次のサンプルコードは、関数のプロトタイプを示しています。

    distinctTopNTvf('distinct_fields', 'sort_fields', 'topn', 'distinct_count', 'searcher_topn', 'searcher_distinct_count', (sql))

    distinct_fields 関数は、フィールドを分散するために使用されます。複数のフィールドを指定することも、パラメーターを空のままにすることもできます。複数のフィールドはコンマ (,) で区切ります。

    sort_fields: データのソートに使用するフィールド。複数のフィールドを指定できます。プラス記号 (+) は、システムがデータを昇順でソートすることを指定します。マイナス記号 (-) は、システムがデータを降順でソートすることを指定します。デフォルトでは、システムはデータを昇順でソートします。このフィールドを空にすることはできません。

    topn: 保持される返されるレコードの総数。

    distinct_count: 各分散グループに予約されているフィールドの数。

    searcher_topn: サーチャーの各列に予約されている返されるレコードの総数。

    searcher_distinct_count: サーチャーの各列の各分散グループに予約されているフィールドの数。

    計算プロセス:

    1. sort_fields パラメーターを使用してデータをソートします。

    2. 各行を走査します。

      distinct_fields を使用してグループを計算します。グループの数が distinct_count で指定された値よりも小さい場合、行は出力キューに入れられ、グループの数に 1 を加えたものがグループの総数になります。グループの数が distinct_count パラメーターの値以上の場合、行は待機キューに入れられます。

    3. 出力キューの行数が topn 以上の場合、出力キューからいくつかの行が返されます。次のパラメーターは、返される行数を指定します: topn。

      出力キューの行数が n で、n が topn パラメーターの値よりも小さい場合、待機キューからいくつかの行が必要な順序で出力キューにマージされます。待機キューから取得される行数は、次の式を使用して計算されます: topn パラメーターの値 - n。次に、マージされた行が返されます。

    OneSummaryTvf

    OneSummaryTvf 関数は、1 つのサマリープラグインチェーンを実行するために使用されます。この関数は、HA3 プラグインプラットフォームの 1 つのサマリープラグインの元のロジックと互換性があります。

    "sql_tvf_plugin_config" : {
        "modules" : [
            {
                "module_name": "tvf",
                "module_path": "libPluginOnline.so",
                "parameters": {}
            }
        ],
        "tvf_profiles" : [
            {
                "func_name": "OneSummaryTvf",
                "tvf_name": "tpp",                                          // TVF 名。
                "parameters": {
                    "config_path" : "pluginsConf/one_summary.json",         // 1 つのサマリープラグインの構成。
                    "schema_path" : "schemas/mainse_summary_schema.json",   // サマリースキーマの構成。
                    "chain" : "tpp_default"                                 // TVF のサマリーチェーン。
                }
            }
        ]
    }

    OneSummaryTvf 関数を使用して、複数の TVF プロトタイプを構成できます。各プロトタイプは、1 つのサマリープラグインチェーンを表します。

    tpp(
    'dl:tpp_default',                                      // kvpair                                
    '',                                                    // クエリ句。ほとんどの場合、クエリ句は必要ありません。
    (                                                      // sql
        SELECT
            *
        FROM
            mainse_summary_summary_
        WHERE
            ha_in(nid, '620598126603|619969492623')
    )
)

    ヒント

    デフォルトでは、サマリープラグインは元の入力フィールドのみを処理します。フィールドを追加する場合は、追加フィールドに関する情報を iquan に登録します。追加フィールドに関する情報は、サマリープラグインの collectOutputInfo インターフェースを使用して登録できます。情報を登録しないと、追加フィールドの結果は提供されません。

    typedef std::vector<std::pair<std::string, std::string>> SummaryOutputInfoType;
virtual SummaryOutputInfoType collectOutputInfo();

// 例:
SummaryOutputInfoType PostFeeSummaryExtractor::collectOutputInfo() {
    if (_dstSummaryField.empty()) {
        return {};
    }
    return {make_pair(_dstSummaryField, "string")};    // [(フィールド名, 型)]
}

    rerankByQuotaTvf

    rerankByQuotaTvf('group_fields',
                 'actual_group_field_values',
                 'quota_num',
                 'rerank_fields',
                 'sort_fields',
                 'per_rerank_field_max_num',
                 'window_size',
                 'need_makeup',
                 (sql)
                )

    • group_fields

      データをグループ化する基準となるフィールド。複数の列を指定できます。複数の列はセミコロン (;) で区切ります。

    • actual_group_field_values

      group_fields パラメーターのすべての列挙値。group_fields パラメーターの値が単一の列である場合、すべての列挙値をセミコロン (;) で区切ります。group_fields パラメーターの値が複数の列で構成されている場合、すべての列挙値のグループをセミコロン (;) で区切ります。列挙値の各グループでは、複数の列の値をコンマ (,) で区切ります。

    • quota_num

      各グループのクォータ。このパラメーターは、グループの 2 つのフェーズのクォータを指定します。たとえば、最初のフェーズではサーチャーで最大 10 個のデータエントリを返すことができ、2 番目のフェーズでは最大 20 個のデータエントリを返すことができます。この場合、このグループのパラメーター値は (10,20) です。グループの 2 つのフェーズのクォータはコンマ (,) で区切ります。このパラメーターを指定するグループの数は、actual_group_field_values パラメーターで指定されたグループ数と同じである必要があります。このパラメーターを指定するグループの数が actual_group_field_values パラメーターの値よりも小さい場合、最後に指定したグループのクォータが、quota_num パラメーターを指定していない追加グループのデフォルトクォータとして機能します。このパラメーターを指定するグループの数が actual_group_field_values パラメーターの値よりも大きい場合、システムはエラーを報告します。

    • rerank_fields

      分散するフィールド。複数の列を指定できます。複数の列はセミコロン (;) で区切ります。フィールドを分散したくない場合は、このフィールドを空のままにします。

    • sort_fields

      データのソートに使用するフィールド。+field0;-field1;field2 など、複数の列を指定できます。+ は、データが昇順でソートされることを指定します。- は、データが降順でソートされることを指定します。デフォルトでは、データは昇順でソートされます。

    • per_rerank_field_max_num

      グループの各カテゴリで返される結果の最大数。データを分散する場合に、このパラメーターを使用できます。

    • window_size

      グループ間でデータを不均一に分散するために使用されるウィンドウ。データを不均一に分散する場合に、このパラメーターを使用できます。

    • need_makeup

      クォータに到達するために結果を補足するかどうかを指定します。t は結果が補足されることを指定します。f は結果が補足されないことを指定します。このパラメーターは、t;f など、2 つのフェーズの補足選択肢を指定します。2 つのフェーズの補足選択肢はセミコロン (;) で区切られます。

    使用上の注意: 異なるグループのフィールドはセミコロン (;) で区切ります。フィールドは複数値フィールドにすることができます。複数の列挙された複数値フィールドは番号記号 (#) で区切ります。

    手順

    1. システムは、グループ化フィールドの列挙値に基づいて input_hash を計算します。

    2. システムはテーブル内のデータを走査し、すべてのデータのハッシュ値を計算し、ハッシュ値を input_hash パラメーターの値と照合します。この場合、列挙されたグループデータに対応するグループが取得されます。

    3. システムは、手順 2 で取得された複数のグループを分散します。

      1. rerank_fields パラメーターに基づいて、グループを分散する必要があるかどうかを判断します。rerank_fields パラメーターを空のままにした場合、グループを分散する必要はありません。この場合、per_rerank_field_max_num パラメーターと window_size パラメーターを 0 に設定できます。

      2. グループを分散する場合は、次の手順を実行します。

        1. rerank_fields パラメーターで指定された値に基づいてデータをグループ化します。

        2. sort_fields パラメーターの値に基づいて、グループ内のデータをソートします。

        3. グループは、window_size パラメーターに基づいて優先的にソートされます。window_size パラメーターは、グループのウィンドウサイズを指定します。グループ内のデータは数回抽出されます。

        4. グループから抽出されたデータが per_rerank_field_max_num パラメーターの値に達すると、システムはグループからのデータの抽出を停止します。すべてのグループから抽出されたデータの量が上限に達すると、システムはすべてのグループからのデータの抽出を停止します。

        5. システムがすべてのグループからのデータの抽出を停止した後、2 つのデータセットを取得できます。1 つのデータセットはユーザーのすべてのルールを満たしています。もう 1 つのデータセットはバックアップセットです。

      3. グループを分散したくない場合は、次の手順を実行します。

        1. sort_fields パラメーターの値に基づいて、グループ内のデータをソートします。

        2. システムは、クォータに基づいてすべてのグループのデータをフィルタリングします。2 つのデータセットを取得できます。1 つのデータセットは指定されたクォータに達しています。もう 1 つのデータセットはバックアップセットです。

    4. クォータに到達するために結果を補足するかどうかを指定します。結果を補足する場合は、バックアップセットのデータを結果に追加します。結果を補足する必要がない場合は、バックアップデータセットを破棄します。データの補足に使用されるポリシーは、actual_group_field_values パラメーターの列挙値におけるグループの順序によって異なります。順序番号が小さいほど、データの補足の優先順位が高くなります。

    例

    rerankByQuotaTvf('trigger_type',
                 '1;11',
                 '100,200;100,300',
                 'ju_category_id',
                 '-final_score',
                 '50',
                 '15',
                 't;t',
                 (sql)
                )

    simpleRerankTvf

    simpleRerankTvf('group_fields',
                'actual_group_field_values',
                'quota_num',
                'sort_fields',
                'need_makeup',
                (sql)
               )

    • group_fields

      データをグループ化する基準となるフィールド。複数の列を指定できます。複数の列はセミコロン (;) で区切ります。

    • actual_group_field_values

      group_fields パラメーターのすべての列挙値。group_fields パラメーターの値が単一の列である場合、異なるグループのすべての列挙値をセミコロン (;) で区切ります。group_fields パラメーターの値が複数の列で構成されている場合、異なるグループの列挙値をセミコロン (;) で区切ります。グループの複数の列の列挙値はコンマ (,) で区切ります。

    • quota_num

      各グループのクォータ。

    • sort_fields

      データのソートに使用するフィールド。+field0;-field1;field2 など、複数の列を指定できます。+ は、データが昇順でソートされることを指定します。- は、データが降順でソートされることを指定します。デフォルトでは、データは昇順でソートされます。このパラメーターを空のままにした場合、データはソートされません。

    • need_makeup

      クォータに到達するために結果を補足するかどうかを指定します。t は結果を補足する必要があることを指定します。f は結果を補足する必要がないことを指定します。このパラメーターは、2 つのフェーズのクォータを指定します。

    手順

    1. システムは、グループ化フィールドの列挙値に基づいて input_hash を計算します。

    2. システムはテーブル内のデータを走査し、すべてのデータのハッシュ値を計算し、ハッシュ値を input_hash パラメーターの値と照合します。この場合、列挙されたグループデータに対応するグループが取得されます。

    3. システムは、手順 2 で取得されたグループのデータの分散と補足を行います。

      1. システムは、sort_fields パラメーターの値に基づいて、グループ内のデータをソートします。sort_fields パラメーターを空のままにした場合、データはソートされません。

      2. システムは、クォータに基づいてすべてのグループのデータをフィルタリングします。2 つのデータセットを取得できます。1 つのデータセットは指定されたクォータに達しています。もう 1 つのデータセットはバックアップセットです。

    4. クォータに到達するために結果を補足するかどうかを指定します。結果を補足する場合は、バックアップセットのデータを結果に追加します。結果を補足する必要がない場合は、バックアップセットのデータを破棄します。データの補足に使用されるポリシーは、actual_group_field_values パラメーターの列挙値におけるグループの順序によって異なります。順序番号が小さいほど、データの補足の優先順位が高くなります。

    例

    simpleRerankTvf('trigger_type',
                '1;11',
                '100',
                '-final_score',
                't',
                (sql)
               )

    使用上の注意

    1. SELECT 文を実行して TVF の結果をクエリする場合、FROM 句に table (xxxTvf()) を含めます。

    2. TVF 内の SQL 文は括弧 () で囲む必要があります。一度に実行できる SQL 文は 1 つだけです。たとえば、sql1 union all sql2 ではエラーが報告されます。この問題を解決するには、文を select * from (sql1 union all sql2) に変更します。

    3. TVF は STRING 型のパラメーターのみをサポートします。