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

com.atlassian.jira.index.EntitySearchExtractor and its subtypes:

  1. com.atlassian.jira.index.ChangeHistorySearchExtractor

  2. com.atlassian.jira.index.CommentSearchExtractor

  3. com.atlassian.jira.index.IssueSearchExtractor

Use com.atlassian.jira.search.entity.EntityIndexExtractor and its subtypes instead:

  1. com.atlassian.jira.search.entity.ChangeHistoryIndexExtractor

  2. com.atlassian.jira.search.entity.CommentIndexExtractor

  3. com.atlassian.jira.search.entity.IssueIndexExtractor

  4. com.atlassian.jira.search.entity.WorkLogIndexExtractor

jira-api

com.atlassian.jira.jql.query.ClauseQueryFactory and related interfaces:

  1. com.atlassian.jira.jql.query.QueryFactoryResult

  2. com.atlassian.jira.jql.query.OperatorSpecificQueryFactory

Use com.atlassian.jira.search.jql.ClauseQueryMapper instead, and the corresponding interfaces:

  1. com.atlassian.jira.search.jql.QueryFactoryResult

  2. com.atlassian.jira.search.jql.OperatorSpecificQueryFactory

jira-api

com.atlassian.jira.issue.search.LuceneFieldSorter.

Also deprecated, related searcher SPIs:

  1. com.atlassian.jira.issue.customfields.MultiSortableCustomFieldSearcher

  2. com.atlassian.jira.issue.customfields.SortableCustomFieldSearcher

  3. com.atlassian.jira.issue.customfields.NaturallyOrderedCustomFieldSearcher#getSortFieldType()

The deprecated class is used for two use cases: sorting, and loading field values from the index. Depending on the use case, replace LuceneFieldSorter with one of the following:

  • com.atlassian.jira.search.FieldSort

  • com.atlassian.jira.search.FieldValueLoader.

Migrate related searcher SPIs to the corresponding replacements:

  1. com.atlassian.jira.issue.customfields.FieldSortsCustomFieldSearcher

  2. com.atlassian.jira.issue.customfields.ValueLoaderCustomFieldSearcher

Remove implementations of com.atlassian.jira.issue.customfields.NaturallyOrderedCustomFieldSearcher#getSortFieldType(), i.e. revert to default.

lucene

  • org.apache.lucene.search.SortField

  • org.apache.lucene.search.FieldComparatorSource

Use com.atlassian.jira.search.FieldSort instead.

Use one of the subtypes that corresponds with the legacy FieldComparatorSource:

  1. NaturalFieldSort: replaces StringSortComparatorSource and LongSortComparatorSource

  2. ValueLoaderFieldSort: replaces MappedSortComparator

  3. ScoreComputedFieldSort: replaces UserHistoryFieldComparatorSource

jira-api

com.atlassian.jira.issue.index.indexers.FieldIndexer

Base classes:

  • com.atlassian.jira.issue.index.indexers.impl.BaseFieldIndexer
  • com.atlassian.jira.issue.index.indexers.impl.AbstractCustomFieldIndexer


Deprecated indexers are registered into Jira by the following SPI which is also deprecated:

  • com.atlassian.jira.issue.search.searchers.information.SearcherInformation#getRelatedIndexers()

Implement com.atlassian.jira.search.issue.index.indexers.FieldIndexer instead, or extend one of its base classes:

  • com.atlassian.jira.search.issue.index.indexers.impl.VisibilityBaseFieldIndexer

  • com.atlassian.jira.search.issue.index.indexers.impl.BaseCustomFieldIndexer

Use the following SPI to register new indexers:

  • com.atlassian.jira.issue.search.searchers.information.SearcherInformation#getIndexers()

lucene

org.apache.lucene.document.Document

To read indexed documents, use com.atlassian.jira.search.Document instead.

To index into a document, use com.atlassian.jira.search.field.FieldValueCollector instead.
Also see:

  • com.atlassian.jira.search.issue.index.indexers.FieldIndexer

  • com.atlassian.jira.search.entity.EntityIndexExtractor

lucene

org.apache.lucene.search.Query

Use com.atlassian.jira.search.Query instead.

jira-api

DocumentConstants#LUCENE_SORTFIELD_PREFIX

Use #SORTFIELD_PREFIX instead.

jira-api

com.atlassian.jira.issue.index.SecurityIndexingUtils methods that return a org.apache.lucene.util.ByteRef:

  • generateProjectPermissionFieldContents(...)

  • generateIssueLevelPermissionContents(...)

Use these following methods that return a String instead:

  • generateProjectPermissionFieldContentString(...)

  • generateIssueLevelPermissionContentString(...)

jira-api

com.atlassian.jira.util.index.IndexLifecycleManager methods:

  • isIndexAvailable()

  • isIndexConsistent()

  • getAllIndexPaths()

No replacements. These methods are Lucene specific, not relevant on OpenSearch going forward.

jira-core

com.atlassian.jira.index.EntityDocumentFactory and its subtypes:

  1. com.atlassian.jira.issue.index.ChangeHistoryDocumentFactory

  2. com.atlassian.jira.issue.index.CommentDocumentFactory

  3. com.atlassian.jira.issue.index.IssueDocumentFactory

  4. com.atlassian.jira.issue.index.WorklogDocumentFactory

Use these interfaces instead:

  1. com.atlassian.jira.search.issue.index.ChangeHistoryFieldValuesFactory

  2. com.atlassian.jira.search.issue.index.CommentFieldValuesFactory (will come in a future version)

  3. com.atlassian.jira.search.issue.index.IssueFieldValuesFactory

  4. com.atlassian.jira.search.issue.index.WorklogFieldValuesFactory (will come in a future version)

lucene

org.apache.lucene.search.IndexSearcher, including its subtypes:

  • com.atlassian.jira.index.ManagedIndexSearcher

  • com.atlassian.jira.index.UnmanagedIndexSearcher

Use com.atlassian.jira.search.index.IndexSearcher instead.

jira-lucene-dmz

com.atlassian.jira.issue.search.SearchProvider

Use com.atlassian.jira.search.issue.IssueDocumentSearchService instead.

jira-lucene-dmz

com.atlassian.jira.issue.search.SearchProviderFactory

Use com.atlassian.jira.search.index.IndexAccessorRegistry

  • If searching for issues, use getIssuesIndexAccessor to get IndexAccessor

  • Otherwise, use getOrCreate(final String indexName) to get IndexAccessor

Then get IndexSearcher from IndexAccessor

jira-lucene-dmz

com.atlassian.jira.issue.search.parameters.lucene.JiraBytesRef

No replacement. These methods are Lucene specific, not relevant on OpenSearch going forward.

jira-lucene-dmz

com.atlassian.jira.issue.search.parameters.lucene.sort.JiraLuceneFieldFinder

No replacement. These methods are Lucene specific, not relevant on OpenSearch going forward.

jira-core

com.atlassian.jira.search.IndexConsistencyChecker

No replacements. This class is Lucene specific, not relevant on OpenSearch going forward.

jira-lucene-dmz

com.atlassian.jira.issue.search.SearchQuery

Use com.atlassian.jira.search.request.SearchRequest instead for document based search, or com.atlassian.jira.issue.search.SearchRequest for issue search.

jira-lucene-dmz

com.atlassian.jira.issue.index.IssueIndexManager

Use com.atlassian.jira.search.index.IndexAccessor or com.atlassian.jira.issue.index.IssueIndexer instead.

jira-lucene-dmz

com.atlassian.jira.issue.index.TemporaryIndexProvider

This class only supports Lucene index which is deprecated. No replacements to support other search platforms such as OpenSearch.

lucene

org.apache.lucene.search.Collector

Use com.atlassian.jira.search.index.IndexSearcher#scan(SearchRequest request, Function<Document, Boolean> callback) instead.

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: /api/2/cluster/index-snapshot/{nodeId}

The Jira Data Center REST API

No replacements. This endpoint is Lucene specific, not relevant for the Search API or OpenSearch going forward.

Last modified on Jan 21, 2025

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.