Item queries for single entities

Efficient caching lets you deliver content quickly and improves user experience. When fetching single entities in Optimizely Graph, use item queries instead of items to improve cache hit ratios.

In GraphQL, item returns a single result identified by a unique field, while items returns a list.

Prerequisites

Before you implement item queries, confirm you have the following:

• Familiarity with GraphQL queries.
• An active Optimizely Graph endpoint.
• A content model that exposes a unique identifier field (such as RelativePath).

Understand the cache challenge

The flexibility of GraphQL can lead to queries that fetch lists with items. This approach is useful in many scenarios, but it reduces caching efficiency. Even when a query returns only a single item, items requires refreshing the entire list cache when any item in the list changes. This broad cache invalidation lowers performance compared to targeted caching.

Benefits of item queries

The item query lets you implement precision caching by targeting a single item with its unique identifier. When an item changes, only that item's cache entry refreshes instead of the entire list cache. This improves cache efficiency and overall performance.

Example item query

The following code sample shows an item query that retrieves a single item by its RelativePath:

query GetItem($relativePath: String) {  
  Content(where: { RelativePath: { eq: $relativePath } }) {  
    item { Name RelativePath }  
  }  
}

Optimize the cache with item

Follow the recommendations in this section to make item queries deliver the largest gains in cache hit ratio and content freshness. Each item describes when to apply item and how the GraphQL server caches the result.

• Unique-identifier-driven queries – Use item only when retrieving a single item by a unique identifier, such as:
  • Relative paths
  • URLs
  • Segments
  • Code
  • Any other uniquely identifiable field
• ID-based caching and purging – The GraphQL server caches the result of the item query using the returned id of the fetched item. The system purges the cached result only when that item is republished with changes. If other items update, the cached item result remains valid, maximizing cache hits.