How to Use Wildcard and Prefix Queries for Flexible Pattern Matching in OpenSearch

The aws-samples OpenSearch tutorials repository implements flexible pattern matching through a search Lambda that constructs wildcard queries for glob-style patterns (lines 310-324) and match_phrase_prefix queries for autocomplete behavior (lines 351-366) based on JSON request payloads.

Wildcard and prefix queries enable powerful, flexible search capabilities in OpenSearch without requiring exact matches. The aws-samples/sample-for-amazon-opensearch-service-tutorials-101 repository demonstrates production-ready implementations of these query types through a serverless search Lambda, allowing API consumers to choose between glob-style wildcard matching and autocomplete-style prefix searching.

Understanding Wildcard and Prefix Query Patterns

Wildcard queries use * and ? operators to match any character sequences, making them ideal for partial matches across entire fields. Prefix queries match documents containing terms that start with the specified prefix, optimized for autocomplete and type-ahead functionality.

Implementing Wildcard Queries for Glob-Style Matching

Wildcard Query Construction in opensearch_search.py

In artifacts/search_lambda/opensearch_search.py (lines 310-324), the Lambda handles wildcard_match request types by extracting attribute_name, attribute_value, and an optional case_insensitive boolean. The implementation constructs a standard OpenSearch wildcard clause:

{
  "wildcard": {
    "<attribute_name>": {
      "value": "<attribute_value>",
      "case_insensitive": true
    }
  }
}

Practical Wildcard Query Example

To search for products containing "run" anywhere in the name:

{
  "type": "wildcard_match",
  "attribute_name": "product_name",
  "attribute_value": "*run*",
  "case_insensitive": true
}

The case_insensitive parameter controls whether the pattern matching respects case sensitivity, defaulting to the OpenSearch cluster settings when omitted.

Building Prefix Queries for Autocomplete Functionality

Match Phrase Prefix Implementation

For autocomplete scenarios, the repository implements prefix_match requests using match_phrase_prefix queries. Located in artifacts/search_lambda/opensearch_search.py (lines 351-366), this logic constructs queries with specific expansion controls:

{
  "match_phrase_prefix": {
    "<attribute_name>": {
      "query": "<attribute_value>",
      "max_expansions": 10,
      "slop": 1
    }
  }
}

Handling Empty Values and Edge Cases

The implementation includes defensive programming for empty inputs. When attribute_value is empty or null, the Lambda falls back to a match_all query rather than constructing an invalid prefix clause. This ensures the search returns results rather than errors when users clear autocomplete inputs.

Prefix Query Request Example

To implement type-ahead search for products starting with "run":

{
  "type": "prefix_match",
  "attribute_name": "product_name",
  "attribute_value": "run"
}

The max_expansions: 10 parameter limits the prefix expansion to the top 10 matching terms, controlling query performance while maintaining autocomplete responsiveness.

The Complete Query Execution Flow

The search Lambda follows a structured pipeline when processing wildcard and prefix queries:

1. Request Validation – Validates that attribute_name is a string and attribute_value is a string or integer, rejecting malformed inputs before query construction.

2. Query Construction – Based on the type field (wildcard_match or prefix_match), inserts the appropriate clause into a standard OpenSearch body with size: 100.

3. Execution – Sends the constructed body via ops_client.search to the OpenSearch domain defined in search_tutorials/opensearch_proxy_stack.py.

4. Post-Processing – When hits exist, the Lambda generates presigned URLs for result assets before returning the formatted response.

This architecture, exposed through API Gateway defined in search_tutorials/api_gateway_stack.py, provides a serverless interface for flexible pattern matching without managing search cluster connections client-side.

Summary

• Wildcard queries in artifacts/search_lambda/opensearch_search.py (lines 310-324) enable glob-style pattern matching using * and ? operators with optional case-insensitive flags.

• Prefix queries via match_phrase_prefix (lines 351-366) provide autocomplete functionality with controlled expansion limits and automatic fallback to match_all for empty inputs.

• Both query types integrate into a validated, serverless pipeline that constructs OpenSearch DSL, executes via the Python client, and returns processed results with presigned URLs.

• The implementation demonstrates production-ready pattern matching strategies suitable for partial text search and type-ahead interfaces.

Frequently Asked Questions

What is the difference between wildcard and prefix queries in OpenSearch?

Wildcard queries use * and ? characters to match patterns anywhere within field values, making them suitable for partial matches like *shoe*. Prefix queries match only the beginning of terms, optimized for autocomplete scenarios where users type the start of a word. The repository implements wildcard queries via the wildcard DSL clause and prefix queries via match_phrase_prefix.

How do I make wildcard queries case-insensitive?

Set the case_insensitive parameter to true in your JSON request payload. In artifacts/search_lambda/opensearch_search.py (lines 310-324), the Lambda extracts this boolean flag and passes it directly to the OpenSearch wildcard query clause. When omitted, the query respects the cluster's default case sensitivity settings.

What happens when I send an empty value to a prefix query?

The search Lambda implements defensive handling for empty inputs. When attribute_value is empty or null, the code falls back to a match_all query instead of constructing an invalid match_phrase_prefix clause. This ensures the search returns all documents rather than throwing errors when users clear autocomplete input fields.

Which query type should I use for autocomplete functionality?

Use prefix queries (prefix_match type) for autocomplete implementations. The repository's match_phrase_prefix configuration includes max_expansions: 10 and slop: 1 parameters that control expansion behavior and phrase flexibility. This approach efficiently matches documents where the last term of the input phrase is a prefix of indexed terms, providing responsive type-ahead results without the performance overhead of wildcard scans.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}