DocumentationMappingConfig.cs

// Licensed to Elasticsearch B.V under one or more agreements.
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
// See the LICENSE file in the project root for more information

using Elastic.Mapping;
using Elastic.Mapping.Analysis;
using Elastic.Mapping.Mappings;

namespace Elastic.Documentation.Search;

[ElasticsearchMappingContext]
[Index<DocumentationDocument>(
	NameTemplate = "docs-{type}.lexical-{env}",
	DatePattern = "yyyy.MM.dd.HHmmss",
	Configuration = typeof(LexicalConfig)
)]
[Index<DocumentationDocument>(
	NameTemplate = "docs-{type}.semantic-{env}",
	Variant = "Semantic",
	DatePattern = "yyyy.MM.dd.HHmmss",
	Configuration = typeof(SemanticConfig)
)]
[AiEnrichment<DocumentationDocument>(
	Role = "Expert technical writer creating search metadata for Elastic documentation (Elasticsearch, Kibana, Beats, Logstash). Audience: developers, DevOps, data engineers.",
	MatchField = "url",
	IndexVariant = "Semantic"
)]
public static partial class DocumentationMappingContext;

public class LexicalConfig : IConfigureElasticsearch<DocumentationDocument>
{
	public AnalysisBuilder ConfigureAnalysis(AnalysisBuilder analysis) => analysis;

	public IReadOnlyDictionary<string, string>? IndexSettings => null;

	public MappingsBuilder<DocumentationDocument> ConfigureMappings(MappingsBuilder<DocumentationDocument> mappings) =>
		ConfigureCommonMappings(mappings)
			.StrippedBody(f => f
				.Analyzer("synonyms_fixed_analyzer")
				.SearchAnalyzer("synonyms_analyzer")
				.TermVector("with_positions_offsets")
			);

	internal static MappingsBuilder<DocumentationDocument> ConfigureCommonMappings(MappingsBuilder<DocumentationDocument> m) => m
		// Text fields with custom analyzers and multi-fields
		.SearchTitle(f => f
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer")
			.MultiField("completion", mf => mf.SearchAsYouType()
				.Analyzer("synonyms_fixed_analyzer")
				.SearchAnalyzer("synonyms_analyzer")
				.IndexOptions("offsets")))
		.Title(f => f
			.SearchAnalyzer("synonyms_analyzer")
			.MultiField("keyword", mf => mf.Keyword().Normalizer("keyword_normalizer"))
			.MultiField("starts_with", mf => mf.Text()
				.Analyzer("starts_with_analyzer")
				.SearchAnalyzer("starts_with_analyzer_search"))
			.MultiField("completion", mf => mf.SearchAsYouType().SearchAnalyzer("synonyms_analyzer")))
		.Abstract(f => f
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer"))
		.Headings(f => f
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer"))
		// AI fields with custom analyzers not on the attribute
		.AddField("ai_rag_optimized_summary", f => f.Text()
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer"))
		.AddField("ai_questions", f => f.Text()
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer")
			.MultiField("completion", mf => mf.SearchAsYouType()
				.Analyzer("synonyms_fixed_analyzer")
				.SearchAnalyzer("synonyms_analyzer")
				.IndexOptions("offsets")))
		.AddField("ai_autocomplete_questions", f => f.Text()
			.Analyzer("synonyms_fixed_analyzer")
			.SearchAnalyzer("synonyms_analyzer")
			.MultiField("completion", mf => mf.SearchAsYouType()
				.Analyzer("synonyms_fixed_analyzer")
				.SearchAnalyzer("synonyms_analyzer")
				.IndexOptions("offsets"))
			.MultiField("suggest", mf => mf.Completion()))
		// Keyword fields with multi-fields
		.Url(f => f
			.MultiField("match", mf => mf.Text())
			.MultiField("prefix", mf => mf.Text().Analyzer("hierarchy_analyzer")))
		// Rank features — no attribute available, must use AddField
		.AddField("navigation_depth", f => f.RankFeature().PositiveScoreImpact(false))
		.AddField("navigation_table_of_contents", f => f.RankFeature().PositiveScoreImpact(false))
		// Nested applies_to — sub-fields don't match C# structure (custom JsonConverter)
		.AddField("applies_to.type", f => f.Keyword().Normalizer("keyword_normalizer"))
		.AddField("applies_to.sub-type", f => f.Keyword().Normalizer("keyword_normalizer"))
		.AddField("applies_to.lifecycle", f => f.Keyword().Normalizer("keyword_normalizer"))
		.AddField("applies_to.version", f => f.Version())
		// Parent document multi-fields
		.AddField("parents.url", f => f.Keyword()
			.MultiField("match", mf => mf.Text())
			.MultiField("prefix", mf => mf.Text().Analyzer("hierarchy_analyzer")))
		.AddField("parents.title", f => f.Text()
			.SearchAnalyzer("synonyms_analyzer")
			.MultiField("keyword", mf => mf.Keyword()));
}

public class SemanticConfig : IConfigureElasticsearch<DocumentationDocument>
{
	public AnalysisBuilder ConfigureAnalysis(AnalysisBuilder analysis) => analysis;

	public IReadOnlyDictionary<string, string>? IndexSettings => null;

	public MappingsBuilder<DocumentationDocument> ConfigureMappings(MappingsBuilder<DocumentationDocument> mappings) =>
		LexicalConfig.ConfigureCommonMappings(mappings)
			.StrippedBody(s => s
				.Analyzer("synonyms_fixed_analyzer")
				.SearchAnalyzer("synonyms_analyzer")
				.TermVector("with_positions_offsets")
			)
			// Semantic text fields — uses platform default inference
			.AddField("title.semantic_text", f => f.SemanticText())
			.AddField("abstract.semantic_text", f => f.SemanticText())
			.AddField("ai_rag_optimized_summary.semantic_text", f => f.SemanticText())
			.AddField("ai_questions.semantic_text", f => f.SemanticText())
			.AddField("ai_autocomplete_questions.semantic_text", f => f.SemanticText())
			.AddField("ai_use_cases.semantic_text", f => f.SemanticText());
}

/// <summary>
/// Builds analysis settings at runtime (includes synonyms that are loaded from configuration).
/// </summary>
public static class DocumentationAnalysisFactory
{
	public static AnalysisBuilder BuildAnalysis(AnalysisBuilder analysis, string synonymSetName, string[] indexTimeSynonyms) => analysis
		.Normalizer("keyword_normalizer", n => n.Custom()
			.CharFilter("strip_non_word_chars")
			.Filters("lowercase", "asciifolding", "trim"))
		.Analyzer("starts_with_analyzer", a => a.Custom()
			.Tokenizer("starts_with_tokenizer")
			.Filter("lowercase"))
		.Analyzer("starts_with_analyzer_search", a => a.Custom()
			.Tokenizer("keyword")
			.Filter("lowercase"))
		.Analyzer("synonyms_fixed_analyzer", a => a.Custom()
			.Tokenizer("group_tokenizer")
			.Filters("lowercase", "synonyms_fixed_filter", "kstem"))
		.Analyzer("synonyms_analyzer", a => a.Custom()
			.Tokenizer("group_tokenizer")
			.Filters("lowercase", "synonyms_filter", "kstem"))
		.Analyzer("highlight_analyzer", a => a.Custom()
			.Tokenizer("group_tokenizer")
			.Filters("lowercase", "english_stop"))
		.Analyzer("hierarchy_analyzer", a => a.Custom()
			.Tokenizer("path_tokenizer"))
		.CharFilter("strip_non_word_chars", cf => cf.PatternReplace()
			.Pattern(@"\W")
			.Replacement(" "))
		.TokenFilter("synonyms_fixed_filter", tf => tf.SynonymGraph()
			.Synonyms(indexTimeSynonyms))
		.TokenFilter("synonyms_filter", tf => tf.SynonymGraph()
			.SynonymsSet(synonymSetName)
			.Updateable(true))
		.TokenFilter("english_stop", tf => tf.Stop()
			.Stopwords("_english_"))
		.Tokenizer("starts_with_tokenizer", t => t.EdgeNGram()
			.MinGram(1)
			.MaxGram(10)
			.TokenChars("letter", "digit", "symbol", "whitespace"))
		.Tokenizer("group_tokenizer", t => t.CharGroup()
			.TokenizeOnChars("whitespace", ",", ";", "?", "!", "(", ")", "&", "'", "\"", "/", "[", "]", "{", "}"))
		.Tokenizer("path_tokenizer", t => t.PathHierarchy()
			.Delimiter('/'));
}