適用於 GraphQL 的 API 中的匯總

利用 GraphQL 聚合，將您的 Microsoft Fabric 資料轉化為可行的洞察。你不必在應用程式中擷取數千筆個別紀錄並處理，而是可以請 Fabric 將資料分組並在伺服器端計算摘要——大幅提升效能並減少資料傳輸。

GraphQL 聚合的運作方式類似 SQL GROUP BY 操作，但透過 GraphQL API 進行。你可以在一個高效的查詢中，逐類別統計項目、計算營收總額、尋找平均評分，或在湖邊屋和倉庫表格中計算最小值與最大值。

主要優點：

伺服器端處理：善用 Fabric 優化的查詢引擎進行計算
減少資料傳輸：取得摘要而非原始紀錄
單一查詢效率：以一個聚合取代多個客戶端操作

本指南將以一個實用的電子商務範例，教你如何建立聚合查詢，涵蓋從基本分組到進階函數及重要限制的各種內容。

誰應該使用聚合

GraphQL 聚合的價值在於：

應用程式開發者正在建置需要彙整 Fabric 資料的自訂儀表板與分析應用程式
資料工程師 建立資料 API，提供來自 Fabric 湖屋與倉庫的預先計算指標與關鍵績效指標
BI 開發人員 利用彙整的 Fabric 資料來建立補充 Power BI 的客製化分析解決方案
整合開發者正在建立需要來自 Fabric 的摘要統計的應用程式與工作流程
由資料分析師構建自助分析解決方案，這些方案需要從 Fabric 資料中分組並彙總洞見。

如果你是為了顯示圖表、計算總數、產生報告或分析趨勢而擷取資料，彙整能大幅提升應用程式效能並減少資料傳輸。

你可以回答的常見商業問題

GraphQL 聚合在回答關於 Fabric 資料的分析問題方面表現優異：

計數與分組：「 每個類別有多少商品？ 」或 「每月有多少訂單？」
財務計算：「 各區域的總營收是多少？ 」或 「按客戶區隔的平均訂單價值？」
績效指標：「 每個類別中評分最高和最低的產品是什麼？」
客戶洞察：「 本月有多少獨立客戶造訪？ 」或 「哪些城市擁有最活躍的用戶？」

這些查詢非常適合建立儀表板、產生報告，以及驅動需要彙整資料而非單一紀錄的分析應用程式。

先決條件

在使用 GraphQL 聚合前，請確保您具備：

具有適當權限的 Microsoft Fabric 工作區
湖屋或倉庫，裡面有你想彙整的資料表
為你的 Fabric 項目配置的 GraphQL 端點 API
對 GraphQL 查詢語法的基本熟悉

在哪裡執行這些查詢

快速入門：在你的 Fabric 工作區中使用 GraphQL 編輯器的 API ，測試本文中的所有範例。編輯器提供結構探索、查詢驗證及即時結果。

應用方面：使用任何程式語言的 GraphQL 用戶端函式庫，將查詢作為 HTTP POST 請求發送給你的 GraphQL 端點。

開發方面：像 GraphQL Playground、Insomnia 或 Postman 這類工具非常適合查詢開發和測試。

備註

本文中的範例在你為 GraphQL 端點設定好 API 後，即可複製並執行。有些範例為了簡潔而被簡化，可能需要針對你的具體架構做調整。

範例情境：Fabric 中的電子商務資料

本指南使用一個虛構的電子商務資料集，儲存在你的 Microsoft Fabric 湖屋或倉庫中。此情境展示了如何利用 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)等等。每個函式回傳一個物件，讓你能選擇一個或多個該欄位。

備註

在 Microsoft Fabric 的 GraphQL API 中，像 count、 sum、 avg、 min等 max 彙整操作目前僅適用於數值或量化欄位（整數、浮點數）。你不能直接在文字或日期欄位使用它們。例如，你無法計算弦場的「平均值」。未來 Fabric 更新中可能會新增對其他資料類型執行聚合（如文字串接或字典序最小/最大）的支援。

匯總查詢基本概念

要在 Fabric 的 GraphQL API 中執行聚合，你在查詢中指定 groupBy 一個參數來定義如何將資料分組，並在結果中請求彙總欄位（如計數或總和）。 Fabric 的 GraphQL 引擎會針對底層的湖屋或倉儲資料表高效處理這些查詢，回傳一份分組紀錄清單及其關鍵值及計算出的彙整指標。

範例 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]) 告知 Fabric GraphQL 引擎依欄位分組產品 category_id 。
在結果選取中，您會在group欄位上要求count和匯總id。使用 id 可以有效地計算該群組中的產品。

結果看起來像這樣： 回應中的每個專案都代表一個類別群組。物件 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 有三個產品、類別 2 有 2 個等。

範例 2：總和平均值

我們可以在一個查詢中要求多個匯總計量。假設我們想要針對每個類別，所有產品的總價格和平均評等：

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：使用 distinct

彙總功能支持使用相異修飾詞來計算或考慮唯一值。例如，若要了解產品集合中有多少個不同的類別，您可以使用相異計數：

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 子句來篩選匯總的結果。例如，您可以修改上一個範例，只傳回大於兩個的結果：

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

結果會傳回具有兩個以上產品之唯一類別的單一值：

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

限制和最佳做法

當你在 Microsoft Fabric 的 GraphQL API 中使用聚合時，有一些重要的規則和限制需要考慮。遵循這些最佳實務並了解這些限制，你可以打造有效的 GraphQL 聚合查詢，帶來強大的洞見，並確保結果可預測，尤其是在處理大型資料集或實施分頁時。

匯總功能適用於報告和分析使用案例，但確實需要仔細建構查詢。請務必仔細檢查您的 groupBy 欄位是否與選取的輸出欄位一致，新增可預測順序的排序，特別是在分頁時，並適當地針對數據類型使用相異和匯總函數。

以下章節涵蓋三個你需要了解的關鍵領域：聚合與原始項目互斥、分組結果排序需明確排序，以及適當使用不同聚合。

聚合與原始項目是互斥的

目前，你無法同時取得同一查詢中分組摘要資料和原始項目清單。當你在查詢中使用時 groupBy ，API 會切換到「聚合模式」，只回傳分組結果。這種設計讓回應結構保持明確——每個查詢要麼處於「聚合模式」，要麼是「清單項目模式」，但絕不會同時出現兩者。

實務上的運作方式：

查詢 products(...) 返回以下其中一項：

未使用 groupBy 時的個別產品清單
包含彙總資料的分組結果列表（在使用 groupBy 時）

請注意，在上述彙總範例中，回應包含 groupBy 和集合欄位，但缺少通常 items 的產物清單。

如果你兩種方法都試試看會怎樣：

如果你嘗試在同一查詢中同時請求一般項目和群組，GraphQL 引擎會回傳錯誤或不允許該選擇。

因應措施：

如果你同時需要原始資料和彙總資料，請執行兩個獨立查詢：一個是原始資料，一個是彙總資料。這種方法讓你能完全掌控這兩個資料集，並可根據你的快取需求和效能進行優化。

排序分組結果需要指定排序

聚合後的群組會以不可預測的順序回傳，除非你指定明確排序。務必使用 orderBy 或 sort 論證，以確保結果一致且有意義。

為什麼明確排序很重要：

不可預測的預設順序：若無 orderBy，群組可能會以資料庫任意決定的順序返回
分頁要求：穩定的排序順序對於一致性的分頁行為至關重要
使用者體驗：可預測的排序提升資料解讀與應用可靠性

當你必須指定排序時：

groupBy 欄位中沒有主鍵：如果你的分組欄位沒有主鍵，你必須新增 orderBy
非唯一分組鍵：當依類別名稱或日期等欄位分組時
分頁情境：任何你打算使用極限/偏移或游標分頁的情況

最佳做法：

依照總量排序（例如先排序最高計數）以獲得分析洞察
使用字母排序來分類類別
結合多種排序標準以滿足複雜的排序需求

適當使用不同的聚合

distinct修飾符會在進行彙整前消除重複值，確保資料中有重複值時計算準確。

常見用例：

唯一計數： count(field: category_id, distinct: true) 計算每組中存在多少不同類別
去重總和： sum(field: price, distinct: true) 每個唯一價格值每組只加一次
連接情境：當產品因表格連結而多次出現時，唯一機制確保每項物品只被計算一次

何時使用不同：

你的資料包含真實的重複資料，會扭曲計算
你正在處理連接資料表，這會導致產生重複的行
你需要計算的是獨特數值，而非總次數

效能考量：

不同的操作需要更多的處理。只有在資料準確性必要時才使用。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-21