Pleasanter Technical Manual

テーマ

全文検索の環境構築 ​

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

データベース側の全文検索機能を整える手順をまとめます。PostgreSQL に日本語の部分一致検索を高速化する拡張機能 pg_bigm を導入する方法と、Docker で動かす SQL Server 2025 にフルテキスト検索を組み込む方法です。

先に結論です。プリザンターの PostgreSQL の標準検索は、pg_bigm をインストールするだけでは高速化できません。 標準検索は pg_trgm の演算子を使っているためです。SQL Server は、Linux コンテナーでは mssql-server-fts を組み込んだイメージを作る必要があります。

プリザンターが RDBMS ごとにどのような全文検索 SQL を発行しているかは 検索機能の内部実装 を参照してください。

PostgreSQL：pg_bigm の導入 ​

検証環境

プリザンターの実装確認はバージョン 1.5.8.1 が対象です。Docker の手順と検証用 SQL は PostgreSQL 17.11・pg_bigm 1.2（v1.2-20250903）で実行しています。Windows・AlmaLinux のオンプレミス手順は配布元資料に基づく手順例で、実機での動作確認はしていません。プリザンターの画面検索を高速化した実測結果でもありません。

プリザンターの標準検索との関係 ​

プリザンター 1.5.8.1 は、PostgreSQL のフルテキストインデックスを次の SQL で作成しています。

sql
create index if not exists "ftx" on "Items" using gin ("FullText" gin_trgm_ops);

CreateFullText.sql

gin_trgm_ops は、3 文字のまとまりを使う拡張機能 pg_trgm の演算子クラスです（演算子クラスは、インデックスでどのような比較を扱うかを定義するものです）。

  • 検索条件は "Items"."FullText" %> 検索語 の形です。%> は pg_trgm の語の類似度による判定で、LIKE '%検索語%' の部分一致とは意味が異なります（検索条件の実装、PostgreSQL の pg_trgm）
  • 通常の部分一致用の SQL には ILIKE を使います。これも pg_bigm の LIKE 用インデックスをそのまま使える条件ではありません（部分一致演算子の実装）
検索条件対応するインデックスの例pg_bigm 導入時の扱い
標準フルテキスト検索の %>gin_trgm_ops標準インデックスを維持する
通常の部分一致検索の ILIKEgin_trgm_opsgin_bigm_ops への単純置き換えはできない
独自 SQL の LIKEgin_bigm_opspg_bigm による高速化を検証できる

WARNING

ftx を削除して gin_bigm_ops で作り直しても、標準検索の %> には対応しません。pg_trgm と既存の ftx は残してください。pg_bigm 1.2 と pg_trgm は同じ DB で共存できます。

標準検索を速くしたい場合の確認順序 ​

まず、プリザンターが接続している DB でインデックスを確認します。名前だけで判断せず、FullText 列に対する gin_trgm_ops のインデックスがあるかを定義で確認してください。

sql
SELECT schemaname, indexname, indexdef
FROM pg_indexes
WHERE tablename = 'Items';

公式マニュアルでは、初期構築時のプリザンターが 1.4.6 以前の場合、後からバージョンアップしてもフルテキストインデックスの生成手順が必要と説明されています。該当する環境は PostgreSQL フルテキストインデックスを生成する を確認してください。

そのうえで、遅い操作で発行される SQL の実行計画、データ量、検索語、統計情報を調べます。標準検索の改善と、独自の LIKE 検索への pg_bigm 導入を切り分けると、対策を選びやすくなります。

図を読み込み中…

導入の流れ ​

pg_bigm は文字列を 2 文字ずつのまとまりに分け、GIN インデックス（文字のまとまりから、それを含むレコードを探すための索引）に登録します。日本語の短い検索語を含む部分一致検索で効果が期待できますが、速くなるかどうかは検索語やヒット件数にも左右されます（pg_bigm 公式ドキュメント）。

  1. PostgreSQL サーバにライブラリと拡張定義ファイルを配置する
  2. 利用する DB ごとに CREATE EXTENSION pg_bigm を実行する
  3. 検索対象の列に gin_bigm_ops のインデックスを作成する

配置先は DB サーバ

プリザンターの Web サーバと DB サーバを分けている場合、Web サーバにファイルを置いても DB 側では使えません。

以下は PostgreSQL 17 の例です。既存環境ではメジャーバージョンを合わせ、設定変更・インデックス作成の前に DB と設定ファイルのバックアップを取得してください。

Windows オンプレミス ​

1. Windows 向けのビルドを用意する ​

上流の pg_bigm 公式ドキュメントが挙げる動作確認 OS は Linux と macOS です。Windows では、別の開発者による HiraokaHyperTools/pg_bigm の Windows 向け配布を利用する方法があります。同リポジトリの README では、PostgreSQL 9.6〜18.0 向けの配布と、20260107.7z の展開・コピー手順が案内されています。利用する PostgreSQL のメジャーバージョンと CPU アーキテクチャに合うフォルダを選びます。

INFO

この Windows 向けバイナリは、上流の pgbigm/pg_bigm プロジェクトが配布する公式 Windows パッケージではありません。採用前に配布元、含まれるソースの版、依存ランタイム、運用中の PostgreSQL との組み合わせを確認してください。上流の同名バージョンと修正内容が同じとは限りません。

2. PostgreSQL の配置先を確認してコピーする ​

powershell
$pgRoot = 'C:\Program Files\PostgreSQL\17'
& "$pgRoot\bin\pg_config.exe" --version
& "$pgRoot\bin\pg_config.exe" --pkglibdir
& "$pgRoot\bin\pg_config.exe" --sharedir

管理者権限で、配布アーカイブ内の PostgreSQL 17・x64 向けフォルダの中身を $pgRoot へ、ディレクトリ構造を保ってコピーします。

ファイル配置先の例
pg_bigm.dllC:\Program Files\PostgreSQL\17\lib
pg_bigm.controlC:\Program Files\PostgreSQL\17\share\extension
pg_bigm--*.sqlC:\Program Files\PostgreSQL\17\share\extension

既に読み込み済みの DLL を更新する場合は、対象の PostgreSQL サービスを停止してから差し替えます。

3. プリロードを設定して DB に接続する ​

psql または pgAdmin で、接続先サーバの設定ファイルと既存値を確認します。

sql
SHOW config_file;
SHOW shared_preload_libraries;

確認した postgresql.conf で、既存のライブラリを残して pg_bigm を追加します（上流ドキュメントのプリロード方式）。既存値が空の場合の例です。

ini
shared_preload_libraries = 'pg_bigm'

既に pg_stat_statements がある場合は 'pg_stat_statements,pg_bigm' のように併記します。管理者 PowerShell でサービス名を確認し、対象だけを再起動してから対象 DB に接続します。

powershell
Get-Service -Name '*postgres*'
# 実際のサービス名に合わせて変更する
Restart-Service -Name 'postgresql-x64-17'

& "$pgRoot\bin\psql.exe" -h localhost -U postgres -d 'Implem.Pleasanter'

接続後、後述の「共通：対象 DB に登録する」を実行します。

AlmaLinux オンプレミス ​

1. PostgreSQL と開発用ファイルをそろえる ​

AlmaLinux 9・x86_64 に PGDG 版 PostgreSQL 17 が導入済みであることを前提にします。PGDG は PostgreSQL プロジェクトが提供するパッケージリポジトリです（Red Hat 系向け導入案内）。OS 標準パッケージと PGDG 版では、パッケージ名・配置先・サービス名が異なります。既存 DB に対して initdb を実行する必要はありません。

bash
/usr/pgsql-17/bin/pg_config --version
sudo dnf install -y gcc make git postgresql17-devel

開発用パッケージの依存関係が見つからない場合は、利用中の AlmaLinux の版に対応する CRB などのリポジトリ設定を確認します。別バージョンの開発用パッケージで代用しないでください。

2. ソースからビルドして配置する ​

使用するリリースを固定して取得し、PostgreSQL の拡張用ビルド環境 PGXS でビルドします。PG_CONFIG には、拡張を導入する PostgreSQL と同じ版のコマンドを指定します（pg_bigm のビルド手順）。

bash
git clone --depth 1 --branch v1.2-20250903 \
  https://github.com/pgbigm/pg_bigm.git
cd pg_bigm

make USE_PGXS=1 PG_CONFIG=/usr/pgsql-17/bin/pg_config
sudo make USE_PGXS=1 PG_CONFIG=/usr/pgsql-17/bin/pg_config install

3. プリロードを設定する ​

bash
sudo -u postgres /usr/pgsql-17/bin/psql -d postgres \
  -c 'SHOW config_file;' -c 'SHOW shared_preload_libraries;'

確認した postgresql.conf に、Windows と同じ要領で pg_bigm を追加します（既存値が空なら shared_preload_libraries = 'pg_bigm'）。サービスを再起動し、対象 DB へ接続して後述の共通手順を実行します。

bash
sudo systemctl restart postgresql-17
sudo systemctl status postgresql-17 --no-pager
sudo -u postgres /usr/pgsql-17/bin/psql -d 'Implem.Pleasanter'

Docker ​

1. 拡張を含む DB イメージをビルドする ​

実行中のコンテナ内だけに追加すると、コンテナの作り直しでファイルが失われます。pg_bigm を含む PostgreSQL イメージを作成します。以下は Debian ベースの postgres:17-bookworm 用です。Alpine ベースではビルド環境や C ライブラリが異なるため、この成果物をそのままコピーしないでください。

dockerfile
FROM postgres:17-bookworm AS builder
ARG PG_BIGM_VERSION=v1.2-20250903
RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential ca-certificates git postgresql-server-dev-17 \
    && git clone --depth 1 --branch "${PG_BIGM_VERSION}" https://github.com/pgbigm/pg_bigm.git /src/pg_bigm \
    && make -C /src/pg_bigm USE_PGXS=1 PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config \
    && make -C /src/pg_bigm USE_PGXS=1 PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config DESTDIR=/stage install

FROM postgres:17-bookworm
COPY --from=builder /stage/ /

ビルド段階で生成した拡張ファイルだけを実行用イメージへコピーしています。本番運用では、検証したベースイメージの digest も記録・固定すると、再ビルド時の差を管理しやすくなります。

2. 独立した検証用 DB を起動する ​

次の Compose は新規の検証用 DB です。プリザンター本体や既存 DB の移行は含みません。

yaml
services:
  db:
    build: .
    image: pg-bigm:17
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
      POSTGRES_DB: bigm_lab
    command: ["postgres", "-c", "shared_preload_libraries=pg_bigm"]
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d bigm_lab"]
      interval: 5s
      timeout: 5s
      retries: 12
volumes:
  pgdata:

同じディレクトリに .env を作成して POSTGRES_PASSWORD に自分で決めたパスワードを設定し、.env は Git 管理から除外します。

text
POSTGRES_PASSWORD=ここを自分のパスワードに置き換える
bash
docker compose up -d --build --wait
docker compose exec db psql -U postgres -d bigm_lab

起動後に共通手順で拡張を登録します。Windows ホストから実行する場合も、このイメージは Linux コンテナとして動かします。

WARNING

既存 DB に適用するときは、その DB と同じ PostgreSQL メジャーバージョンでイメージを作成します。メジャーバージョンの異なるデータボリュームを付け替えても DB のアップグレードにはなりません。また、既存の shared_preload_libraries の値は保持してください。

  • 公式イメージの POSTGRES_DB や /docker-entrypoint-initdb.d による初期化は、データディレクトリが空のときに実行されます。既存ボリュームでは、対象 DB に接続して拡張登録を実行してください（PostgreSQL 公式 Docker イメージ）
  • プリザンターの DB を CodeDefiner で新規作成する構成では、DB 作成後に実際のプリザンター用 DB へ拡張を登録します。postgres や検証用の bigm_lab に登録しただけでは、別 DB であるプリザンター用 DB では利用できません

共通：対象 DB に登録する ​

対象 DB に管理者権限で接続し、配置とプリロードを確認してから拡張を登録します。

sql
SELECT current_database(), version();
SHOW shared_preload_libraries;

SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name = 'pg_bigm';

CREATE EXTENSION IF NOT EXISTS pg_bigm;

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('pg_bigm', 'pg_trgm');

pg_available_extensions に表示されるのは、サーバが拡張の定義ファイルを見つけられる状態です。pg_extension に表示されて、初めて接続中の DB に登録されています。

インデックスの効果を SQL で確かめる ​

本番のプリザンター用テーブルは変更せず、検証用 DB で試します。10 万件のうち 100 件に「東京」を含むデータです。

sql
CREATE TABLE bigm_demo (
    id integer PRIMARY KEY,
    body text NOT NULL
);

INSERT INTO bigm_demo
SELECT n,
       CASE WHEN n % 1000 = 0
           THEN '東京都の契約書 ' || n
           ELSE '大阪府の請求書 ' || n
       END
FROM generate_series(1, 100000) AS n;

ANALYZE bigm_demo;

EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM bigm_demo
WHERE body LIKE likequery('東京');

likequery() は、入力を部分一致用のパターンに変換し、% や _ なども文字として検索できるようエスケープする関数です。アプリケーションから使う場合、検索語は別途 SQL パラメータで渡してください。

続いて GIN インデックスを作成して比較します。

sql
CREATE INDEX bigm_demo_body_idx
ON bigm_demo USING gin (body gin_bigm_ops);

ANALYZE bigm_demo;

EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM bigm_demo
WHERE body LIKE likequery('東京');

SELECT count(*) FROM bigm_demo
WHERE body LIKE likequery('東京');

Docker での検証結果です。

条件実行計画の主な処理取得件数実行時間
インデックス作成前Seq Scan100 件7.013 ms
インデックス作成後Bitmap Index Scan と Bitmap Heap Scan100 件0.165 ms

小さな検証データでの単回測定であり、プリザンターの画面表示時間や実データで同じ改善率になることを示すものではありません。評価時は同じ条件で複数回実行し、キャッシュの影響や更新処理の負荷も確認してください。

検索条件が違うと効果も変わる ​

同じ DB で pg_trgm も登録し、条件を変えてみます。

sql
CREATE EXTENSION IF NOT EXISTS pg_trgm;

EXPLAIN
SELECT id FROM bigm_demo WHERE body ILIKE '%東京%';

EXPLAIN
SELECT id FROM bigm_demo WHERE body %> '東京';

検証では、どちらも Seq Scan でした。gin_bigm_ops を作っても、この 2 つの条件を処理するインデックスにはなりません。これが、プリザンターの標準検索をインデックスの差し替えだけで高速化できない理由です。

大文字・小文字を区別しない独自検索を設計する場合は、たとえば lower(body) の式にインデックスを作り、検索側も lower(body) LIKE likequery(lower(検索語)) にそろえる方法があります。ただし照合順序なども含めて、既存の ILIKE と同じ結果になるかの検証が必要です。

プリザンターで活用する際の判断ポイント ​

標準検索を pg_bigm で処理するには、検索 SQL やインデックス管理の変更が必要で、標準設定の切り替えだけでは完了しません。独自検索を実装する場合も、次の点を確認します。

  • LIKE への変更で、類似検索・英字の大小・複数語・否定条件の結果がどう変わるか
  • 検索結果にプリザンターのテナント境界とレコードのアクセス権を適用できているか
  • レコード更新時に検索対象データが更新されるか
  • CodeDefiner やバージョンアップ後に、独自インデックスが維持されるか

Rds.json には手動インデックスを扱うための DisableIndexChangeDetection があります。ただしこれはインデックスの差異検出を抑制する設定で、検索を pg_bigm へ切り替える設定ではありません。標準のインデックス更新にも影響するため、独自インデックスの保守方針とあわせて判断します（Rds.json の公式説明）。

検索以外の負荷も確認してください。

  • GIN インデックスにはディスク容量と更新コストがかかります。大量インポートや頻繁な更新がある環境では、検索時間だけでなく登録・更新時間も比較します
  • ヒットする割合が大きい場合やテーブルが小さい場合は、インデックスがあっても Seq Scan が選ばれることがあります。インデックス利用の有無だけでなく、実行時間・読み取ったページ数・検索結果の一致を確認します

うまく動かないときの確認箇所 ​

症状確認すること
extension "pg_bigm" is not available接続先 DB サーバの拡張ディレクトリに pg_bigm.control と SQL があるか
共有ライブラリや DLL を読み込めないPostgreSQL のメジャーバージョン、CPU アーキテクチャ、配置先、依存ライブラリが合っているか
設定変更後に PostgreSQL が起動しないサーバログを確認し、プリロード指定と実際のライブラリ配置を照合する
gin_bigm_ops が見つからない接続中の DB に CREATE EXTENSION 済みか、拡張を配置したスキーマが検索パスにあるか
インデックスが使われない条件が LIKE か、対象列・式が一致しているか、統計情報が更新されているか
コンテナ再作成で拡張が使えなくなった実行用イメージに拡張ファイルが含まれているか

EXPLAIN ANALYZE は実際に SQL を実行します。本番で重い検索を調べる際は、実行する時間帯と負荷を考慮してください。

SQL Server 2025（Docker）：フルテキスト検索を有効にする ​

Docker で SQL Server を起動できても、そのままフルテキスト検索が使えるとは限りません。利用するには、サーバー側のコンポーネントと、検索対象テーブルのフルテキストインデックスが必要です。

プリザンターは SQL Server の全文索引を CodeDefiner で作成しますが、Full-Text Search 機能が入っていないと索引の作成に失敗したまま CodeDefiner が正常終了します（検索機能の内部実装 の「索引の作成に失敗しても CodeDefiner は正常終了する」を参照）。コンテナで構築する場合は、以下の手順で機能を組み込んでおきます。

対象環境

SQL Server 2025 / Ubuntu 24.04 ベースの Linux コンテナーです。Docker Compose v2 と x86-64 環境を前提にし、開発・検証用の Developer エディションを使用しています。

必要なもの ​

Linux 版 SQL Server では、フルテキスト検索用のパッケージ mssql-server-fts をインストールします（Microsoft Learn のインストール手順）。Docker では、この追加インストールを Dockerfile に記述します。起動済みコンテナーに手作業で追加するだけだと、コンテナーを作り直したときに失われるためです。

図を読み込み中…

作業用ディレクトリの構成です。

text
sqlserver-fts/
├── Dockerfile
├── compose.yaml
├── .env
├── .gitignore
└── .dockerignore

フルテキスト検索を追加したイメージを作る ​

dockerfile
FROM mcr.microsoft.com/mssql/server:2025-CU8-ubuntu-24.04

USER root

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && curl -fsSL https://packages.microsoft.com/config/ubuntu/24.04/mssql-server-2025.list \
        -o /etc/apt/sources.list.d/mssql-server-2025.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends mssql-server-fts \
    && rm -rf /var/lib/apt/lists/*

USER mssql
  • インストール時は USER root に切り替え、実行時は USER mssql に戻します
  • SQL Server 2025 用の APT リポジトリを追加します。一般的な Microsoft 製品用リポジトリだけでは、目的のパッケージが見つからない場合があります
  • 署名検証には、ベースイメージに登録済みの Microsoft の鍵を使います
  • コンテナー内では systemctl で SQL Server を起動せず、ベースイメージの起動処理を引き継ぎます

リポジトリの指定は Ubuntu への SQL Server インストール手順 に基づいています。ベースイメージの OS と SQL Server のメジャーバージョンに合わせることが大切です。

WARNING

ベースイメージの CU と OS を指定しても、APT リポジトリの内容は更新されます。また、mssql-server-fts の依存関係として SQL Server 本体のパッケージが追加・更新されることがあります。厳密な再現性が必要な場合は、ベースイメージのタグまたは digest に加え、本体と FTS パッケージのバージョンも揃えて固定してください。

検証では、ベースイメージは CU8 でしたが、追加インストール後の本体は SQL Server 2025 CU9（17.0.5005.3）、FTS パッケージは 17.0.5005.3-1 になりました。以下の手順はこの構成で確認しています。

Docker Compose の設定 ​

yaml
services:
  sqlserver:
    build: .
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_PID: "Developer"
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD in .env}"
    ports:
      - "127.0.0.1:1433:1433"
    volumes:
      - sqlserver-data:/var/opt/mssql

volumes:
  sqlserver-data:
  • Developer は開発・テスト向けのエディションです。本番利用時は適切なライセンスとエディションを選んでください
  • ポートはローカルホストに限定し、データは名前付きボリュームに保存しています

.env には自分で決めた強いパスワードを設定し、.gitignore と .dockerignore の両方で除外します。

dotenv
MSSQL_SA_PASSWORD='Replace-With-Your-Own-Strong-Password!42'
text
.env
text
.env
.git

ビルドして起動する ​

作業用ディレクトリで実行します（PowerShell でも実行できます）。

powershell
docker compose up -d --build
docker compose logs -f sqlserver

ログに接続受付の準備ができた旨のメッセージが表示されたら、Ctrl+C でログ表示を終了します。コンテナーは動作を続けます（起動・接続方法は Microsoft Learn の Docker クイックスタート も参照）。

インストールされたか確認する ​

コンテナー内の sqlcmd で接続し、プロンプトに .env と同じパスワードを入力します。-C はサーバー証明書を信頼するオプションで、ここではローカル検証用の接続に使っています。この SQL Server 2025 のイメージでは、ツールのパスは /opt/mssql-tools18/bin です。

powershell
docker compose exec sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -C

接続後、次の SQL を実行します（GO は sqlcmd のバッチ区切りです）。

sql
SELECT @@VERSION AS Version;
SELECT FULLTEXTSERVICEPROPERTY('IsFullTextInstalled') AS IsFullTextInstalled;
GO

SELECT name, lcid
FROM sys.fulltext_languages
WHERE lcid = 1041;
GO
  • IsFullTextInstalled が 1 ならインストール済み、0 なら未インストールです（FULLTEXTSERVICEPROPERTY）
  • 1041 は日本語の言語 ID です。日本語を単語に分解する機能が登録されているかも確認しておきます

日本語のフルテキスト検索を試す ​

同じ sqlcmd セッションで、新しい検証用データベースに対して一度だけ実行する想定です。

sql
CREATE DATABASE FullTextDemo;
GO
USE FullTextDemo;
GO

CREATE TABLE dbo.Documents
(
    Id int NOT NULL CONSTRAINT PK_Documents PRIMARY KEY,
    Body nvarchar(1000) NOT NULL
);

INSERT INTO dbo.Documents (Id, Body)
VALUES
    (1, N'自転車で公園へ行きます。'),
    (2, N'図書館で本を借ります。');
GO

日本語を格納するため、列の型を nvarchar にし、文字列リテラルに N を付けています。

フルテキストカタログ（フルテキストインデックスをまとめる論理的な入れ物）とインデックスを作ります。

sql
CREATE FULLTEXT CATALOG DemoCatalog;
GO

CREATE FULLTEXT INDEX ON dbo.Documents
(
    Body LANGUAGE 1041
)
KEY INDEX PK_Documents
ON DemoCatalog
WITH CHANGE_TRACKING AUTO;
GO
  • KEY INDEX には、各行を一意に識別できる、単一列かつ NULL を許可しない一意インデックスを指定します。ここでは主キーの PK_Documents です
  • CHANGE_TRACKING AUTO では初回のインデックス作成後も変更が自動反映されます。ただし反映は非同期です（CREATE FULLTEXT INDEX）

検索します。

sql
SELECT Id, Body
FROM dbo.Documents
WHERE CONTAINS(Body, N'"自転車"', LANGUAGE 1041);
GO

インデックスへの反映後に次の 1 行が取得できました。作成直後に結果が空だった場合は、少し待って再実行してください。

text
Id  Body
1   自転車で公園へ行きます。

反映状況は次のクエリで確認できます。

sql
SELECT
    OBJECTPROPERTYEX(OBJECT_ID(N'dbo.Documents'), 'TableFulltextPopulateStatus') AS PopulateStatus,
    OBJECTPROPERTYEX(OBJECT_ID(N'dbo.Documents'), 'TableFulltextItemCount') AS IndexedItems;
GO

このサンプルでは、PopulateStatus が 0（処理中ではない）、IndexedItems が 2 になることを確認します。状態が 0 というだけでは取り込み成功とは判断できません（OBJECTPROPERTYEX）。確認が終わったら QUIT で sqlcmd を終了します。

INFO

フルテキスト検索は、LIKE N'%文字列%' と同じ部分一致検索ではありません。単語の分割結果や、検索対象から除外される単語（ストップワード）によって検索結果が変わります（フルテキスト検索のクエリ）。

うまくいかないときの確認ポイント ​

症状確認すること
mssql-server-fts が見つからないSQL Server 2025 用の APT リポジトリを追加したか、追加後に apt-get update を実行したか
IsFullTextInstalled が 0FTS を追加したイメージから起動しているか、接続先が別の SQL Server ではないか
コンテナーが終了するdocker compose logs sqlserver でパスワード要件やメモリ不足などのエラーを確認する
sqlcmd が見つからない使用中のイメージのバージョンとツールの配置場所を確認する
フルテキストインデックスが作れない対象列の型と KEY INDEX の要件、コンポーネントのインストール状態を確認する
検索結果が空になる取り込み状況、対象データ、言語設定、ストップワードを確認する

設定を変更した場合は、イメージの再ビルドとコンテナーの再作成を行います。単なる restart ではイメージの変更は反映されません。

powershell
docker compose up -d --build --force-recreate

既存の名前付きボリュームを再利用する場合、.env のパスワードを書き換えるだけでは既存の sa のパスワードは変わりません。

停止 ​

powershell
docker compose down

名前付きボリュームは残るので、次回の起動時にもデータを利用できます。データも破棄する場合だけ docker compose down -v を実行してください。

関連ページ ​

変更履歴

第2版記事のファイル名に並び順の番号を付け、元記事リンクを frontmatter の sources に移行
第1版検索機能の解説に横断検索・添付ファイル全文検索・実践編を追加し、全文検索の環境構築ページを追加