Pleasanter Technical Manual

テーマ

IndexCreator による索引の計画と運用 ​

第5版作成 最終更新 （日本時間）
確認バージョン1.5.8.1

IndexCreator v0.3.0（最新版）では、plan で追加索引の計画を確認し、_rds / apply で適用します。初回の配置と接続設定は 導入と接続設定 を先に確認してください。機能ごとの対応版は 概要、版ごとの変更は 変更履歴 にあります。索引候補の規則は v0.2.0 から v0.3.0 で変わっていません。

対応する条件 ​

Results・Issues・Wikis のサイト設定を解析します。件数は DB の各物理テーブルからサイトごとに数え、既定は １万件以上を索引の対象にします。

対象候補を生成する条件
保存ビューのフィルタ通常の等価・範囲・前方一致条件
保存ビューの並べ替え関数を伴わない並べ替え。数値は Nullable=true など、本体の式に合う条件
自分が担当（Own）
v0.2.0 以降		Manager / Owner の OR 分岐ごとに候補を生成。v0.1.x は対象外
Issues の期限が近い・期限超過
v0.2.0 以降		CompletionTime、期限超過では Status も別の範囲候補を生成
リンク・サマリSiteId と対応するリンク項目
リンク選択肢の条件
v0.2.0 以降		Links[].View にある通常条件・明示的な並べ替えを、リンク先 Results / Issues に対して解析
項目連携
v0.2.0 以降		各段の子マスタにある単一選択の親リンク列と ID を候補化。数値変換は残る
既定の並べ替えSQL Server・MySQL では追加。PostgreSQL は標準主キーで足りるため追加しない
フィルタ欄の項目/include-filter-columns を指定したときに、対応する等価条件を追加

分類の選択肢があっても検索方法が部分一致なら、完全一致の候補にはしません。業務上、値全体を比較する条件ならサイトのフィルタ設定を完全一致にできますが、索引のために検索の意味を変えないでください。

部分一致、複数選択、任意の OR、否定、リンク先を JOIN する条件、長いテキスト、ColumnFilterExpressions、式索引が必要な並べ替え、親から子への JOIN、Items.Title の追加索引は未対応です。既知の Own の OR 分岐と、リンク選択肢の取得先に直接指定された通常条件は上の規則で扱います。一時的な画面条件・API 条件・拡張 SQL は SiteSettings にないため解析しません。未対応条件は診断として報告します。

複数の範囲・前方一致がある場合は、それぞれの列を持つ別の候補を生成します（v0.1.x は最初の範囲列だけ）。Own と組み合わせると担当者の分岐ごとに候補が増えます。複数の索引が同時に使われることや、範囲の後ろの並べ替えまでカバーすることは保証しません。Own・期限条件が有効な否定設定で反転されている場合は、肯定条件の候補に加えません。

項目連携・リンク選択肢の制約 v0.2.0 以降 ​

「都道府県 → 市区町村」の項目連携なら、市区町村マスタ側の都道府県リンク列を調べます。候補は SiteId, 親リンク列, レコードID です。本体コードを変更せず、標準索引や列の追加・変更も行いません。

単一選択でも本体はリンク値を数値変換して比較します。この変換は残るため、親リンク列の値で直接絞る索引検索をカバーしたとは判断できません。MySQL の分類列は prefix 索引なので、変換に使う値全体の読み取りもカバーできるとは限りません。複数選択は部分一致を使うため、項目連携専用の追加候補を作りません。通常のリンク索引の候補は別の規則で残る場合があります。

リンク先の件数に /min-records を適用します。小さいマスタも検討する場合は値を下げ、計画と更新負荷を確認してください。リンク元が１万件未満でも、リンク先の解析は行います。

リンク選択肢の既定順は Items.Title です。リンク選択肢の条件から作る候補には、保存ビューで使う UpdatedTime の並べ替えやタイブレーカを補いません。Wiki 本文の選択肢は対象外です。連携先・親リンク列が取得できない場合や、複数の親リンクがあって編集項目順を特定できない場合は、理由を診断して専用候補を追加しません。

計画して適用する ​

powershell
dotnet VehicleVision.PleasanterTools.IndexCreator.dll plan
dotnet VehicleVision.PleasanterTools.IndexCreator.dll _rds

plan は DB を変更しません。_rds は計画を表示してから yes の入力を求めます。変更する候補がない場合は確認入力を行わず終了します。非対話の実行では /y が必要です。

powershell
dotnet VehicleVision.PleasanterTools.IndexCreator.dll _rds /p "C:\web\pleasanter\Implem.Pleasanter" /y

/c は確認のみです。/y・/f を付けても DB は変更しません。_rds は CodeDefiner 自体を実行せず、DB 作成・言語・タイムゾーンなどの設定も変更しません。

計画の表示意味
Create不足する候補を新規作成
Keep同名の有効な索引、または対応する既存の通常 B-tree で足りる
Repair無効な索引、または /f の管理索引を再作成
Drop/prune で不要な管理索引を削除
WARNING未対応条件やキー長などの確認事項

INFO・WARNING の意味と対処 ​

INFO は動作方針の案内です。WARNING: Site <ID>: はそのサイトの候補生成に関する診断で、必ずしも処理失敗を意味しません。警告が出たサイト全体をスキップするわけではありません。 対応できる別のフィルタ、既定の並べ替え、リンク・サマリなどから候補が残る場合があります。

次の表は v0.3.0 のログに対応します。項目連携の診断（Relating columns ...）と ColumnFilterExpressions の診断は v0.2.0 で追加されました。サイト ID と項目名は環境によって変わります。

メッセージ作成への影響確認・対処
Indexes are created online. Editions without online index operations stop; use /offline only in a maintenance window.SQL Server の通常モードの案内。オンライン非対応のエディションでは、適用時に停止エディションを確認。オフライン操作を許容する保守時間帯に限り /offline を指定
Class keys may exceed the SQL Server 1700-byte limit. Review maximum value lengths before applying.この警告では候補を除外しない。 実際に長さを超えれば作成や後の登録・更新が失敗する可能性がある複合キー全体のバイト数と、今後入力できる値の最大長を確認
The ClassA filter uses partial match, so no index can serve it. Set the search type to exact match in the site's filter settings if the choices are compared as whole values.その分類フィルタを、完全一致・前方一致の索引候補から除外フィルタの検索方法を確認。値全体の一致が業務要件の場合だけ完全一致へ変更
A filter cannot use a plain B-tree key (joined, text, partial-match or unknown column).そのフィルタを通常の B-tree の候補から除外フィルタ項目の型、検索方法、複数選択、対応項目かどうかを確認
A sort needs an expression or joined key; automatic creation is not supported in v0.1. Enable Nullable for numeric columns where appropriate.その保存ビューの並べ替え列とタイブレーカを候補へ追加しない。完全一致の絞り込み列があれば、その部分の候補は残る並べ替え項目の型、リンク、数値の Nullable 設定を確認。業務上の空値の扱いを確認してから設定を検討
Relating columns target site 20, ClassA: a raw-column index with record ID was planned; numeric conversion remains a residual condition, not an indexed seek.単一選択の項目連携に候補を生成するが、数値変換は残る本体 SQL の変換付き条件と実行計画を確認。変換値で直接絞れる索引とは判断しない
Relating columns target site 20, ClassA: multiple selections use contains matching; no additional relation index was generated.複数選択の項目連携専用候補を生成しない部分一致の検索条件を確認。通常のリンク候補が残っても、この条件をカバーしたとは判断しない
Relating columns target site 20, ClassA: below the minimum record threshold; no additional relation index was generated.件数不足の連携先には専用候補を生成しない小さいマスタも検討する場合は /min-records を下げて計画を再確認
ColumnFilterExpressions are not covered by ordinary index planning.式条件の候補を生成しない。対応できる別条件の候補は残る生成 SQL と式条件を照合し、未対応条件による負荷を測定

オンライン操作と /offline ​

最初の INFO は、SQL Server を選び /offline を指定していない場合に出ます。エディションの確認に成功したことや、索引の作成が完了したことを示すログではありません。plan の段階でも表示されます。

オンライン操作が非対応の場合、自動でオフラインに切り替えません。保守時間帯にロックを許容して実行する場合は、計画と適用の両方に指定します。

powershell
dotnet VehicleVision.PleasanterTools.IndexCreator.dll plan /offline /output indexes-plan.sql
dotnet VehicleVision.PleasanterTools.IndexCreator.dll _rds /offline

/offline はオンライン操作の制約に対する指定です。キー長、部分一致、式を必要とする並べ替えの制約は解消しません。負荷とロックの扱いは 稼働中の DB に適用する場合 を参照してください。

SQL Server の 1700 バイト警告 ​

v0.3.0 は、SQL Server の候補に ClassA などの分類列が含まれるとこの警告を出します。実データを測って上限超過を検出した結果ではありません。警告だけでは、作成できるとも、必ず失敗するとも判断できません。

上限は分類列1つの文字数ではなく、非クラスター化インデックスのキー列全体の合計バイト数です。例えば SiteId, ClassA, ClassB, UpdatedTime, ResultId なら、分類2列以外のキーも含めて確認します。文字列の文字数とバイト数は同じとは限らないため、SQL Server の DATALENGTH などで現在の値を確認し、列定義と入力制約から将来の最大長も確認してください。

可変長列では、現在のデータが収まっていれば索引を作成できても、後から長い値を登録・更新すると失敗する場合があります。作成成功だけで安全と判断しないでください。これは SQL Server の CREATE INDEX の制約 によるものです。

IndexCreator はキーを自動で短縮せず、SQL Server 向けに /mysql-prefix を使うこともできません。候補を個別選択する機能もないため、安全を確認できない候補がある場合は、plan /output indexes-plan.sql で内容を確認し、適用前に DB 管理者と索引設計を見直してください。

分類フィルタの部分一致 ​

例えばログが The ClassA filter uses partial match... なら、そのサイトの ClassA の検索方法を確認します。選択肢が設定された分類でも、検索方法が部分一致なら完全一致の候補にはなりません。

ツールは保存ビューの ColumnFilterSearchTypes、項目の SearchType の順に検索方法を読みます。どちらも省略されている場合は、選択肢を持つ分類を完全一致、それ以外を部分一致として判定します。項目設定だけを変更しても、保存ビューに指定が残っている場合は、その指定が優先されます。

「受付」という値全体で絞りたいなら完全一致を検討できますが、文字列の途中を検索したい業務では部分一致を維持します。警告を消すためだけに検索の意味を変更しないでください。 前方一致も対応範囲ですが、部分一致と同じ検索ではありません。

ログの no index can serve it は、このツールがその部分一致条件向けの通常の B-tree キーを生成しないという意味です。DB が既存索引を別の条件に使ったり、索引を走査したりする可能性まで否定するものではありません。

通常の B-tree にできないフィルタ ​

A filter cannot use a plain B-tree key... は複数の理由をまとめた診断です。本文の括弧内は理由の例で、すべてがそのサイトに該当するという意味ではありません。

対象には、分類の複数選択、対応する検索方法以外の分類、Title・Body・Comments などのテキスト、ツールが型を判定できない項目などが含まれます。OR・否定・リンク先の条件には、別の除外メッセージが出る場合もあります。

この汎用メッセージには項目名と保存ビューの識別情報が含まれません。サイト ID から対象サイトを開き、保存ビューのフィルタ設定と項目設定を照合してください。このログだけで「どの項目が原因か」は特定できません。未対応の条件を設定に残しても、その条件の索引候補が生成されないだけで、検索設定自体をツールが変更することはありません。

式・リンクを必要とする並べ替え ​

A sort needs an expression or joined key... は、保存ビューの並べ替えを、そのままの物理列による索引で対応できないとツールが判定した場合に出ます。分類・チェック、リンク項目、テキスト・未対応項目、Nullable が無効の一部の数値項目などが対象です。

数値項目は、空値を許可する Nullable=true の場合に通常の列キーとして候補にできるものがあります。ただし、Nullable を有効にすれば、どの並べ替えも対応できるわけではありません。 空値の許可や並べ替え結果が業務に合うかを確認し、分類・チェックやリンクに対する対処と混同しないでください。

未対応の並べ替えがある保存ビューでも、完全一致の絞り込み列がある場合は、その列までの候補が残ります。並べ替え高速化まで対応したと判断せず、生成 SQL のキー列と実行計画を確認してください。この警告にも項目名・保存ビュー名は含まれません。ログにある v0.1 は旧来の文言で、v0.3.0 でも表示されます。

警告が出たときの確認順序 ​

  1. plan /output indexes-plan.sql で、変更予定と実際のキー列を確認します。
  2. 1700 バイト警告はキー長、部分一致は検索方法、並べ替えの警告は項目型・Nullable・リンク設定を確認します。
  3. 設定を変更する場合は、検索結果と空値の扱いが業務要件に合うことを確認します。
  4. 再度 plan を実行し、残る候補と警告を確認してから適用します。

警告がないことだけでは、性能改善や運用上の安全は保証されません。代表クエリの実行計画と、登録・更新への影響を合わせて確認してください。

管理する索引 ​

名前は IX_vvplic_{ReferenceType}_{SiteId}_{用途}_{定義ハッシュ16桁} です。列・方向・MySQL の prefix 長・PostgreSQL の opclass を含む定義からハッシュを作ります。

同じ物理テーブルに対する同じ候補は共有し、候補を生成した最小のサイト ID を名前に使います。再実行では実 DB のカタログを読み直すため、前回の状態ファイルは不要です。

標準索引、他ツールの索引、列、テーブルは削除しません。同じ管理名なのに定義が違う場合や、必要な列がない場合は変更を止めます。フィルタ索引・式索引・無効索引などを、通常の索引の代替として扱うこともありません。

DB に接続せず候補を試す ​

次のファイルは、完全一致の ClassA と Nullable=true の NumA の降順を使う架空の案件サイトです。

検証用 sites.json をダウンロード

json
[
  {
    "SiteId": 100,
    "Title": "案件",
    "ReferenceType": "Results",
    "RecordCount": 20000,
    "SiteSettings": {
      "GridColumns": [
        "ResultId",
        "ClassA",
        "NumA",
        "UpdatedTime"
      ],
      "Columns": [
        {
          "ColumnName": "ClassA",
          "LabelText": "状態",
          "ControlType": "ChoicesText",
          "ChoicesText": "10,受付,受\n20,対応中,中\n30,完了,完",
          "SearchType": "ExactMatch"
        },
        {
          "ColumnName": "NumA",
          "LabelText": "金額",
          "Nullable": true
        }
      ],
      "Views": [
        {
          "Id": 1,
          "ColumnFilterHash": {
            "ClassA": "[\"10\"]"
          },
          "ColumnSorterHash": {
            "NumA": "desc"
          }
        }
      ]
    }
  }
]

VehicleVision.PleasanterTools.IndexCreator.dll があるフォルダーへ保存し、次を実行します。

powershell
dotnet VehicleVision.PleasanterTools.IndexCreator.dll plan /sites sites.json /dbms PostgreSQL /output indexes.sql

この例の候補は SiteId, ClassA, NumA DESC, UpdatedTime DESC, ResultId DESC です。SQL Server と MySQL の計画を比較する場合は /dbms SQLServer・/dbms MySQL に変えます。これらは既定並べ替え用の候補も追加します。

/sites は計画専用で、既存索引との比較と実 DB の列の検査は行いません。本体設定を用意せず計画する場合は DisableIndexChangeDetection の警告が出ますが、計画は実行できます。一般的なサイトのエクスポート ZIP をそのまま渡す書式ではありません。入力は SiteId・ReferenceType・RecordCount・SiteSettings を持つ配列です。

/output は検査時点の操作 SQL を保存します。DB が変わった後の SQL を流用せず、現在の構成でツールを再実行してください。

主なオプション ​

指定内容・既定値
/min-records <n>索引対象の最小件数。既定10000。小規模な検証では計画と適用の両方に 0 を指定可能
/include-filter-columnsフィルタ欄の対応する項目も候補にする
/mysql-prefix <n>MySQL 分類列の prefix 長。1〜191、既定100文字
/prune現在の候補で不要になった管理索引を削除
/f同じ定義の管理索引を DROP → CREATE で再作成
/offlineロックを伴う索引操作を許可。保守時間帯に使う
/lock-timeout <秒>DDL のロック待ち。1〜3600、既定5。DBMS ごとの例外は次節
/output <path>計画の SQL を保存
/sites <path>DB に接続しない計画専用。/prune と併用不可

/exclude-site・/exclude-tree は View 用で、索引候補の絞り込みには使えません。候補を個別選択する機能はありません。引数は / 形式で、同じオプションの重複指定はエラーです。

稼働中の DB に適用する場合 ​

通常はオンラインの索引操作を使います。オンラインでも、短いロック、CPU・I/O の負荷、索引を維持する更新コストは発生します。事前の測定と監視を行ってください。

DBMS通常の操作待機時の扱い
SQL ServerONLINE=ON。2022 以降・Azure SQL の作成には低優先度待機を使用対応しないエディションでは停止。低優先度待機は分単位のため、作成の１回の待機は最大１分
PostgreSQLCREATE / DROP INDEX CONCURRENTLYこの操作には lock_timeout を設定せず、既存トランザクションの終了を待つ
MySQLALGORITHM=INPLACE, LOCK=NONE開始・終了のメタデータロックに待機上限を設定。後続処理が一時的に待つ場合がある

再試行可能なロック待ちエラーでは、間隔を空けて最大２回再試行します。/lock-timeout 5 は処理全体の５秒制限ではありません。SQL Server の低優先度待機では再試行を含め約３分待つ場合があります。

オンライン作成に対応しない SQL Server で適用する場合は、ロックを許容できる保守時間帯に、計画と適用の両方で /offline を指定します。自動でオフライン作成に切り替わることはありません。

索引キーの上限にも注意します。SQL Server の分類キーは1700バイトの制限に抵触し、作成後の長い値の登録・更新が失敗する場合があります。PostgreSQL の B-tree にも行サイズの上限があります。MySQL の prefix index は分類値の先頭部分だけを使います。

サイト変更後と CodeDefiner 実行後 ​

  1. サイト編集と CodeDefiner 実行を終えます。同時に適用しません。
  2. plan /prune /output indexes-plan.sql で新しい候補と整理対象を確認します。
  3. 列の長さ・値の分布・代表クエリの実行計画を確認します。
  4. _rds /prune を実行します。自動実行なら /y を追加します。
  5. plan /prune で残る操作を確認し、一覧と登録・更新を再測定します。

必要な新規索引を作成・検証してから不要な管理索引を削除します。追加だけなら /prune は不要です。CodeDefiner のテーブル再構成で追加索引がなくなった場合も、_rds の再実行で補います。

定期運用では、最小件数・prefix 長・フィルタ欄オプションを固定します。設定を変えると候補が変わり、/prune の削除対象も変わります。

失敗したとき ​

DB 全体をまとめてロールバックする処理ではありません。途中で失敗しても、成功した変更は残ります。ログと plan を確認し、権限・接続・ロック・キーサイズなどの原因を解消して再実行します。PostgreSQL の無効な管理索引は、再実行の計画で修復対象になります。

終了コード内容
0成功・計画完了
1ファイルなどの一般エラー
2設定・引数・整合性エラー、または確認キャンセル
3DB エラー
130中断

関連ページ ​

変更履歴

第5版ツールのマニュアルをツール別の独立した構成にし、変更履歴とバージョン別の機能差を追加した
第4版IndexCreator v0.2.0のリンク選択肢と項目連携の制約を説明
第3版IndexCreator の警告が示す制約と確認・対処手順を追加
第2版IndexCreator v0.1.1 と Azure Kudu 向け x86 版の導入手順を更新
第1版IndexCreator の操作手順と MCP OAuth v0.2.0 の接続方法を更新する