---
title: "全文検索"
version: 5.2
locale: ja
source: https://docs.djangoproject.com/ja/5.2/ref/contrib/postgres/search/
canonical: https://djangodocs.dev/ja/5.2/ref/contrib/postgres/search/
---
# 全文検索

`django.contrib.postgres.search` モジュールのデータベース関数は PostgreSQL の [全文検索エンジン](https://www.postgresql.org/docs/current/textsearch.html) を利用しやすくしています。

このドキュメントの例では、 [クエリを作成する](/ja/5.2/topics/db/queries/) で定義されたモデルを使用します。

> **See also**
>
> 検索の概要については、 [トピックのドキュメント](/ja/5.2/topics/db/search/) を参照してください。

## `search` ルックアップ

全文検索の一般的な使用方法は、データベースの1つのカラムに対して1つの用語を検索することです。たとえば:

```pycon
>>> Entry.objects.filter(body_text__search="Cheese")
<QuerySet [<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]>
```

これにより、データベース内の `body_text` フィールドから `to_tsvector` が作成され、検索語 `'Cheese'` から `plainto_tsquery` が作成されます。両方ともデフォルトのデータベース検索設定を使用しています。結果は、クエリとベクトルを一致させることで取得されます。

`search` ルックアップを使用するには、[`INSTALLED_APPS`](/ja/5.2/ref/settings/#std-setting-INSTALLED_APPS) に `'django.contrib.postgres'` を含める必要があります。

## `SearchVector`

#### `class SearchVector(*expressions, config=None, weight=None)`

単一のフィールドに対する検索は素晴らしいですが、制約があります。検索対象となる `Entry` インスタンスは `Blog` に属しており、 `tagline` フィールドを持っています。両方のフィールドに対してクエリを行うには、 `SearchVector` を使用します:

```pycon
>>> from django.contrib.postgres.search import SearchVector
>>> Entry.objects.annotate(
...     search=SearchVector("body_text", "blog__tagline"),
... ).filter(search="Cheese")
<QuerySet [<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]>
```

`SearchVector` への引数は、任意の [`Expression`](/ja/5.2/ref/models/expressions/#django.db.models.Expression) またはフィールドの名前を指定できます。複数の引数は、スペースを使用して連結され、検索ドキュメントにすべて含まれます。

`SearchVector` オブジェクトは組み合わせて再利用できます。たとえば:

```pycon
>>> Entry.objects.annotate(
...     search=SearchVector("body_text") + SearchVector("blog__tagline"),
... ).filter(search="Cheese")
<QuerySet [<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]>
```

`config` パラメータおよび `weight` パラメータの説明については、[検索設定を変更する](#postgresql-fts-search-configuration) と [クエリを重み付けする](#postgresql-fts-weighting-queries) を参照してください。

## `SearchQuery`

#### `class SearchQuery(value, config=None, search_type='plain')`

`SearchQuery` は、ユーザーが提供した用語を検索クエリオブジェクトに変換し、データベースが検索ベクトルと比較する機能を提供します。デフォルトでは、ユーザーが提供したすべての単語がステミングアルゴリズムを通過され、その結果の用語すべてに一致するものを検索します。

もし `search_type` が `'plain'` (デフォルト) の場合、用語は別々のキーワードとして扱われます。もし `search_type` が `'phrase'` の場合、用語は1つのフレーズとして扱われます。もし `search_type` が `'raw'` の場合、用語と演算子を含む書式付きの検索クエリを指定できます。もし `search_type` が `'websearch'` の場合、Web検索エンジンで使用されるものに類似した書式で検索クエリを指定できます。 `'websearch'` には PostgreSQL ≥ 11 が必要です。違いや構文については PostgreSQL の [Full Text Search docs](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES) を参照してください。例:

```pycon
>>> from django.contrib.postgres.search import SearchQuery
>>> SearchQuery("red tomato")  # two keywords
>>> SearchQuery("tomato red")  # same results as above
>>> SearchQuery("red tomato", search_type="phrase")  # a phrase
>>> SearchQuery("tomato red", search_type="phrase")  # a different phrase
>>> SearchQuery("'tomato' & ('red' | 'green')", search_type="raw")  # boolean operators
>>> SearchQuery(
...     "'tomato' ('red' OR 'green')", search_type="websearch"
... )  # websearch operators
```

`SearchQuery` の用語は論理的に組み合わせることで、柔軟性を高めることができます:

```pycon
>>> from django.contrib.postgres.search import SearchQuery
>>> SearchQuery("meat") & SearchQuery("cheese")  # AND
>>> SearchQuery("meat") | SearchQuery("cheese")  # OR
>>> ~SearchQuery("meat")  # NOT
```

`config` パラメータの説明については、[検索設定を変更する](#postgresql-fts-search-configuration) を参照してください。

## `SearchRank`

#### `class SearchRank(vector, query, weights=None, normalization=None, cover_density=False)`

これまでに、ベクトルとクエリの間で一致する結果を返してきました。おそらく結果をある種の関連性によって並べ替えたいと思うかもしれません。PostgreSQLにはランキング関数が用意されており、クエリ用語がドキュメント内にどれだけ多く現れるか、用語がドキュメント内でどれだけ近くにあるか、そしてそれらが発生するドキュメント内の部分がどれだけ重要かを考慮します。一致度が高いほど、ランクの値が高くなります。関連度で並び替えるには:

```pycon
>>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector
>>> vector = SearchVector("body_text")
>>> query = SearchQuery("cheese")
>>> Entry.objects.annotate(rank=SearchRank(vector, query)).order_by("-rank")
<QuerySet [<Entry: Cheese on Toast recipes>, <Entry: Pizza recipes>]>
```

`weights` パラメータの説明については、[クエリを重み付けする](#postgresql-fts-weighting-queries) を参照してください。

`cover_density` パラメーターを `True` に設定して、カバー密度ランキングを有効にします。これにより、クエリ用語の一致する近接度が考慮されます。

`normalization` パラメータに整数を指定すると、順位の正規化を制御できます。この整数はビットマスクであり、複数の動作を組み合わせることができます。

```pycon
>>> from django.db.models import Value
>>> Entry.objects.annotate(
...     rank=SearchRank(
...         vector,
...         query,
...         normalization=Value(2).bitor(Value(4)),
...     )
... )
```

PostgreSQLのドキュメントに、 [different rank normalization options](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING) についての詳細があります。

## `SearchHeadline`

#### `class SearchHeadline(expression, query, config=None, start_sel=None, stop_sel=None, max_words=None, min_words=None, short_word=None, highlight_all=None, max_fragments=None, fragment_delimiter=None)`

単一のテキストフィールドまたは式、クエリ、設定、およびオプションのセットを受け入れ、ハイライトされた検索結果を返します。

`start_sel` パラメータと `stop_sel` パラメータには、ハイライトされたクエリ語をドキュメントで囲むために使用する文字列値を設定します。PostgreSQLのデフォルトは `<b>` と `</b>` です。

パラメータ `max_words` と `min_words` に整数値を指定して、最長と最短の見出しを決定します。PostgreSQLのデフォルトは35と15です。

`short_word` パラメータに整数値を指定すると、各見出しでこの長さ以下の単語を破棄します。PostgreSQLのデフォルトは3です。

`highlight_all` パラメータを `True` に設定すると、フラグメントの代わりにドキュメント全体を使用し、 `max_words`、`min_words`、`short_word` パラメータを無視します。PostgreSQLではデフォルトで無効になっています。

表示するフラグメントの最大数を設定するには、 `max_fragments` に0以外の整数値を指定してください。PostgreSQLではデフォルトで無効になっています。

`fragment_delimiter` 文字列パラメータを設定すると、フラグメント間の区切り文字を構成できます。PostgreSQL のデフォルトは `" ... "` です。

PostgreSQL のドキュメントには、[highlighting search results](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE) に関する詳細が記載されています。

使用例:

```pycon
>>> from django.contrib.postgres.search import SearchHeadline, SearchQuery
>>> query = SearchQuery("red tomato")
>>> entry = Entry.objects.annotate(
...     headline=SearchHeadline(
...         "body_text",
...         query,
...         start_sel="<span>",
...         stop_sel="</span>",
...     ),
... ).get()
>>> print(entry.headline)
Sandwich with <span>tomato</span> and <span>red</span> cheese.
```

`config` パラメータの説明については、[検索設定を変更する](#postgresql-fts-search-configuration) を参照してください。

## 検索設定を変更する

[`SearchVector`](#django.contrib.postgres.search.SearchVector) および [`SearchQuery`](#django.contrib.postgres.search.SearchQuery) に `config` 属性を指定して、異なる検索設定を使用できます。これにより、データベースで定義された異なる言語の解析機能や辞書を使用できます。

```pycon
>>> from django.contrib.postgres.search import SearchQuery, SearchVector
>>> Entry.objects.annotate(
...     search=SearchVector("body_text", config="french"),
... ).filter(search=SearchQuery("œuf", config="french"))
<QuerySet [<Entry: Pain perdu>]>
```

`config` の値は別の列にも保存できます。

```pycon
>>> from django.db.models import F
>>> Entry.objects.annotate(
...     search=SearchVector("body_text", config=F("blog__language")),
... ).filter(search=SearchQuery("œuf", config=F("blog__language")))
<QuerySet [<Entry: Pain perdu>]>
```

## クエリを重み付けする

すべてのフィールドがクエリにおいて同じ重要度を持つとは限りません。そのため、それらを組み合わせる前に、複数のベクトルの重みを設定できます。

```pycon
>>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector
>>> vector = SearchVector("body_text", weight="A") + SearchVector(
...     "blog__tagline", weight="B"
... )
>>> query = SearchQuery("cheese")
>>> Entry.objects.annotate(rank=SearchRank(vector, query)).filter(rank__gte=0.3).order_by(
...     "rank"
... )
```

重みは次のいずれかの文字である必要があります: D, C, B, A。デフォルトでは、これらの重みはそれぞれ `0.1`, `0.2`, `0.4`, `1.0` に対応しています。異なる重みを使用する場合は、同じ順序で四つの浮動小数点数のリストを、上記の通りに [`SearchRank`](#django.contrib.postgres.search.SearchRank) に `weights` として渡してください。

```pycon
>>> rank = SearchRank(vector, query, weights=[0.2, 0.4, 0.6, 0.8])
>>> Entry.objects.annotate(rank=rank).filter(rank__gte=0.3).order_by("-rank")
```

## パフォーマンス

これらの関数を使用するために特別なデータベース設定をする必要はありませんが、数百以上のレコードを検索する場合、パフォーマンスの問題に直面する可能性が高くなります。全文検索は、例えば整数のサイズを比較するよりも負荷の高い処理です。

クエリ対象の全てのフィールドが特定のモデルに含まれている場合、使いたい検索ベクトルにマッチする関数 [`GIN`](/ja/5.2/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GinIndex) または [`GiST`](/ja/5.2/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GistIndex) インデックスを作成できます。たとえば:

```
GinIndex(
    SearchVector("body_text", "headline", config="english"),
    name="search_vector_idx",
)
```

PostgreSQL のドキュメントには、[フルテキスト検索用のインデックス作成の詳細](https://www.postgresql.org/docs/current/textsearch-tables.html#TEXTSEARCH-TABLES-INDEX) が記載されています。

### `SearchVectorField`

#### `class SearchVectorField`

この方法が遅すぎる場合は、モデルに `SearchVectorField` を追加できます。このフィールドには、例えば [PostgreSQL documentation](https://www.postgresql.org/docs/current/textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS) で説明されているように、トリガーを入力しておく必要があります。そうすれば、あたかもアノテーションされた `SearchVector` のようにフィールドに問い合わせることができます:

```pycon
>>> Entry.objects.update(search_vector=SearchVector("body_text"))
>>> Entry.objects.filter(search_vector="cheese")
<QuerySet [<Entry: Cheese on Toast recipes>, <Entry: Pizza recipes>]>
```

## trigram（トリグラム）類似度

検索の別の手法として trigram 類似度があります。trigram は3つの連続する文字のグループです。 [`trigram_similar`](/ja/5.2/ref/contrib/postgres/lookups/#std-fieldlookup-trigram_similar)、[`trigram_word_similar`](/ja/5.2/ref/contrib/postgres/lookups/#std-fieldlookup-trigram_word_similar)、[`trigram_strict_word_similar`](/ja/5.2/ref/contrib/postgres/lookups/#std-fieldlookup-trigram_strict_word_similar) の他にもいくつかの式を使用できます。

これらを使用するには、PostgreSQL上で [pg\_trgm 拡張機能](https://www.postgresql.org/docs/current/pgtrgm.html) を有効にする必要があります。これは、 [`TrigramExtension`](/ja/5.2/ref/contrib/postgres/operations/#django.contrib.postgres.operations.TrigramExtension) マイグレーション・オペレーションを使用してインストールできます。

### `TrigramSimilarity`

#### `class TrigramSimilarity(expression, string, **extra)`

フィールド名や式、文字列や式を受け取ります。2つの引数の間の trigram 類似度を返します。

使用例:

```pycon
>>> from django.contrib.postgres.search import TrigramSimilarity
>>> Author.objects.create(name="Katy Stevens")
>>> Author.objects.create(name="Stephen Keats")
>>> test = "Katie Stephens"
>>> Author.objects.annotate(
...     similarity=TrigramSimilarity("name", test),
... ).filter(
...     similarity__gt=0.3
... ).order_by("-similarity")
<QuerySet [<Author: Katy Stevens>, <Author: Stephen Keats>]>
```

### `TrigramWordSimilarity`

#### `class TrigramWordSimilarity(string, expression, **extra)`

文字列または式、およびフィールド名または式を受け入れます。2つの引数間の trigram 単語類似度を返します。

使用例:

```pycon
>>> from django.contrib.postgres.search import TrigramWordSimilarity
>>> Author.objects.create(name="Katy Stevens")
>>> Author.objects.create(name="Stephen Keats")
>>> test = "Kat"
>>> Author.objects.annotate(
...     similarity=TrigramWordSimilarity(test, "name"),
... ).filter(
...     similarity__gt=0.3
... ).order_by("-similarity")
<QuerySet [<Author: Katy Stevens>]>
```

### `TrigramStrictWordSimilarity`

#### `class TrigramStrictWordSimilarity(string, expression, **extra)`

文字列または式とフィールド名または式を受け取り、2つの引数間の trigram 厳密単語類似度を返します。 [`TrigramWordSimilarity()`](#django.contrib.postgres.search.TrigramWordSimilarity) と似ていますが、この関数は範囲境界を単語境界と一致させるように強制します。

### `TrigramDistance`

#### `class TrigramDistance(expression, string, **extra)`

フィールド名または式と、文字列または式を受け入れます。2つの引数の間の trigram 距離を返します。

使用例:

```pycon
>>> from django.contrib.postgres.search import TrigramDistance
>>> Author.objects.create(name="Katy Stevens")
>>> Author.objects.create(name="Stephen Keats")
>>> test = "Katie Stephens"
>>> Author.objects.annotate(
...     distance=TrigramDistance("name", test),
... ).filter(
...     distance__lte=0.7
... ).order_by("distance")
<QuerySet [<Author: Katy Stevens>, <Author: Stephen Keats>]>
```

### `TrigramWordDistance`

#### `class TrigramWordDistance(string, expression, **extra)`

文字列または式と、フィールド名または式を受け取ります。2つの引数間の trigram 単語距離を返します。

使用例:

```pycon
>>> from django.contrib.postgres.search import TrigramWordDistance
>>> Author.objects.create(name="Katy Stevens")
>>> Author.objects.create(name="Stephen Keats")
>>> test = "Kat"
>>> Author.objects.annotate(
...     distance=TrigramWordDistance(test, "name"),
... ).filter(
...     distance__lte=0.7
... ).order_by("distance")
<QuerySet [<Author: Katy Stevens>]>
```

### `TrigramStrictWordDistance`

#### `class TrigramStrictWordDistance(string, expression, **extra)`

文字列または式、フィールド名または式を受け入れ、これらの引数間の trigram strict 単語距離を返します。