bricks_create_global_query

Phase 4IntermediateComplexity: 6/10
Create a reusable global query

Overview

Create a reusable global query configuration that can be referenced by any element with a query loop across the entire site. Global queries (Bricks v2.1) centralize query settings so you define them once and reuse everywhere.

Supports all four object types: post (WP_Query), term (WP_Term_Query), user (WP_User_Query), and api (external REST API). After creation, any element can reference this query via useGlobalQuery: "<id>" in its query settings. Updating the global query automatically propagates to all referencing elements.

Key Features

Centralized Configuration
Define query settings once. All elements referencing this global query use the same configuration and automatically get updates when the query changes.
Four Object Types
Create global queries for posts/CPTs, taxonomy terms, WordPress users, or external API endpoints — same flexibility as inline queries.
Category Organization
Organize global queries into categories for easy management on sites with many reusable queries.
Complex Query Support
Full support for tax_query, meta_query with AND/OR relations, custom orderby, and API authentication — all saved in a reusable package.

When to Use

Creating a query that will be reused on multiple pages (e.g., "Latest 6 Blog Posts" on homepage and sidebar)
Setting up complex queries with tax_query + meta_query that would be tedious to configure on each element
Establishing consistent query configurations across the site
Building a library of reusable queries for a multi-template site
Prerequisites
Bricks version 2.1 or higher
The queried post type or taxonomy must exist
For API queries: a valid, accessible API endpoint

When NOT to Use

A one-off query that only appears on a single page — use bricks_set_query_loop directly
You need to list existing global queries — use bricks_get_global_queries first
The query needs to be different on each page (e.g., per-page category filtering)

Parameters

12 Total Parameters1 Required11 Optional
labelstringREQUIRED
Display name for the global query (e.g., "Latest Blog Posts", "Featured Products", "Team Members").
categorystringoptional
Category for organizing global queries.
query.objectTypestringoptional
Query object type.
Default: post Values: post, term, user, api
query.post_typestring | string[]optional
[post] Post type(s) to query.
query.posts_per_pagenumberoptional
[post] Number of posts per page.
query.orderbystringoptional
[post/term/user] Field to order results by.
query.orderstringoptional
Sort direction.
Values: ASC, DESC
query.tax_queryarrayoptional
[post] Array of taxonomy filter objects.
query.meta_queryarrayoptional
[post/term/user] Array of meta field filter objects.
query.taxonomystring | string[]optional
[term] Taxonomy name(s) to query.
query.rolestring | string[]optional
[user] User role(s) to filter by.
query.api_urlstringoptional
[api] API endpoint URL.

Code Examples


Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Create and reference a global blog query

Create a reusable "Latest Blog Posts" query and reference it from a query loop element.

JSON
// Step 1: Create the global query
const result = await bricks_create_global_query({
  label: "Latest Blog Posts",
  category: "Blog",
  query: {
    objectType: "post",
    post_type: "post",
    posts_per_page: 6,
    orderby: "date",
    order: "DESC",
    exclude_current_post: true
  }
});
// Returns: { id: "gq_abc123", label: "Latest Blog Posts", ... }

// Step 2: Reference it in any query loop
bricks_set_query_loop({
  page_id: 33,
  element_id: "loop-item-id",
  query: { useGlobalQuery: "gq_abc123" }
});

Common Mistakes


Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
Always check bricks_get_global_queries first to see if a similar query already exists. Creating duplicates defeats the purpose of centralized management.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
After creating a global query, you must use its ID in bricks_set_query_loop via useGlobalQuery. Creating the global query alone does not attach it to any element.

Tips & Warnings

Tips & Warnings

Use descriptive labels like « Latest 6 Blog Posts » or « Featured Products (In Stock) » so the query purpose is clear when browsing the global queries list.

Organize with categories on sites with many global queries. Common categories: « Blog », « Products », « Team », « Portfolio ».

Update propagation: When you update a global query with bricks_update_global_query, all elements referencing it automatically use the new settings on the next page load.

Return Values

FieldTypeDescription
idstringThe unique ID of the created global query. Use this in bricks_set_query_loop via useGlobalQuery.
labelstringThe display name of the query.
queryobjectThe full query configuration as stored.

Related Tools

Technical Details

Tool ID
bricks_create_global_query
API Endpoint
/bricks-mcp/v1/design-system/global-queries
HTTP Method
POST
Namespace
content-queries
Source File
content/global-queries.ts
Version
1.0
Min Bricks Version
2.1
Requires Auth
Yes

Changelog

v1.0
Initial release with Bricks v2.1 global queries
20250101