Home / / How to Add Custom Field Filters to Property Queries

How to Add Custom Field Filters to Property Queries

50 views

Filter: wpestate_query_2026_meta_query

This filter gives you direct access to the meta query clauses that the Query 2026
engine has built. Meta queries are the part of a WordPress database query that filters posts by their
custom field (post meta) values — for example, filtering properties by price range, number of
bedrooms, property size, or any custom field you have defined.

The filter fires after the engine has finished building all meta clauses from the caller’s parameters
(including price ranges, bedroom/bathroom counts, agent filters, featured-only flags, custom fields
from theme options, and any raw pass-through clauses), but before the
'relation' key is added. You can add your own clauses, modify existing ones, or remove
clauses you do not want.

When Does This Filter Fire?

This filter fires inside the main orchestrator function wpestate_query_2026_property(),
after Step 10 (custom fields meta clauses have been merged with standard meta clauses) and before
Step 11 (where the 'relation' key is added and the clauses are assigned to
$args['meta_query']).

Source file: libs/query/query2026/wpestate_query_2026_property.php

Filter Signature

$meta_clauses = apply_filters( 'wpestate_query_2026_meta_query', $meta_clauses, $params, $context );

Parameters

Parameter Type Description
$meta_clauses array A flat array of individual meta query clause arrays. Each element is a standard WordPress
meta_query clause with keys like ‘key’, ‘value’,
‘compare’, and ‘type’. This is the value you must return from
your callback function.
$params array The normalized parameter array. Provided as a read-only reference so you can check what
filters are active. Modifying $params here has no effect on the query.
$context string The query context: ‘directory’, ‘map’,
‘dashboard’, or ‘featured’. Use this to apply your changes
only to specific page types.

What the meta_clauses Array Looks Like

When this filter fires, the $meta_clauses array is a flat list of
individual clause arrays. The 'relation' key has not been added yet —
the pipeline adds it in the next step based on the meta_relation parameter. Here is an
example of what the array might look like when a visitor has filtered by price (100,000–500,000)
and minimum 2 bedrooms: 

array(
    array(
        'key'     => 'property_price',
        'value'   => array( 100000, 500000 ),
        'type'    => 'NUMERIC',
        'compare' => 'BETWEEN',
    ),
    array(
        'key'     => 'property_bedrooms',
        'value'   => 2,
        'type'    => 'NUMERIC',
        'compare' => '>=',
    ),
)

If no meta filters were applied by the user, the $meta_clauses array will be empty.

Child Theme Examples

Example 1: Filter Properties by Year Built on the Dashboard

If your properties have a custom field called year_built and you want the dashboard to
only show properties built after 2010: 

<?php
/**
 * Only show properties built after 2010 on the dashboard.
 *
 * This assumes your properties have a custom field with the meta key 'year_built'
 * that stores a numeric year value (e.g. 2015, 2020).
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_meta_query', 'my_child_dashboard_year_filter', 10, 3 );
function my_child_dashboard_year_filter( $meta_clauses, $params, $context ) {
    // Only apply this filter on the dashboard.
    if ( 'dashboard' !== $context ) {
        return $meta_clauses;
    }

    $meta_clauses[] = array(
        'key'     => 'year_built',
        'value'   => 2010,
        'type'    => 'NUMERIC',
        'compare' => '>=',
    );

    return $meta_clauses;
}

Example 2: Filter Properties by Agency on Directory Pages

If you want directory listing pages to only show properties assigned to a specific agency
(for example, agency with post ID 55): 

<?php
/**
 * Only show properties from agency ID 55 on directory listing pages.
 *
 * The 'property_agency' meta key stores the agency post ID assigned to each property.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_meta_query', 'my_child_agency_filter', 10, 3 );
function my_child_agency_filter( $meta_clauses, $params, $context ) {
    if ( 'directory' !== $context ) {
        return $meta_clauses;
    }

    $meta_clauses[] = array(
        'key'     => 'property_agency',
        'value'   => 55,
        'type'    => 'NUMERIC',
        'compare' => '=',
    );

    return $meta_clauses;
}

Example 3: Filter Properties by Energy Class

If your properties have an “energy_class” custom field and you want to show only properties rated
A or B across all contexts: 

<?php
/**
 * Only show properties with energy class A or B.
 *
 * This uses the IN comparison operator to match multiple values.
 * The 'CHAR' type is used because energy class values are text strings, not numbers.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_meta_query', 'my_child_energy_class', 10, 3 );
function my_child_energy_class( $meta_clauses, $params, $context ) {
    $meta_clauses[] = array(
        'key'     => 'energy_class',
        'value'   => array( 'A', 'B' ),
        'compare' => 'IN',
        'type'    => 'CHAR',
    );
    return $meta_clauses;
}

Example 4: Remove Price Filters From Featured Widget Queries

If your featured property widgets should display all featured listings regardless of price (even if
a price filter was somehow applied), you can remove price-related clauses: 

<?php
/**
 * Remove any price range filters from featured widget queries.
 *
 * This scans the meta_clauses array and removes any clause where the key
 * is 'property_price'. All other meta filters (bedrooms, bathrooms, etc.)
 * are preserved.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_meta_query', 'my_child_no_price_on_featured', 10, 3 );
function my_child_no_price_on_featured( $meta_clauses, $params, $context ) {
    // Only apply to featured widget queries.
    if ( 'featured' !== $context ) {
        return $meta_clauses;
    }

    // Remove any clause targeting the property_price meta key.
    $meta_clauses = array_filter( $meta_clauses, function( $clause ) {
        return ! isset( $clause['key'] ) || 'property_price' !== $clause['key'];
    } );

    // Re-index the array to prevent gaps in numeric keys.
    return array_values( $meta_clauses );
}

Important Notes

  • The 'relation' key is added after this filter. You do not need to
    set 'relation' in the meta_clauses array. The pipeline automatically adds it in the
    next step, using the value of $params['meta_relation'] (which defaults to
    'AND'). If you need to change the relation from AND to OR, use the
    wpestate_query_2026_params filter and set
    $params['meta_relation'] = 'OR'.
  • Removing all clauses is safe. If your callback removes every clause from the
    array (so it becomes empty), the pipeline will simply skip the meta_query argument
    entirely. The query will still work — it just will not filter by any custom field values.
  • Each clause follows the standard WordPress meta_query format.
    Every clause is an associative array with these keys:

    • 'key' — The meta key (custom field name) to filter by.
    • 'value' — The value to compare against. Can be a single value or an array (for BETWEEN or IN comparisons).
    • 'compare' — The comparison operator: '=', '>=', '<=', 'BETWEEN', 'LIKE', 'IN', 'NOT IN', etc.
    • 'type' — The value type for casting: 'NUMERIC', 'CHAR', 'DATE', etc.
  • The $params parameter is read-only. You can read values from it
    to make conditional decisions, but modifying it here has no effect on the query. To modify
    params, use the wpestate_query_2026_params filter.