Lesson 2.4: Sort Priority Without Breaking Pagination

The dealership wanted high-priority units — featured listings, new arrivals, price-reduced — to appear at the top of the inventory page regardless of which page the visitor was on. Simple idea. The naive implementation produces a query pattern that doesn't just slow the page down — it makes it unusable.

The situation

The 745-second listing page load was caused by a WP_Query that fetched all inventory posts, sorted them in PHP by a meta value, then used array_slice() to paginate the result. The query retrieved every post to sort them, then threw away most of the results. With 166 units in inventory, that meant 166 queries (one for each unit's meta value) on every page load — the classic N+1 pattern.

This is a surprisingly common WordPress mistake. The WP_Query orderby parameter supports meta values, but without proper setup it either doesn't sort numerically (treats the value as a string, so 10 < 2) or it produces additional subqueries per post.

What I did

Named meta_query clause for MySQL-level sorting

WP_Query's meta_query parameter supports named clauses. A named clause in meta_query can be referenced in the orderby parameter. When you do this, WordPress translates the sort into a single SQL JOIN — MySQL does the sort, no PHP involved, no additional queries.

Named meta_query clause — MySQL-level sort, no N+1

$query = new WP_Query( [
    'post_type'      => '[client]_inventory',
    'post_status'    => 'publish',
    'posts_per_page' => 24,
    'paged'          => max( 1, get_query_var( 'paged' ) ),
    'meta_query'     => [
        'sort_clause' => [
            'key'     => '[client]_sort_priority',
            'type'    => 'NUMERIC',
            'compare' => 'EXISTS',
        ],
    ],
    'orderby'        => [
        'sort_clause' => 'DESC',
        'date'        => 'DESC',
    ],
] );

The 'type' => 'NUMERIC' cast is critical. Without it, WordPress treats the meta value as a string. String sort puts 100 before 20 because 1 < 2 alphabetically. Numeric sort correctly places 100 after 20. This is an easy mistake that silently produces wrong sort order.

The 'compare' => 'EXISTS' clause means posts without this meta key are included (they just sort to the bottom because WP_Query will LEFT JOIN and NULL sorts last DESC). This prevents the query from silently dropping posts that haven't had a sort priority set yet.

The wp_postmeta index check

Even with the named clause, a full table scan on wp_postmeta for 166 units is slow if the meta_key column isn't indexed. The meta_key column has an index by default in WordPress's schema, but hosting providers occasionally restore from backups or migrate databases without preserving index definitions. Verify it:

Verify wp_postmeta index

SHOW INDEX FROM wp_postmeta WHERE Column_name = 'meta_key';

-- If missing, add it:
ALTER TABLE wp_postmeta ADD INDEX meta_key_idx (meta_key(191));

Pagination with paged, not offset

The original implementation used offset to paginate. Offset pagination has a subtle problem with sorted queries: if you sort all posts to get the right order, then offset into that sorted list, MySQL still has to produce the full sorted result set before applying the offset. The work doesn't decrease as you paginate deeper — it stays the same.

WordPress's native pagination with paged and posts_per_page uses LIMIT and OFFSET at the MySQL level, but combined with the named meta_query join, MySQL can use the join to produce only the rows needed for the requested page. The query plan is substantially more efficient.

Correct pagination — paged not offset

// In the query args:
'posts_per_page' => 24,
'paged'          => max( 1, get_query_var( 'paged' ) ),

// After the loop:
wp_reset_postdata(); // Non-optional — resets $post global

// Pagination links:
echo paginate_links( [
    'total'   => $query->max_num_pages,
    'current' => max( 1, get_query_var( 'paged' ) ),
] );

wp_reset_postdata() after a custom WP_Query loop is non-optional. Without it, the global $post object remains set to the last post in your custom query. Any subsequent template code that calls get_the_ID(), the_title(), or similar functions will return data from the wrong post.

Filter and sort parameter passthrough

The inventory page has category filters and sort options. These parameters need to survive pagination — clicking to page 2 should maintain whatever filter and sort the visitor selected on page 1.

Filter parameter passthrough in pagination

$current_filters = [
    'condition' => sanitize_text_field( $_GET['condition'] ?? '' ),
    'make'      => sanitize_text_field( $_GET['make'] ?? '' ),
    'sort'      => sanitize_key( $_GET['sort'] ?? 'priority' ),
];

echo paginate_links( [
    'total'   => $query->max_num_pages,
    'current' => max( 1, get_query_var( 'paged' ) ),
    'add_args' => array_filter( $current_filters ),
] );

Why it matters

The inventory page is the product page. A visitor who hits a 745-second load time doesn't wait — they leave. The fix wasn't a server upgrade or caching layer (though both help); it was eliminating a query pattern that was wrong from the start.

Named meta_query clauses are one of WordPress's least-documented performance features. Most WP developers never encounter them because most sites don't have enough data to make the N+1 pattern's cost visible. A dealership with 166 units hits it immediately. A site with 1,600 listings would be completely unusable.

The Anchor build

The query pattern fix alone brought the inventory page from 745 seconds to under 400ms — a 1,800× improvement from a single change to the query args array. The server didn't change. The hosting didn't change. The data didn't change. The query changed.

The sort priority field gives the sales team direct control over what visitors see first. Units on sale, new arrivals, and high-margin units get a high sort priority in the spreadsheet. The sync writes that value to WordPress. The query sorts by it. The sales team never touches WordPress admin to control the front page of inventory.

Do this, not that

Use named meta_query clauses, not PHP-level sorting. The named clause moves the sort to MySQL. PHP-level sorting requires fetching all records first — that's the N+1 pattern.
Always include 'type' => 'NUMERIC' for numeric sorts. String sort is the default. 100 < 20 as strings. This produces silently wrong sort order with no error output.
Call wp_reset_postdata() after every custom WP_Query loop. Without it, the global $post object is wrong for the rest of the page, and template functions return incorrect data.
Check the wp_postmeta index. The default schema includes it, but migrations and restores sometimes drop it. A missing index means a full table scan on every inventory query.
Use paged and posts_per_page for pagination, not offset. WordPress's native pagination interacts correctly with the named meta_query sort. Manual offset does not.

← Previous Lesson 2.3 — Image Pipelines Module complete → Module 02 — Inventory OS

When you’re ready to build

The lessons are yours. When you want it built, we’re here.

Every lesson stays free — no account, no paywall, no email gate, ever. But if you’d rather have this system standing on your business than wire all 48 lessons yourself, leave your email. We’ll send you a direct line to a build — and you’ll be first to hear when we add new tools to the curriculum.

None of this gates a single lesson. The curriculum was free before you got here and it stays that way.

Done learning how it’s built? We’ll build it.

You came here to understand the system, and now you do. If you’d rather have it standing on your business than spend the next three months wiring it yourself, GAP Concierge is the same architecture from these lessons — a white-label AI agent that knows your catalog and captures your leads — set up for you, from $97/mo.

See GAP Concierge →