Adds "Querying semantic_text fields" section #136076

kosabogi · 2025-10-07T10:48:30Z

This PR adds a new section to the semantic_text field type documentation with quick links to examples for querying semantic_text fields using different query types (match, kNN, sparse_vector, and semantic).

The links to the specific query type examples will be added by @charlotte-hoblik in her PR, as she’s currently working on creating those example pages.

Related issue: https://github.com/elastic/developer-docs-team/issues/321

github-actions · 2025-10-07T10:50:10Z

🔍 Preview links for changed docs

github-actions · 2025-10-07T10:50:11Z

ℹ️ 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?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

elasticsearchmachine · 2025-10-07T11:03:06Z

Pinging @elastic/core-docs (Team:Docs)

leemthompo

Left couple options for how we might proceed here, as the original assumed scope of a standalone page has shrunk quite a bit.

docs/reference/elasticsearch/mapping-reference/semantic-text.md

kderusso · 2025-10-07T12:22:03Z

docs/reference/elasticsearch/mapping-reference/semantic-text.md

+
+- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. Refer to examples of sparse vector queries on `semantic_text` fields.
+
+- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. Refer to examples of semantic queries on `semantic_text` fields.


As the semantic query is GA and still supported, do we really want to use this language?

We don't need to use this exact verbiage, but if we have strong opinions and we don't think folks should use semantic queries in new implementations, then we should be quite clear about that.

I believe @serenachou raised the original issue in slack, (which I had misremembered as coming from you Kathleen 😄) :

semantic_text now supports multiple query types (match, knn, sparse_vector) that provide more flexibility and customization options. This leads to confusion and has led to feature requests for functionality that already exists in other query types.

So there's nothing wrong with being clear in our recommendations, while still stating that semantic queries remain supported

@kosabogi @charlotte-hoblik we should add a note to https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-semantic-query to reiterate this point

Co-authored-by: Liam Thompson <[email protected]>

leemthompo

Few more little things, thanks for iterating :)

leemthompo · 2025-10-07T13:15:47Z

docs/reference/elasticsearch/mapping-reference/semantic-text.md

- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. Refer to examples of sparse vector queries on `semantic_text` fields.
-
- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. Refer to examples of semantic queries on `semantic_text` fields.
+- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. 


Suggested change

- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields.

- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md): The recommended method for querying `semantic_text` fields.

You can perform match queries in query DSL or ESQL, so we should use tabs here (like we do in this doc) and mention https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/search-functions#esql-match

I think this should be included in the query examples section (the one we link to from here), right?
cc @charlotte-hoblik

right but if you're linking to query DSL here, then you should link to ESQL too for symmetry, but it doesn't necessarily have to be tabs if that's too heavy-handed

You could just do something like:

Match query: The recommended method for querying semantic_text fields. You can use Query DSL or ES|QL syntax.

docs/reference/elasticsearch/mapping-reference/semantic-text.md

Co-authored-by: Liam Thompson <[email protected]>

leemthompo

Thanks @kosabogi!

As a last action on this PR, I had one other suggestion in there to add a note to the semantic query page that mirrors this verbiage:

We don't recommend this legacy query type for new projects, because the alternatives in this list enable more flexibility and customization. The semantic query remains available to support existing implementations.

Ignore if the plan was to add that in another PR :)

…ch into query-semantic-text

kosabogi · 2025-10-08T11:37:30Z

Thanks @kosabogi!

As a last action on this PR, I had one other suggestion in there to add a note to the semantic query page that mirrors this verbiage:

We don't recommend this legacy query type for new projects, because the alternatives in this list enable more flexibility and customization. The semantic query remains available to support existing implementations.

Ignore if the plan was to add that in another PR :)

@leemthompo I added the note in this PR, could you take a last look please? Thank you! :)

leemthompo · 2025-10-08T12:02:05Z

🚢

* Adds Querying semantic_text fields section * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Comment out links temporarily * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Adds ESQL link to match query * Fixes link * Adds note to the Semantic query page --------- Co-authored-by: Liam Thompson <[email protected]>

elasticsearchmachine · 2025-10-08T12:49:02Z

💚 Backport successful

Status	Branch	Result
✅	9.2

* Adds Querying semantic_text fields section * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md * Comment out links temporarily * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md * Adds ESQL link to match query * Fixes link * Adds note to the Semantic query page --------- Co-authored-by: Liam Thompson <[email protected]>

Adds Querying semantic_text fields section

f126b9b

kosabogi requested review from charlotte-hoblik and leemthompo October 7, 2025 10:48

elasticsearchmachine added needs:triage Requires assignment of a team area label v9.3.0 labels Oct 7, 2025

kosabogi added the documentation label Oct 7, 2025

kosabogi added the Team:Docs Meta label for docs team label Oct 7, 2025

elasticsearchmachine removed the Team:Docs Meta label for docs team label Oct 7, 2025

kosabogi requested a review from a team October 7, 2025 10:51

kosabogi added the Team:Docs Meta label for docs team label Oct 7, 2025

elasticsearchmachine removed the Team:Docs Meta label for docs team label Oct 7, 2025

kosabogi added Team:Docs Meta label for docs team and removed needs:triage Requires assignment of a team area label labels Oct 7, 2025

elasticsearchmachine added needs:triage Requires assignment of a team area label and removed Team:Docs Meta label for docs team labels Oct 7, 2025

leemthompo added Team:Docs Meta label for docs team auto-backport Automatically create backport pull requests when merged v9.2.0 >docs General docs changes labels Oct 7, 2025

elasticsearchmachine removed the needs:triage Requires assignment of a team area label label Oct 7, 2025

leemthompo reviewed Oct 7, 2025

View reviewed changes

docs/reference/elasticsearch/mapping-reference/semantic-text.md Outdated Show resolved Hide resolved

docs/reference/elasticsearch/mapping-reference/semantic-text.md Outdated Show resolved Hide resolved

kderusso reviewed Oct 7, 2025

View reviewed changes

kosabogi and others added 3 commits October 7, 2025 14:24

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

6cfaf35

Co-authored-by: Liam Thompson <[email protected]>

Comment out links temporarily

50a5e24

Merge branch 'main' into query-semantic-text

64446ef

leemthompo reviewed Oct 7, 2025

View reviewed changes

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

67d9f5c

Co-authored-by: Liam Thompson <[email protected]>

kosabogi and others added 6 commits October 7, 2025 15:32

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

11089a7

Co-authored-by: Liam Thompson <[email protected]>

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

38a79de

Co-authored-by: Liam Thompson <[email protected]>

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

a8435b6

Co-authored-by: Liam Thompson <[email protected]>

Adds ESQL link to match query

1cdabcb

Fixes link

30b9341

Merge branch 'main' into query-semantic-text

f525152

leemthompo approved these changes Oct 8, 2025

View reviewed changes

kosabogi and others added 3 commits October 8, 2025 13:34

Adds note to the Semantic query page

964aec6

Merge branch 'query-semantic-text' of github.com:kosabogi/elasticsear…

206a3cd

…ch into query-semantic-text

Merge branch 'main' into query-semantic-text

b718123

kosabogi merged commit 9063ec6 into elastic:main Oct 8, 2025
11 checks passed

kosabogi mentioned this pull request Oct 8, 2025

[9.2] Adds "Querying semantic_text fields" section (#136076) #136180

Merged


		- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. Refer to examples of sparse vector queries on `semantic_text` fields.

		- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. Refer to examples of semantic queries on `semantic_text` fields.

	- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields.
	- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md): The recommended method for querying `semantic_text` fields.

Adds "Querying semantic_text fields" section #136076

Adds "Querying semantic_text fields" section #136076

Conversation

kosabogi commented Oct 7, 2025

Uh oh!

github-actions bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Oct 7, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

elasticsearchmachine commented Oct 7, 2025

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

kosabogi commented Oct 8, 2025

Uh oh!

leemthompo commented Oct 8, 2025

Uh oh!

Uh oh!

elasticsearchmachine commented Oct 8, 2025

💚 Backport successful

Uh oh!

Uh oh!

github-actions bot commented Oct 7, 2025 •

edited

Loading