The meta query builder lets you filter your query results by custom fields without custom code. Just pick your field name, choose an operator, and type a value.
What is a meta query?
A custom field (also called meta) is an extra piece of data saved on a post, page, product, term, or user. For example, a product might have a custom field called featured with a value of yes. A meta query filters your results based on those fields.
This plugin adds a visual builder so you can set up meta queries inside the block editor, no PHP or code required.
Where to find it
The meta query builder works with all four query types in GB Query Enhancements: Post, Term, User, and WooCommerce. Look for the Meta Query panel in the block’s inspector controls (the sidebar on the right when you select a Query block).
How it is structured
A meta query has two parts: a relation and one or more clauses.
- A clause is one rule. It says: “the field named X must match value Y in this way.”
- The relation decides how multiple clauses work together. It can be AND or OR.
Click Add clause to add more rules. The AND/OR relation control only shows up once you have two or more clauses. The default is AND.
AND vs. OR
- AND: an item must pass every clause to show up. Think of it like a checklist: all boxes must be checked.
- OR: an item only needs to pass at least one clause. Think of it like a multiple-choice question: any correct answer counts.
The four parts of a clause
Each clause has four fields:
- Meta key — the name of the custom field (for example,
featuredorrelease_date). - Operator — how to compare the field to the value (for example, equals, greater than, contains).
- Value — what you are comparing against (for example,
yesor2024-01-01). Some operators do not use this field. - Value type — how WordPress should read the value (as text, a number, a date, and so on).
You can add each as needed using the “Add property…” at the bottom of each clause.
Operators
An operator tells WordPress how to compare the custom field to your value.
| Operator | What it does |
|---|---|
= | Field equals the value exactly. |
!= | Field does not equal the value. |
> | Field is greater than the value. |
>= | Field is greater than or equal to the value. |
< | Field is less than the value. |
<= | Field is less than or equal to the value. |
LIKE | Field contains the value (partial match). |
NOT LIKE | Field does not contain the value. |
IN | Field matches any one of several values you list. |
NOT IN | Field does not match any of the values you list. |
BETWEEN | Field falls between two values you list. |
NOT BETWEEN | Field does not fall between the two values. |
EXISTS | The field is set (has any value). Ignores the value box. |
NOT EXISTS | The field is not set at all. Ignores the value box. |
REGEXP | Field matches a regular expression pattern. |
NOT REGEXP | Field does not match the pattern. |
RLIKE | Same as REGEXP — an alternate name for the same match. |
Tip: IN, NOT IN, BETWEEN, and NOT BETWEEN accept more than one value. The builder splits the values you enter into a list automatically.
Tip: EXISTS and NOT EXISTS only check whether the field is present. You can leave the value box empty when using these operators.
Value types
The value type tells WordPress how to read your value when comparing it. For example, comparing numbers as text can give wrong results (10 sorts before 9 alphabetically). Picking the right type fixes that.
| Value type | What it means |
|---|---|
CHAR | Plain text. This is the default. |
NUMERIC | A whole or decimal number. |
BINARY | Text with exact, case-sensitive matching. |
DATE | A date in YYYY-MM-DD format. |
DATETIME | A date and time (YYYY-MM-DD HH:MM:SS). |
DECIMAL | A precise decimal number (for example, prices). |
SIGNED | A whole number that can be negative. |
TIME | A time value (HH:MM:SS). |
UNSIGNED | A whole number that cannot be negative. |
Worked example
Suppose you are building a product grid. You want to show a product if it is marked as featured or if it has a special badge. Here is how to set that up:
- Set the relation to OR.
- Clause 1: Meta key =
featured| Operator ==| Value =yes| Value type =CHAR - Clause 2: Meta key =
badge| Operator =EXISTS| (leave Value empty) | Value type =CHAR
With OR, a product shows up if it matches clause 1 or clause 2 (or both). Products that are not featured and have no badge are filtered out.
Quick tips
- Make sure your meta key matches the exact name saved in the database. Spelling and uppercase matter.
- Use
NUMERICorDECIMALwhen comparing numbers so sorting and range checks work correctly. - Use
DATEorDATETIMEwhen filtering by date fields so that date comparisons are accurate. - Start with one clause and test before adding more. This makes it easier to spot problems.