GraphQL 用 API の集計

GraphQL 集計を使用して、Microsoft Fabric データを実用的な分析情報に変換します。何千もの個々のレコードを取得してアプリケーションで処理する代わりに、Fabric にデータをグループ化し、サーバー側の概要を計算するように依頼できます。これにより、パフォーマンスが大幅に向上し、データ転送が削減されます。

GraphQL 集計は SQL GROUP BY 操作と同様に機能しますが、GraphQL API を使用します。カテゴリごとにアイテムをカウントしたり、収益合計を計算したり、平均評価を見つけたり、lakehouse テーブルと Warehouse テーブル全体の最小値/最大値を決定したりできます。すべて、1 つの効率的なクエリで行うことができます。

主な利点:

サーバー側の処理: 計算に Fabric の最適化されたクエリエンジンを活用する
データ転送の削減: 生レコードの代わりに概要を取得する
1 つのクエリ効率: 複数のクライアント側操作を 1 つの集計に置き換える

このガイドでは、基本的なグループ化から高度な関数、重要な制限事項まで、実用的な e コマースの例を使用して集計クエリを作成する方法について説明します。

集計を使用すべき人

GraphQL 集計は、次の場合に価値があります。

要約された Fabric データを必要とするカスタムダッシュボードと分析アプリケーションを構築するアプリケーション開発者
データエンジニアは、Fabric LakehouseおよびWarehouseから事前計算済みのメトリックやKPIを提供するデータAPIを作成します。
集計された Fabric データで Power BI を補完するカスタム分析ソリューションを構築する BI 開発者
Fabric の概要統計を必要とするアプリケーションとワークフローを作成する統合開発者
データアナリストは、Fabric データからグループ化された集計インサイトを必要とするセルフサービス分析ソリューションを構築します。

グラフの表示、合計の計算、レポートの生成、傾向の分析のためにデータを取得する場合、集計によってアプリケーションのパフォーマンスが大幅に向上し、データ転送が減少する可能性があります。

回答できる一般的なビジネス上の質問

GraphQL 集計は、Fabric データに関する分析的な質問に回答する場合に優れています。

カウントとグループ化: "各カテゴリに含まれる製品の数" または "1 か月あたりの注文数?"
財務計算: "リージョン別の総収益は何ですか?" または "顧客セグメント別の平均注文金額?"
パフォーマンスメトリック: "各カテゴリで最も高く評価されている製品と最も低い製品は何ですか?
顧客の分析情報: "今月訪問したユニークな顧客の数" または "最もアクティブなユーザーが最も多い都市はどれですか?

これらのクエリは、個々のレコードではなく集計データが必要なダッシュボードの構築、レポートの生成、分析アプリケーションの強化に最適です。

[前提条件]

GraphQL 集計を使用する前に、次のことを確認してください。

適切なアクセス許可を持つ Microsoft Fabric ワークスペース
集計したいデータを格納したテーブルを備えたレイクハウスまたはウェアハウス
Fabric 項目用に構成された GraphQL エンドポイント用の API
GraphQL クエリ構文に関する基本的な知識

これらのクエリを実行する場所

クイックスタート: Fabric ワークスペースの GraphQL エディター用 API を使用して、この記事のすべての例をテストします。エディターでは、スキーマの探索、クエリの検証、および即時の結果が提供されます。

アプリケーションの場合: プログラミング言語用の任意の GraphQL クライアントライブラリを使用して、GraphQL エンドポイントに HTTP POST 要求としてクエリを送信します。

開発用: GraphQL プレイグラウンド、不眠症、Postman などのツールは、クエリの開発とテストに適しています。

注

この記事の例では、GraphQL エンドポイント用の API を構成したら、コピーして実行する準備ができています。簡潔にするためにいくつかの例が短縮されており、特定のスキーマに適応が必要な場合があります。

シナリオ例: Fabric の E コマースデータ

このガイドでは、Microsoft Fabric のレイクハウスまたはウェアハウスに格納されている架空の e コマースデータセットを使用します。このシナリオでは、GraphQL 集計を使用して小売データを分析する方法を示します。

この例では、製品データはカテゴリに属し、各 Product には価格や評価 (集計に最適な数値) などのフィールドと、 Categoryとの関係が含まれています。 Fabric の GraphQL 用 API を使用してこれらのテーブルを公開すると、生成されるスキーマは次のようになります。

type Category {
  id: ID!
  name: String!
  products: [Product!]!  # one-to-many relationship
}

type Product {
  id: Int!
  name: String!
  price: Float!
  rating: Int!
  category_id: Int!
  category: Category!  # many-to-one relationship
}

type ProductResult { # automatically generated, adding groupBy capabilities
  items: [Product!]!
  endCursor: String
  hasNextPage: Boolean!
  groupBy(fields: [ProductScalarFields!]): [ProductGroupBy!]!
}

type Query {
  products(
    first: Int
    after: String
    filter: ProductFilterInput
    orderBy: ProductOrderByInput
  ): ProductResult!
}

この例では、 products クエリは、通常のアイテムの一覧を返すか、 groupBy を使用する場合は集計結果を返すことができます。このクエリの groupBy 機能と集計機能の使用に焦点を当ててみましょう。

注

通常の項目とグループ化された結果の両方を同じクエリで取得することはできません。詳細については、「集計と未加工アイテムは相互に排他的である」を参照してください。

使用可能な集計関数

使用できる関数は実装によって異なりますが、一般的な集計操作は次のとおりです。

count – グループ内のレコードの数 (またはフィールドの null 以外の値)。
sum – 数値フィールド内のすべての値の合計。
avg – 数値フィールドの値の平均 (平均)。
min – フィールドの最小値。
max – フィールドの最大値。

GraphQL 集計では、 count(field: id)、 sum(field: price)などの例に示すように、関数名とターゲットフィールドを指定します。各関数は、適用された 1 つ以上のフィールドを選択できるオブジェクトを返します。

注

Microsoft Fabric の GraphQL 用 API では、現在、 count、 sum、 avg、 min、 max などの集計操作は、数値フィールドまたは定量的フィールド (整数、浮動小数点数) でのみ機能します。テキストフィールドまたは日付フィールドで直接使用することはできません。たとえば、文字列フィールドの "average" を計算することはできません。他のデータ型 (テキストの連結や辞書式の最小/最大など) に対する集計の実行のサポートは、Fabric の今後の更新で追加される可能性があります。

集計クエリの基本

Fabric の GraphQL API で集計を実行するには、クエリで groupBy 引数を指定して、データをグループ化する方法を定義し、結果の集計フィールド (カウントや合計など) を要求します。 Fabric の GraphQL エンジンは、基になる Lakehouse テーブルまたはウェアハウステーブルに対してこれらのクエリを効率的に処理し、キー値と計算された集計メトリックを含むグループ化されたレコードの一覧を返します。

例 1: カテゴリごとの製品数

カテゴリ別に製品をグループ化し、各グループに含まれる製品の数をカウントしてみましょう。クエリは次のようになります。

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id # grouped key values
      }
      aggregations {
        count(field: id) # count of products in each group (count of "id")
     } 
   }
  }
}

このクエリの場合:

groupBy(fields: [category_id]) は、 category_id フィールドで製品をグループ化するように Fabric GraphQL エンジンに指示します。
結果の選択では、group フィールドにcountとid集計を要求します。 idカウントすると、そのグループ内の製品が効果的にカウントされます。

結果は次のようになります。 応答内の各項目は、1 つのカテゴリグループを表します。 groupBy オブジェクトには、グループ化キーが含まれています。ここには category_id 値が含まれており、 count { id } はそのカテゴリ内の製品の数を示します。

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2
          }
        },
        // Sample shortened for brevity
      ]
    }
  }
}

この出力は、カテゴリ 1 に 3 つの製品があり、カテゴリ 2 に 2 があることを示しています。

例 2: 合計と平均

1 つのクエリで複数の集計メトリックを要求できます。カテゴリごとに、すべての製品の合計価格と平均評価が必要だとします。

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        count(field: id)   # number of products in the category
        sum(field: price)  # sum of all product prices in the category
        avg(field: rating) # average rating of products in the category
     } 
   }
  }
}

このクエリでは、次の結果が返されます。

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3,
            "sum": 2058.98,
            "avg": 4
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2,
            "sum": 109.94,
            "avg": 4
          }
        },
        ...
      ]
    }
  }
}

各グループオブジェクトには、カテゴリと計算された集計 (製品の数、価格の合計、そのカテゴリの平均評価など) が含まれます。

例 3: 複数のフィールドでグループ化する

複数のフィールドでグループ化して、複数レベルのグループ化を取得できます。たとえば、製品に rating フィールドがある場合は、 category_id と rating の両方でグループ化し、グループの平均 price を計算できます。

query {
  products {
   groupBy(fields: [category_id, rating])
   {
      fields {
         category_id
         rating
      }
     aggregations {
        avg(field: price)
     }
   }
  }
}

これにより、次に示すように、カテゴリと評価の固有の組み合わせによって製品がグループ化されます。

 {
    "fields": {
        "category_id": 10,
        "rating": 4
    },
    "aggregations": {
        "avg": 6.99
    }
}

データ内のカテゴリと評価のペアごとに、次の処理を行います。

ヒント

複数のフィールドでグループ化する場合、明示的な並べ替えは、予測可能な結果にとって特に重要になります。「グループ化された結果の並べ替えには明示的な順序が必要です」を参照してください。

例 4: 個別の使用

集計機能では、一意の値をカウントまたは考慮するための個別の修飾子がサポートされています。たとえば、製品コレクションに存在する個別のカテゴリの数を調べるには、個別の数を使用できます。

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        count(field: id, distinct: true) 
     } 
   }
  }
}

このクエリは、各カテゴリの一意の製品の数を含む結果を返します。結果は次のようになります。

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2
          }
        },
        ...
      ]
    }
  }
}

ヒント

個別の集計を適切に使用するタイミングと方法の詳細については、「個別の集計を適切に使用する」を参照してください。

例 5: エイリアスの使用

集計のエイリアスを作成して、集計結果のわかりやすい名前を提供できます。たとえば、前の例の集計には、個別の製品カテゴリをカウントして結果をより深く理解するため、 distinctProductCategoryCount として名前を付けることができます。

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        distinctProductCategoryCount: count(field: id, distinct: true) 
     } 
   }
  }
}

結果は似ていますが、カスタムエイリアスの方が意味があります。

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "distinctProductCategoryCount": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "distinctProductCategoryCount": 2
          }
        },
        ...
      ]
    }
  }
}

例 6: `having` 句の使用

集計された結果を having 句でフィルター処理できます。たとえば、前の例を変更して、2 より大きい結果のみを返すことができます。

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        distinctProductCategoryCount: count(field: id, distinct: true, having:  {
           gt: 2
        }) 
     } 
   }
  }
}

結果は、2 つ以上の製品を含む唯一のカテゴリを持つ 1 つの値を返します。

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "distinctProductCategoryCount": 3
          }
        }
      ]
    }
  }
}

制限事項とベストプラクティス

Microsoft Fabric の GraphQL 用 API で集計を使用する場合は、考慮すべき重要な規則と制限事項があります。これらのベストプラクティスに従い、これらの制限を理解することで、強力な分析情報を生成する効果的な GraphQL 集計クエリを作成できます。また、特に大規模なデータセットを操作する場合や改ページ位置を実装する場合は、予測可能な結果が得られます。

集計機能はレポートと分析のユースケースに役立ちますが、クエリを慎重に構成する必要があります。 groupByフィールドが選択した出力フィールドと一致していることを常に再確認し、特にページ分割時に予測可能な順序の並べ替えを追加し、データ型に対して個別および集計関数を適切に使用します。

次のセクションでは、理解する必要がある 3 つの重要な領域について説明します。集計と未加工の項目は相互に排他的であり、グループ化された結果を並べ替える場合は明示的な順序付けが必要であり、個別の集計を適切に使用する必要があります。

集計項目と未加工アイテムは相互に排他的です

現時点では、グループ化されたサマリーデータと、同じクエリ内のアイテムの生リストの両方を 同時に取得することはできません。クエリで groupBy を使用すると、API は "集計モード" に切り替わり、グループ化された結果のみを返します。この設計では、応答構造が明確に保たれ、各クエリは "集計モード" または "リストアイテムモード" になりますが、両方を使用することはありません。

これが実際にどのように機能するか:

products(...) クエリは、次のいずれかを返します。

個々の製品の一覧 ( groupBy が使用されていない場合)
集計データを含むグループ化された結果の一覧 ( groupBy が使用されている場合)

上記の集計された例では、応答に groupBy フィールドと集計フィールドが含まれていますが、通常の items 製品の一覧が見つからないことに注意してください。

両方を試すとどうなりますか。

同じクエリで通常の項目とグループの両方を要求しようとすると、GraphQL エンジンはエラーを返すか、その選択を許可しません。

回避策:

生データと集計データの両方が必要な場合は、生データ用と集計データ用の 2 つの個別のクエリを実行します。この方法では、両方のデータセットを完全に制御でき、特定のキャッシュとパフォーマンスの要件に基づいて最適化できます。

グループ化された結果を並べ替える場合は、明示的な順序付けが必要です

明示的な並べ替えを指定しない限り、集計されたグループは予測できない順序で返されます。常に orderBy または sort 引数を使用して、一貫性のある意味のある結果を確保します。

明示的な順序付けが重要な理由:

予測できない既定の順序: orderByしないと、グループはデータベースによって決定された任意の順序で返される可能性があります
改ページ位置の要件: 安定した並べ替え順序は、一貫性のある改ページ位置の動作に不可欠です
ユーザーエクスペリエンス: 予測可能な順序付けにより、データの解釈とアプリケーションの信頼性が向上します

順序を指定する必要がある場合:

groupBy フィールドに主キーがない: グループ化フィールドに主キーが含まれていない場合は、追加する必要があります orderBy
一意でないグループ化キー: カテゴリ名や日付などのフィールドでグループ化する場合
ページネーションシナリオ: 常に制限/オフセットまたはカーソルページネーションを使用する計画がある場合

ベストプラクティス:

集計値を基にして（例: 最初に最も高いカウント順に）、分析情報に基づく洞察を得るために並べ替える
カテゴリベースのグループ化にアルファベット順の並べ替えを使用する
複雑な順序付けのニーズに合わせて複数の並べ替え条件を組み合わせる

個別の集計を適切に使用する

distinct修飾子は、集計を実行する前に重複する値を排除し、データに重複が含まれている場合に正確な計算を行います。

一般的なユースケース:

一意のカウント: count(field: category_id, distinct: true) は、各グループに存在する異なるカテゴリの数をカウントします
重複除去された合計: sum(field: price, distinct: true) は、グループごとに 1 回だけ一意の価格値を追加します
結合シナリオ: テーブル結合により製品が複数回出現する場合、distinctを使用して各項目が一度だけカウントされることを保証します。

個別に使用する場合:

データに、計算を歪める正当な重複が含まれている
重複する行を作成する結合テーブルを操作している
出現回数の合計ではなく、一意の値をカウントする必要がある

パフォーマンスに関する考慮事項:

個別の操作では、より多くの処理が必要です。データの精度に必要な場合にのみ使用します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-21