Query Functions

Memanipulasi nilai field-field dalam GraphQL query, melalui kumpulan utilitas dan direktif khusus yang menyediakan kemampuan meta-programming.

Field to Input

Dapatkan nilai suatu field, manipulasi, dan masukkan ke field lain, semuanya dalam query yang sama.

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

Iterasi dan Manipulasi Nilai Field

Penambahan meta-direktif ke skema GraphQL, untuk mengiterasi dan memanipulasi elemen nilai dari field bertipe array dan object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem membuat direktif bersarang diterapkan pada item tertentu dari array.

Dalam query di bawah ini, hanya item pertama dalam array berisi nama-nama kategori yang diubah menjadi huruf kapital:

query {
  posts {
    categoryNames
      @underArrayItem(index: 0)
        @strUpperCase
  }
}

...menghasilkan:

{
  "data": {
    "posts": {
      "categoryNames": [
        "NEWS",
        "sports"
      ]
    }
  }
}

Field on Field

Penambahan direktif @applyField, untuk mengeksekusi field tertentu pada nilai field yang telah di-resolve.

Diterapkan pada suatu field, direktif @applyField memungkinkan eksekusi field lain (yang tersedia pada tipe yang sama dan diterapkan pada objek yang sama), dan meneruskan nilai hasilnya ke direktif lain, atau menimpa nilai field tersebut.

Dalam query di bawah ini, field Post.title untuk objek memiliki nilai "Hello world!". Dengan menambahkan @applyField untuk mengeksekusi field _strUpperCase:

{
  post(by: { id: 1 }) {
    title
      @passOnwards(as: "input")
      @applyField(
        name: "_strUpperCase"
        arguments: {
          text: $input
        },
        setResultInResponse: true
      )
  }
}

...nilai field diubah menjadi huruf kapital, menghasilkan:

{
  "data": {
    "post": {
      "title": "HELLO WORLD!"
    }
  }
}

Manipulasi Field Bersyarat

Penambahan meta-direktif @if dan @unless ke skema GraphQL, untuk mengeksekusi direktif bersarang secara kondisional pada field.

@if mengeksekusi direktif-direktif bersarangnya hanya jika kondisi bernilai true.

Dalam query ini, pengguna "Leo" dan "Peter" mendapatkan nama mereka diubah menjadi huruf kapital, karena mereka berada dalam array "pengguna istimewa", sementara "Martin" tidak:

query {
  users {
    name
      @passOnwards(as: "userName")
      @applyField(
        name: "_inArray"
        arguments: {
          value: $userName
          array: ["Leo", "John", "Peter"]
        }
        passOnwardsAs: "isSpecialUser"
      )
      @if(
        condition: $isSpecialUser
      )
        @strUpperCase
  }
}

...menghasilkan:

{
  "data": {
    "users": [
      {
        "name": "LEO"
      },
      {
        "name": "Martin"
      },
      {
        "name": "PETER"
      }
    ]
  }
}

Nilai Default Field

Penambahan direktif @default, untuk menetapkan nilai pada field yang null atau kosong.

Dalam contoh di bawah ini, ketika sebuah post tidak memiliki gambar unggulan, field featuredImage mengembalikan null:

{
  post(by: { id: 1 }) {
    featuredImage {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": null
    }
  }
}

Dengan menggunakan @default, kita kemudian dapat mengambil gambar default:

{
  post(by: { id: 1 }) {
    featuredImage @default(value: 55) {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": {
        "id": 55,
        "src": "http://mysite.com/wp-content/uploads/my-default-image.webp"
      }
    }
  }
}

Penghapusan Field dari Respons

Penambahan direktif @remove ke skema GraphQL, yang menghapus output suatu field dari respons.

Dalam query di bawah ini, kita menghasilkan URL untuk mengirim permintaan HTTP, dengan menggabungkan domain situs dan endpoint REST API. Karena nilai dari komponen-komponen ini tidak diperlukan, tidak perlu mencetaknya dalam respons, dan kita dapat menggunakan @remove:

query {
  siteURL: optionValue(name: "siteurl")
    @remove
 
  requestURL: _sprintf(
    string: "%s/wp-json/wp/v2/comments/11/?_fields=id,content,date",
    values: [$__siteURL]
  )
    @remove
 
  _sendJSONObjectItemHTTPRequest(
    input: {
      url: $__requestURL
    }
  )
}

...menghasilkan respons ini (perhatikan bahwa field siteURL dan requestURL telah dihapus):

{
  "data": {
    "_sendJSONObjectItemHTTPRequest": {
      "id": 11,
      "date": "2020-12-12T04:07:36",
      "content": {
        "rendered": "<p>Btw, I really like this stuff<\/p>\n"
      }
    }
  }
}

Pemicu Error dalam Respons

Penambahan field global _fail dan direktif @fail ke skema GraphQL, untuk secara eksplisit menambahkan entri ke properti errors dalam respons, serta field global _warn dan direktif @warn, untuk menambahkan entri ke properti warnings dalam respons.

Field _fail selalu menambahkan error, dan direktif @fail menambahkannya ketika kondisi pada argumen condition terpenuhi:

query {
  _fail(message: "Some error")
  
  posts {
    featuredImage @fail(
      condition: IS_NULL,
      message: "The post does not have a featured image"
    ) {
      id
      src
    }
  }
  
  users {
    name @fail(
      condition: IS_EMPTY,
      message: "The retrieved user does not have a name"
    )
  }
}