mirror of
https://github.com/django/django.git
synced 2025-10-25 06:36:07 +00:00
112 lines
4.0 KiB
Plaintext
112 lines
4.0 KiB
Plaintext
===========================
|
|
PostgreSQL specific lookups
|
|
===========================
|
|
|
|
Trigram similarity
|
|
==================
|
|
|
|
.. fieldlookup:: trigram_similar
|
|
|
|
``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`:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> City.objects.filter(name__trigram_similar="Middlesborough")
|
|
['<City: Middlesbrough>']
|
|
|
|
.. fieldlookup:: trigram_word_similar
|
|
|
|
``trigram_word_similar``
|
|
------------------------
|
|
|
|
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`:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> Sentence.objects.filter(name__trigram_word_similar="Middlesborough")
|
|
['<Sentence: Gumby rides on the path of Middlesbrough>']
|
|
|
|
.. fieldlookup:: trigram_strict_word_similar
|
|
|
|
``trigram_strict_word_similar``
|
|
-------------------------------
|
|
|
|
Similar to :lookup:`trigram_word_similar`, except that it forces extent
|
|
boundaries to match word boundaries.
|
|
|
|
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_strict_word_similar`` lookup can be used on
|
|
:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`.
|
|
|
|
.. _`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`:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> 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.
|