Query Functions

จัดการค่าของฟิลด์ภายใน GraphQL queries ด้วยชุดเครื่องมือยูทิลิตี้และ directive พิเศษที่มอบความสามารถด้าน meta-programming

Field to Input

ดึงค่าของฟิลด์ จัดการค่านั้น แล้วส่งเป็น input ไปยังฟิลด์อื่นภายใน queries เดียวกัน

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

การวนซ้ำและจัดการค่าของฟิลด์

เพิ่ม meta directive ลงใน GraphQL schema เพื่อวนซ้ำและจัดการค่าองค์ประกอบของฟิลด์ประเภท array และ object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem ทำให้ directive ที่ซ้อนอยู่ถูกนำไปใช้กับรายการเฉพาะในอาร์เรย์

ใน queries ด้านล่าง เฉพาะรายการแรกในอาร์เรย์ที่มีชื่อหมวดหมู่เท่านั้นที่ถูกแปลงเป็นตัวพิมพ์ใหญ่:

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

...ผลลัพธ์:

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

Field on Field

เพิ่ม directive @applyField เพื่อรันฟิลด์หนึ่งบนค่าที่ฟิลด์ที่ถูก resolve แล้วส่งกลับมา

เมื่อนำไปใช้กับฟิลด์ใดฟิลด์หนึ่ง directive @applyField ช่วยให้สามารถรันฟิลด์อื่น (ที่มีอยู่ในประเภทเดียวกันและนำไปใช้กับ object เดียวกัน) แล้วส่งค่าผลลัพธ์ไปยัง directive อื่น หรือเขียนทับค่าของฟิลด์ได้

ใน queries ด้านล่าง ฟิลด์ Post.title ของ object มีค่าเป็น "Hello world!" เมื่อเพิ่ม @applyField เพื่อรันฟิลด์ _strUpperCase:

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

...ค่าของฟิลด์จะถูกแปลงเป็นตัวพิมพ์ใหญ่ ได้ผลลัพธ์:

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

การจัดการฟิลด์แบบมีเงื่อนไข

เพิ่ม meta directive @if และ @unless ลงใน GraphQL schema เพื่อรัน directive ที่ซ้อนอยู่บนฟิลด์ตามเงื่อนไข

@if จะรัน directive ที่ซ้อนอยู่เฉพาะเมื่อเงื่อนไขมีค่าเป็น true

ใน queries นี้ ผู้ใช้ "Leo" และ "Peter" จะได้ชื่อที่แปลงเป็นตัวพิมพ์ใหญ่ เนื่องจากอยู่ในอาร์เรย์ "special user" ในขณะที่ "Martin" ไม่ได้รับการแปลง:

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

...ผลลัพธ์:

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

ค่าเริ่มต้นของฟิลด์

เพิ่ม directive @default เพื่อกำหนดค่าให้กับฟิลด์ที่เป็น null หรือว่างเปล่า

ในตัวอย่างด้านล่าง เมื่อโพสต์ไม่มีรูปภาพเด่น ฟิลด์ featuredImage จะคืนค่า null:

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

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

ด้วยการใช้ @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"
      }
    }
  }
}

การลบ Response ของฟิลด์

เพิ่ม directive @remove ลงใน GraphQL schema เพื่อลบ output ของฟิลด์ออกจาก response

ใน queries ด้านล่าง เราสร้าง URL สำหรับส่ง HTTP request โดยการต่อ domain ของไซต์และ endpoint ของ REST API เนื่องจากค่าของส่วนประกอบเหล่านี้ไม่จำเป็นสำหรับเรา จึงไม่ต้องแสดงใน response และสามารถใช้ @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
    }
  )
}

...ได้ response ดังนี้ (สังเกตว่าฟิลด์ siteURL และ requestURL ถูกลบออกแล้ว):

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

การกระตุ้น Error ใน Response

เพิ่ม global field _fail และ directive @fail ลงใน GraphQL schema เพื่อเพิ่มรายการลงใน property errors ใน response อย่างชัดเจน รวมถึง global field _warn และ directive @warn เพื่อเพิ่มรายการลงใน property warnings ใน response

ฟิลด์ _fail เพิ่ม error ทุกครั้ง ส่วน directive @fail จะเพิ่ม error เมื่อเงื่อนไขภายใต้ argument condition ถูกตรงตามเงื่อนไข:

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