Veri API oluşturucusunda GraphQL ile veri toplama

Veri API'si oluşturucusu (DAB), SQL ailesi veritabanları ve Azure Synapse Analytics (Ayrılmış SQL havuzu) için GraphQL toplama ve gruplandırma özelliklerini destekler. Toplamalar, özel API kodu yazmadan sayısal alanları ve grup sonuçlarını özetlemenizi sağlar. Toplama ve groupBy NoSQL, PostgreSQL veya MySQL için Azure Cosmos DB'de kullanılamaz.

Önkoşullar

Desteklenen veritabanı:
- SQL Server 2016 veya üzeri
- Azure SQL Veritabanı
- Azure SQL Yönetilen Varlık
- Microsoft Fabric SQL
- Azure Synapse Analytics (yalnızca Ayrılmış SQL havuzu)
Veri API'si oluşturucu CLI. CLI'yi yükleme
Varlığınızın GraphQL aracılığıyla kullanıma sunulduğu bir DAB yapılandırma dosyası.
Sorguları çalıştırmak için bir GraphQL istemcisi (örneğin, Banana Cake Pop veya GraphQL Playground).

Desteklenen veritabanları

Veritabanı	Toplama desteği
SQL Server / Azure SQL / Microsoft Fabric SQL	✅ Evet
Azure Synapse (Ayrılmış SQL havuzu)	✅ Evet
Azure Synapse (Sunucusuz SQL havuzu)	❌ Hayır
PostgreSQL	❌ Hayır
MySQL	❌ Hayır
NoSQL için Azure Cosmos DB	❌ Hayır

Toplama işlevleri

DAB aşağıdaki toplama işlevlerini destekler:

İşlev	Şunlar için geçerlidir:	Description
`sum`	Yalnızca sayısal alanlar	Tüm değerlerin toplamı
`average`	Yalnızca sayısal alanlar	Tüm değerlerin ortalaması
`min`	Yalnızca sayısal alanlar	Minimum değer
`max`	Yalnızca sayısal alanlar	Maksimum değer
`count`	Herhangi bir alan	Null olmayan değerlerin sayısı

Constraints

sum, average, minve max yalnızca sayısal veri türleri (int, decimal, float vb.) üzerinde çalışır.
count dizeler ve tarihler de dahil olmak üzere herhangi bir veri türünde çalışır.
Tabloda sayısal sütunlar yoksa, DAB bu varlık için toplama düğümleri oluşturmaz. Yine de sayısal olmayan alanlarda kullanabilirsiniz count .

İsteğe bağlı değiştiriciler

Değiştirici	Amaç	Example
`distinct: true`	Yalnızca benzersiz değerleri sayma	Farklı müşterileri sayma
`having: { ... }`	Toplamadan sonra grupları filtreleme	Toplam > 1000 içeren grupları göster

DAB çalışma zamanını çalıştırma

GraphQL uç noktasının kullanılabilir olması için YAPıLANDıRMA dosyanızla DAB'yi başlatın.

dab start

Toplanmış sonuçları sorgula

Bu bölümde tablo şemasını, GraphQL sorgusunu, oluşturulan SQL'i ve JSON yanıtını gösteren eksiksiz bir örnek gösterilir.

Tablo şeması

CREATE TABLE books (
    id INT PRIMARY KEY,
    title NVARCHAR(200),
    year INT,
    pages INT
);

GraphQL sorgusu

Satırları gruplandırmak ve sayısal alanlar için toplama değerleri döndürmek için GraphQL kullanın.

{
  books(
    groupBy: { fields: ["year"] }
  ) {
    items {
      year
    }
    aggregates {
      pages {
        sum
        average
        min
        max
      }
    }
  }
}

groupBy.fields satırları belirtilen sütunlara göre gruplandırma.
aggregates sayısal alanlar için toplama işlevlerini kullanıma sunar (örneğin, pages).
GraphQL şeması yalnızca bunları destekleyen alanlar için toplamaları kullanıma sunar; kullanılabilir toplama alanlarını ve işlevlerini onaylamak için istemcinizde şema iç gözlemini kullanın.

Oluşturulan SQL

DAB, GraphQL sorgusunu T-SQL'e çevirir:

SELECT 
    [year],
    SUM([pages]) AS [sum],
    AVG([pages]) AS [average],
    MIN([pages]) AS [min],
    MAX([pages]) AS [max]
FROM [dbo].[books]
GROUP BY [year]
FOR JSON PATH, INCLUDE_NULL_VALUES

JSON yanıtı

{
  "data": {
    "books": {
      "items": [
        { "year": 2023 },
        { "year": 2024 }
      ],
      "aggregates": {
        "pages": [
          { "sum": 3200, "average": 320, "min": 120, "max": 450 },
          { "sum": 4500, "average": 300, "min": 140, "max": 510 }
        ]
      }
    }
  }
}

items ve aggregates dizileri dizine göre hizalanır; aggregates.pages içindeki ilk öğe items ilk gruba karşılık gelir.

Gruplandırma olmadan toplama

groupBy öğesini atlarsanız tüm satırlardaki toplamları hesaplayın.

GraphQL sorgusu

{
  books {
    aggregates {
      pages {
        sum
        average
        min
        max
        count
      }
      id {
        count
      }
    }
  }
}

Oluşturulan SQL

SELECT
    SUM([pages]) AS [sum],
    AVG([pages]) AS [average],
    MIN([pages]) AS [min],
    MAX([pages]) AS [max],
    COUNT([pages]) AS [count],
    COUNT([id]) AS [count]
FROM [dbo].[books]
FOR JSON PATH, INCLUDE_NULL_VALUES

JSON yanıtı

{
  "data": {
    "books": {
      "aggregates": {
        "pages": {
          "sum": 15420,
          "average": 308,
          "min": 120,
          "max": 850,
          "count": 50
        },
        "id": {
          "count": 50
        }
      }
    }
  }
}

groupBy olmadan, tüm satırlar tek bir sonuçta daraltıldığından yanıt, dizi değil, tek bir nesne döndürür.

Bir veya daha fazla alana göre gruplandırma

Bir veya daha fazla sütuna göre satırları gruplandır ve grup başına toplamları döndür.

Tablo şeması

CREATE TABLE sales (
    id INT PRIMARY KEY,
    year INT,
    category NVARCHAR(50),
    revenue DECIMAL(10,2),
    quantity INT
);

GraphQL sorgusu

{
  sales(
    groupBy: { fields: ["year", "category"] }
  ) {
    items {
      year
      category
    }
    aggregates {
      revenue {
        sum
        average
      }
      quantity {
        sum
      }
    }
  }
}

Oluşturulan SQL

SELECT
    [year],
    [category],
    SUM([revenue]) AS [sum],
    AVG([revenue]) AS [average],
    SUM([quantity]) AS [sum]
FROM [dbo].[sales]
GROUP BY [year], [category]
FOR JSON PATH, INCLUDE_NULL_VALUES

JSON yanıtı

{
  "data": {
    "sales": {
      "items": [
        { "year": 2023, "category": "Books" },
        { "year": 2023, "category": "Electronics" },
        { "year": 2024, "category": "Books" }
      ],
      "aggregates": {
        "revenue": [
          { "sum": 45000.00, "average": 150.00 },
          { "sum": 120000.00, "average": 600.00 },
          { "sum": 52000.00, "average": 173.33 }
        ],
        "quantity": [
          { "sum": 300 },
          { "sum": 200 },
          { "sum": 300 }
        ]
      }
    }
  }
}

Yanıt items ve dizileri aynı sırada döndürür, böylece grupları birleştirilmiş değerleriyle hizalayabilirsiniz.

Toplanan sonuçları filtrelemek zorunda olma

Toplamadan sonra grupları filtrelemek için kullanın having . Bu, SQL yan tümcesine HAVING eşdeğerdir.

Tablo şeması

CREATE TABLE products (
    id INT PRIMARY KEY,
    category NVARCHAR(50),
    price DECIMAL(10,2)
);

GraphQL sorgusu

{
  products(
    groupBy: { fields: ["category"] }
  ) {
    items { category }
    aggregates {
      price {
        sum(having: { gt: 10000 })
        average
      }
    }
  }
}

Oluşturulan SQL

SELECT
    [category],
    SUM([price]) AS [sum],
    AVG([price]) AS [average]
FROM [dbo].[products]
GROUP BY [category]
HAVING SUM([price]) > 10000
FOR JSON PATH, INCLUDE_NULL_VALUES

JSON yanıtı

Yalnızca toplamın 10000'i aştığı kategoriler döndürülür:

{
  "data": {
    "products": {
      "items": [
        { "category": "Electronics" },
        { "category": "Furniture" }
      ],
      "aggregates": {
        "price": [
          { "sum": 15000.00, "average": 300.00 },
          { "sum": 12000.00, "average": 400.00 }
        ]
      }
    }
  }
}

HAVING operatörleri

Operator	SQL eşdeğeri	Example
`eq`	`=`	`having: { eq: 100 }`
`neq`	`<>`	`having: { neq: 0 }`
`gt`	`>`	`having: { gt: 1000 }`
`gte`	`>=`	`having: { gte: 500 }`
`lt`	`<`	`having: { lt: 100 }`
`lte`	`<=`	`having: { lte: 50 }`

Uyarı

Her having filtre, toplama işlevine bağımsız olarak uygulanır. Tek bir GraphQL sorgusunda "toplam > 1000 VEYA sayı < 10" gibi çapraz toplama koşulları oluşturamazsınız.

Toplamalarda DISTINCT

distinct: true ile benzersiz değerleri sayın.

Tablo şeması

CREATE TABLE orders (
    id INT PRIMARY KEY,
    customer_id INT,
    product_id INT
);

GraphQL sorgusu

{
  orders(
    groupBy: { fields: ["customer_id"] }
  ) {
    items { customer_id }
    aggregates {
      product_id {
        count(distinct: true)
        count
      }
    }
  }
}

Oluşturulan SQL

SELECT
    [customer_id],
    COUNT(DISTINCT [product_id]) AS [count],
    COUNT([product_id]) AS [count]
FROM [dbo].[orders]
GROUP BY [customer_id]
FOR JSON PATH, INCLUDE_NULL_VALUES

JSON yanıtı

{
  "data": {
    "orders": {
      "items": [
        { "customer_id": 101 },
        { "customer_id": 102 }
      ],
      "aggregates": {
        "product_id": [
          { "count": 5 },
          { "count": 3 }
        ]
      }
    }
  }
}

İlk count (ile distinct: true) müşteri başına benzersiz ürünler döndürür. İkinci count , toplam siparişleri döndürür.

Uyarı

Aynı alanda birden çok toplama isteğinde bulunurken, DAB bunları istenen sırayla döndürür. Yanıtları kendi kendini belgeleyen hale getirmek için diğer adları (örneğin, uniqueProducts: count(distinct: true)) kullanın.

Filtreleri toplama ile birleştirme

Önce satırlara filter uygulayın, ardından toplamadan sonra gruplara having uygulayın. İşlemlerin sırasını anlamak kritik önem taşır:

Filter (SQL WHERE) gruplandırmadan önce satırları kaldırır
Grupla kalan satırları gruplar halinde toplar
Toplama , grup başına toplam/ort/minimum/maksimum/sayıyı hesaplar
Having, koşulla eşleşmeyen grupları kaldırır.

GraphQL sorgusu

{
  sales(
    filter: { year: { gte: 2023 } }
    groupBy: { fields: ["region"] }
  ) {
    items { region }
    aggregates {
      revenue { sum average }
    }
  }
}

Oluşturulan SQL

SELECT
    [region],
    SUM([revenue]) AS [sum],
    AVG([revenue]) AS [average]
FROM [dbo].[sales]
WHERE [year] >= 2023
GROUP BY [region]
FOR JSON PATH, INCLUDE_NULL_VALUES

Tavsiye

Toplamadan önce satırları dışlamak için kullanın filter . Toplamadan sonra grupları filtrelemek için kullanın having .

Toplamalarla takma adları kullanma

GraphQL diğer adlarını kullanarak anlamlı alan adları oluşturun.

{
  products(
    groupBy: { fields: ["category"] }
  ) {
    items { category }
    aggregates {
      price {
        totalRevenue: sum
        avgPrice: average
        cheapest: min
        mostExpensive: max
        productCount: count
      }
    }
  }
}

Şema incelemesi

Bir varlık için hangi toplamaların kullanılabilir olduğunu görmek için iç gözlem kullanın.

{
  __type(name: "BooksAggregates") {
    fields {
      name
      type { name }
    }
  }
}

Sayısal alanlar sum, average, min, max ve count alanlarını kullanıma sunar. Sayısal olmayan alanlar görünür hale getirir count.

İpuçları ve sınırlamalar

Toplama ve groupBy yalnızca SQL Server, Azure SQL, Microsoft Fabric SQL ve Azure Synapse Ayrılmış SQL havuzu için geçerlidir.
Toplamalar sayısal alanlarda çalışır; count herhangi bir alanda çalışır. Sayısal sütun içermeyen tablolar yalnızca count'i gösterir.
Gruplandırma, aynı varlık üzerindeki alanlara uygulanır (çapraz varlık için groupBy uygulanmaz).
Büyük kümelemeler pahalı olabilir; mümkün olduğunda grup oluşturmadan önce groupBy kolonlarınızı dizine ekleyin ve satırları filtreleyin.
Sorgu performansını geliştirmek için sık kullanılan groupBy sütunlarda dizinler oluşturun.

Sorun giderme

Hata: Alan toplamayı desteklemiyor

Neden: Sayısal olmayan bir alanda , sum, averageveya min kullanmamax.

Çözüm:

Alan türlerini doğrulamak için şema iç gözlemi kullanın.
Sayısal olmayan alanlar için kullanın count .
Özel alan adları kullanıyorsanız alan eşlemelerini denetleyin.

Hata: Toplama düğümleri bulunamadı

Neden: Varlığın sayısal sütunu yok.

Çözüm:

Tablo şemasında en az bir sayısal sütun olduğunu doğrulayın.
Sayısal olmayan alanlarda gerekiyorsa count agregaları kullanın.

Yavaş toplama sorguları

Neden: Düzgün dizinleri olmayan büyük tablolar.

Çözüm:

groupBy sütunlarına dizinler oluşturun.
Toplamadan önce satırları sınırlamak için kullanın filter .
Döndürülen grup sayısını azaltmak için kullanın having .

Sonraki adım

Özellik kullanılabilirliğini denetleme

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-28

Aracılığıyla paylaş

Veri API oluşturucusunda GraphQL ile veri toplama

Önkoşullar

Desteklenen veritabanları

Toplama işlevleri

Constraints

İsteğe bağlı değiştiriciler

DAB çalışma zamanını çalıştırma

Toplanmış sonuçları sorgula

Tablo şeması

GraphQL sorgusu

Oluşturulan SQL

JSON yanıtı

Gruplandırma olmadan toplama

GraphQL sorgusu

Oluşturulan SQL

JSON yanıtı

Bir veya daha fazla alana göre gruplandırma

Tablo şeması

GraphQL sorgusu

Oluşturulan SQL

JSON yanıtı

Toplanan sonuçları filtrelemek zorunda olma

Tablo şeması

GraphQL sorgusu

Oluşturulan SQL

JSON yanıtı

HAVING operatörleri

Toplamalarda DISTINCT

Tablo şeması

GraphQL sorgusu

Oluşturulan SQL

JSON yanıtı

Filtreleri toplama ile birleştirme

GraphQL sorgusu

Oluşturulan SQL

Toplamalarla takma adları kullanma

Şema incelemesi

İpuçları ve sınırlamalar

Sorun giderme

Hata: Alan toplamayı desteklemiyor

Hata: Toplama düğümleri bulunamadı

Yavaş toplama sorguları

İlgili içerik

Sonraki adım

Geri Bildirim

Ek kaynaklar