Skip to content

App Builder の Query Builder のステップバイステップ ガイド

Query Builder 変数とコンポーネントの概要

App Builder の Query Builder コンポーネントは、次の 2 つの主要な概念に基づいて動作します:

  • ツールボックス内のクエリ変数とクエリ ビルダー コンポーネント。

クエリ変数は、現在プレビュー版環境の一部としてのみ利用可能であり、データ ソースと対話する特殊な変数であり、API リクエストを通じてデータを動的にフィルター処理することで大規模なデータセットを効率的に処理できるように設計されています。これらのリクエストは、高度な式をパラメーターとして駆動するサーバー側のフィルタリングを利用し、大量のデータを処理する際に最適なパフォーマンスを保証します。

この変数はクエリ ビルダー コンポーネントと統合され、動的なデータ管理と UI 駆動型のフィルタリングが可能になります。

クエリ変数の概念は、クエリ ビルダー コンポーネントが使用される 2 つの主な方法をカバーします。

  • クエリ ビルダー コンポーネントが、App Builder に統合され、クエリ変数エディターとして使用される場合。
  • クエリ ビルダー コンポーネントが UI 要素として機能し、ツールボックスからキャンバスに配置された際にエンドユーザーが直接操作できる場合。

ステップバイステップの紹介

手順 1. ユーザー ストーリーを定義して実装します

次のユースケースを実現してみましょう。選択したカテゴリに属し、orderDetails テーブルで指定された範囲内の数量で注文されたすべての製品を、products テーブルから取得します。

SQL の例:

SELECT * 
FROM products 
WHERE categoryId = "Beverages" 
AND productId IN (
  SELECT productId
  FROM orderDetails
  WHERE quantity >= 5
  AND quantity <= 10
)
  1. メイン クエリ (Products テーブル):

    • products テーブルからすべての列 (*) を選択します。
    • categoryId = “Beverages” の製品をフィルタリングします (Beverages カテゴリの製品のみ)。
  2. サブクエリ (OrderDetails テーブル):

    • 注文された quantity が 5 〜 10 (両端を含む) の orderDetails から productId を取得します。
    • これらの productId は、メイン クエリの IN 句で使用され、製品をフィルター処理します。

    最終出力:

結果は、5 〜 10 個の数量で注文された飲料製品のリストになります。

手順 2. クエリ変数を作成します

クエリ変数を作成しましょう。この変数は、API リクエストを通じてデータを動的にフィルタリングすることで、大規模なデータセットを処理するために使用されます。

  1. 新しい変数を作成します。

  2. データ API リクエストから初期化することを選択します。

  3. 新しく追加されたクエリ ビルダー エンドポイントを選択します。App Builder のテスト OpenAPI は、サーバー側のフィルタリングをサポートするようになりました。

  4. 「query」 エンドポイントを検索し、ExecuteQuery.products を選択します。これは、複雑なクエリの例の基本テーブルとして機能します。

    🖼️ Query Builder エンドポイントの選択を表示

    エンドポイントの選択


    結果:

手順 3.クエリ変数を設定します

まず、[クエリの編集] パネルを開きます。

2 つのテーブルで機能する複雑なクエリを構築します。

  • products – データが取得されるメイン テーブル。
  • orderDetails – 範囲内の数量に基づいて製品をフィルタリングするためにサブクエリで使用されます。

💡 注: 値をハードコーディングする代わりに、各条件を変数にバインドし、アプリのコンポーネントを通じてユーザーが動的に更新できるようにします。

選択したカテゴリで製品をフィルタリングします:

  • クエリ条件を設定するために WHERE 句の構築を開始します。
  • Select コンポーネントで使用される、デフォルト値が 1 の数値変数を作成します。
🖼️ カテゴリ フィルターの設定を表示n

カテゴリ フィルターの設定を表示


指定された範囲内の数量の注文の製品 ID を取得するための条件を設定します。

  • デフォルト値が 10 と 15 である 2 つの数値変数 (quantityGreaterThan、quantityLessThan) を作成します。
  • これらは Input コンポーネントによって制御されます。
🖼️ 最小数量構成を表示

最小数量構成を表示


🖼️ 最大数量設定を表示

最大数量設定を表示


💡 注: ハードコードされた値も使用できますが、このデモでは、動的フィルタリングに変数を使用します。

手順 4.クエリを適用して保存します

  1. [保存] をクリックして、複雑なクエリ変数の設定を保存します。

  2. [SEND] ボタンを使用してクエリの実行をテストします。

    クエリ実行テストを表示


    この時点で、4 つの変数があります。

    • ComplexQuery → サーバー側のフィルタリングを処理するクエリ変数。
    • selectedCategory → カテゴリ ID を保持します。
    • quantityGreaterThan → 最小数量を定義します。
    • quantityLessThan → 最大数量を定義します。

手順 5.インタラクティブなコンポーネントを追加します

これらの変数は、サンプル アプリ内のコンポーネントにバインドされます。

  • カテゴリ選択の Select コンポーネント。
  • 数量の範囲を指定するための 2 つの Input コンポーネント。

Select コンポーネントと 2 つの Input コンポーネントを追加し、それらを手順 3 で作成した変数にバインドします。

🖼️ コンポーネントの追加を表示

コンポーネントの追加を表示


バインドします:

Select コンポーネント: Select コンポーネントにフォーカスし、[Select item] をクリックします。Northwind データ ソースの Category テーブルを使用して、これにデータ リピーターを適用します。

🖼️ データ リピーターの設定を表示

データ リピーターの設定を表示


Select item 要素の Content と Value を Category -> Name と CategoryID にバインドします。

🖼️ Select item のバインディングを表示

Select item のバインディングを表示


Select コンポーネントにフォーカスし、selectedCategory 変数にバインドします。

🖼️ Select コンポーネントのバインディングを表示

Select コンポーネントのバインディングを表示


quantityGreaterThan の Input コンポーネント:

🖼️ 最小数量入力バインディングを表示

最小数量入力バインディングを表示


quantityLessThan Input コンポーネント:

🖼️ 最大数量入力バインディングを表示

最大数量入力バインディングを表示


  1. Value プロパティの双方向バインディングが有効になっていることを確認してください。
  2. Grid コンポーネントを追加し、手順 2 で作成したクエリ変数にバインドします。
🖼️ Grid コンポーネントのバインディングを表示

Grid コンポーネントのバインディングを表示


結果:

インタラクティブなコンポーネントの結果を表示

手順 6.特定の数量で注文された商品を表示します

これまでのところ、クエリは、Dairy Products カテゴリに属し、数量が 5 から 7 の間で注文されたすべての製品を返します。

🖼️ 最初のクエリ結果を表示

最初のクエリ結果を表示


ただし、クエリは products テーブルからのみデータを取得するため、実際の注文数量は表示されません。結果を検証するには、対応する注文数量が表示されるように UI を変更する必要があります。

手順 7.グリッド行選択を使用して製品ごとの注文数量を表示

  1. グリッドの行選択変更インタラクションを追加し、それに変数をバインドします。

    🖼️ グリッドの行選択インタラクションを表示

    グリッドの行選択インタラクションを表示


  2. 変数が ProductDTO タイプであることを確認してください。

    🖼️ 変数タイプの設定を表示

    変数タイプの設定を表示


  3. 関連データを表示するには、Dialog とその中に Grid を追加します。

    🖼️ ダイアログとグリッドの設定を表示

    ダイアログとグリッドの設定を表示


  4. 特定のカテゴリ内の製品の order details を取得する別のクエリ変数を構成します。

    クエリの例:

    SELECT * 
    FROM orderDetails 
    WHERE productId IN (
        SELECT productId 
        FROM products 
        WHERE categoryId = 1
    )
    AND Quantity BETWEEN 5 AND 15;
    

    結果:

    orderDetails クエリ結果を表示

  5. Grid コンポーネントを OrdersComplexQuery 変数にバインドします。

    🖼️ orderDetails にグリッド バインディングを表示

    orderDetails にグリッド バインディングを表示


手順 8.アプリをプレビューします。

  • [プレビュー] をクリックします。
  • Input コンポーネントを使用してクエリ結果を動的に調整します。
  • ユース ケースの例:
    • Confections カテゴリーを検索します。
    • Quantity を 4 ~ 8 の間で設定します。

🖼️ Confections の例でアプリのプレビューを表示

Confections の例でアプリのプレビューを表示

手順 9.クエリ ビルダーを使用してリアルタイムでクエリを変更します

この手順では、クエリをリアルタイムで変更する方法を示します。数量範囲内で注文をフィルタリングする代わりに、特定の数量以上になるように変更します。

  1. ツールボックスから Query Builder コンポーネントをドラッグアンドドロップします
🖼️ Query Builder コンポーネントの追加を表示

Query Builder コンポーネントの追加を表示


  1. それを先ほど作成した複雑なクエリ変数にバインドします。

  2. これで、クエリ コンポーネントはクエリ変数にバインドされ、データ リクエストを動的に処理するようになりました。

🖼️ Query Builder のバインディング結果を表示

Query Builder のバインディング結果を表示


クエリを編集する前 - クエリは数量が 5 ~ 11 のすべての Confections を返します。

編集前のクエリ結果を表示


クエリを編集した後の結果: - 2 番目の条件を削除して、Quantity が 10 以上の注文を返すように WHERE 句を変更します。

編集後にクエリ結果を表示

FAQ

  1. Query Builder はなぜ OData を使用しないのですか? OData はサブクエリをサポートしていませんが、Query Builder は主に条件ツリーを構築しますが、一部の式は OData 互換のフィルターにマップされる場合があります。ただし、OData の制限により、完全なサポートは保証されません。

Query Builder は、フィルタリング ロジックを直接制御できるようにすることで柔軟性を高め、OData がネイティブにサポートしていないサブクエリなどの複雑なシナリオをより適切にサポートできるようにします。

既知の問題と制限

  • コード生成なし - クエリ変数またはクエリ ビルダーを使用してアプリケーションをコード生成しようとすると、「コンポーネントはサポートされていません」というメッセージが表示されます。
  • プレビュー版環境のクエリ コンポーネント - 条件を完全に制御できますが、バインディングは失われ、現在の値 (5 と 10) が取得されます。変数の初期状態に戻す場合は、コンポーネントを再度追加して最初からやり直す必要があります。
  • リクエストを実行する際に特定のフィールドを設定することは許可されていません。他のコンポーネントにこれを知らせるメカニズムがないため、常にすべてのフィールドが取得され、不整合が発生します。
  • Query Builder の返却フィールドは無効です - フィールドのサブセットを選択するとデータ的には機能しますが、App Builder は動的な構造をサポートしていないため、クエリ ビルダーの返却フィールドの変更を無効にする必要があります。その結果、グリッドをインスタンス化するときに、すべての列が利用可能であると想定されます。
  • 問題や不一致が発生した場合は、ページを更新してください (F5)。

横断的な機能のサポート

  • リピーターのサポート: 使用できません。
  • コピー/貼り付け:
    • 同じビュー内: 使用できます。
    • 異なるビュー間: リンクされたクエリ変数を取得する必要がありますか?
  • バインド可能なプロパティ: 変数バインディングをサポートするのは 「Query」 プロパティのみです。

サーバー側の大文字と小文字の区別

  • 独自のデータ サーバーを実装する場合は、大文字と小文字を区別するフィールド名を構成しないことを検討してください。

その他のリソース