Text Search

Marketplace product and listing search uses OpenSearch with a 6-tier scoring hierarchy that prioritizes exact matches over fuzzy matches. This page documents how text search queries are constructed, how locale-aware field resolution works, and how results are ranked.

Overview

Scoring Hierarchy

When a user types a search query, we generate multiple OpenSearch clauses per field, each with a different boost value. OpenSearch picks the highest-scoring clause that matches, so exact matches always rank above fuzzy matches.

Query Flow

Locale-Aware Field Resolution

When a locale is provided (e.g., fr for French), the search targets locale-specific translation fields first, with a fallback to the base English name field.

Field Selection

Field Precedence Multiplier

Each subsequent field gets 95% of the previous field’s boost (fieldPrecedence: 0.95). This means locale-specific results rank higher than base name matches:

French field boost:  1000 × 0.95⁰ = 1000  (textMatchAll)
English field boost: 1000 × 0.95¹ = 950   (textMatchAll)

The same multiplier applies to all 6 priority levels, so a French exact phrase match (5000) always beats an English exact phrase match (4750).

Query Structure Example

For a query like "Black Lotus" with locale=fr, the generated OpenSearch DSL looks like:

{
  bool: {
    should: [
      // --- French translation field (multiplier: 1.0) ---
      // P1: Exact phrase
      { match_phrase: { "product.translations.fr.name": { query: "Black Lotus", slop: 0, boost: 5000 } } },
      // P2: Flexible phrase
      { match_phrase: { "product.translations.fr.name": { query: "Black Lotus", slop: 2, boost: 2500 } } },
      // P3: All words match
      { match: { "product.translations.fr.name": { query: "Black Lotus", operator: "and", boost: 1000 } } },
      // P4: Prefix exact
      { multi_match: { query: "Black Lotus", type: "bool_prefix",
          fields: ["product.translations.fr.name.suggest", "...._2gram", "...._3gram"], boost: 100 } },
      // P5: Prefix fuzzy
      { multi_match: { query: "Black Lotus", type: "bool_prefix",
          fields: ["product.translations.fr.name.suggest", "...._2gram", "...._3gram"],
          fuzziness: 1, prefix_length: 2, boost: 50 } },
      // P6: Fuzzy fallback
      { match: { "product.translations.fr.name": { query: "Black Lotus", fuzziness: 1,
          prefix_length: 2, operator: "or", boost: 10 } } },
 
      // --- Base name field (multiplier: 0.95) ---
      // Same 6 clauses with boost × 0.95 ...
    ],
    minimum_should_match: 1
  }
}

Sort Behavior

The sort strategy depends on whether the user is doing a text search and whether they specified an explicit sort:

Comparison with MongoDB Atlas Search

Inventory search still uses MongoDB Atlas Search via configureSearchOperator(). Both implementations follow the same conceptual hierarchy:

The boost values are identical across both engines to ensure consistent search behavior.

Index Schema Requirements

Text search relies on specific field mappings in the OpenSearch index:

• product.name: text with product_name_analyzer + .keyword + .suggest (search_as_you_type)
• product.translations.{locale}.name: Same mapping as product.name (via translationNameField())
• product.expansion.name: text with keyword + .suggest (search_as_you_type)
• product.expansion.translations.{locale}.name: Same as above

The product_name_analyzer uses standard tokenizer with lowercase and asciifolding filters, so accented characters like “Épée” match searches for “epee”.

The search_as_you_type sub-field automatically creates internal ._2gram, ._3gram, and ._index_prefix sub-fields that enable efficient prefix matching.

Code Locations