Skip to content

[Docs] ESQL - Add _source details in the search tutorial#144052

Open
carlosdelest wants to merge 4 commits intoelastic:mainfrom
carlosdelest:docs/esql-when-should-retrieve-source-metadata
Open

[Docs] ESQL - Add _source details in the search tutorial#144052
carlosdelest wants to merge 4 commits intoelastic:mainfrom
carlosdelest:docs/esql-when-should-retrieve-source-metadata

Conversation

@carlosdelest
Copy link
Member

This PR adds a section to the ES|QL search tutorial that includes when it would be useful to use _source instead of selecting individual fields.

@jimczi how does this look like from the technical PoV?

@leemthompo I'm thinking to add some / all of this to the metadata fields section. WDYT? Should we add all details there and put a link to that on the search tutorial?

@carlosdelest carlosdelest added >docs General docs changes Team:Search Relevance Meta label for the Search Relevance team in Elasticsearch labels Mar 11, 2026
@carlosdelest carlosdelest requested a review from a team as a code owner March 11, 2026 18:12
@carlosdelest carlosdelest added :Search Relevance/ES|QL Search functionality in ES|QL v9.4.0 labels Mar 11, 2026
@elasticsearchmachine
Copy link
Collaborator

Pinging @elastic/es-search-relevance (Team:Search Relevance)

@github-actions
Copy link
Contributor

github-actions bot commented Mar 11, 2026

@github-actions
Copy link
Contributor

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

@leemthompo
Copy link
Contributor

As you suggested Carlos, I'd lean towards putting the "when to use / when not to use" lists in the metadata fields page and linking there from the final sentence in the tutorial:

"Using _source or selecting fields are both valid options, but can have performance and data format implications that you should consider based on your use case. To learn more, refer to Sort results by search score.

You could keep a brief line in the tutorial about "You should consider using _source when foo bar baz"

@carlosdelest
Copy link
Member Author

I added the original criteria in the metadata page, and summarized in the search tutorial. LMKWYT @leemthompo @jimczi !

Copy link
Contributor

@leemthompo leemthompo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Co-authored-by: Liam Thompson <leemthompo@gmail.com>
Using _`source` is useful when you want to retrieve most or all fields from a document.

You should consider retrieving `_source` instead of individual fields when:
- You need several fields from a document, and most of them are text fields.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

geo fields suffer the same, maybe would be worthy to add them here, in particular big geo_shape fields.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

>docs General docs changes :Search Relevance/ES|QL Search functionality in ES|QL Team:Search Relevance Meta label for the Search Relevance team in Elasticsearch v9.4.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants