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 для итерации и манипуляции элементами значений полей типов array и object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem применяет вложенную директиву к конкретному элементу массива.

В приведённом ниже запросе только первый элемент массива с именами категорий преобразуется в верхний регистр:

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

...производя:

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

Поле на поле

Добавление директивы @applyField, позволяющей выполнить определённое поле на значении разрешённого поля.

Применённая к некоторому полю, директива @applyField позволяет выполнить другое поле (доступное на том же типе и применяемое к тому же объекту) и либо передать полученное значение следующей директиве, либо переопределить значение поля.

В приведённом ниже запросе поле Post.title объекта имеет значение "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!"
    }
  }
}

Условная манипуляция полями

Добавление мета-директив @if и @unless в схему GraphQL для условного выполнения вложенной директивы над полем.

@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"
      }
    ]
  }
}

Значение поля по умолчанию

Добавление директивы @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"
      }
    }
  }
}

Удаление поля из ответа

Добавление директивы @remove в схему GraphQL, которая удаляет вывод поля из ответа.

В приведённом ниже запросе мы формируем URL для отправки HTTP-запроса, конкатенируя домен сайта и конечную точку REST API. Поскольку значения этих компонентов нас не интересуют, их не нужно выводить в ответе, и мы можем применить к ним @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"
      }
    }
  }
}

Триггер ошибки в ответе

Добавление глобального поля _fail и директивы @fail в схему GraphQL для явного добавления записи в свойство 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"
    )
  }
}