Restructuring the semantic_text field type page

[kosabogi]

📷 Preview

Semantic text field type

• semantic_text field type reference
• How-to guides for semantic_text

Summary

This PR restructures and refines the semantic_text field type page.

Main changes

1. Content and wording refinements

• Renamed sections to be more concise and shorter
• Standardized terminology
• Added relevant links
• Simplified language where applicable
• For how-to content, added stepper syntax where it was applicable (more than 1 step)

2. Content restructuring

Restructured the semantic_text documentation into three focused pages:

• Main page (semantic-text.md): Converted to an overview page with an introduction explaining what semantic_text is and an overview section linking to the reference and how-to pages.

• Reference page (semantic-text-reference.md): New dedicated reference page containing parameter descriptions, inference endpoint configurations, chunking behavior, update operations, querying options, and limitations.

• How-to guides page (semantic-text-how-tos.md): New dedicated how-to page containing procedure descriptions and examples for common tasks, including configuring inference endpoints, pre-chunking content, retrieving embeddings, highlighting fragments, and cross-cluster search.

Our main reasons for splitting the docs this way:

• Separating reference from how-to content follows documentation best practices
• It scales better as we add more guides without making the main pages too long
• Improves readability: people looking up parameters don't have to skip through procedures, and people following guides don't have to read through parameter details

Feedback and suggestions are welcome!

• What do you think about this new structure? Does splitting the page by content type improve readability for users?
• Do you have suggestions for moving any content to different pages?
• Any comments or suggestions on naming, titles, or organization?

Related issue: elastic/docs-content#3836

[elasticsearchmachine]

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

[github-actions]

🔍 Preview links for changed docs

• docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md
• docs/reference/elasticsearch/mapping-reference/semantic-text-ingestions.md
• docs/reference/elasticsearch/mapping-reference/semantic-text-reference.md
• docs/reference/elasticsearch/mapping-reference/semantic-text-search-retrieval.md
• docs/reference/elasticsearch/mapping-reference/semantic-text-setup-configuration.md
• docs/reference/elasticsearch/mapping-reference/semantic-text.md
• docs/reference/query-languages/query-dsl/query-dsl-semantic-query.md

[github-actions]

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

[leemthompo]

This is looking really nice already, I left some comments and ideas, but particularly the how-to ideas might be best left until SMEs have had the time to digest the initial proposal of breaking these pages up, which will have to wait until next week.

I think the landing page feedback is probably actionable right now though if you want to rework that a bit :)

[leemthompo]

High-level I think we can organize the how-to's into 3 clear categories:

• Setup and configuration
• Ingestion
• Search and retrieval

Maybe they could be subpages, but please don't feel obliged to jump on this immediately and also of course feel free to push back if that sounds like overkill. Here's the overview of what that might look like, and note that it also implies moving a couple of things out of the reference section which might belong together more naturally under how-to. But this might require additional refactoring that isn't worth the ROI immediately. So just take this as food for thought :)

Expand to see what a potential how-to subpages restructuring would look like

# How-to guides for `semantic_text`

## Setup & configuration

### Configure inference endpoints
- Use default and preconfigured endpoints
- Use ELSER on EIS  
- Use a custom inference endpoint
- Use dedicated endpoints for ingestion and search
- **[MOVED FROM REF]** Inference endpoint validation

## Ingestion

### Index pre-chunked content
- Disable automatic chunking
- Index documents

### Use copy_to and multi-fields with semantic_text
- Use copy_to
- Use multi-fields

### **[MOVED FROM REF]** Update documents with semantic_text fields
- Full document updates (examples)
- Partial updates using Bulk API (examples)
- Partial updates using Update API (examples)
- Scripted updates

## Search & retrieval

### **[MOVED FROM REF]** Query semantic_text fields
- Using match queries
- Using kNN queries  
- Using sparse vector queries
- Using semantic queries (legacy)

### Retrieve indexed chunks

### Return semantic_text field embeddings
- Return semantic field embeddings in _source
- Return semantic field embeddings using fields

### Highlight the most relevant fragments
- Highlight semantic_text fields
- Enforce semantic highlighter
- Retrieve fragments in original order

### Perform cross-cluster search (CCS) for semantic_text

[kosabogi]

I like this organization idea! I'll wait for SME feedback before implementing. If they agree, I'll reorganize the how-to content accordingly.

[leemthompo]

Overview page is looking good! I have a few language suggestions, and a few optional nits at this stage :)

[kosabogi]

I've left some overall technical feedback, but at a higher level it feels like this could be significantly condensed. There's a lot of repetition that I don't know how valuable it is to users. Furthermore things like multi fields - do we really need explicit examples for this because it just should work like any other field? Food for thought, I will defer to @leemthompo 's expertise on flow and layout.

My questions on recommending EIS are a business question, I do not know the official answer.

Thank you for your review! I’ve fixed a few points you highlighted and responded to each comment to clarify where needed.

Regarding the multi-field example: I agree with your point that it may not add much value in its current form, especially without additional context or a specific use case. I’m happy to remove it now and if needed, we can add it back later in a follow-up PR with clearer justification and a concrete use case?

Your technical feedback has been really helpful. Even though this PR is primarily focused on restructuring and not adding/removing content (beyond summaries and intro text), it’s great that you caught these issues so we can improve the content itself as well.

[kderusso]

My original technical edits have been addressed, thanks.
We should answer the question of recommending EIS before merging.
Deferring approval for structure etc. to the docs team. :)

[leemthompo]

Just noticed a couple minor things :)

It might be good to get another writer to this final review too, but happy to approve once you're ready if necessary

[marciw]

Looking good! Small comments

[marciw]

The tab item title says "default," but then the text on the tab says "preconfigured," which is confusing because the other 2 tabs distinguish default and preconfigured... I might just be confused. :)

[kosabogi]

Great point, thank you! I changed the wording to "default".

[maxjakob]

I think there is an important distinction that we should represent here:

• Preconfigured endpoints are automatically created by Elasticsearch on startup. These are many in an ES cluster. Examples: .elser-2-elasticsearch, .elser-2-elastic or .jina-embeddings-v3 (about to be released).
• Some features like semantic_text have default endpoints configured. There is always just one per features. Examples: semantic_text uses .elser-2-elasticsearch, text_similarity_reranker will use .jina-reranker-v2 (soon).

[maxjakob]

@kosabogi pinging here to make sure you saw this. Could be a good follow up to clarify the terms

[kosabogi]

Hey @maxjakob, thanks a lot for the clarification. I’ve added this as an item to address in a follow-up issue.

[leemthompo]

LGTM with a big ++ to @marciw's suggestions. Thanks for iterating!