Search API upgrade guide
Introduction
To provide you with more agnostic options for search tooling, we’re adding an abstraction layer to Jira’s search functionality. This change is key to enable future OpenSearch support, and is the start of our plans to remove Lucene from public APIs. Search and indexing performance will remain consistent with the existing Lucene implementation, ensuring a smooth transition.
This page documents Lucene-specific API and components that have been deprecated in favor of the platform-agnostic search API. We’ll add further information as the feature progresses.
You may also wish to visit the FieldIndexer migration details page and https://developer.atlassian.com/server/jira/platform/custom-field/#custom-field-sorting for further details.
Migrating deprecated code 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 com
|
jira-api | com 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:
Remove implementations of |
lucene |
| Use Use one of the subtypes that corresponds with the legacy FieldComparatorSource:
|
jira-api |
Base classes:
Deprecated indexers are registered into Jira by the following SPI which is also deprecated:
| Implement
Use the following SPI to register new indexers:
|
lucene |
| To read indexed documents, use To index into a document, use
|
lucene |
| Use |
jira-api |
| Use |
jira-api |
| Use these following methods that return a
|
jira-api |
| No replacements. These methods are Lucene specific, not relevant on OpenSearch going forward. |
jira-core |
| Use these interfaces instead:
|
lucene |
| Use |
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-core |
| No replacements. This class is Lucene specific, not relevant on OpenSearch going forward. |
jira-lucene-dmz |
| 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 |
| Use This will scan through all the matching documents from the index. We do not recommend this for performing aggregations (e.g. count, sum, etc) because it will perform poorly when running on OpenSearch, since it would result in transferring an unnecessarily large amount of data over the network. We’re currently working on introducing aggregation support on Jira’s search API which utilizes OpenSearch's aggregation API to do this in an efficient manner. This will come in a future version of Jira 10. |
REST API | PUT: | No replacements. This endpoint is Lucene specific, not relevant for the Search API or OpenSearch going forward. |