===========================

PostgreSQL specific lookups

===========================

Trigram similarity

==================

.. fieldlookup:: trigram_similar

The ``trigram_similar`` lookup allows you to perform trigram lookups,

measuring the number of trigrams (three consecutive characters) shared, using a

dedicated PostgreSQL extension. A trigram lookup is given an expression and

returns results that have a similarity measurement greater than the current

similarity threshold.

To use it, add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`

and activate the `pg_trgm extension`_ on PostgreSQL. You can install the

extension using the

:class:`~django.contrib.postgres.operations.TrigramExtension` migration

operation.

The ``trigram_similar`` lookup can be used on

:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`::

    >>> City.objects.filter(name__trigram_similar="Middlesborough")

    ['<City: Middlesbrough>']

.. fieldlookup:: trigram_word_similar

.. versionadded:: 4.0

The ``trigram_word_similar`` lookup allows you to perform trigram word

similarity lookups using a dedicated PostgreSQL extension. It can be

approximately understood as measuring the greatest number of trigrams shared

between the parameter and any substring of the field. A trigram word lookup is

given an expression and returns results that have a word similarity measurement

greater than the current similarity threshold.

To use it, add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`

and activate the `pg_trgm extension`_ on PostgreSQL. You can install the

extension using the

:class:`~django.contrib.postgres.operations.TrigramExtension` migration

operation.

The ``trigram_word_similar`` lookup can be used on

:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`::

    >>> Sentence.objects.filter(name__trigram_word_similar='Middlesborough')

    ['<Sentence: Gumby rides on the path of Middlesbrough>']

.. _`pg_trgm extension`: https://www.postgresql.org/docs/current/pgtrgm.html

``Unaccent``

============

.. fieldlookup:: unaccent

The ``unaccent`` lookup allows you to perform accent-insensitive lookups using

a dedicated PostgreSQL extension.

This lookup is implemented using :class:`~django.db.models.Transform`, so it

can be chained with other lookup functions. To use it, you need to add

``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS` and activate

the `unaccent extension on PostgreSQL`_. The

:class:`~django.contrib.postgres.operations.UnaccentExtension` migration

operation is available if you want to perform this activation using migrations).

.. _unaccent extension on PostgreSQL: https://www.postgresql.org/docs/current/unaccent.html

The ``unaccent`` lookup can be used on

:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`::

    >>> City.objects.filter(name__unaccent="México")

    ['<City: Mexico>']

    >>> User.objects.filter(first_name__unaccent__startswith="Jerem")

    ['<User: Jeremy>', '<User: Jérémy>', '<User: Jérémie>', '<User: Jeremie>']

.. warning::

    ``unaccent`` lookups should perform fine in most use cases. However, queries

    using this filter will generally perform full table scans, which can be slow

    on large tables. In those cases, using dedicated full text indexing tools

    might be appropriate.