ES|QL editor: Document SET unmapped_fields support

[florent-leborgne]

Summary

{{kib}} 9.4 adds {{esql}} editor support for the SET unmapped_fields directive, which controls how queries treat fields that are not in an index mapping. Three values are accepted:

• DEFAULT (current behavior): queries fail when they reference fields that are not in the mapping.
• NULLIFY: treats unmapped fields as null.
• LOAD: loads unmapped fields from _source as keyword (planned for the stack, not yet GA).

Editor behavior to document:

• Autocomplete suggests the setting name and its accepted values.
• After NULLIFY or LOAD is set, unmapped fields referenced in the query are added to autocomplete and treated like normal columns. They stop being suggested if they are dropped or renamed.
• A warning is shown the first time an unmapped field is referenced in the query.
• If columns are dropped via KEEP or STATS, new unmapped references after that point are flagged as errors.
• Setting unmapped_fields to FAIL (or omitting the directive) preserves the previous behavior.

Why this needs docs: New {{kib}} editor support for an {{esql}} setting that changes how the editor validates queries, surfaces autocomplete suggestions, and warns users. People querying partially mapped data sources need to know the option exists and what to expect.

Note

This issue depends on #6091, which introduces the umbrella Define query settings with SET section on the same page. Once that PR merges, the work here is to extend that section with an unmapped_fields subsection (sibling to approximation and project_routing).

Resources

• PR #248606: [ES|QL] Support unmapped fields
• Product issue: [ES|QL] Supports unmapped fields kibana#246587
• Depends on: docs: describe SET directive and approximation in ES|QL Kibana page (#4962) #6091
• Reference: SET directive, unmapped_fields

Screenshots from PR

Availability

Channel	Details
Stack	9.4.0
Serverless	Available (estimated 2026-01-26, 7 days after merge)
Feature status	GA, except LOAD value which is planned on the stack
Feature flag	None

Suggested edits

Use ES|QL in the Kibana UI > Define query settings with SET

• What the docs say (after docs: describe SET directive and approximation in ES|QL Kibana page (#4962) #6091 merges): Lists approximation and project_routing as settings particularly useful from {{kib}}.
• What to change: Add unmapped_fields to the bullet list of useful settings, with a link to the new subsection described below. Applies from 9.4 and in serverless.

Use ES|QL in the Kibana UI > Handle unmapped fields with SET unmapped_fields (new subsection)

• What to change: Add a new subsection, sibling to Approximate STATS results with SET approximation and Search across projects with SET project_routing, that:
  • Briefly explains the three accepted values (DEFAULT, NULLIFY, LOAD) and links to the SET reference for the full type and behavior reference.
  • Describes the {{kib}} editor experience: autocomplete for the setting name and values; once NULLIFY or LOAD is set, unmapped fields referenced in the query are added to autocomplete and treated like regular columns; a warning is shown the first time an unmapped field is referenced; new unmapped references after a KEEP or STATS that drops columns are flagged as errors.
  • Includes a short example using NULLIFY with a FROM source.
  • Adds applies_to: stack: ga 9.4 / serverless: ga, and notes that the LOAD value is currently planned on the stack. Applies from 9.4 and in serverless.

---

Created with Docs Quest Scanner by @florent-leborgne

[github-actions]

Elastic Docs AI Menu

Check one box to run an AI workflow for this issue.

• Triage (docs-triage).
• Scope the docs work (docs-issue-scope).

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.