Extension:CirrusSearch

MediaWiki 拡張機能マニュアル

CirrusSearch リリースの状態: 安定
実装	検索, API , フック
説明	Elasticsearch を使った MediaWiki 検索の実装
作者	Nik Everett, Chad Horohoe, Erik Bernhardson
最新バージョン	継続的な更新
互換性の方針	MediaWiki とともにリリースされるスナップショット。 master には後方互換性がありません。
Composer	mediawiki/cirrussearch
ライセンス	GNU 一般公衆利用許諾書 2.0 以降
ダウンロード	拡張機能をダウンロード Git [?]: Git master をダウンロード リポジトリを参照 (Phabricator · GitHub) コミット履歴 リポジトリの貢献者 (GitHub) コード レビュー README
パラメーター $wgCirrusSearchDeduplicateInQuery $wgCirrusSearchLanguageWeight $wgCirrusSearchAutomationCIDRs $wgCirrusSearchUseIcuFolding $wgCirrusSearchStemmedWeight $wgCirrusSearchQueryStringMaxDeterminizedStates $wgCirrusSearchCrossClusterSearch $wgCirrusSearchExtraIndexSettings $wgCirrusSearchAutomationUserAgentRegex $wgCirrusSearchTalkNamespaceWeight $wgCirrusSearchPrefixWeights $wgCirrusSearchPrefixSearchRescoreProfile $wgCirrusSearchDisableUpdate $wgCirrusSearchActiveTest $wgCirrusSearchExtraFieldsInSearchResults $wgCirrusSearchMoreLikeThisMaxQueryTermsLimit $wgCirrusSearchUseIcuTokenizer $wgCirrusSearchCompletionBannedPageIds $wgCirrusSearchOptimizeIndexForExperimentalHighlighter $wgCirrusSearchRescoreProfiles $wgCirrusSearchPhraseRescoreBoost $wgCirrusSearchInterwikiProv $wgCirrusSearchDefaultCluster $wgCirrusSearchQueryStringMaxWildcards $wgCirrusSearchElasticQuirks $wgCirrusSearchMaxFileTextLength $wgCirrusSearchFallbackProfiles $wgCirrusSearchMoreLikeThisTTL $wgCirrusSearchAllowLeadingWildcard $wgCirrusSearchInterwikiPrefixOverrides $wgCirrusSearchMaintenanceTimeout $wgCirrusSearchReplicas $wgCirrusSearchPhraseSlop $wgCirrusSearchBoostOpening $wgCirrusSearchWriteBackoffExponent $wgCirrusSearchUserTesting $wgCirrusSearchShardCount $wgCirrusSearchUseCompletionSuggester $wgCirrusSearchPhraseSuggestReverseField $wgCirrusSearchFallbackProfile $wgCirrusSearchFragmentSize $wgCirrusSearchUnlinkedArticlesToUpdate $wgCirrusSearchCustomPageFields $wgCirrusSearchClientSideUpdateTimeout $wgCirrusSearchIgnoreOnWikiBoostTemplates $wgCirrusSearchRegexMaxDeterminizedStates $wgCirrusSearchInterwikiHTTPConnectTimeout $wgCirrusSearchExtraIndexes $wgCirrusSearchCategoryDepth $wgCirrusSearchMergeSettings $wgCirrusSearchClusters $wgCirrusSearchCrossProjectShowMultimedia $wgCirrusSearchBannedPlugins $wgCirrusSearchMoreLikeThisConfig $wgCirrusSearchClusterOverrides $wgCirrusSearchCrossProjectBlockScorerProfiles $wgCirrusSearchEnableIncomingLinkCounting $wgCirrusSearchNearMatchWeight $wgCirrusSearchWriteIsolateClusters $wgCirrusSearchIndexedRedirects $wgCirrusSearchIndexAllocation $wgCirrusSearchNumCrossProjectSearchResults $wgCirrusSearchLanguageDetectors $wgCirrusSearchUpdateShardTimeout $wgCirrusSearchEnableCrossProjectSearch $wgCirrusSearchFullTextQueryBuilderProfiles $wgCirrusSearchCompletionDefaultScore $wgCirrusSearchWriteClusters $wgCirrusSearchCompletionSuggesterHardLimit $wgCirrusSearchRecycleCompletionSuggesterIndex $wgCirrusSearchLogElasticRequests $wgCirrusSearchConnectionAttempts $wgCirrusSearchElasticaWritePartitionCounts $wgCirrusSearchWikiToNameMap $wgCirrusSearchMaxFullTextQueryLength $wgCirrusSearchLogElasticRequestsSecret $wgCirrusSearchEnableAltLanguage $wgCirrusSearchNaturalTitleSort $wgCirrusSearchDeduplicateInMemory $wgCirrusSearchEnableRegex $wgCirrusSearchClientSideSearchTimeout $wgCirrusSearchIndexFieldsToCleanup $wgCirrusSearchUseEventBusBridge $wgCirrusSearchDeduplicateAnalysis $wgCirrusSearchExtraBackendLatency $wgCirrusSearchNamespaceMappings $wgCirrusSearchWMFExtraFeatures $wgCirrusSearchPreferRecentUnspecifiedDecayPortion $wgCirrusSearchNamespaceResolutionMethod $wgCirrusSearchDocumentSizeLimiterProfiles $wgCirrusSearchSearchShardTimeout $wgCirrusSearchCategoryMax $wgCirrusSearchPrivateClusters $wgCirrusSearchSimilarityProfiles $wgCirrusSearchCategoryEndpoint $wgCirrusSearchRescoreFunctionChains $wgCirrusSearchPoolCounterKey $wgCirrusSearchCompletionProfiles $wgCirrusSearchMaxShardsPerNode $wgCirrusSearchWeights $wgCirrusSearchEnableArchive $wgCirrusSearchSimilarityProfile $wgCirrusSearchInterwikiThreshold $wgCirrusSearchIndexDeletes $wgCirrusSearchDocumentSizeLimiterProfile $wgCirrusSearchFiletypeAliases $wgCirrusSearchDevelOptions $wgCirrusSearchPrefixSearchStartsWithAnyWord $wgCirrusSearchUpdateConflictRetryCount $wgCirrusSearchInterwikiHTTPTimeout $wgCirrusSearchFetchConfigFromApi $wgCirrusSearchBoostTemplates $wgCirrusSearchExtraIndexBoostTemplates $wgCirrusSearchPrefixIds $wgCirrusSearchFullTextQueryBuilderProfile $wgCirrusSearchStripQuestionMarks $wgCirrusSearchMoreLikeThisFields $wgCirrusSearchIndexBaseName $wgCirrusSearchMasterTimeout $wgCirrusSearchSanityCheck $wgCirrusSearchTextcatConfig $wgCirrusSearchNamespaceWeights $wgCirrusSearchCrossProjectOrder $wgCirrusSearchTextcatModel $wgCirrusSearchRescoreProfile $wgCirrusSearchMoreAccurateScoringMode $wgCirrusSearchMaxPhraseTokens $wgCirrusSearchCrossProjectSearchBlockList $wgCirrusSearchCrossProjectProfiles $wgCirrusSearchLanguageToWikiMap $wgCirrusSearchMaxIncategoryOptions $wgCirrusSearchEnableEventBusWeightedTags $wgCirrusSearchWikimediaExtraPlugin $wgCirrusSearchCompletionSuggesterUseDefaultSort $wgCirrusSearchLinkedArticlesToUpdate $wgCirrusSearchCompletionSuggesterSubphrases $wgCirrusSearchPreferRecentDefaultHalfLife $wgCirrusSearchSlowSearch $wgCirrusSearchFunctionRescoreWindowSize $wgCirrusSearchEnablePhraseSuggest $wgCirrusSearchCompletionSettings $wgCirrusSearchUseExperimentalHighlighter $wgCirrusSearchFeedbackLink $wgCirrusSearchUpdateDelay $wgCirrusSearchRefreshInterval $wgCirrusSearchInterleaveConfig $wgCirrusSearchPhraseRescoreWindowSize $wgCirrusSearchMoreLikeThisAllowedFields $wgCirrusSearchPreferRecentDefaultDecayPortion $wgCirrusSearchClientSideConnectTimeout $wgCirrusSearchPhraseSuggestUseText $wgCirrusSearchPhraseSuggestProfiles $wgCirrusSearchDefaultNamespaceWeight $wgCirrusSearchInterwikiSources $wgCirrusSearchPhraseSuggestUseOpeningText $wgCirrusSearchICUNormalizationUnicodeSetFilter $wgCirrusSearchICUFoldingUnicodeSetFilter $wgCirrusSearchReplicaGroup
使用するフック APIAfterExecute APIQuerySiteInfoGeneralInfo APIQuerySiteInfoStatisticsInfo ApiBeforeMain ArticleRevisionVisibilitySet BeforeInitialize CirrusSearchAddQueryFeatures CirrusSearchAnalysisConfig CirrusSearchSimilarityConfig GetPreferences LinksUpdateComplete PageDelete PageDeleteComplete PageMoveComplete PageUndeleteComplete PrefixSearchExtractNamespace ResourceLoaderGetConfigVars SearchGetNearMatch SearchIndexFields ShowSearchHitTitle SoftwareInfo SpecialSearchResults SpecialSearchResultsAppend SpecialStatsAddExtra TitleMove UploadComplete UserGetDefaultOptions
提供するフック CirrusSearchAddQueryFeatures CirrusSearchAnalysisConfig CirrusSearchBuildDocumentFinishBatch CirrusSearchBuildDocumentLinks CirrusSearchBuildDocumentParse CirrusSearchFulltextQueryBuilder CirrusSearchFulltextQueryBuilderComplete CirrusSearchMappingConfig CirrusSearchProfileService CirrusSearchRegisterFullTextQueryClassifiers CirrusSearchScoreBuilder
四半期ごとのダウンロード数	263 (Ranked 18th)
使用中の公開ウィキ	1,226 (Ranked 212nd)
translatewiki.net で翻訳を利用できる場合は、CirrusSearch 拡張機能の翻訳にご協力ください
Vagrant role	cirrussearch
問題点	未解決のタスク · バグを報告

CirrusSearch 拡張機能はElasticsearchを使った MediaWiki 検索を実装します。

Elasticsearch is a standalone third-party software you must install as a requirement for this extension. It is a database system that provides search and indexing functionality, where the current text of your wiki pages gets indexed for faster and improved search results. The communication between MediaWiki and ElasticSearch is done through web services.

この拡張機能の使用についてのヘルプページも参照してください。

目標

• ネイティブな依存関係がなくてもインストールが簡単にできること

** 唯一の依存関係は pure-PHP MediaWiki 拡張機能と Elasticsearch だけ

• 他の MediaWiki 拡張機能で拡張できるウィキページについて、ほぼリアルタイムに検索インデックスを返す

• MWSearch が利用者に開放したクエリオプションすべてと、その他を提供

依存関係

PHPとcURL

• CirrusSearchでは、MediaWikiの標準的なPHPの要件に加えて、cURLをサポートしてコンパイルされたPHPが必要です。

Elasticsearch

• Elasticsearchをインストールする必要があります。

Every version of ElasticSearch changes how web services work and causes compatibility problems. You must install the version of Elastic Search compatible with the version of MediaWiki you are currently using:

MediaWiki 1.39+ require Elasticsearch 7.10.2 (6.8.23+ is possible using a compatibility layer ). See this revision for compatibility information with earlier versions of MediaWiki.

Elasticsearch versions before 6.8 are incompatible with PHP 8+.

なお、OpenJDKなどのJavaのインストールが別途必要です。 Elasticsearchの公式Dockerイメージか、セルフホスティング版を使用するのがベストです。 Amazon OpenSearch（旧Amazon Elasticsearch）のようなマネージド製品でも動作しますが、その仕様によっては追加の設定が必要な場合があります。 例えば、Amazon OpenSearchは、ポート443上のHTTPSでElasticsearch APIリクエストをリッスンするだけなので（つまり、既定のElasticsearchポート9200を公開しない）、TLS対応プロキシ（例：Nginx）でCirrusSearchとAmazon OpenSearchクラスタの通信を可能にすることができます。

Elastica

• ElasticaはElasticsearchと対話するためのPHPライブラリです。以下の説明に従ってElasticaをインストールしてください。

その他

• Due to the actual handling of jobs by the CirrusSearch extension, it is advisable to set up jobs in Redis to prevent messages like Notice: unserialize(): Error at offset 64870 of 65535 bytes in JobQueueDB.php and subsequent errors like Unsupported operand types.

タスク T157759 を参照してください。

インストール

Elastica

以下の説明では、gitからインストールする場合にのみComposerを実行するようになっていますが、PHPの依存コンポーネントをすべてインストールするためには、いずれにせよComposerを実行する必要があります。

• ダウンロードして、ファイルをextensions/フォルダー内のElasticaという名前のディレクトリ内に配置します。
  開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Elastica
• Gitでのインストールの場合のみ、PHPの依存関係をインストールするためComposerを実行します。 (合併症の可能性についてはタスク T173141を参照。)
• 以下のコードを LocalSettings.php ファイルの末尾に追加します:

  wfLoadExtension( 'Elastica' );
  

•  完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

CirrusSearch

• ダウンロードして、ファイルをextensions/フォルダー内のCirrusSearchという名前のディレクトリ内に配置します。
  開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CirrusSearch
• Gitでのインストールの場合のみ、PHPの依存関係をインストールするためComposerを実行します。 (合併症の可能性についてはタスク T173141を参照。)
• 以下のコードを LocalSettings.php ファイルの末尾に追加します:

  wfLoadExtension( 'CirrusSearch' );
  

• 拡張機能とともに配布されるCirrusSearch README、つまり$IP/extensions/CirrusSearch/READMEに記載されているセットアップ手順に従います。特に、サポートされているElasticsearchのバージョンについては、あなたの拡張機能のバージョンに当てはまらないかもしれないことに注意してください。
• 必要に応じて設定してください。
•  完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

Enable regex queries

This is an optional step. You will need to install the search-extra plugin for this. Do so by following these steps:

1. execute the following command:

   /usr/share/elasticsearch/bin/elasticsearch-plugin/elasticsearch-plugin install org.wikimedia.search:extra:7.10.2-wmf12
   

2. add the following line to your LocalSettings.php file:

   $wgCirrusSearchWikimediaExtraPlugin[ 'regex' ] = [ 'build', 'use', 'max_inspect' => 10000 ];
   

3. restart Elasticsearch with the following command:

   systemctl restart elasticsearch
   

4. recreate the search index by executing the following commands:

   1. php path/to/extensions/CirrusSearch/maintenance/UpdateSearchIndexConfig.php --startOver
      

   2. php path/to/extensions/CirrusSearch/maintenance/ForceSearchIndex.php
      

アップグレード

CirrusSearch UPGRADE ファイルに記載されているアップグレード方法に従ってください。

設定

CirrusSearchの設定パラメータは、"settings.txt"ファイルに記載されています。 See also documentation on CirrusSearch configuration profiles.

Elasticsearch will fail to index for CirrusSearch if one uses a database name for MySQL containing a capital character, e.g., "MyWikiDatabaseName." To mitigate this, CirrusSearch provides the $wgCirrusSearchIndexBaseName configuration parameter, which one needs to set, e.g., $wgCirrusSearchIndexBaseName = 'mywikidatabasename';.

フック

CirrusSearch 拡張機能が規定するフックは他の拡張機能でも利用でき、それぞれのコアのスキーマ拡張と説明文書の変更に使えます。 使用できるフックは次の通りです。

• CirrusSearchAnalysisConfig - 解析のために設定にフックすることができます
• CirrusSearchMappingConfig - フィールドのマッピングを設定することができます。
• CirrusSearchBuildDocumentParse - ページから生成されたElasticSearchドキュメントを拡張機能で変更できるようになりました。
• CirrusSearchBuildDocumentLinks - 拡張機能でドキュメントの受信リンクと送信リンクを処理できるようにする
• CirrusSearchBuildDocumentFinishBatch - ページのバッチがインデックスされたときに呼び出されます。
• CirrusSearchAddQueryFeatures - クエリパーサの機能を追加する拡張機能
• CirrusSearchScoreBuilder - 拡張機能でリスコアビルダー関数を定義できます
• CirrusSearchProfileService - 拡張機能でさまざまな検索コンポーネントと構成を宣言できるようにする

API

CirrusSearch の機能は API クエリで使用可能です。 Searching happens via the normal search API, action=query&list=search; you can use CirrusSearch-specific features, such as the morelike: special prefix to find pages related to Marie Curie and radium:

api.php?action=query&list=search&srsearch=morelike:Marie_Curie%7Cradium&srlimit=10&srprop=size&formatversion=2

CirrusSearchの設定とデバッグ情報を照会するためのカスタムAPIとパラメータが提供されています。

• action=cirrusdump module: 2014?action=cirrusdump
• 特別:検索または検索APIクエリへのcirrusDumpQueryパラメータ: https://en.wikipedia.org/wiki/Special:Search/cat%20dog%20chicken?cirrusDumpQuery
• 特別:検索または検索APIクエリへのcirrusDumpResultパラメータ: https://en.wikipedia.org/wiki/Special:Search/cat%20dog%20chicken?cirrusDumpResult
• An additional parameter, cirrusExplain, can be passed with cirrusDumpResult to have the Lucene explanation of the score included with the result dump: https://en.wikipedia.org/wiki/Special:Search/cat%20dog%20chicken?cirrusDumpResult&cirrusExplain It can also be used to get the explanation in a human-readable format, by giving it one of the values verbose, pretty or hot, such as: https://en.wikipedia.org/wiki/Special:Search/cat%20dog%20chicken?cirrusDumpResult&cirrusExplain=pretty
• CirrusSearchのセットアップからダンプを取得するためのcirrus-config-dump, cirrus-settings-dump, cirrus-mapping-dump, cirrus-profiles-dumpモジュールです。 api.php?action=cirrus-config-dump&formatversion=2

関連項目

一般的なリンク

• 使用方法に関するヘルプページ - CirrusSearch使用説明書(インストール後に必要)
• プロジェクトのページ
• ウィキメディアの Cirrus/Elastic 設定に関する情報
• 構成ヘルプページ - 索引作りにさまざまな影響を与える調整可能なパラメータのセット
• Extension:WikiSearch - provides faceted search API for Semantic MediaWiki using ElasticSearch.
• Extension:AdvancedSearch - Enhances Special:Search by providing advanced parameters

デバッグ

• サーチバックエンドとして実際にCirrusが使用されているかどうかを判断する方法

ローカル開発

Elastic Searchサービスは、Vagrantのロール（cirrussearch）とMediaWiki Vagrantで実行することができます。

Dockerの場合は、docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" elasticsearch:6.8.2のようなコマンドを使用することができます。 その後、インストールと設定の指示に従います。 ウェブホストがコンテナに入っている場合、上記のコンテナが同じネットワーク上にあることを確認し、LocalSettings.php ファイルでホスト名としてelasticsearchを参照するようにしたい。 WMFのプラグインはありませんが、基本的なテストには十分でしょう。