Agregasi dalam API untuk GraphQL

Ubah data Microsoft Fabric Anda menjadi wawasan yang dapat ditindaklanjuti dengan agregasi GraphQL. Alih-alih mengambil ribuan rekaman individual dan memprosesnya di aplikasi Anda, Anda dapat meminta Fabric untuk mengelompokkan data Anda dan menghitung ringkasan sisi server—secara dramatis meningkatkan performa dan mengurangi transfer data.

Agregasi GraphQL berfungsi seperti operasi SQL GROUP BY, tetapi melalui API GraphQL. Anda dapat menghitung item per kategori, menghitung total pendapatan, menemukan peringkat rata-rata, atau menentukan nilai min/maks di seluruh tabel lakehouse dan gudang Anda—semuanya dalam satu kueri yang efisien.

Manfaat utama:

  • Pemrosesan sisi-server: Memanfaatkan mesin kueri yang sudah dioptimalkan Fabric untuk perhitungan
  • Pengurangan transfer data: Dapatkan ringkasan alih-alih rekaman mentah
  • Efisiensi kueri tunggal: Ganti beberapa operasi sisi klien dengan satu agregasi

Panduan ini menunjukkan kepada Anda cara membangun kueri agregasi menggunakan contoh e-niaga praktis, mencakup semuanya mulai dari pengelompokan dasar hingga fungsi tingkat lanjut dan batasan penting.

Siapa yang harus menggunakan agregasi

Agregasi GraphQL sangat berharga untuk:

  • Pengembang aplikasi yang membangun dasbor kustom dan aplikasi analisis yang membutuhkan data Fabric yang dirangkum
  • Insinyur data yang membuat API data yang melayani metrik dan KPI pra-dihitung dari lakehouse Fabric dan gudang
  • Pengembang BI membangun solusi analitik kustom yang melengkapi Power BI dengan data Fabric agregat
  • Pengembang integrasi yang membuat aplikasi dan alur kerja yang membutuhkan statistik ringkasan dari Fabric
  • Analis data membangun solusi analitik layanan mandiri yang memerlukan wawasan yang dikelompokkan dan diagregasi dari data Fabric

Jika Anda mengambil data untuk menampilkan bagan, menghitung total, membuat laporan, atau menganalisis tren, agregasi dapat secara signifikan meningkatkan performa aplikasi Anda dan mengurangi transfer data.

Pertanyaan bisnis umum yang dapat Anda jawab

Agregasi GraphQL unggul dalam menjawab pertanyaan analitik tentang data Fabric Anda:

  • Menghitung dan mengelompokkan: "Berapa banyak produk yang ada di setiap kategori?" atau "Berapa banyak pesanan per bulan?"
  • Perhitungan keuangan: "Berapa total pendapatan menurut wilayah?" atau "Nilai pesanan rata-rata menurut segmen pelanggan?"
  • Metrik performa: "Apa produk dengan peringkat tertinggi dan terendah di setiap kategori?"
  • Wawasan pelanggan: "Berapa banyak pelanggan unik yang dikunjungi bulan ini?" atau "Kota mana yang memiliki pengguna paling aktif?"

Kueri ini sangat ideal untuk membangun dasbor, membuat laporan, dan mendukung aplikasi analitik di mana Anda memerlukan data ringkasan daripada rekaman individual.

Prasyarat

Sebelum menggunakan agregasi GraphQL, pastikan Anda memiliki:

  • Ruang kerja Microsoft Fabric dengan izin yang sesuai
  • Lakehouse atau gudang dengan tabel yang berisi data yang ingin Anda agregat
  • API untuk titik akhir GraphQL yang dikonfigurasi untuk item Fabric Anda
  • Keakraban dasar dengan sintaks kueri GraphQL

Lokasi untuk menjalankan kueri ini

Mulai cepat: Gunakan API untuk editor GraphQL di ruang kerja Fabric Anda untuk menguji semua contoh dalam artikel ini. Editor menyediakan eksplorasi skema, validasi kueri, dan hasil langsung.

Untuk aplikasi: Kirim kueri sebagai permintaan HTTP POST ke titik akhir GraphQL Anda, menggunakan pustaka klien GraphQL apa pun untuk bahasa pemrograman Anda.

Untuk pengembangan: Alat seperti GraphQL Playground, Insomnia, atau Postman bekerja dengan baik untuk pengembangan dan pengujian kueri.

Nota

Contoh dalam artikel ini siap untuk disalin dan dijalankan setelah Anda mengonfigurasi API untuk titik akhir GraphQL. Beberapa contoh dipersingkat untuk singkat dan mungkin memerlukan adaptasi untuk skema spesifik Anda.

Contoh skenario: Data e-niaga dalam Fabric

Untuk panduan ini, kami menggunakan himpunan data e-niaga fiktif yang disimpan di microsoft Fabric lakehouse atau gudang Anda. Skenario ini menunjukkan bagaimana Anda dapat menganalisis data ritel menggunakan agregasi GraphQL.

Dalam contoh ini, data produk termasuk dalam kategori, dengan masing-masing Product bidang yang berisi seperti harga dan peringkat (nilai numerik yang sempurna untuk agregasi), dan hubungan dengan Category. Saat Anda mengekspos tabel ini melalui API Fabric untuk GraphQL, skema yang dihasilkan mungkin terlihat seperti:

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!
}

Dalam contoh ini, products kueri dapat mengembalikan daftar item normal atau, jika groupBy digunakan, hasil agregat. Mari kita fokus pada penggunaan groupBy dan fitur agregasi dari kueri ini.

Nota

Anda tidak dapat mengambil item normal dan mengelompokkan hasil dalam kueri yang sama. Untuk detail selengkapnya, lihat Agregasi dan item mentah saling eksklusif.

Fungsi agregasi yang tersedia

Fungsi yang tepat tersedia tergantung pada implementasi, tetapi operasi agregasi umum meliputi:

  • count – Jumlah rekaman (atau nilai bidang yang bukan null) dalam grup.
  • sum – Jumlah semua nilai dalam bidang numerik.
  • rata-rata – Nilai rata-rata (mean) dalam bidang numerik.
  • min – Nilai minimum dalam bidang.
  • max – Nilai maksimum dalam bidang.

Dalam agregasi GraphQL, Anda menentukan nama fungsi dan bidang target, seperti yang ditunjukkan dalam contoh count(field: id), sum(field: price), dll. Setiap fungsi mengembalikan objek yang memungkinkan Anda memilih satu atau beberapa bidang yang diterapkannya.

Nota

Dalam API Microsoft Fabric untuk GraphQL, operasi agregasi seperti count, , sumavg, min, dan max saat ini hanya berfungsi pada bidang numerik atau kuantitatif (bilangan bulat, float). Anda tidak dapat menggunakannya pada bidang teks atau tanggal secara langsung. Misalnya, Anda tidak dapat menghitung "rata-rata" bidang string. Dukungan untuk melakukan agregat pada jenis data lain (seperti perangkaian teks atau min/maks leksikografis) mungkin ditambahkan dalam pembaruan di masa mendatang ke Fabric.

Dasar-dasar kueri agregasi

Untuk melakukan agregasi di GraphQL API Fabric, Anda menentukan groupBy argumen dalam kueri Anda untuk menentukan cara mengelompokkan data, dan meminta bidang agregasi (seperti hitungan atau jumlah) dalam hasilnya. Mesin GraphQL Fabric memproses kueri ini secara efisien terhadap tabel lakehouse atau gudang yang mendasarinya, mengembalikan daftar rekaman yang dikelompokkan dengan nilai kuncinya dan metrik agregat yang dihitung.

Contoh 1: Menghitung produk per kategori

Mari kelompokkan produk berdasarkan kategorinya dan hitung berapa banyak produk yang ada di setiap grup. Kueri mungkin terlihat seperti:

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")
     } 
   }
  }
}

Dalam kueri ini:

  • groupBy(fields: [category_id]) memberi tahu mesin Fabric GraphQL untuk mengelompokkan produk menurut category_id bidang .
  • Dalam pilihan hasil, Anda meminta group dan mengagregasi count pada bidang id. Menghitung id secara efektif menghitung produk dalam grup tersebut.

Seperti apa hasilnya: Setiap item dalam respons mewakili satu grup kategori. Objek groupBy berisi kunci pengelompokan. Di sini memuat category_id nilai dan count { id } menyediakan jumlah produk dalam kategori tersebut.

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

Output ini memberi tahu kami kategori 1 memiliki tiga produk, kategori 2 memiliki 2, dan sebagainya.

Contoh 2: Jumlah dan rata-rata

Kita dapat meminta beberapa metrik agregasi dalam satu kueri. Misalkan kita ingin, untuk setiap kategori, total harga semua produk dan peringkat rata-rata:

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
     } 
   }
  }
}

Kueri ini akan mengembalikan hasil berikut:

{
  "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
          }
        },
        ...
      ]
    }
  }
}

Setiap objek grup mencakup kategori dan agregat komputasi seperti jumlah produk, jumlah harganya, dan peringkat rata-rata dalam kategori tersebut.

Contoh 3: Kelompokkan menurut beberapa bidang

Anda bisa mengelompokkan menurut lebih dari satu bidang untuk mendapatkan pengelompokan multi-tingkat. Misalnya, jika produk Anda memiliki bidang rating, Anda dapat mengelompokkan berdasarkan category_id dan rating, kemudian menghitung rata-rata price untuk kelompok tersebut.

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

Ini akan mengelompokkan produk dengan kombinasi unik kategori dan peringkat seperti yang ditunjukkan di bawah ini:

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

Dan sebagainya untuk setiap pasangan peringkat kategori dalam data.

Tip

Saat mengelompokkan menurut beberapa bidang, pengurutan eksplisit menjadi sangat penting untuk hasil yang dapat diprediksi. Lihat Mengurutkan hasil yang dikelompokkan memerlukan urutan eksplisit.

Contoh 4: Menggunakan distinct

Fitur agregasi mendukung pengubah yang berbeda untuk menghitung atau mempertimbangkan nilai unik. Misalnya, untuk mengetahui berapa banyak kategori berbeda yang ada dalam koleksi produk, Anda dapat menggunakan jumlah yang berbeda:

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

Kueri ini mengembalikan hasil dengan jumlah produk unik untuk setiap kategori. Hasilnya akan terlihat seperti:

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

Tip

Untuk panduan selengkapnya tentang kapan dan bagaimana menggunakan berbeda dengan tepat, lihat Menggunakan agregasi yang berbeda dengan tepat.

Contoh 5: Menggunakan alias

Anda dapat membuat alias untuk agregasi untuk memberikan nama yang bermakna dan mudah dipahami untuk hasil agregat. Misalnya, Anda dapat memberi nama agregasi dalam contoh distinctProductCategoryCount sebelumnya karena menghitung kategori produk yang berbeda untuk lebih memahami hasilnya:

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

Hasilnya serupa tetapi lebih bermakna dengan alias kustom:

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

Contoh 6: Menggunakan having klausa

Dimungkinkan untuk memfilter hasil agregat dengan having klausa. Misalnya, Anda dapat memodifikasi contoh sebelumnya untuk hanya mengembalikan hasil yang lebih besar dari dua:

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

Hasilnya mengembalikan nilai tunggal dari satu-satunya kategori yang memiliki lebih dari dua produk.

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

Pembatasan dan praktik terbaik

Saat Anda menggunakan agregasi di API Microsoft Fabric untuk GraphQL, ada aturan dan batasan penting yang perlu dipertimbangkan. Dengan mengikuti praktik terbaik ini dan memahami pembatasan ini, Anda dapat membangun kueri agregasi GraphQL yang efektif yang menghasilkan wawasan yang kuat sambil memastikan hasil yang dapat diprediksi, terutama saat bekerja dengan himpunan data besar atau menerapkan penomoran halaman.

Fitur agregasi berguna untuk kasus penggunaan pelaporan dan analitik, tetapi memerlukan penataan kueri yang cermat. Selalu periksa kembali apakah bidang Anda groupBy selaras dengan bidang output yang Anda pilih, tambahkan pengurutan untuk urutan yang dapat diprediksi terutama saat paginating, dan gunakan fungsi yang berbeda dan agregat dengan tepat untuk jenis data.

Bagian berikut mencakup tiga area utama yang perlu Anda pahami: Agregasi dan item mentah saling eksklusif, Mengurutkan hasil yang dikelompokkan memerlukan pengurutan eksplisit, dan Menggunakan agregasi yang berbeda dengan tepat.

Agregasi dan item mentah saling eksklusif

Saat ini, Anda tidak dapat mengambil data ringkasan yang dikelompokkan dan daftar mentah item dalam kueri yang sama secara bersamaan. Saat Anda menggunakan groupBy dalam kueri, API beralih ke "mode agregasi" dan hanya mengembalikan hasil yang dikelompokkan. Desain ini menjaga struktur respons tetap tidak ambigu - setiap kueri berada dalam "mode agregasi" atau "mode item daftar", tetapi tidak pernah keduanya.

Cara kerja ini dalam praktiknya:

Kueri products(...) mengembalikan salah satu dari:

  • Daftar produk individual (saat groupBy tidak digunakan)
  • Daftar hasil yang dikelompokkan dengan data agregat (saat groupBy digunakan)

Perhatikan dalam contoh agregat di atas bahwa respons berisi groupBy dan bidang agregat, tetapi daftar produk yang biasa items hilang.

Apa yang terjadi jika Anda mencoba keduanya:

Jika Anda mencoba meminta item dan grup normal dalam kueri yang sama, mesin GraphQL mengembalikan kesalahan atau tidak akan mengizinkan pilihan tersebut.

Solusi:

Jika Anda memerlukan data mentah dan data agregat, jalankan dua kueri terpisah: satu untuk data mentah dan satu untuk data agregat. Pendekatan ini memberi Anda kontrol penuh atas dataset dan bisa dioptimalkan sesuai dengan kebutuhan caching dan performa spesifik Anda.

Mengurutkan hasil yang dikelompokkan memerlukan pengurutan eksplisit

Grup agregat dikembalikan dalam urutan yang tidak dapat diprediksi kecuali Anda menentukan pengurutan eksplisit. Selalu gunakan orderBy atau sort argumen untuk memastikan hasil yang konsisten dan bermakna.

Mengapa pemesanan eksplisit penting:

  • Urutan default yang tidak dapat diprediksi: Tanpa orderBy, grup mungkin kembali dalam urutan yang ditentukan database arbitrer
  • Persyaratan penomoran halaman: Urutan pengurutan yang stabil sangat penting untuk perilaku penomoran halaman yang konsisten
  • Pengalaman pengguna: Urutan yang dapat diprediksi meningkatkan interpretasi data dan keandalan aplikasi

Saat Anda harus menentukan pengurutan:

  • Tidak ada kunci utama di bidang groupBy: Jika bidang pengelompokan Anda tidak menyertakan kunci utama, Anda harus menambahkan orderBy
  • Kunci pengelompokan non-unik: Saat mengelompokkan menurut bidang seperti nama kategori atau tanggal
  • Skenario paginasi: Kapan saja Anda berencana untuk menggunakan batas/offset atau paginasi kursor

Praktik terbaik:

  • Mengurutkan menurut nilai agregat (seperti jumlah tertinggi terlebih dahulu) untuk wawasan analitis
  • Menggunakan pengurutan alfabet untuk pengelompokan berbasis kategori
  • Menggabungkan beberapa kriteria pengurutan untuk kebutuhan pengurutan yang kompleks

Gunakan agregasi berbeda dengan tepat

Pengubah distinct menghilangkan nilai duplikat sebelum melakukan agregasi, memastikan perhitungan yang akurat saat data Anda berisi duplikat.

Kasus penggunaan umum:

  • Jumlah unik: count(field: category_id, distinct: true) menghitung berapa banyak kategori berbeda yang ada di setiap grup
  • Jumlah yang dideduksi: sum(field: price, distinct: true) menambahkan setiap nilai harga unik hanya sekali per grup
  • Skenario penggabungan: Ketika produk muncul beberapa kali karena penggabungan tabel, distinct memastikan setiap item dihitung sekali.

Kapan menggunakan 'distinct':

  • Data Anda berisi duplikat yang sah yang akan mempengaruhi perhitungan.
  • Anda bekerja dengan tabel gabungan yang membuat baris duplikat
  • Anda perlu menghitung jumlah nilai yang unik daripada total kemunculan.

Pertimbangan performa:

Operasi yang berbeda memerlukan lebih banyak pemrosesan. Hanya gunakan jika perlu untuk akurasi data.

Konten terkait

  • Last updated on