Skip to content
Skills Library
Programming · Review & audit

wp-query-cache

/wp-query-cache

Review and implement WordPress core query-cache usage on WP 6.9+, especially direct interaction with query cache groups now using salted cache helpers. Covers wp_cache_get_salted, wp_cache_set_salted, wp_cache_get_multiple_salted, wp_cache_set_multiple_salted, wp_cache_get_last_changed, affected query groups like post-queries, term-queries, user-queries, comment-queries, site-queries, and why plugins should usually use WP_Query APIs instead of writing query cache entries directly. Use when code touches those core query groups/salts, duplicates WP_Query cache internals, or shows stale/miss beha

Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Review and implement WordPress core query-cache usage on WP 6.9+, especially direct interaction with query cache groups now using salted cache helpers. Covers wp_cache_get_salted, wp_cache_set_salted, wp_cache_get_multiple_salted, wp_cache_set_multiple_salted, wp_cache_get_last_changed, affected query groups like post-queries, term-queries, user-queries, comment-queries, site-queries, and why plugins should usually use WP_Query APIs instead of writing query cache entries directly. Use when code touches those core query groups/salts, duplicates WP_Query cache internals, or shows stale/miss beha

Original author description

Review and implement WordPress core query-cache usage on WP 6.9+, especially direct interaction with query cache groups now using salted cache helpers. Covers wp_cache_get_salted, wp_cache_set_salted, wp_cache_get_multiple_salted, wp_cache_set_multiple_salted, wp_cache_get_last_changed, affected query groups like post-queries, term-queries, user-queries, comment-queries, site-queries, and why plugins should usually use WP_Query APIs instead of writing query cache entries directly. Use when code touches those core query groups/salts, duplicates WP_Query cache internals, or shows stale/miss beha

How it works

  1. When to use this skill
  2. Prefer core query APIs
  3. Salted cache helpers
  4. Affected groups
  5. Invalidation
  6. Upgrade behavior
  7. Critical rules
  8. Common mistakes
  9. Cross-references
  10. What this skill does NOT cover
Original SKILL.md headings · 147 lines, 854 words
SKILL.md preview
---
name: wp-query-cache
description: Review and implement WordPress core query-cache usage on WP 6.9+,
  especially direct interaction with query cache groups now using salted
  cache helpers. Covers wp_cache_get_salted, wp_cache_set_salted,
  wp_cache_get_multiple_salted, wp_cache_set_multiple_salted,
  wp_cache_get_last_changed, affected query
  groups like post-queries, term-queries, user-queries, comment-queries,
  site-queries, and why plugins should usually use WP_Query APIs instead
  of writing query cache entries directly. Use when code touches those core
  query groups/salts, duplicates WP_Query cache internals, or shows stale/miss
  behavior specifically after direct query-cache reads or writes; use the
  database-performance skill for general SQL, transient, OFFSET, or N+1 issues.
metadata:
  wp-skills-author: "Soczó Kristóf"
  wp-skills-contact: "mailto:lonsdale201@hotmail.com"
  wp-skills-plugin: "wordpress"
  wp-skills-plugin-version-tested: "6.9 - 7.1"
  wp-skills-wp-version-tested: "7.1"
  wp-skills-php-min: "7.4"
  wp-skills-last-updated: "2026-08-20"
---

# WordPress Query Cache

WordPress 6.9 changed how query cache groups store invalidation state. Core now uses stable cache keys with stored salts instead of baking changing `last_changed` values into every key. This reduces unreachable cache keys on high-update sites.

This skill is for plugin code that directly reads/writes object-cache entries for query results. Most plugins should not do that.

Do not trigger this skill merely because code uses a transient or has a slow
query; general SQL shape, indexes, pagination, N+1 calls, payload size, and
cache stampedes are out of scope here.

## When to use this skill

Trigger when ANY of the following is true:

- Code directly calls `wp_cache_get()` / `wp_cache_set()` in query groups such as `post-queries`, `term-queries`, `user-queries`, `comment-queries`, `site-queries`, or `network-queries`.
- Code builds cache keys with `wp_cache_get_last_changed()`.
- The task mentions persistent object cache misses, query cache bloat, cache invalidation, or stale query results after updates.
- A plugin duplicates `WP_Query`, `WP_User_Query`, `WP_Term_Query`, or `WP_Comment_Query` cache behavior.

## Prefer core query APIs

Before writing custom cache logic, ask whether the normal query API already caches the result:

- `WP_Query` and helpers for posts.
- `WP_Term_Query` / taxonomy helpers for terms.
- `WP_User_Query` / user helpers for users.
- `WP_Comment_Query` / comment helpers for comments.
- Site/network query classes on multisite.

Direct query-cache writes are a maintenance liability. They couple plugin code to internal cache key formats that changed in WP 6.9.

## Salted cache helpers

Use these only when you deliberately maintain a cache entry whose validity depends on one or more core `last_changed` salts:

```php
$last_changed = wp_cache_get_last_changed( 'posts' );
$cache_key    = 'myplugin:featured_ids:' . md5( wp_json_encode( $args ) );

$ids = wp_cache_get_salted( $cache_key, 'post-queries', $last_changed );
if ( false === $ids ) {
    $ids = myplugin_expensive_featured_post_ids_query( $args );
    wp_cache_set_salted( $cache_key, $ids, 'post-queries', $last_changed, HOUR_IN_SECONDS );
}
```

For data depending on multiple groups, pass an array of salts:

```php
$salt = array(
    wp_cache_get_last_changed( 'posts' ),
    wp_cache_get_last_changed( 'terms' ),
);

$result = wp_cache_get_salted( $cache_key, 'post-queries', $salt );
```

The helper stores an array containing `data` and `salt`. Do not assume the raw cached value is your data when reading entries written by `wp_cache_set_salted()`.

For batches, pair `wp_cache_get_multiple_salted()` with
`wp_cache_set_multiple_salted()`. Their per-key values use the same salt/data
envelope.

Do not cache literal `false` when your code uses `false` as the miss/stale
sentinel: a valid cached `false` is indistinguishable from a miss. `null` is
also unsuitable because the compatibility helper checks the data key with
`isset()`. Wrap such domain values in a non-null array/object.

## Affected groups

Core WP 6.9 uses salted query cache helpers in groups including:

- `post-queries`
- `term-queries`
- `comment-queries`
- `user-queries`
- `site-queries`
- `network-queries`

If old plugin code directly sets any of these groups with `wp_cache_set()`, it can bypass the new salt shape and produce stale reads or misses depending on how the value is later consumed.

## Invalidation

Use WordPress mutation APIs whenever possible. They update the relevant `last_changed` salts through core hooks.

```php
// Good: core updates post caches and last_changed state.
wp_update_post( array(
    'ID'         => $post_id,
    'post_title' => $title,
) );

// Risky: direct SQL bypasses normal cache invalidation.
$wpdb->update( $wpdb->posts, array( 'post_title' => $title ), array( 'ID' => $post_id ) );
```

If you deliberately perform direct SQL, call the correct cache clean function afterwards (`clean_post_cache()`, `clean_term_cache()`, `clean_user_cache()`, etc.) rather than manually setting query group salts.

## Upgrade behavior

After upgrading to WP 6.9, a temporary increase in cache misses is expected because affected query cache keys are different. Do not "fix" this by forcing old keys back. Let the cache warm naturally unless the object-cache backend needs a one-time eviction plan.

## Critical rules

- **Do not write core query groups with plain `wp_cache_set()`** unless you fully control every reader of that key.
- **Do not append `last_changed` to query cache keys in new code.** Use `wp_cache_*_salted()` helpers when direct query caching is justified.
- **Do not read salted entries with raw `wp_cache_get()`** and expect the original data shape.
- **Prefer WP query APIs over direct cache choreography.**
- **Invalidate through core mutation APIs** or the matching `clean_*_cache()` function after direct SQL.

## Common mistakes

```php
// WRONG - old pattern creates unreachable keys as last_changed changes.
$key  = 'my_query:' . md5( $sql ) . ':' . wp_cache_get_last_changed( 'posts' );
$data = wp_cache_get( $key, 'post-queries' );

// RIGHT
$salt = wp_cache_get_last_changed( 'posts' );
$key  = 'my_query:' . md5( $sql );
$data = wp_cache_get_salted( $key, 'post-queries', $salt );

// WRONG - direct set into a core query group with arbitrary shape.
wp_cache_set( $key, $data, 'post-queries' );

// RIGHT - if direct caching is truly needed.
wp_cache_set_salted( $key, $data, 'post-queries', $salt );
```

## Cross-references

- Run **`wp-plugin-options-storage`** when persistent data is being stored in options/transients instead of cache.
- Run **`wp-security-audit`** when direct SQL is part of the cache path.

## What this skill does NOT cover

- Writing a persistent object cache drop-in.
- CDN/page cache invalidation.
- General query optimization unrelated to core query-cache keys.

## References

- WordPress 6.9 query cache dev note: <https://make.wordpress.org/core/2025/11/17/consistent-cache-keys-for-query-groups-in-wordpress-6-9/>
- Salted cache helpers: `wp-includes/cache-compat.php`
- Query cache usage examples: `wp-includes/class-wp-query.php`, `wp-includes/class-wp-term-query.php`, `wp-includes/class-wp-user-query.php`

Versions

The database has no other skills named wp-query-cache.

Database snapshot: 13.11.2026 · package version 1a562b49fcac (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90tanstack-react-query-best-practices
    TanStack Query conventions for cache-backed React server state. Use when creating or reviewing React queries, mutations, query keys, or cache updates.
  • 90tanstack-react-query-best-practices
    TanStack Query conventions for cache-backed React server state. Use when creating or reviewing React queries, mutations, query keys, or cache updates.
  • 100tanstack-query
    Implement, debug, or review modern TanStack Query code using the installed @tanstack query package and adapter. Use for query keys/options, cache freshness, invalidation, cancellation, retries, network modes, mutations and optimism, offline persistence, infinite queries, tracked…
  • 95wp-performance-review
    WordPress performance code review and optimization analysis. Use when reviewing WordPress PHP code for performance issues, auditing themes/plugins for scalability, optimizing WP_Query, analyzing caching strategies, checking code before launch, or detecting anti-patterns, or when…
  • 100wp-metadata-api
    Implements and audits WordPress post, user, term, comment, and generic metadata code, including slashing contracts, revision redirection, multi-row keys, exact meta_id operations, return-value ambiguity, cache and hook behavior, registration/auth schemas, scalar typing, and safe…
  • 90tanstack-svelte-query-best-practices
    TanStack Query conventions for reactive, cache-backed Svelte server state. Use when creating or reviewing Svelte queries, mutations, query keys, or cache updates.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.