Current documentation for Jira Data Center text searching does not provide sufficient detail on how the underlying Lucene engine tokenizes strings containing special characters (dots, underscores, dashes, etc.). This leads to "silent exclusions" where users expect a match based on visual string similarity, but the search returns incomplete results due to how tokens are stored and queried.

We request that the following technical details be incorporated into Search syntax for text fields - Jira Software Data Center 11.3 - Atlassian Documentation and Advanced searching - Jira Software Data Center 11.3 - Atlassian Documentation:

Proposed Documentation Updates:

1. Punctuation & Tokenization: Explicitly state that most punctuation is not stored in the index and acts as a token separator.
2. Dot (.) Handling: Clarify that a dot not followed by whitespace is typically kept inside the token. Consequently, hostnames (e.g., atlassian.com) and email addresses are indexed as a single token.
3. Underscores (_) and Dashes (-): These are treated as separators. A value like www_atlassian_com_au is split into four distinct tokens (www, atlassian, com, au) and is never stored as a single string.
4. Alphanumeric "Glue": Note that numbers can "glue" tokens together; for example, com_v2 may stay as one token depending on the analyzer.
5. Wildcard Limitations:
   • Wildcard searches ( * , ?) operate on single stored tokens only.
   • Wildcard terms are not analysed.
   • A wildcard search will return 0 results if the search term contains a character that causes a token split (e.g., text ~ "azure_diag*" will fail because the underscore splits the query into terms that don't match the single-token wildcard logic).
6. Phrase Search vs. Subdomains: Phrase searches ("...") match exact adjacent tokens. They can silently omit issues where the search term is part of a larger token.
   • Example: A search for "atlassian.com" will not match an issue containing www.atlassian.com if the latter is indexed as a single token.
7. Search Completeness & Alternatives: Formally state that no native JQL (~) form guarantees a 100% complete result set for arbitrary strings containing special characters. Recommend the following supported alternatives for "System of Record" requirements:
   • Use a dedicated custom field with an Exact Text Searcher (queried with =).
   • Use regex-based search aliases (e.g., via ScriptRunner).
8. Behavioral Changes: Reference the behavior change introduced/fixed in JRASERVER-79387, where all resulting tokens from a query must be present in the document for a match to occur (included in Jira 11.3.7+).

Why this is important

Jira is frequently used as an operational system of record. Without clear documentation on these Lucene-specific rules, users create filters for SLAs, reporting, and automation that silently exclude valid issues, creating significant operational risk.