Belajar GraphQL - Menguasai Query Operations

#Pendahuluan

Query adalah cara utama client membaca data dari GraphQL. Di episode 3 kalian merancang schema; sekarang saatnya menulis operasi yang meminta data dari schema tersebut. Episode 4 membedah seluruh elemen query operation secara sistematis.

Kita akan mulai dari struktur dasar dan nested query, lalu argument, alias, fragment, variabel, dan direktif. Setelah episode ini, kalian bisa menulis query yang efisien, tidak duplikatif, dan siap dipakai di aplikasi nyata.

#Struktur Dasar Query

#Field Selection dan Nested Query

Struktur query sangat sederhana: pilih field, dan untuk field bertipe objek, lanjutkan memilih field di dalamnya. Bentuk response mengikuti persis bentuk query.

query AmbilProfil {
  user(id: 1) {
    id
    username
    posts {
      title
    }
  }
}

Perhatikan bahwa response akan berupa JSON dengan struktur persis seperti query: objek user berisi id, username, dan array posts yang masing-masing berisi title.

#Query Operation Name

Menamai operasi (query AmbilProfil) adalah praktik wajib untuk production, karena memudahkan logging, debugging, dan pembacaan di Apollo Studio. Operasi yang sama tanpa nama hanya boleh muncul satu kali dalam satu request. Selalu beri nama pada operasi kalian.

#Arguments dan Parameter

Field bisa menerima argument untuk menyaring atau mengubah hasil. Argument bisa wajib (bertanda ! di schema) atau opsional dengan nilai default:

query CariProduk {
  products(category: "elektronik", limit: 10, sort: "termurah") {
    id
    name
  }
}

Aturan penulisan: argument ditulis dalam kurung setelah nama field. Di schema, argument opsional biasanya diberi nilai default (seperti limit: Int = 10) agar client tidak perlu selalu menyebutkannya. Di episode 3 kalian sudah melihat pola ini pada type Query.

#Aliases

Alias memungkinkan memakai field yang sama beberapa kali dalam satu query tanpa konflik nama, atau untuk memberi nama field hasil dengan cara yang berbeda:

query DuaTampilan {
  murah: products(sort: "termurah") {
    id
    name
  }
  populer: products(sort: "terlaris") {
    id
    name
  }
}

Tanpa alias, dua field products dalam satu query akan menabrak aturan unik field. Dengan alias, response menjadi dua objek terpisah: murah dan populer. Alias sangat berguna untuk membandingkan data atau menampilkan banyak varian dari field yang sama.

#Fragments

#Named Fragments dan Composition

Fragment adalah unit field yang bisa dipakai ulang di banyak operasi:

fragment UserBasis on User {
  id
  username
  avatar
}
 
query TampilUser($id: ID!) {
  user(id: $id) {
    ...UserBasis
    email
  }
}

Fragment memungkinkan composition: sebuah fragment bisa memakai fragment lain. Ini menghilangkan duplikasi field dan menjaga konsistensi — satu tempat untuk mengubah definisi field yang sama.

#Fragment Variables dan Type Conditions

GraphQL 2021 menghadirkan fragment arguments sehingga fragment bisa menerima variabel. Dan dengan type condition ... on Type, fragment hanya berlaku untuk tipe tertentu — ini yang dipakai bersama interface dan union seperti yang dibahas di episode 3.

#Variables dan Directives

#Variables

Variabel memisahkan nilai dari teks query, sehingga query bisa dipakai ulang dengan nilai berbeda. Variabel dideklarasikan di blok ($nama: Tipe) dan ditandai $ saat dipakai:

query AmbilPost($id: ID!, $includeAuthor: Boolean!) {
  post(id: $id) {
    id
    title
    author @include(if: $includeAuthor) {
      name
    }
  }
}

Variabel dikirim terpisah dari query sebagai objek JSON: {"id": "1", "includeAuthor": true}. Gunakan tipe non-null untuk variabel wajib, dan beri default value untuk yang opsional. Jangan pernah menyelipkan nilai user langsung ke dalam teks query — selalu pakai variabel untuk keamanan.

#Direktif @include dan @skip

Direktif mengubah eksekusi query secara kondisional. @include(if: Boolean) menyertakan field hanya jika kondisinya benar; @skip(if: Boolean) kebalikannya:

query Post($id: ID!, $tanpaKonten: Boolean!) {
  post(id: $id) {
    id
    title
    body @skip(if: $tanpaKonten)
  }
}

Keduanya sangat berguna untuk UI yang membutuhkan data secara bertahap. Ada juga direktif @deprecated yang menandai field yang akan dihapus — kita bahas detailnya di episode 18. Direktif lain seperti @defer dan @stream akan kalian pelajari di episode 40.

#Penutup

Inti yang harus dibawa pulang:

• Query menentukan bentuk response persis seperti bentuk query.
• Selalu beri operation name untuk kemudahan debugging.
• Argument menyaring dan mengubah hasil; gunakan default value untuk argument opsional.
• Alias memungkinkan pemakaian field yang sama berkali-kali dalam satu query.
• Fragment menghilangkan duplikasi dan bisa di-compose serta diberi type condition.
• Variabel memisahkan nilai dari query; direktif @include dan @skip mengontrol field secara kondisional.

Di episode 5 selanjutnya kalian akan mempelajari mutations untuk create, update, dan delete — struktur mutation, input types yang baik, pola response, eksekusi serial, hingga best practices penamaan dan idempotensi. Data kalian tidak akan hanya bisa dibaca, tapi juga ditulis!