Optimizing GraphQL Responses

In WP Engine Smart Search GraphQL API, the includeFields and excludeFields parameters within the options object of a query provide powerful mechanisms for specifying which data should be included or excluded in the query results. This allows you to tailor the response to your application’s needs, optimizing data transfer and improving efficiency.

includeFields

The includeFields parameter is an array of strings, where each string represents a field that you want to include in the results. When includeFields is specified, only the fields listed in this array will be present in the data object of the returned objects. Any fields not listed will be omitted.

excludeFields

Conversely, the excludeFields parameter is also an array of strings, but it specifies the fields that you want to exclude from the results. Any fields listed in excludeFields will not be present in the data object. All fields not in the excludeFields list will be returned.

Using Both includeFields and excludeFields

It’s important to note how includeFields and excludeFields interact when used together:

• If both are provided: includeFields takes precedence. Only the fields specified in includeFields will be returned, and excludeFields will be ignored.

Examples

Let’s revisit your GraphQL queries and see how these parameters are applied:

1. Simple Query

query Simple {
  find(
    query: "*"
    options: { includeFields: ["post_title"], excludeFields: ["post_content"] }
  ) {
    total
    documents {
      score
      id
      data
    }
  }
}

In this query:

• includeFields: ["post_title"] ensures that only the post_title field is included in the data object of each document.
• excludeFields: ["post_content"] attempts to exclude the post_content field. However, because includeFields is also present, excludeFields is effectively ignored.
• The result will contain the post_title, but will not contain post_content.

2. Similarity Query

query Similar {
  similarity(
    input: {
      nearest: { field: "post_content", text: "revenge on a plane" }
      options: {
        includeFields: ["post_title"]
        excludeFields: ["post_content"]
      }
    }
  ) {
    docs {
      score
      id
      data
    }
  }
}

This query behaves similarly to the Simple query:

• It searches for documents similar to ”revenge on a plane" based on the post_content field.
• includeFields: ["post_title"] ensures that only the post_title is included in the result.
• excludeFields: ["post_content"] is ignored because includeFields is present.
• The result will contain the post_title, but not post_content.

Best Practices

• Use includeFields for clarity: It’s generally clearer to use includeFields when you know exactly which fields you need. This avoids any ambiguity.
• Use excludeFields sparingly: excludeFields can be useful when you want most of the fields but only need to exclude a few large or sensitive ones.
• Optimize for performance: By retrieving only the necessary fields, you can reduce the size of the response, leading to faster query execution and reduced network overhead. This is especially important when dealing with large datasets.