Jira 11 の検索 API の非推奨機能およびアップグレード ガイド
検索ツールでより柔軟なオプションを利用できるように、Jira の検索機能に抽象化レイヤーが導入されます。この変更により、公開 API から Lucene への参照が削除され、OpenSearch がサポートされるようになります。この変更にかかわらず、検索とインデックス化のパフォーマンスは現在の Lucene 実装と同じで、スムーズな移行が保証されます。
このページでは、削除される Lucene 固有の API とコンポーネントについて概説し、プラットフォームに依存しない検索 API への移行方法について詳しく説明します。
アトラシアンでは、アップグレード ドキュメントに積極的に取り組んでおり、今後もこの記事を更新していく予定です。さらに、すべての変更を変更ログでお知らせするため、簡単に追跡できます。変更ログについては、こちらをご確認ください。
このページの内容
重大な API の変更を検索 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 | 廃止 | 手順 |
|---|---|---|
jira-api |
| 代わりに
|
jira-api |
|
|
jira-api |
| 代わりに
|
jira-api |
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 |
| 代わりに 従来の
|
jira-api |
Base classes:
非推奨のインデクサーは次の SPI によって Jira に登録されますが、これも非推奨です。
| 代わりに
次の SPI を使用して新しいインデクサーを登録します。
|
Lucene |
| To read indexed documents, use ドキュメントにインデックスを付けるには、代わりに Also see: |
Lucene |
| 代わりに 非推奨の実装では、空のクエリは 空のクエリは |
jira-api |
| 代わりに |
jira-api |
| Use these following methods that return a
|
jira-core |
| Use these interfaces instead:
|
Lucene |
| 代わりに c |
jira-lucene-dmz |
| 代わりに |
jira-lucene-dmz |
|
Then get |
jira-lucene-dmz |
| 代替はありません。これらのメソッドは Lucene 固有のものであり、今後の OpenSearch には関係ありません。 |
jira-lucene-dmz |
| 代替はありません。これらのメソッドは Lucene 固有のものであり、今後の OpenSearch には関係ありません。 |
jira-lucene-dmz | com.atlassian.jira.issue.search.SearchQuery | ドキュメントベースの検索には代わりに |
jira-lucene-dmz |
| 代わりに |
jira-lucene-dmz |
| このクラスは、非推奨の Lucene インデックスのみをサポートしています。OpenSearch などの他の検索プラットフォームをサポートする代替はありません。 |
Lucene |
| |
REST API |
| 代替はありません。このエンドポイントは Lucene 固有のものであり、今後の検索 API や OpenSearch には関係ありません。 |
jira-api |
| 非推奨の ソート機能付きのカスタム フィールド サーチャーをすでに使用しているカスタム フィールドでは、追加の変更なしで 同等のカスタム フィールド サーチャーの実装を次に示します。
可能であれば、 複数値フィールドの場合、 |
jira-core |
|
|
jira-api |
|
|
jira-lucene-dmz |
| jira-api モジュールの検索 API の代替機能を使用します。
|
jira-api |
| このクラスは、検索 API への移行を容易にすることを目的として Jira 10.4 で追加された一時的なヘルパーです。Jira 11 にはこれに代わるものはありません。 |
jira-api |
|
|
Lucene |
| 代わりに |
日付フィールドのインデックス化
LocalDate は、エポックからの日数単位ではなく、エポックからのミリ秒単位で保存されるようになりました。この変更は、期限、作業時間ログの日付、カスタム日付ピッカーの各フィールドに影響します。ただし、このアップデートは、検索 API を介したデータ アクセスではシームレスに行われます。
Jira 11 をインストールする際には、再インデックス化が必要になります。日付をインデックス化する場合は、エポックからのミリ秒単位でインデックス化してください。
ドキュメントの合計数をクエリで照会する
インデックス内のドキュメントの総数をクエリで照会するには、既存の Lucene API を使用できます。課題の総数を取得する方法を次に示します。
// Deprecated searchProviderFactory.getSearcher(SearchProviderFactory.ISSUE_INDEX).getIndexReader().numDocs()検索 API サービスには、ドキュメントのカウント用に IssueDocumentSearchService.getHitCount() メソッドが用意されています。ただし、Jira には、空の JQL クエリに対して一致なしを強制的に返す設定オプションがあります。
String JIRA_EMPTY_JQL_RETURNS_NO_DATA_ENABLED = "jira.empty.jql.returns.no.data.enabled"このオプションを有効にした場合、getHitCount では空の JQL が解析されて 0 が返されます。
代わりに次の方法を使用すると、jira.empty.jql.returns.no.data.enabled の設定に関係なく、正しいドキュメント数が返されます。
- このオプションを使用するには、
IssueIndexAccessorRegistryを依存関係として自動注入してから、次のように実行します。
issueIndexAccessorRegistry.getIssuesIndexAccessor().getSearcher() .getHitCount(SearchRequest.builder().query(DefaultMatchAllDocsQuery.INSTANCE).documentType(DocumentTypes.ISSUE).build(), timeout);- 結果を現在の
ApplicationUserに基づく権限フィルターでフィルタリングする必要がある場合は、次の手順に従ってください。
DefaultQueryFactoryを依存関係として自動注入します。フィルター クエリを
DefaultMatchAllDocsQuery.INSTANCEに設定した空の JQL クエリを使用します。var query = defaultQueryFactory.createIssueQuery(applicationUser, jqlQuery, DefaultMatchAllDocsQuery.INSTANCE, overrideSecurity); issueIndexAccessorRegistry.getIssuesIndexAccessor().getSearcher() .getHitCount(SearchRequest.builder().query(query).documentType(DocumentTypes.ISSUE).build(), timeout);
OpenSearch との互換性確保のための準備を行う
検索 API は、コードをコンパイルして Lucene と OpenSearch の両方でシームレスに機能できるようにする統一されたインターフェイスを提供しますが、これら 2 つの基盤となる検索プラットフォームには、特に規模とパフォーマンスに関して根本的な違いがあることを認識する必要があります。プラグイン コードが検索 API に対してコンパイルを行い、Lucene で正常に動作する場合でも、OpenSearch で実行した場合は特定の操作に新しい制限が適用されることがあります。
検索結果のサイズ制限
Lucene には、1 回の検索リクエストで返されるドキュメントの数に制限はありませんが、OpenSearch にはその制限があります。既定値は 10,000 ですが、OpenSearch インデックスの max_result_window で設定可能です。
関連する OpenSearch ドキュメントをご確認ください。
ドキュメントを無制限または大量に取得せずに済むようにアプリを設計することをお勧めします。そのためのテクニックとして、ページネーションや集計 API を使用できます。
避けられない場合は、searchStream API を使用すると、検索プラットフォームに関係なく大量の結果を安全にストリーミングできます。
用語クエリのサイズ制限
com.atlassian.jira.search.query.TermSetQuery は、Lucene の TermsQuery と同等の検索 API です。
Lucene とは異なり、OpenSearch では用語クエリに含めることができる用語の数に制限があります。この制限は max_terms_count で設定可能で、既定値は 65.536 です。
関連する OpenSearch ドキュメントをご確認ください。