bricks-global-queries

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Requires: Bricks 2.4+ with the Abilities API enabled

要求： 启用Abilities API的Bricks 2.4及以上版本

Update check

更新检查

Run first when filesystem tools are available:

bash

_BS_UPDATE_CHECK=""
for _CAND in "$HOME/.bricks/skills/bricks-skills/scripts/bricks-skills-update-check" "$PWD/scripts/bricks-skills-update-check" "$HOME/.claude/skills/bricks-skills/scripts/bricks-skills-update-check" "$HOME/.codex/skills/bricks-skills/scripts/bricks-skills-update-check"; do
  [ -f "$_CAND" ] && _BS_UPDATE_CHECK="$_CAND" && break
done
[ -n "$_BS_UPDATE_CHECK" ] && sh "$_BS_UPDATE_CHECK" || true

If it prints

BRICKS_SKILLS_UPDATE_AVAILABLE <old> <new> <tag>

, load bricks-skills-update before continuing. If it prints

BRICKS_SKILLS_JUST_UPDATED <old> <new>

, mention the new version and continue.

当文件系统工具可用时，首先运行以下命令：

bash

_BS_UPDATE_CHECK=""
for _CAND in "$HOME/.bricks/skills/bricks-skills/scripts/bricks-skills-update-check" "$PWD/scripts/bricks-skills-update-check" "$HOME/.claude/skills/bricks-skills/scripts/bricks-skills-update-check" "$HOME/.codex/skills/bricks-skills/scripts/bricks-skills-update-check"; do
  [ -f "$_CAND" ] && _BS_UPDATE_CHECK="$_CAND" && break
done
[ -n "$_BS_UPDATE_CHECK" ] && sh "$_BS_UPDATE_CHECK" || true

如果输出

BRICKS_SKILLS_UPDATE_AVAILABLE <旧版本> <新版本> <标签>

，请先加载bricks-skills-update再继续。如果输出

BRICKS_SKILLS_JUST_UPDATED <旧版本> <新版本>

，则提及新版本并继续。

Bricks: global queries (via MCP)

Bricks：全局查询（通过MCP）

A global query is a named, reusable query definition stored at the site level. Multiple loop/filter elements can reference the same global query by ID instead of duplicating args. Useful when the query is complex (ACF meta filters, taxonomy unions, custom SQL) and reused across templates.

Storage:

bricks_global_queries

(query rows with

id

name

category

, and

settings

) +

bricks_global_queries_categories

(category rows with

id

and

name

for the builder UI grouping).

全局查询是存储在站点级别的命名可复用查询定义。多个循环/筛选元素可通过ID引用同一个全局查询，无需重复参数。当查询逻辑复杂（如ACF元数据筛选、分类联合、自定义SQL）且需要在多个模板中复用时，这一功能非常实用。

存储方式：

bricks_global_queries

（包含

id

、

name

、

category

和

settings

的查询行） +

bricks_global_queries_categories

（用于构建器UI分组的包含

id

和

name

的分类行）。

Abilities

功能接口（Abilities）

bricks/list-global-queries
: summary rows plus category list.
bricks/get-global-query
:
```
{ queryId }
```
. Full query object.
bricks/create-global-query
:
```
{ label, category?, query }
```
. Returns
```
{ query }
```
. The API accepts
```
label
```
and
```
query
```
, then stores them in Bricks as
```
name
```
and
```
settings
```
. The optional
```
category
```
is a category ID, not a label.

bricks/update-global-query
:

{ queryId, label?, category?, query? }

. If

query

is provided, it replaces the whole query settings object.

bricks/delete-global-query
:
```
{ queryId }
```
. Does not unlink referencing elements: those keep the dangling id and fall back to their local query or render empty.

bricks/create-global-query-category
:

{ name }

. Returns

{ category }

bricks/delete-global-query-category
:
```
{ categoryId }
```
. Queries in that category are kept and become uncategorized.

bricks/list-global-queries
：返回查询摘要行及分类列表。
bricks/get-global-query
：参数
```
{ queryId }
```
，返回完整的查询对象。
bricks/create-global-query
：参数
```
{ label, category?, query }
```
，返回
```
{ query }
```
。该API接受
```
label
```
和
```
query
```
，并将其作为
```
name
```
和
```
settings
```
存储在Bricks中。可选参数
```
category
```
是分类ID，而非分类标签。

bricks/update-global-query
：参数

{ queryId, label?, category?, query? }

。如果提供

query

，则会替换整个查询设置对象。

bricks/delete-global-query
：参数
```
{ queryId }
```
。不会解除与引用元素的关联：这些元素会保留无效ID，并回退到本地查询或渲染为空。

bricks/create-global-query-category
：参数

{ name }

，返回

{ category }

。

bricks/delete-global-query-category
：参数
```
{ categoryId }
```
。该分类下的查询会被保留，但变为未分类状态。

Query shape

查询结构

Same shape as an inline query on a loop element:

{
  objectType: "post",      // "post" | "term" | "user"
  postType: ["post"],
  posts_per_page: 6,
  orderby: "date",
  order: "DESC",
  meta_query: [ ... ],
  tax_query: [ ... ]
}

objectType

lives inside the

query

object. Common values are

post

term

user

, and

array

; Query API flows can also use

api

. For

post

term

, and

user

, it decides which Bricks query runner handles the args and which hooks fire (

bricks/posts/query_vars

bricks/terms/query_vars

bricks/users/query_vars

). The ability stores the query object as provided and does not narrow

objectType

itself (

includes/abilities/queries.php:123-142

与循环元素上的内联查询结构相同：

{
  objectType: "post",      // "post" | "term" | "user"
  postType: ["post"],
  posts_per_page: 6,
  orderby: "date",
  order: "DESC",
  meta_query: [ ... ],
  tax_query: [ ... ]
}

objectType

位于

query

对象内部。常见值为

post

、

term

、

user

和

array

；Query API流程还可使用

api

。对于

post

、

term

和

user

，它决定由哪个Bricks查询运行器处理参数，以及触发哪些钩子（

bricks/posts/query_vars

bricks/terms/query_vars

bricks/users/query_vars

）。功能接口会按原样存储查询对象，不会自行限制

objectType

（见

includes/abilities/queries.php:123-142

）。

Binding to a loop

绑定到循环元素

An element consuming a global query stores its id in

settings.query.id

query:
  id: "abc123"    // presence of this makes Bricks load the global query settings
  # inline args are ignored when id points to a valid global query

Write this through

bricks/update-element

on the target element; the query runner resolves the id at render time.

使用全局查询的元素会在

settings.query.id

中存储其ID：

query:
  id: "abc123"    // 存在该ID时，Bricks会加载全局查询设置
  # 当ID指向有效的全局查询时，内联参数会被忽略

通过对目标元素调用

bricks/update-element

来写入此配置；查询运行器会在渲染时解析ID。

分类

Categories are pure UI: they group queries in the builder's dropdown. Write shape:

bricks/update-global-query
  queryId: abc123
  category: "cat_abc"

If you need a new category, call

bricks/create-global-query-category

first and pass the returned category ID into

create-global-query

update-global-query

. Passing a new label as

category

is wrong; the current schema expects a category ID.

分类仅用于UI：在构建器的下拉菜单中对查询进行分组。写入格式：

bricks/update-global-query
  queryId: abc123
  category: "cat_abc"

如果需要新分类，请先调用

bricks/create-global-query-category

，并将返回的分类ID传入

create-global-query

或

update-global-query

。传入新标签作为

category

是错误的；当前架构要求传入分类ID。

Tool availability

工具可用性

If a
bricks/*
ability is not available as a direct tool: first check whether it is outside the fast path and call it through
mcp-adapter-execute-ability
with
ability_name: "bricks/<name>"
. If the dispatcher also rejects it, call
bricks-list-ability-status
to check whether a site admin disabled it under Bricks > AI.

如果
bricks/*
功能接口无法作为直接工具使用：首先检查它是否不在快速路径中，然后通过
mcp-adapter-execute-ability
调用它，参数为
ability_name: "bricks/<name>"
。如果调度器也拒绝调用，请调用
bricks-list-ability-status
检查站点管理员是否在Bricks > AI下禁用了该功能。

Typical flow: reusable "Featured Products" query

典型流程：可复用的“精选产品”查询

bricks/create-global-query-category { name: "Shop" }
  -> { category: { id: "cat_abc", name: "Shop" } }

bricks/create-global-query
  label: "Featured Products"
  category: "cat_abc"
  query:
    objectType: "post"
    postType: ["product"]
    posts_per_page: 8
    meta_query:
      - { key: "_featured", value: "yes" }
  -> { query: { id: "fp_8h2", name: "Featured Products", category: "cat_abc", settings: {...} } }

bricks/create-global-query-category { name: "Shop" }
  -> { category: { id: "cat_abc", name: "Shop" } }

bricks/create-global-query
  label: "Featured Products"
  category: "cat_abc"
  query:
    objectType: "post"
    postType: ["product"]
    posts_per_page: 8
    meta_query:
      - { key: "_featured", value: "yes" }
  -> { query: { id: "fp_8h2", name: "Featured Products", category: "cat_abc", settings: {...} } }

Now bind it to an existing Products Loop element:

现在将其绑定到现有的产品循环元素：

bricks/update-element postId: 42 elementId: "loop-xyz" settings: query: id: "fp_8h2"


All future edits to "Featured Products" propagate to every element whose `settings.query.id` references that global query.

bricks/update-element postId: 42 elementId: "loop-xyz" settings: query: id: "fp_8h2"


未来对“精选产品”查询的所有编辑都会同步到所有`settings.query.id`引用该全局查询的元素。

Cross-context notes

跨上下文注意事项

Global queries respect element-specific context. If the element lives in a single-post template,
```
get_the_ID()
```
inside query filters still resolves to the current post: the global query is the args, not the context.
```
bricks/posts/query_vars
```
filter fires for global queries exactly as it does for inline ones. Match on the calling element id, not the query id, if you need to branch per-consumer.

全局查询会尊重元素特定的上下文。如果元素位于单篇文章模板中，查询筛选器内的
```
get_the_ID()
```
仍会解析为当前文章：全局查询仅提供参数，而非上下文。
```
bricks/posts/query_vars
```
钩子针对全局查询的触发方式与内联查询完全相同。如果需要根据使用方进行分支，请匹配调用元素的ID，而非查询ID。

Don't

注意事项

Don't delete a global query without first replacing or clearing references. Query-list controls on elements silently fall back when the id is missing, and that's hard to spot in a big site.
Don't embed element-specific context in a global query (e.g., a hard-coded post id). Use dynamic tags (
```
{post_id}
```
) or the
```
bricks/posts/query_vars
```
hook so the query stays reusable.
Do not treat the category field as load-bearing beyond UI organization. It is a category ID that points to a display label; it is not a permission or routing key.

请勿在未替换或清除引用的情况下删除全局查询。元素上的查询列表控件在ID缺失时会静默回退，这在大型站点中很难发现。
请勿在全局查询中嵌入元素特定的上下文（如硬编码的文章ID）。使用动态标签（
```
{post_id}
```
）或
```
bricks/posts/query_vars
```
钩子，确保查询保持可复用性。
请勿将分类字段视为UI组织之外的关键功能。它是指向显示标签的分类ID，而非权限或路由键。