Query Functions

Manipula los valores de los campos dentro de la consulta GraphQL, mediante una colección de utilidades y directivas especiales que proporcionan capacidades de meta-programación.

Field to Input

Obtén el valor de un campo, manipúlalo y pásalo como entrada a otro campo, todo dentro de la misma consulta.

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

Iteración y manipulación de valores de campos

Adición de meta-directivas al esquema GraphQL para iterar y manipular los elementos del valor de los campos de tipo array y object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem hace que la directiva anidada se aplique a un elemento específico del array.

En la consulta siguiente, solo el primer elemento del array con los nombres de categoría se transforma a mayúsculas:

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

...produciendo:

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

Campo sobre campo

Adición de la directiva @applyField, para ejecutar un determinado campo sobre el valor del campo resuelto.

Aplicada a algún campo, la directiva @applyField permite ejecutar otro campo (que está disponible en el mismo tipo y se aplica sobre el mismo objeto), y o bien pasar ese valor resultante a otra directiva, o sobrescribir el valor del campo.

En la consulta siguiente, el campo Post.title para el objeto tiene el valor "Hello world!". Al añadir @applyField para ejecutar el campo _strUpperCase:

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

...el valor del campo se transforma a mayúsculas, produciendo:

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

Manipulación condicional de campos

Adición de las meta-directivas @if y @unless al esquema GraphQL, para ejecutar condicionalmente una directiva anidada sobre el campo.

@if ejecuta sus directivas anidadas solo si una condición tiene valor true.

En esta consulta, los usuarios "Leo" y "Peter" ven sus nombres convertidos a mayúsculas, ya que están en el array de "usuarios especiales", mientras que "Martin" no:

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

...produciendo:

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

Valor por defecto del campo

Adición de la directiva @default, para establecer un valor a los campos nulos o vacíos.

En el ejemplo siguiente, cuando una entrada no tiene una imagen destacada, el campo featuredImage devuelve null:

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

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

Usando @default, podemos entonces recuperar una imagen por defecto:

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

Eliminación de la respuesta de un campo

Adición de la directiva @remove al esquema GraphQL, que elimina la salida de un campo de la respuesta.

En la consulta siguiente, generamos la URL para enviar una petición HTTP, concatenando el dominio del sitio y el endpoint de la REST API. Como los valores de estos componentes no nos interesan, no es necesario imprimirlos en la respuesta, y podemos hacer @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
    }
  )
}

...produciendo esta respuesta (observa que los campos siteURL y requestURL han sido eliminados):

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

Disparador de errores en la respuesta

Adición del campo global _fail y la directiva @fail al esquema GraphQL, para añadir explícitamente una entrada a la propiedad errors en la respuesta, y del campo global _warn y la directiva @warn, para añadir una entrada a la propiedad warnings en la respuesta.

El campo _fail añade el error siempre, y la directiva @fail cuando se cumple la condición especificada en el argumento 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"
    )
  }
}