fake-haris
diff --git a/‎dev_docs/tutorials/saved_objects_esql.mdx‎
Lines changed: 177 additions & 0 deletions b/‎dev_docs/tutorials/saved_objects_esql.mdx‎
Lines changed: 177 additions & 0 deletions
diff --git a/‎examples/saved_objects/server/esql_example_routes.ts‎
Lines changed: 111 additions & 0 deletions b/‎examples/saved_objects/server/esql_example_routes.ts‎
Lines changed: 111 additions & 0 deletions
diff --git a/‎examples/saved_objects/server/plugin.ts‎
Lines changed: 2 additions & 0 deletions b/‎examples/saved_objects/server/plugin.ts‎
Lines changed: 2 additions & 0 deletions
@@ -0,0 +1,177 @@
+---
+id: kibDevTutorialSavedObjectsEsql
+slug: /kibana-dev-docs/tutorials/saved-objects-esql
+title: Saved Object `esql` method
+description: Learn how to use the `esql` method to query Saved Objects using ES|QL.
+date: 2026-03-02
+tags: ['kibana', 'dev', 'tutorials', 'saved-objects', 'esql']
+---
+
+`SavedObjectsClientContract.esql` allows you to query Saved Objects using [ES|QL (Elasticsearch Query Language)](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql). It returns tabular results (columns and values) directly from Elasticsearch, which can be useful for analytics, aggregations, and cross-type queries that don't fit the `find` or `search` methods.
+
+## Relationship to `find` and `search`
+
+| Method | Use case | Response format |
+|--------|----------|----------------|
+| `find` | Simple filtering and pagination of saved objects | Structured `SavedObject[]` |
+| `search` | Complex queries using Elasticsearch Query DSL | Raw Elasticsearch search hits |
+| `esql` | Tabular queries using ES|QL syntax | Tabular columns + values |
+
+Use `esql` when you need ES|QL-specific features like `STATS`, `EVAL`, `ENRICH`, or pipe-based query composition.
+
+<DocCallOut title="With great power comes great responsibility">
+  While the `esql` method is powerful, it can increase code complexity, introduce performance issues and introduce security risks (like injection attacks). Carefully consider how you would like to use this method in your plugin to unlock value for users.
+</DocCallOut>
+
+## The `pipeline` concept
+
+Like `search` and `find`, you specify saved object **types** as a dedicated parameter — you never need to know or write index names. The `esql` method resolves the correct Elasticsearch indices from the `type` parameter and auto-generates the `FROM` clause. Security filters (namespace + type restriction) are injected via the `filter` parameter, so you don't need `WHERE type ==` either.
+
+You write only the ES|QL **processing pipeline** — everything after `FROM`:
+
+```ts
+import { isResponseError } from '@kbn/es-errors';
+import { MY_TYPE } from './saved_objects';
+
+/** ...inside a route handler: */
+async (ctx, req, res) => {
+  const core = await ctx.core;
+  const savedObjectsClient = core.savedObjects.client;
+  try {
+    const result = await savedObjectsClient.esql({
+      type: [MY_TYPE],
+      namespaces: ['default'],
+      pipeline: `| KEEP ${MY_TYPE}.title, ${MY_TYPE}.description
+        | SORT ${MY_TYPE}.title
+        | LIMIT 100`,
+    });
+    return res.ok({ body: { columns: result.columns, values: result.values } });
+  } catch (e) {
+    if (isResponseError(e)) {
+      log.error(JSON.stringify(e.meta.body, null, 2));
+    }
+    throw e;
+  }
+}
+```
+
+To include METADATA fields on the auto-generated FROM clause, use the `metadata` option:
+
+```ts
+const result = await savedObjectsClient.esql({
+  type: [MY_TYPE],
+  namespaces: ['default'],
+  metadata: ['_id', '_source'],
+  // generates: FROM .kibana METADATA _id, _source | WHERE ...
+  pipeline: '| WHERE my_type.title LIKE "test*" | LIMIT 100',
+});
+```
+
+See the full example in the Kibana repository at `examples/saved_objects`.
+
+## Safe pipeline construction with ES|QL params
+
+When interpolating user input into ES|QL pipelines, **never** use string concatenation. Instead, use ES|QL's native parameterization — named params (`?paramName`) or positional params (`?`) — to separate code from data at the protocol level.
+
+### Named params `?paramName` (recommended for user input)
+
+Use `?paramName` placeholders in the pipeline string and pass the values via the `params` array as `{ name: value }` entries. This is true parameterization — the values are never interpolated into the query string, preventing injection attacks.
+
+```ts
+import type { estypes } from '@elastic/elasticsearch';
+
+const userInput = req.body.searchTerm;
+
+const result = await savedObjectsClient.esql({
+  type: ['my_type'],
+  namespaces: ['default'],
+  pipeline: '| WHERE my_type.title LIKE ?searchTerm | LIMIT 100',
+  // Named params are supported by ES at runtime, but the ES client TypeScript types
+  // only define positional params — cast through unknown to bridge the type gap.
+  params: [{ searchTerm: userInput }] as unknown as estypes.EsqlESQLParam[],
+});
+```
+
+The pipeline sent to Elasticsearch will be `| WHERE my_type.title LIKE ?searchTerm | LIMIT 100` — with `searchTerm` as a separate parameter, never interpolated into the pipeline string.
+
+### Positional params `?` (alternative)
+
+ES|QL also supports positional `?` placeholders. Params are plain values (string, number, boolean, or null) matched by position:
+
+```ts
+const result = await savedObjectsClient.esql({
+  type: ['my_type'],
+  namespaces: ['default'],
+  pipeline: '| WHERE my_type.title LIKE ? | LIMIT 100',
+  params: [userInput],
+});
+```
+
+## Security model
+
+### Execution context — `kibana_system` user
+
+The ES|QL pipeline executes with the privileges of the `kibana_system` Elasticsearch user, which has elevated access including `manage_enrich` and broad index monitoring permissions. This means the pipeline can access resources that the end user may not be authorized to see.
+
+**Never inject arbitrary or untrusted user input directly into the pipeline string.** If a user can control the full pipeline, they could use commands like `ENRICH` to join against enrich policies whose source data they would not normally have access to — this is a privilege escalation. Always construct the pipeline server-side and use parameterized values (see [Safe pipeline construction](#safe-pipeline-construction-with-esql-params)) for any user-provided input.
+
+Using `ENRICH` in your pipeline is perfectly fine when you control the pipeline and are enriching from a policy whose data is appropriate for all users who will see the results.
+
+### Index resolution from types
+
+Like `search` (which passes `index: getIndicesForTypes(types)` internally), the `esql` method resolves the correct Elasticsearch indices from the `type` parameter and auto-generates the `FROM` clause. You never need to know the index name — it is an implementation detail handled by the saved objects system.
+
+### Space and type filtering
+
+When you call `esql()`, namespace (space) and type filters are automatically injected into the `filter` parameter of the ES|QL request. The filter restricts results to the specified types and namespaces, so you don't need `WHERE type == "..."` in your pipeline. This works the same way as the `search` method:
+
+1. `spacesExtension.getSearchableNamespaces()` resolves which namespaces the user can access
+2. `securityExtension.authorizeFind()` checks RBAC permissions
+3. A namespace bool filter (including type restriction) is constructed and merged with any user-provided `filter`
+
+If the user is not authorized to access any of the requested namespaces or types, an empty response is returned.
+
+### User-provided filters are merged, not replaced
+
+If you provide a `filter` in the options, it is merged with the security filter using `{ bool: { must: [securityFilter, yourFilter] } }`. Your filter is never used in isolation.
+
+## Encrypted attributes
+
+Encrypted saved object attributes are handled differently depending on whether `_source` is present in the response:
+
+- **With `_source` (via `metadata: ['_id', '_source']`):** The full document in `_source` contains all attributes needed for AAD (Additional Authenticated Data) reconstruction. Encrypted attributes are by default stripped from `_source`, or are **decrypted** in `_source`, using the same path as `find` and `search`, if registered with the `dangerouslyExposeValue` option. If decryption fails (e.g., key rotation), all encrypted attributes are stripped from `_source`.
+- **Standalone scalar columns (e.g., `connector.secrets`):** Always replaced with `null`, regardless of `_source` decryption. These columns contain raw ciphertext that cannot be used outside the document context.
+
+For example, if a `connector` type has an encrypted `secrets` attribute:
+- `connector.secrets` column → always `null`
+- `_source` column → contains the full document with `secrets` decrypted (or stripped on failure)
+
+## Response structure
+
+The `esql` method returns the raw ES|QL response with `columns` and `values`:
+
+```json
+{
+  "columns": [
+    { "name": "index-pattern.title", "type": "keyword" },
+    { "name": "type", "type": "keyword" }
+  ],
+  "values": [
+    ["logs-*", "index-pattern"],
+    ["metrics-*", "index-pattern"]
+  ]
+}
+```
+
+## When to use
+
+- You need ES|QL-specific operations like `STATS`, `EVAL`, `ENRICH`, `DISSECT`, or `GROK`
+- You want tabular results for analytics or reporting
+- You need to compute aggregations across saved object types
+
+## When not to use
+
+- You want structured `SavedObject` instances with `id`, `attributes`, `references` - use `find` instead
+- You need Elasticsearch Query DSL features like runtime mappings or aggregation trees - use `search` instead
+- Simple filtering and pagination - use `find` instead
+- You need ES|QL source commands like `ROW`, `SHOW`, or `METRICS` - use the raw Elasticsearch client directly
@@ -0,0 +1,111 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { AuthzDisabled } from '@kbn/core-security-server';
+import type { IRouter, Logger } from '@kbn/core/server';
+import type { estypes } from '@elastic/elasticsearch';
+import { isResponseError } from '@kbn/es-errors';
+import { TYPE_A, TYPE_B } from './saved_objects';
+import { setupData } from './saved_objects_data';
+
+export function registerEsqlExampleRoutes(router: IRouter, log: Logger) {
+  // Basic query — no user input, plain pipeline string is safe.
+  router.versioned
+    .post({
+      path: '/api/saved_objects_example/_esql_query',
+      summary: 'Query saved objects using ES|QL',
+      access: 'public',
+      security: {
+        authz: AuthzDisabled.fromReason('This route is an example'),
+      },
+    })
+    .addVersion(
+      {
+        version: '2023-10-31',
+        validate: false,
+      },
+      async (ctx, req, res) => {
+        log.info('Querying saved objects with ES|QL');
+        const core = await ctx.core;
+        const savedObjectsClient = core.savedObjects.client;
+        await setupData(savedObjectsClient);
+        try {
+          // The `type` parameter controls index resolution (FROM clause is auto-generated)
+          // and security filtering (type + namespace restrictions are injected via the
+          // `filter` parameter). You don't need FROM or WHERE type == in your pipeline.
+          const result = await savedObjectsClient.esql({
+            type: [TYPE_A, TYPE_B],
+            namespaces: ['default'],
+            pipeline: `| KEEP type, ${TYPE_A}.myField, ${TYPE_B}.anotherField | SORT type | LIMIT 100`,
+          });
+          return res.ok({
+            body: {
+              columns: result.columns,
+              values: result.values,
+            },
+          });
+        } catch (e) {
+          if (isResponseError(e)) {
+            log.error(JSON.stringify(e.meta.body, null, 2));
+          }
+          throw e;
+        }
+      }
+    );
+
+  // Parameterized query — when the pipeline includes user-provided values,
+  // use ES|QL named params (`?paramName`) to prevent injection attacks.
+  // Values are passed via the `params` array as `{ name: value }` entries
+  // and are never interpolated into the query string.
+  // Note: the ES client types don't include the named param record format,
+  // but Elasticsearch supports named params at runtime.
+  router.versioned
+    .post({
+      path: '/api/saved_objects_example/_esql_query_parameterized',
+      summary: 'Query saved objects using ES|QL with parameters',
+      access: 'public',
+      security: {
+        authz: AuthzDisabled.fromReason('This route is an example'),
+      },
+    })
+    .addVersion(
+      {
+        version: '2023-10-31',
+        validate: false,
+      },
+      async (ctx, req, res) => {
+        const core = await ctx.core;
+        const savedObjectsClient = core.savedObjects.client;
+        await setupData(savedObjectsClient);
+
+        // Simulate user input — NEVER interpolate this into the pipeline string.
+        const searchTerm = 'some search term';
+
+        try {
+          const result = await savedObjectsClient.esql({
+            type: TYPE_A,
+            namespaces: ['default'],
+            pipeline: `| WHERE ${TYPE_A}.myField == ?searchTerm | LIMIT 10`,
+            params: [{ searchTerm }] as unknown as estypes.EsqlESQLParam[],
+          });
+          return res.ok({
+            body: {
+              columns: result.columns,
+              values: result.values,
+            },
+          });
+        } catch (e) {
+          if (isResponseError(e)) {
+            log.error(JSON.stringify(e.meta.body, null, 2));
+          }
+          throw e;
+        }
+      }
+    );
+}
@@ -16,6 +16,7 @@ import type {
 } from '@kbn/core/server';
 import { typeA, typeB } from './saved_objects';
 import { registerSearchExampleRoutes } from './search_example_routes';
+import { registerEsqlExampleRoutes } from './esql_example_routes';
 
 export class SavedObjectsExamplePlugin implements Plugin {
   private readonly logger: Logger;
@@ -29,6 +30,7 @@ export class SavedObjectsExamplePlugin implements Plugin {
     core.savedObjects.registerType(typeB);
     const router = core.http.createRouter();
     registerSearchExampleRoutes(router, this.logger);
+    registerEsqlExampleRoutes(router, this.logger);
   }
 
   public start(core: CoreStart) {}