How to Customize Property Queries Using WordPress Filter

WP Residence Query 2026 – WordPress Filters Reference

Starting with version 5.4.1, the WP Residence theme includes a new property query engine called Query 2026.
This engine handles all estate_property database queries across the theme, including property listing pages,
map views, dashboard listings, and featured property widgets.

To give child theme developers full control over query behavior, the Query 2026 engine exposes
7 WordPress filters (apply_filters hooks) at key points in the query pipeline.
These filters allow you to customize how properties are queried, filtered, sorted, and returned —
all without modifying the parent theme files or overriding entire functions.

All 7 filters are pass-through safe. This means that if no child theme or plugin registers
a callback for a filter, the original value passes through unchanged and the theme behaves exactly as it does
out of the box. You only need to hook into the filters you want to customize.

How the Query Pipeline Works

Every time the theme needs to load properties, it calls the central function
wpestate_query_2026_property(). This function runs through a series of steps to build and
execute a WP_Query. The 7 filters are placed at natural boundaries between these steps,
so you can intercept and modify data at any stage.

Here is the order in which the pipeline runs and where each filter fires:

Step 1: Build context defaults           → Filter #1: wpestate_query_2026_context_defaults
Step 2: Normalize and sanitize params    → Filter #2: wpestate_query_2026_params
Step 3-7: Build pagination, order, featured priority
Step 8: Build taxonomy query clauses     → Filter #3: wpestate_query_2026_tax_query
Step 9-10: Build meta query clauses      → Filter #4: wpestate_query_2026_meta_query
Step 11-14: Assemble final WP_Query args → Filter #5: wpestate_query_2026_args
Step 15: Execute the WP_Query
Step 16: Format the result               → Filter #6: wpestate_query_2026_result

When properties are loaded via a search form submission, the search parameters go through
a separate parsing function first. That function has its own filter:

Parse search form $_GET data             → Filter #7: wpestate_query_2026_search_params
Then the parsed params are fed into wpestate_query_2026_property(), triggering filters #1 through #6.

Complete Filter List

#	Filter Name	Source File	What It Does
1	wpestate_query_2026_context_defaults	wpestate_query_2026_property.php	Change the base default values (posts per page, sort order, fields mode) before they are merged with the caller’s parameters.
2	wpestate_query_2026_params	wpestate_query_2026_property.php	Modify the fully normalized parameter array before any WP_Query arguments are built. This is the most versatile filter.
3	wpestate_query_2026_tax_query	wpestate_query_2026_property_placeholders.php	Add, remove, or modify taxonomy query clauses (property categories, cities, areas, statuses, features, or custom taxonomies).
4	wpestate_query_2026_meta_query	wpestate_query_2026_property.php	Add, remove, or modify meta query clauses (price ranges, bedrooms, bathrooms, custom fields, or any post meta).
5	wpestate_query_2026_args	wpestate_query_2026_property.php	Modify the complete, final WP_Query arguments array right before the query is executed. Last chance to change anything.
6	wpestate_query_2026_result	wpestate_query_2026_property.php	Inspect or modify the result after the query has executed. Useful for logging, analytics, or replacing results with data from an external source.
7	wpestate_query_2026_search_params	wpestate_query_2026_prepare_search_arguments.php	Modify parameters that were parsed from a search form submission, before they are passed into the main query function.

How to Use These Filters in Your Child Theme

All filters are registered using the standard WordPress add_filter() function.
Place your filter callbacks in your child theme’s functions.php file.

The general pattern looks like this:

<?php
/**
 * Example: Hook into a Query 2026 filter from a child theme.
 * Replace 'filter_name' with the actual filter name from the table above.
 * Replace 'N' with the number of arguments the filter passes (see individual filter docs).
 */
add_filter( 'wpestate_query_2026_filter_name', 'my_child_theme_callback', 10, N );
function my_child_theme_callback( $value_to_filter, $additional_args ) {
    // Your custom logic here.
    // Always return the filtered value.
    return $value_to_filter;
}

Understanding the Context Parameter

Most filters receive a $context parameter as one of their arguments. This string tells you
which part of the theme triggered the query. The four possible values are:

'directory' — Property listing pages (the main property archive, property list page templates). This is the most common context.
'map' — Map pin queries. These typically fetch only post IDs for fast rendering and may load hundreds of results.
'dashboard' — The front-end user dashboard where agents and property owners manage their listings.
'featured' — Featured property widgets and shortcodes that display a small number of highlighted listings.

You can use this parameter inside your filter callback to apply your customization only to specific
pages. For example, you might want to change the number of results only on map pages, or add a
meta filter only on the dashboard. If you do not check the context, your filter will apply to
all property queries across the entire site.

Important Notes

Always return the filtered value. Every filter expects you to return the modified
(or unmodified) value. If your callback does not return anything, the value will become
null and the query will break.
Do not remove required keys. The pipeline expects certain keys to exist in
$params and $args at each stage. You can change their values, but do not
unset keys like post_type, post_status, or posts_per_page.
The $options parameter is read-only. Several filters pass the caller’s
$options array for reference. Modifying this array inside a filter has no effect on
the pipeline — it is provided only so you can read caller flags like
respect_custom_order_zero.
Performance matters. These filters fire on every property query, including AJAX
requests. Avoid running expensive operations (HTTP API calls, heavy database queries) inside filter
callbacks unless you are targeting a specific context and have caching in place.

Where the Query 2026 Engine is Used

The following table shows every location in the theme where the Query 2026 engine is called.
This helps you understand which features your filters will affect. When you hook into a filter,
your callback will fire for all of these call sites (unless you use the
$context parameter to target specific ones).

Property Listing Pages (context: ‘directory’)

Feature	File	Description
Property List page template	page-templates/property_list.php	The main property listing page template. Displays a paginated grid or list of properties with sorting and filtering.
Property List Half Map page template	page-templates/property_list_half.php	The split-screen layout with a property list on one side and an interactive map on the other.
Taxonomy archive pages	taxonomy.php	Archive pages for property taxonomies (e.g. browsing all properties in a city, category, or status).
Advanced Search Results	page-templates/advanced_search_results.php	The search results page displayed after a visitor submits the advanced search form. Also calls wpestate_query_2026_prepare_search_arguments() to parse the search form data (triggering filter #7).
Directory functions helper	libs/directory_functions/directory_functions.php	Shared directory query logic used by property list page templates.

AJAX Property Queries (context: ‘directory’)

Feature	File	Description
AJAX filter listings	libs/ajax_functions_property_query.php	Handles AJAX requests when visitors change filters on property listing pages (category, city, price range, etc.) without a full page reload.
AJAX advanced search filters	libs/ajax_functions_property_query.php	Handles AJAX re-sorting of search results when a visitor changes the sort order on the results page.
AJAX custom advanced search	libs/ajax_functions_property_query.php	Handles AJAX requests from the custom advanced search form (type 2), which sends taxonomy and meta filters directly.
AJAX default search	libs/ajax_functions_property_query.php	Handles AJAX requests from the default advanced search form (type 1), including taxonomy filters, price, bedrooms, bathrooms, and geolocation.

Map Pin Queries (context: ‘map’)

Feature	File	Description
On-demand pin loading	libs/pin_management.php	Loads map pins dynamically when the map viewport changes or when filters are applied. Returns only post IDs for fast rendering.
Full pin loading with cache	libs/pin_management.php	Loads all map pins for the initial map view with optional transient caching. Used for property list and half-map page templates.
AJAX on-demand pins (custom search)	libs/ajax_functions_property_query.php	Handles AJAX requests for map pins when visitors use the custom advanced search form. Returns marker JSON data.
AJAX on-demand pins (default search)	libs/ajax_functions_property_query.php	Handles AJAX requests for map pins when visitors use the default search form or change filters on the half-map page.

Dashboard (context: ‘dashboard’)

Feature	File	Description
Dashboard property list	libs/dashboard_functions/dashboard_functions.php	Displays the paginated list of properties on the front-end agent/owner dashboard. Agents see their own listings; admins see all listings.

Featured Properties (context: ‘featured’)

Feature	File	Description
Similar listings	templates/listing_templates/property-page-templates/similar_listings.php	Displays the “Similar Listings” section at the bottom of a single property page. Finds properties in the same category and city as the current property.

Search Form Parsing (filter #7 only)

Feature	File	Description
Advanced Search Results page	page-templates/advanced_search_results.php	Calls wpestate_query_2026_prepare_search_arguments() to convert raw $_GET search form data into canonical parameters. This is the only call site that triggers the wpestate_query_2026_search_params filter (#7).

Which Filter Should You Use?

Here is a quick decision guide to help you choose the right filter for your use case:

I want to…	Use this filter
Change the default number of properties shown per page	wpestate_query_2026_context_defaults (#1)
Exclude specific property IDs from all queries	wpestate_query_2026_params (#2)
Force a specific taxonomy (e.g. only show “for-sale”)	wpestate_query_2026_params (#2)
Add a custom taxonomy clause (e.g. building_type)	wpestate_query_2026_tax_query (#3)
Add a meta filter (e.g. year_built, energy_class)	wpestate_query_2026_meta_query (#4)
Add a date_query or change post_status	wpestate_query_2026_args (#5)
Log queries or track search analytics	wpestate_query_2026_result (#6)
Map a custom search form field to a query parameter	wpestate_query_2026_search_params (#7)