Skip to content

Adds "Querying semantic_text fields" section #136076

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Oct 8, 2025
+29 −0
Merged

Adds "Querying semantic_text fields" section #136076

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
f126b9b
Adds Querying semantic_text fields section
kosabogi Oct 7, 2025
6cfaf35
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 7, 2025
50a5e24
Comment out links temporarily
kosabogi Oct 7, 2025
64446ef
Merge branch 'main' into query-semantic-text
kosabogi Oct 7, 2025
67d9f5c
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 7, 2025
11089a7
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 7, 2025
38a79de
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 7, 2025
a8435b6
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 7, 2025
1cdabcb
Adds ESQL link to match query
kosabogi Oct 8, 2025
30b9341
Fixes link
kosabogi Oct 8, 2025
f525152
Merge branch 'main' into query-semantic-text
kosabogi Oct 8, 2025
964aec6
Adds note to the Semantic query page
kosabogi Oct 8, 2025
206a3cd
Merge branch 'query-semantic-text' of github.com:kosabogi/elasticsear…
kosabogi Oct 8, 2025
b718123
Merge branch 'main' into query-semantic-text
kosabogi Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/reference/elasticsearch/mapping-reference/semantic-text.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -611,6 +611,21 @@ PUT test-index
}
```

## Querying `semantic_text` fields [querying-semantic-text-fields]

Querying `semantic_text` fields enables semantic search by matching on meaning rather than just keywords. It’s useful for natural language search, intent-aware retrieval, and cases where keyword matching alone isn’t sufficient.

You can query `semantic_text` fields using the following query types:

- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. Refer to examples of match queries on `semantic_text` fields.

- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) - Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. Refer to examples of kNN queries on `semantic_text` fields.

- [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.
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

@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



## Troubleshooting semantic_text fields [troubleshooting-semantic-text-fields]

If you want to verify that your embeddings look correct, you can view the
Expand Down
Loading