Query Functions

GraphQL 쿼리 내 필드 값을 조작하기 위한 유틸리티 및 특수 디렉티브 컬렉션입니다. 메타프로그래밍 기능을 제공합니다.

Field to Input

필드의 값을 가져와 조작한 후, 동일한 쿼리 내에서 다른 필드의 입력값으로 전달합니다.

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

필드 값 반복 및 조작

GraphQL 스키마에 메타 디렉티브를 추가하여, 배열 및 객체 필드의 값 요소를 반복하고 조작합니다:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem은 배열 내 특정 항목에 중첩된 디렉티브를 적용합니다.

아래 쿼리에서는 카테고리 이름 배열의 첫 번째 항목만 대문자로 변환됩니다:

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

...결과는 다음과 같습니다:

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

Field on Field

해결된 필드의 값에 대해 특정 필드를 실행하는 @applyField 디렉티브를 추가합니다.

특정 필드에 적용하면, @applyField 디렉티브는 다른 필드(동일한 타입에서 사용 가능하며 동일한 객체에 적용되는)를 실행하고, 그 결과 값을 다른 디렉티브에 전달하거나 필드의 값을 덮어쓸 수 있습니다.

아래 쿼리에서 객체의 Post.title 필드 값은 "Hello world!"입니다. _strUpperCase 필드를 실행하기 위해 @applyField를 추가하면:

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

...필드 값이 대문자로 변환되어 다음 결과가 생성됩니다:

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

조건부 필드 조작

GraphQL 스키마에 메타 디렉티브 @if와 @unless를 추가하여, 조건에 따라 필드에 중첩된 디렉티브를 실행합니다.

@if는 조건이 true인 경우에만 중첩된 디렉티브를 실행합니다.

이 쿼리에서 "Leo"와 "Peter"는 "특별 사용자" 배열에 포함되어 있으므로 이름이 대문자로 변환되지만, "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"
      }
    ]
  }
}

필드 기본값

null이거나 비어 있는 필드에 값을 설정하는 @default 디렉티브를 추가합니다.

아래 예시에서 게시물에 대표 이미지가 없는 경우, 필드 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"
      }
    }
  }
}

필드 응답 제거

GraphQL 스키마에 @remove 디렉티브를 추가하여, 응답에서 필드의 출력을 제거합니다.

아래 쿼리에서는 사이트 도메인과 REST API 엔드포인트를 연결하여 HTTP 요청을 보낼 URL을 생성합니다. 이러한 구성 요소의 값은 필요하지 않으므로 응답에 출력할 필요가 없으며, @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
    }
  )
}

...다음 응답이 생성됩니다(필드 siteURL과 requestURL이 제거된 것을 확인하세요):

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

응답 오류 트리거

GraphQL 스키마에 글로벌 필드 _fail과 디렉티브 @fail을 추가하여 응답의 errors 속성에 명시적으로 항목을 추가하고, 글로벌 필드 _warn과 디렉티브 @warn을 추가하여 응답의 warnings 속성에 항목을 추가합니다.

필드 _fail은 항상 오류를 추가하며, 디렉티브 @fail은 인수 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"
    )
  }
}