Search API deprecations and upgrade guide for Jira 11
To offer more flexible options for search tools, we're introducing an abstraction layer to Jira's search functionality. This change will support OpenSearch by removing references to Lucene from public APIs. Despite these changes, search and indexing performance will remain consistent with the current Lucene implementation, ensuring a smooth transition.
This page outlines the Lucene-specific APIs and components that are being removed and provides details on how to migrate to the platform-agnostic search API.
We are actively working on the upgrade documentation and will continue to update this article. Additionally, we will communicate any changes in our changelog to make tracking them easier. Explore the changelog
On this page:
- Migrating breaking API changes to Search API
- Date field indexing
- Query total document count
- Preparing for OpenSearch compatibility
Migrating breaking API changes to Search API
Due to the length of some of the strings in the table below, you might not see the full table width. To see more to the right or left, hover your mouse over the table before using it to scroll.
Module | Deprecation | Instructions |
|---|---|---|
jira-api |
| Use
|
jira-api |
| Use |
jira-api |
| Use
|
jira-api |
Classes extending Also deprecated, related searcher SPIs:
| The deprecated class is used for two use cases: sorting, and loading field values from the index. Depending on the use case, replace
Migrate related searcher SPIs to the corresponding replacements:
|
lucene |
| Use Use one of the subtypes that corresponds with the legacy
|
jira-api |
Base classes:
Indexer implementations in
Deprecated indexers are registered into Jira by the following SPI which is also deprecated:
| Implement
Use indexer implementations in the Use the following SPI to register new indexers: Use |
lucene |
| To read indexed documents, use To index into a document, use Also see: |
lucene |
| Use Note that in the deprecated implementation, an empty query would result in An empty query can be replaced with |
jira-api |
| Use |
jira-api |
| Use these following methods that return a
|
jira-core |
| Use these interfaces instead:
|
lucene |
| Use c |
jira-lucene-dmz |
| Use |
jira-lucene-dmz |
| Use
Then get |
jira-lucene-dmz |
| No replacement. These methods are Lucene-specific, not relevant on OpenSearch going forward. |
jira-lucene-dmz |
| No replacement. These methods are Lucene-specific, not relevant on OpenSearch going forward. |
jira-lucene-dmz | com.atlassian.jira.issue.search.SearchQuery | Use |
jira-lucene-dmz |
| Use |
jira-lucene-dmz |
| This class only supports Lucene index which is deprecated. No replacements to support other search platforms such as OpenSearch. |
lucene |
| |
REST API |
| No replacements. This endpoint is Lucene-specific, not relevant for the Search API or OpenSearch going forward. |
jira-api |
| The deprecated A custom field already using a Custom Field Searcher with sorting can remove the The equivalent Custom Field Searcher implementation should:
Note that where possible, other more efficient sort types such as For a multi-value field, |
jira-core |
| See the migration notes above for |
jira-api |
| Use methods from the
|
jira-lucene-dmz |
| Use Search API replacements from the jira-api module:
|
jira-api |
| This class is a temporary helper added in Jira 10.4 to facilitate migrating to Search API. There is no replacement in Jira 11. |
jira-api |
Constructors which have | Use the constructor which doesn't have |
lucene |
| Use |
Date field indexing
The LocalDate is now stored as milliseconds since the epoch instead of days since the epoch. This change affects the following fields: due date, work log date, and custom date picker. However, this update will be seamless for data access through the Search API.
When installing Jira 11, re-indexing will be necessary. If you’re indexing dates, ensure that you index them as milliseconds since the epoch.
Query total document count
To query the total number of documents in the index, you can use the existing Lucene API. Here's how you can retrieve the total number of issues:
// Deprecated searchProviderFactory.getSearcher(SearchProviderFactory.ISSUE_INDEX).getIndexReader().numDocs()For counting documents, the Search API service provides the IssueDocumentSearchService.getHitCount() method. However, Jira has a configuration option that can force the return of no matches for an empty JQL query:
String JIRA_EMPTY_JQL_RETURNS_NO_DATA_ENABLED = "jira.empty.jql.returns.no.data.enabled"When this option is enabled, getHitCount will parse an empty JQL to return 0.
Here are alternatives that return the correct document count regardless of the jira.empty.jql.returns.no.data.enabled configuration setting:
- To use this option, autowire
IssueIndexAccessorRegistryas a dependency, then execute the following:
issueIndexAccessorRegistry.getIssuesIndexAccessor().getSearcher() .getHitCount(SearchRequest.builder().query(DefaultMatchAllDocsQuery.INSTANCE).documentType(DocumentTypes.ISSUE).build(), timeout);- If the result needs to be filtered by a permission filter based on the current
ApplicationUser, follow these steps:
Autowire
DefaultQueryFactoryas a dependency.Use an empty JQL query with a filter query set to
DefaultMatchAllDocsQuery.INSTANCE.var query = defaultQueryFactory.createIssueQuery(applicationUser, jqlQuery, DefaultMatchAllDocsQuery.INSTANCE, overrideSecurity); issueIndexAccessorRegistry.getIssuesIndexAccessor().getSearcher() .getHitCount(SearchRequest.builder().query(query).documentType(DocumentTypes.ISSUE).build(), timeout);
Preparing for OpenSearch compatibility
While the Search API provides a unified interface that allows code to compile and function seamlessly with both Lucene and OpenSearch, it's important to recognize that there are fundamental differences between these two underlying search platforms, especially related to scale and performance. Even when your plugin code compiles against the Search API and works as expected with Lucene, certain operations may be subject to new limitations when running on OpenSearch.
Search results size limit
Lucene has no limit on the number of documents that can be returned from a single search request, but OpenSearch does. The default is 10,000, and it is configurable via the max_result_window setting in the OpenSearch index.
Explore the related OpenSearch documentation:
It's recommended to design your application so that retrieving an unlimited or very large number of documents is not necessary. Some techniques include using pagination or the aggregation API.
If it is unavoidable, the searchStream API provides a safe way to stream a large volume of results regardless of the search platform.
Terms query size limit
com.atlassian.jira.search.query.TermSetQuery is the Search API equivalent of Lucene’s TermsQuery.
Unlike Lucene, OpenSearch enforces a limit on the number of terms that a Terms Query can contain. This limit is configurable via the max_terms_count setting and defaults to 65,536.
Explore the related OpenSearch documentation: