kibana-context-engine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Query Context Engine AI Indices

查询 Context Engine AI Index

Environment Configuration

环境配置

This skill executes Elasticsearch operations through the

elastic

CLI. If the

elastic

CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g.,

GET /

GET /_cat/indices

GET /{index}/_mapping

GET /{index}/_settings/index.mode

POST /_query

). The Operations table at the end of this document maps each shorthand to the equivalent

elastic

CLI command — always use the CLI rather than calling the HTTP API directly.

此 skill 通过

elastic

CLI 执行 Elasticsearch 操作。如果尚未安装

elastic

CLI，请告知用户安装它是必需的。不要猜测凭据、直接调用 HTTP API，也不要尝试其他变通方案。

此 skill 中的操作采用 HTTP 简写形式（例如，

GET /

、

GET /_cat/indices

、

GET /{index}/_mapping

、

GET /{index}/_settings/index.mode

、

POST /_query

）。本文档末尾的操作表将每种简写映射到对应的

elastic

CLI 命令——始终使用 CLI，不要直接调用 HTTP API。

Concepts

概念

AI Index — an Elasticsearch index named

ai-index-idx-*

, or a data stream named

ai-index-ds-*

, registered with the Context Engine under a logical id. The registration lives in Kibana; the knowledge lives in the backing index. Only the list operation knows which

ai-index-*

indices are registered and what to put in

FROM

; the index name alone does not tell you.

Knowledge Indicator (KI) — one document in an AI Index: context prepared for agents, such as a description of some data, a summary, an access pattern, a runnable query, or a record of a Kibana resource. A KI may answer a question outright, or help you locate and use the source that does.

A KI is retired by a tombstone (

governance.lifecycle.status: deleted

) or by an

expires_at

in the past. On a data stream, one KI is several revisions under the same

id

, the newest of which is its current state. The query API returns only current, active, unexpired KIs unless the query asks otherwise (see Lifecycle).

Search the AI Indices before broader retrieval whenever their KIs may cover the question. This skill reads KIs; generating them belongs to the Context Engine's automations and feedback loop.

Three read-only Context Engine HTTP APIs back this skill. The Operations table maps each to its

elastic

CLI command:

Operation HTTP API (shorthand) Input Returns

List

Operation	HTTP API (shorthand)	Input	Returns
List	`GET kbn:/api/context_engine/ai_index`	—	`{ ai_indices: [{ id, description, managed, dest: { type, value } }] }`
Describe	`GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe`	`aiIndexId` in the path	`{ response }` , a free-form context block (fields, counts, examples)
Query	`POST kbn:/api/context_engine/ai_index/_query`	`{ query, params?, limit? }`	`{ columns, values }` , ES\|QL rows

GET kbn:/api/context_engine/ai_index

—

{ ai_indices: [{ id, description, managed, dest: { type, value } }] }

Describe

GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe

aiIndexId

in the path

{ response }

, a free-form context block (fields, counts, examples)

Query

POST kbn:/api/context_engine/ai_index/_query

{ query, params?, limit? }

{ columns, values }

, ES|QL rows

Use them in this order: list → describe → query. Never guess an index id, a

FROM

target, or a field name; describe supplies all three. Nothing else can read an AI Index correctly: a generic ES|QL query (

POST /_query

) or index listing neither knows which indices are registered nor applies the space scoping.

Every call is scoped to one space, and the space comes from the request rather than from anything written into the query. Point the request at another space to read that space's KIs.

AI Index — 一种名为

ai-index-idx-*

的 Elasticsearch index，或一种名为

ai-index-ds-*

的 data stream，并以 logical id 注册到 Context Engine。注册记录位于 Kibana 中；知识数据位于底层 index 中。只有 list 操作知道哪些

ai-index-*

index 已注册，以及

FROM

中应填写的值；仅凭 index 名称无法得知。

Knowledge Indicator (KI) — AI Index 中的一份文档：为 Agent 准备的上下文，例如某份数据的描述、摘要、access pattern、可运行的查询，或一条 Kibana resource 记录。KI 可以直接回答问题，也可以帮助定位并使用能够回答问题的来源。

当

governance.lifecycle.status: deleted

tombstone 存在，或

expires_at

已过期时，KI 会被退役。在 data stream 中，一个 KI 是同一

id

下的多个 revision，其中最新 revision 代表其当前状态。除非查询另有要求（参见生命周期），查询 API 只返回当前、有效且未过期的 KI。

只要 AI Index 中的 KI 可能覆盖问题，就应先搜索 AI Index，再进行更广泛的检索。此 skill 负责读取 KI；生成 KI 属于 Context Engine 的 automations 和 feedback loop。

此 skill 底层使用三个只读的 Context Engine HTTP API。操作表将它们映射到对应的

elastic

CLI 命令：

操作 HTTP API（简写）输入返回值

List

操作	HTTP API（简写）	输入	返回值
List	`GET kbn:/api/context_engine/ai_index`	—	`{ ai_indices: [{ id, description, managed, dest: { type, value } }] }`
Describe	`GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe`	路径中的 `aiIndexId`	`{ response }` ，一个自由格式的上下文块（字段、数量、示例）
Query	`POST kbn:/api/context_engine/ai_index/_query`	`{ query, params?, limit? }`	`{ columns, values }` ，ES\|QL 行

GET kbn:/api/context_engine/ai_index

—

{ ai_indices: [{ id, description, managed, dest: { type, value } }] }

Describe

GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe

路径中的

aiIndexId

{ response }

，一个自由格式的上下文块（字段、数量、示例）

Query

POST kbn:/api/context_engine/ai_index/_query

{ query, params?, limit? }

{ columns, values }

，ES|QL 行

按顺序使用它们：list → describe → query。绝不猜测 index id、

FROM

target 或 field name；describe 会提供这三项信息。其他任何方式都无法正确读取 AI Index：通用 ES|QL query（

POST /_query

）或 index listing 既不知道哪些 index 已注册，也不会应用 space scoping。

每次调用都限定在一个 space 中，且 space 来自请求，而不是查询中写入的任何内容。将请求指向另一个 space，即可读取该 space 的 KI。

The canonical KI schema

标准 KI schema

Elastic's canonical KI indices share these fields. Other AI Indices differ, so treat this as a starting shape and let describe settle the fields for any given index.

Field	ES\|QL type	Purpose
`type`	keyword	Categorization, e.g. `"index_metadata"` , `"document"` , `"entity_profile"` , `"detection"`
`title`	text	Short name of the KI or its backing entity
`description`	text	Short description of this KI
`content`	text	Full text: purpose, questions answered, access patterns
`tags`	keyword	Filter facets; multi-valued, so use `MATCH(tags, ?tag)` rather than `==`
`attributes`	flattened	Structured keyword-queryable metadata (status, themes, entity names). `attributes.esql` holds runnable ES\|QL
`expires_at`	date	Optional; a KI whose `expires_at` has passed is expired and hidden by default
`governance.lifecycle.status`	keyword	`deleted` marks a tombstone, hidden by default. On a data stream, only the newest revision's status counts
`governance.provenance.created_by.uri`	keyword	The automation that wrote the KI, as `workflow://<id>`

Semantic sub-fields use dot notation:

title.semantic

description.semantic

content.semantic

. They exist only where the mapping defines them; the describe block's

Semantic fields

section lists the real ones.

Elastic 的标准 KI index 共享以下字段。其他 AI Index 会有所不同，因此请将此结构作为起点，并通过 describe 确定任意给定 index 的实际字段。

字段	ES\|QL 类型	用途
`type`	keyword	分类，例如 `"index_metadata"` 、 `"document"` 、 `"entity_profile"` 、 `"detection"`
`title`	text	KI 或其实体所对应 backing entity 的短名称
`description`	text	此 KI 的简短描述
`content`	text	完整文本：用途、可回答的问题、access pattern
`tags`	keyword	筛选 facet；支持多值，因此应使用 `MATCH(tags, ?tag)` ，而不是 `==`
`attributes`	flattened	可通过 keyword 查询的结构化元数据（status、themes、entity names）。 `attributes.esql` 保存可运行的 ES\|QL
`expires_at`	date	可选； `expires_at` 已过的 KI 已过期，默认会被隐藏
`governance.lifecycle.status`	keyword	`deleted` 表示 tombstone，默认会被隐藏。在 data stream 中，仅最新 revision 的 status 生效
`governance.provenance.created_by.uri`	keyword	写入该 KI 的 automation，格式为 `workflow://<id>`

语义子字段使用点号表示法：

title.semantic

、

description.semantic

、

content.semantic

。它们仅在 mapping 定义时才存在；describe 块中的

Semantic fields

部分会列出实际存在的字段。

attributes.esql

— a KI's runnable ES|QL

attributes.esql

— KI 的可运行 ES|QL

When a KI carries runnable ES|QL, it lives in

attributes.esql

. That is the canonical location; do not look elsewhere in

attributes

. The field is optional, so a query must tolerate its absence. The same access pattern is also presented as prose inside

content

— templates, params, and returns — so reach for

content

when a KI has no

attributes.esql

, or when the description of the query matters more than the query itself.

attributes

flattened

, so extract the value with

FIELD_EXTRACT

before filtering or keeping it:

esql

FROM <dest.value>
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| WHERE type == "detection"
| EVAL esql = FIELD_EXTRACT(attributes, "esql")
| WHERE esql IS NOT NULL
| KEEP title, description, esql
| LIMIT 5

A KI may store an array of queries, making the extracted value multivalued.

IS NOT NULL

still filters correctly, but scalar comparisons like

==

skip multivalued rows. Add

| MV_EXPAND esql

after the

IS NOT NULL

to get one row per query.

当 KI 携带可运行的 ES|QL 时，它存储在

attributes.esql

中。这是标准位置；不要在

attributes

的其他位置查找。该字段是可选的，因此查询必须允许它不存在。同一个 access pattern 也会以散文形式呈现在

content

中——包括模板、params 和返回结果——因此，当 KI 没有

attributes.esql

，或者查询本身的说明比查询内容更重要时，应使用

content

。

attributes

的类型为

flattened

，因此需先使用

FIELD_EXTRACT

提取值，再进行筛选或保留：

esql

FROM <dest.value>
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| WHERE type == "detection"
| EVAL esql = FIELD_EXTRACT(attributes, "esql")
| WHERE esql IS NOT NULL
| KEEP title, description, esql
| LIMIT 5

一个 KI 可以存储查询数组，因此提取出的值可能是多值的。

IS NOT NULL

仍能正确筛选，但

==

等标量比较会跳过多值行。在

IS NOT NULL

之后添加

| MV_EXPAND esql

，即可为每个查询生成一行。

Flow

流程

Step 1 — List the AI indices

第 1 步 — 列出 AI Index

Call

GET kbn:/api/context_engine/ai_index

. Each entry gives:

```
id
```
, to pass to describe.
```
dest.value
```
, the exact string to put after
```
FROM
```
. Use it verbatim: it differs from the id (
```
sales-knowledge
```
→
```
ai-index-idx-sales-knowledge
```
).
```
dest.type
```
says whether it is an
```
index
```
or a
```
data_stream
```
.
```
description
```
and
```
managed
```
, to choose between entries.

The list is scoped to the caller's space and to what the caller can read. An entry whose backing index is empty or does not exist yet is still listed; an index the caller lacks

read

on is silently left out.

Skip this step when your instructions already name the index. Step 2 still applies: describe supplies the

FROM

target and the field names either way.

调用

GET kbn:/api/context_engine/ai_index

。每个条目都提供：

```
id
```
，用于传给 describe。
```
dest.value
```
，即放在
```
FROM
```
之后的精确字符串。必须原样使用：它与 id 不同（
```
sales-knowledge
```
→
```
ai-index-idx-sales-knowledge
```
）。
```
dest.type
```
表示它是
```
index
```
还是
```
data_stream
```
。
```
description
```
和
```
managed
```
，用于在各个条目之间进行选择。

该列表受调用方 space 以及调用方读取权限的限制。即使某个条目的底层 index 为空或尚不存在，它仍会被列出；调用方没有

read

权限的 index 会被静默排除。

如果你的指令已经指定了 index，可以跳过此步骤。无论如何，第 2 步仍然适用：describe 会提供

FROM

target 和 field name。

Step 2 — Describe the one you picked

第 2 步 — 描述选定的 AI Index

Call

GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe

with the

id

from Step 1. The

response

is a text block meant to be read, not parsed: no regexing it into structured data. It contains:

the
```
Query with ES|QL against:
```
line (the
```
FROM
```
target),
```
Fields
```
, every mapped field as
```
path: type
```
plus
```
searchable
```
/
```
aggregatable
```
(capped at 500; a path mapped inconsistently across matched indices shows as
```
conflict
```
),
```
Semantic fields
```
, the searchable
```
semantic_text
```
fields, when any,
```
Knowledge item types
```
and
```
Tags
```
, the top 20 KI
```
type
```
/
```
tags
```
values by document count in this space, active and unexpired only,
```
Example queries
```
, three ready ES|QL shapes, each opening with the lifecycle pipeline for the index's destination type.

The block is capped at ~16k tokens. Read it and use it; do not echo it back to the user.

使用第 1 步得到的

id

，调用

GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe

。

response

是一个供阅读而非解析的文本块：不要用正则表达式将其解析为结构化数据。其中包含：

```
Query with ES|QL against:
```
行（
```
FROM
```
target）
```
Fields
```
：每个 mapped field 均以
```
path: type
```
加上
```
searchable
```
/
```
aggregatable
```
表示（最多 500 个；在匹配到的各 index 之间 mapping 不一致的 path 显示为
```
conflict
```
）
```
Semantic fields
```
：可搜索的
```
semantic_text
```
字段（如果存在）
```
Knowledge item types
```
和
```
Tags
```
：当前 space 中按文档数统计的前 20 个 KI
```
type
```
/
```
tags
```
值，仅包含有效且未过期的项
```
Example queries
```
：三种可直接使用的 ES|QL 结构，每一种都以目标类型对应的 lifecycle pipeline 开头

该文本块上限约为 16k tokens。请阅读并使用它；不要将其原样回显给用户。

Step 3 — Query

第 3 步 — 查询

Call

POST kbn:/api/context_engine/ai_index/_query

with

{ query, params?, limit? }

. Build the ES|QL from the describe block's field list, starting from its example queries, and pass user input as named parameters (

?query

?type

?tag

) rather than interpolating it into the query string. The response is

{ columns, values }

; summarize it for the user rather than dumping raw rows.

What the server owns and you cannot override:

Constraint	Behavior
Lifecycle filter	Inserted after `FROM` on any query that reads a registered AI Index: active and unexpired KIs only, newest revision per `id` on a data stream, `governance.*` dropped when the query does not name it. See Lifecycle.
Space filter	Applied server-side from the request. Never write a space condition into the query: yours does not replace the server's and can silently match nothing.
Row limit	`limit` defaults to 100, max 1000. A smaller trailing `LIMIT` in the query wins; a larger one is capped.
Query size	10,000 characters max
`params`	At most 100 entries; keys ≤256 chars, string values ≤4096 chars
Index access	The query's `FROM` decides what is read; Elasticsearch index privileges bound it. ES 4xx comes back as-is.

There is no

time_range

and no

filter

parameter. Express time windows in the ES|QL itself (

WHERE @timestamp >= NOW() - 24 hours

) or through

params

调用

POST kbn:/api/context_engine/ai_index/_query

，并传入

{ query, params?, limit? }

。以 describe 块中的示例查询为起点，根据其 field 列表构建 ES|QL，并通过命名参数（

?query

、

?type

、

?tag

）传递用户输入，不要将用户输入插值到查询字符串中。响应为

{ columns, values }

；请为用户总结结果，不要直接转储原始行。

服务器负责且无法覆盖的内容：

约束	行为
Lifecycle filter	插入在读取已注册 AI Index 的任何查询的 `FROM` 之后：仅包含有效且未过期的 KI；在 data stream 中，每个 `id` 仅保留最新 revision；查询未指定 `governance.*` 时会将其丢弃。参见生命周期。
Space filter	在服务端根据请求应用。绝不要在查询中写入 space 条件：你的条件不会替代服务端条件，并且可能静默匹配不到任何内容。
Row limit	`limit` 默认为 100，最大为 1000。查询末尾较小的 `LIMIT` 优先；较大的值会被截断。
Query size	最多 10,000 个字符
`params`	最多 100 个条目；key ≤256 个字符，字符串 value ≤4096 个字符
Index access	查询的 `FROM` 决定读取内容；读取权限受 Elasticsearch index privilege 限制。ES 4xx 错误将原样返回。

不存在

time_range

和

filter

参数。请在 ES|QL 本身中表达时间窗口（

WHERE @timestamp >= NOW() - 24 hours

），或通过

params

传递。

Lifecycle

生命周期

Open every query with the two lifecycle filters, unless reading retired KIs, and end row-returning queries in

KEEP

(aggregations end in

STATS

): the query then reads as what it returns without pulling

governance.*

into context.

esql

| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()

The query API adds these two filters and

DROP governance.*

to any query that omits them, and on a data stream always keeps only the newest revision per

id

(adding

METADATA _id, _index

when missing). A top-level

WHERE

on a lifecycle field switches off that field's filter only; showing the field in

KEEP

does not. Any

governance.*

column named anywhere in the query, the opening status filter included, switches off the

DROP

, so a query that opens with the two filters returns

governance.*

columns unless it ends in

KEEP

STATS

. An index that is not registered as an AI Index is read as-is.

除非需要读取已退役的 KI，否则每个查询都应以两个 lifecycle filter 开头。返回行的查询应以

KEEP

结束（聚合查询则以

STATS

结束）：这样查询所呈现的内容就等同于其返回结果，而不会将

governance.*

带入上下文。

esql

| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()

如果查询未包含这两项 filter，查询 API 会自动添加它们以及

DROP governance.*

；对于 data stream，它始终只保留每个

id

的最新 revision（缺少时还会添加

METADATA _id, _index

）。顶层

WHERE

只会关闭对应 lifecycle field 的 filter；在

KEEP

中显示该 field 不会关闭 filter。查询任意位置只要引用了

governance.*

column，包括开头的 status filter，就会关闭

DROP

。因此，以这两个 filter 开头的查询会返回

governance.*

columns，除非最终使用

KEEP

或

STATS

。未注册为 AI Index 的 index 将按原样读取。

Examples

示例

These run as-is against canonical KI indices. For any other AI Index, adapt the field names from the describe block:

title.semantic

does not exist unless the mapping has it.

以下示例可直接用于标准 KI index。对于其他 AI Index，请根据 describe 块调整 field name：除非 mapping 中存在

title.semantic

，否则该字段不可用。

Full-text search, lexical and semantic fused

全文搜索，融合词法与语义搜索

esql

FROM ai-index-idx-sales-knowledge METADATA _id, _index, _score
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| FORK
    ( WHERE MATCH(title, ?query) OR MATCH(description, ?query) OR MATCH(content, ?query) | SORT _score DESC | LIMIT 20 )
    ( WHERE MATCH(title.semantic, ?query) OR MATCH(description.semantic, ?query) OR MATCH(content.semantic, ?query) | SORT _score DESC | LIMIT 20 )
| FUSE
| SORT _score DESC, _id ASC
| KEEP title, description, content, type, tags
| LIMIT 5

Called with the search phrase as a parameter:

json

{ "query": "<the esql above>", "params": { "query": "refund policy for annual plans" }, "limit": 5 }

esql

FROM ai-index-idx-sales-knowledge METADATA _id, _index, _score
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| FORK
    ( WHERE MATCH(title, ?query) OR MATCH(description, ?query) OR MATCH(content, ?query) | SORT _score DESC | LIMIT 20 )
    ( WHERE MATCH(title.semantic, ?query) OR MATCH(description.semantic, ?query) OR MATCH(content.semantic, ?query) | SORT _score DESC | LIMIT 20 )
| FUSE
| SORT _score DESC, _id ASC
| KEEP title, description, content, type, tags
| LIMIT 5

使用搜索短语作为参数调用：

json

{ "query": "<the esql above>", "params": { "query": "refund policy for annual plans" }, "limit": 5 }

Filter by KI type and tag

按 KI 类型和标签筛选

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| WHERE type == ?type AND MATCH(tags, ?tag)
| KEEP title, description, content, type, tags
| LIMIT 5

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| WHERE type == ?type AND MATCH(tags, ?tag)
| KEEP title, description, content, type, tags
| LIMIT 5

Count KIs by type

按类型统计 KI 数量

A first probe to confirm the index holds KIs visible from this space:

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| STATS count = COUNT(*) BY type
| SORT count DESC
| LIMIT 20

先执行一次探测查询，以确认该 index 中包含当前 space 可见的 KI：

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status IS NULL OR governance.lifecycle.status == "active"
| WHERE expires_at IS NULL OR expires_at > NOW()
| STATS count = COUNT(*) BY type
| SORT count DESC
| LIMIT 20

Read retired KIs, only when asked

读取已退役的 KI（仅在用户提出要求时）

Only when the user asks about deleted or expired knowledge. Tombstoned and expired KIs stay readable, on an index or a data stream:

Tombstoned: a
```
WHERE
```
on
```
governance.lifecycle.status
```
turns off the status filter and, being a
```
governance.*
```
column, the
```
DROP
```
too; the expiry filter still applies.
Expired: a
```
WHERE
```
on
```
expires_at
```
turns off the expiry filter; the status filter still applies.

Nothing else is readable: a KI whose document was removed is gone, and older revisions on a data stream are never returned.

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status == "deleted"
| KEEP title, governance.provenance.created_by.uri
| LIMIT 20

On a data stream, the same query returns the KIs whose newest revision is a tombstone:

esql

FROM ai-index-ds-sales-knowledge
| WHERE governance.lifecycle.status == "deleted"
| KEEP title, governance.provenance.created_by.uri
| LIMIT 20

仅当用户询问已删除或已过期的 knowledge 时才执行。Tombstoned 和 expired KI 在 index 或 data stream 中仍然可读：

Tombstoned： 对
```
governance.lifecycle.status
```
使用
```
WHERE
```
会关闭 status filter；由于它也是一个
```
governance.*
```
column，因此也会关闭
```
DROP
```
。Expiry filter 仍然生效。
Expired： 对
```
expires_at
```
使用
```
WHERE
```
会关闭 expiry filter；status filter 仍然生效。

除此之外的内容都不可读：文档已被移除的 KI 已经消失，data stream 中较旧的 revision 也永远不会返回。

esql

FROM ai-index-idx-sales-knowledge
| WHERE governance.lifecycle.status == "deleted"
| KEEP title, governance.provenance.created_by.uri
| LIMIT 20

在 data stream 中，同一查询会返回最新 revision 为 tombstone 的 KI：

esql

FROM ai-index-ds-sales-knowledge
| WHERE governance.lifecycle.status == "deleted"
| KEEP title, governance.provenance.created_by.uri
| LIMIT 20

Diagnosing

故障诊断

These failure modes look alike from the outside and have different fixes. Work down the table.

Symptom	Cause	Fix
`elastic kb context-engine` is not a known command	The installed `elastic` CLI predates the Context Engine commands	Update the `elastic` CLI
404 from every Context Engine call in one space	`contextEngine:enabled` is off in that space. Not a permissions problem	Turn it on in that space's advanced settings
404 from every Context Engine call on every space	Kibana predates the Context Engine APIs	Check the version against the compatibility note above
403 from every Context Engine call	Caller lacks the Context Engine `read` Kibana privilege	Add Context Engine `read` to the caller's role
403 from query or describe only	Missing Elasticsearch index privilege on the backing `ai-index-*` indices	Grant `read` (query) / `read` and `view_index_metadata` (describe)
Describe returns a block with no counts sections	`type` / `tags` are not aggregatable `keyword` fields, or no documents in this space	Expected; the rest of the block is still usable
An AI index you expect is not listed	No `read` on its backing index, or every document in it belongs to another space	Check privileges and the space the request is scoped to
`Unknown index` from a query whose id was listed	The AI Index is registered but its backing index does not exist yet	Expected for a registration with no data; pick another index
Error saying the query response is too large	The rows exceeded the 20 MB response cap	Narrow with `KEEP` (drop `content` and other large fields), lower `limit` , or aggregate with `STATS`
Query returns nothing but the index has data	Wrong space: the server-side space filter hides other spaces' documents	Scope the request to the right space
A KI you know exists is not returned	It is tombstoned, or its `expires_at` has passed	Filter on `governance.lifecycle.status` or `expires_at` in a `WHERE` to read it (see Lifecycle)
No `governance.*` columns in the result	The query names no `governance.*` column, or a `KEEP` / `STATS` leaves them out	Expected; name the field you need, e.g. in `KEEP`

以下故障模式从外部看相似，但修复方式不同。请按表格顺序排查。

症状	原因	修复方法
`elastic kb context-engine` 不是已知命令	已安装的 `elastic` CLI 早于 Context Engine 命令	更新 `elastic` CLI
某个 space 中所有 Context Engine 调用均返回 404	该 space 的 `contextEngine:enabled` 已关闭。这不是权限问题	在该 space 的 advanced settings 中将其开启
所有 space 中所有 Context Engine 调用均返回 404	Kibana 版本早于 Context Engine API	根据上文的兼容性说明检查版本
所有 Context Engine 调用均返回 403	调用方缺少 Context Engine `read` Kibana privilege	为调用方角色添加 Context Engine `read`
只有 query 或 describe 返回 403	缺少底层 `ai-index-*` index 上的 Elasticsearch index privilege	授予 `read` （query）或 `read` 和 `view_index_metadata` （describe）
Describe 返回的块中没有计数部分	`type` / `tags` 不是可聚合的 `keyword` field，或该 space 中没有文档	属于预期情况；该块的其余部分仍可使用
预期的 AI Index 未被列出	对其底层 index 没有 `read` 权限，或其中所有文档都属于另一个 space	检查权限以及请求所限定的 space
查询已被列出的 id 时出现 `Unknown index`	AI Index 已注册，但其底层 index 尚不存在	对于没有数据的注册属于预期情况；请选择其他 index
错误提示查询响应过大	行数超过了 20 MB 响应上限	使用 `KEEP` 缩小范围（删除 `content` 和其他大型 field）、降低 `limit` ，或使用 `STATS` 进行聚合
查询没有返回结果，但 index 中存在数据	Space 错误：服务端 space filter 隐藏了其他 space 的文档	将请求限定到正确的 space
已知存在的 KI 未被返回	它已被标记为 tombstone，或其 `expires_at` 已过期	在 `WHERE` 中按 `governance.lifecycle.status` 或 `expires_at` 筛选以读取它（参见生命周期）
结果中没有 `governance.*` columns	查询未引用任何 `governance.*` column，或 `KEEP` / `STATS` 将其排除	属于预期情况；通过 `KEEP` 等方式明确指定所需 field

Guidelines

准则

Never skip describe. A query written from memory could fail, or silently returns nothing.
Read AI Indices only through
```
POST kbn:/api/context_engine/ai_index/_query
```
. A direct Elasticsearch query or a cluster-wide ES|QL query (
```
POST /_query
```
) bypasses the space scoping, the lifecycle filter, and the row cap: it returns every revision, deleted and expired ones included. Consult the
```
elasticsearch-esql
```
skill for ES|QL syntax.
Start at
```
limit
```
5 and narrow the columns with
```
KEEP
```
. The whole result enters your context.
If the top 5 don't answer the question, check how they fall short: on topic but incomplete → raise the limit; off topic → the query is wrong, so reword the search terms or loosen the
```
WHERE
```
rather than asking for more rows.
Answer from the rows and cite the KI titles; do not dump the raw result.
An empty result means no current KI. Do not read tombstones or expired KIs unless the user asks about deleted or expired knowledge.

绝不跳过 describe。凭记忆编写的查询可能失败，也可能悄无声息地返回空结果。
仅通过
```
POST kbn:/api/context_engine/ai_index/_query
```
读取 AI Index。直接执行 Elasticsearch query，或执行集群范围的 ES|QL query（
```
POST /_query
```
），会绕过 space scoping、lifecycle filter 和行数上限，并返回所有 revision，包括已删除和已过期的内容。有关 ES|QL 语法，请参阅
```
elasticsearch-esql
```
skill。
从
```
limit
```
5 开始，并通过
```
KEEP
```
缩小 column 范围。整个结果都会进入你的上下文。
如果前 5 条无法回答问题，请检查其不足之处：主题相关但不完整 → 提高 limit；主题不相关 → 查询有误，应改写搜索词或放宽
```
WHERE
```
，而不是要求返回更多行。
根据结果行作答，并引用 KI title；不要转储原始结果。
空结果表示不存在当前 KI。除非用户询问已删除或已过期的 knowledge，否则不要读取 tombstone 或 expired KI。

Out of scope

范围之外

Creating, updating, or deleting AI indices, and managing their
```
sources
```
/
```
automations
```
/
```
feedback_analysis
```
config.
Generating Knowledge Indicators, or deciding what an AI Index should contain. That is the Context Engine's automations and its analyze-and-improve feedback loop, not query time.

创建、更新或删除 AI Index，以及管理其
```
sources
```
/
```
automations
```
/
```
feedback_analysis
```
配置。
生成 Knowledge Indicator，或决定 AI Index 应包含哪些内容。这属于 Context Engine 的 automations 及其 analyze-and-improve feedback loop，而不属于 query time。

Operations

操作

HTTP API (shorthand)	`elastic` CLI command
`GET kbn:/api/context_engine/ai_index`	`elastic kb context-engine get-context-engine-ai-index`
`GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe`	`elastic kb context-engine get-context-engine-ai-index-aiindexid-describe --ai-index-id '<id>'`
`POST kbn:/api/context_engine/ai_index/_query`	`elastic kb context-engine post-context-engine-ai-index-query --query '<esql>' [--params '<json>'] [--limit <n>]`
`GET kbn:/api/context_engine/ai_index/{aiIndexId}`	`elastic kb context-engine get-context-engine-ai-index-aiindexid --ai-index-id '<id>'`

HTTP API（简写）	`elastic` CLI 命令
`GET kbn:/api/context_engine/ai_index`	`elastic kb context-engine get-context-engine-ai-index`
`GET kbn:/api/context_engine/ai_index/{aiIndexId}/_describe`	`elastic kb context-engine get-context-engine-ai-index-aiindexid-describe --ai-index-id '<id>'`
`POST kbn:/api/context_engine/ai_index/_query`	`elastic kb context-engine post-context-engine-ai-index-query --query '<esql>' [--params '<json>'] [--limit <n>]`
`GET kbn:/api/context_engine/ai_index/{aiIndexId}`	`elastic kb context-engine get-context-engine-ai-index-aiindexid --ai-index-id '<id>'`