pg_fts package

Submodules

pg_fts.fields module

class pg_fts.fields.TSVectorField(fields, dictionary='english', **kwargs)[source]
Parameters:
  • fields –

    A tuple containing a tuple of fields and rank to be indexed, it can be only the field name the default the rank ‘D’ will be added

    Example:

    ('field_name', ('field_name2', 'A'))

    Will result in:

    (('field_name', 'D'), ('field_name2', 'A'))
  • dictionary –

    available options:

    Caution

    Dictionary(ies) used must be installed in your database, check
    pg_catalog.pg_ts_config
Raises:

exceptions.FieldError if lookup isn’t tsquery, search or isearch or not a valid option dictionary (in case of multiple dictionaries)

Caution

TSVectorField does not support iexact, it will raise an exception

class pg_fts.fields.TSVectorBaseField(dictionary='english', **kwargs)[source]

Base vector field

Parameters:dictionary – Dictionary name as is in PostgreSQL `pg_catalog.pg_ts_config` more information in PostgreSQL documentation 12.6. Dictionaries
Raises:exceptions.FieldError if lookup isn’t tsquery, search or isearch
class pg_fts.fields.TSVectorTsQueryLookup(lhs, rhs)[source]

TSVectorField Lookup tsquery

Raw to_tsquery lookup, check the documentation for more details
12.3.2. Parsing Queries
Parameters:values (query) –

valid PostgreSQL tsquery

Caution

If the query is not a valid PostgreSQL to_tsquery will result in a syntax error

Example:

Article.objects.filter(
    tsvector__tsquery="'single-quoted phrases' & prefix:A*B & !not | or | weight:ABC"
)

SQL equivalent:

"tsvector" @@ to_tsquery('english', '''singlequoted phrases'' & prefix:A*B & !not | or | weight:ABC')

Note

The lookup will get dictionary value in
TSVectorField, this case english
In case of multiple dictionaries see
DictionaryTransform
class pg_fts.fields.TSVectorSearchLookup(lhs, rhs)[source]

TSVectorField Lookup search

An to_tsquery with AND & operator

Parameters:values (query) – a string with words

Example:

Article.objects.filter(
    tsvector__search="an and query"
)

SQL equivalent::

.. code-block:: sql
“tsvector” @@ to_tsquery(‘english’, ‘an & and & query’)

Note

The lookup will get dictionary value in
TSVectorField, this case english
In case of multiple dictionaries see
DictionaryTransform
class pg_fts.fields.TSVectorISearchLookup(lhs, rhs)[source]

TSVectorField Lookup isearch

An to_tsquery with OR | operator

Parameters:values (query) – a string with words

Example:

Article.objects.filter(
    tsvector__isearch="an and query"
)

SQL equivalent:

"tsvector" @@ to_tsquery('english', 'an | and | query')

Note

The lookup will get dictionary value in
TSVectorField, this case english
In case of multiple dictionaries see
DictionaryTransform
class pg_fts.fields.DictionaryTransform(dictionary, *args, **kwargs)[source]

TSVectorField dictionary transform

Parameters:values (query) – a valid dictionary in TSVectorField field dictionary.options

Example:

# in models.py

class Article(models.Model):
    title = models.CharField(max_length=255)
    article = models.TextField()
    dictionary = models.CharField(
        max_length=15,
        choices=(
            ('english', 'english'),
            ('portuguese', 'portuguese')
        ),
        default='english',
        db_index=True
    )
    fts_index = TSVectorField(
        (('title', 'A'), 'article'),
        dictionary='dictionary'
    )

>>> Article.objects.filter(
        tsvector__english__isearch="an and query"
    )
# will create a ts_query with english dictionary
# SQL -> to_tsquery('english', 'an | and | query')

>>> Article.objects.filter(
        tsvector__portuguese__isearch="an and query"
    )
# will create a ts_query with portuguese dictionary
# SQL -> to_tsquery('portuguese', 'an | and | query')

>>> Article.objects.filter(
        tsvector__isearch="an and query"
    )
# will create a ts_query with english dictionary, it's the default in
# dictionary, but if there was no default it wold get the 1st option in
# options
# SQL -> to_tsquery('english', 'an | and | query')
# but if dictionary is not in options will raise FieldError
>>> Article.objects.filter(
        tsvector__japonese__isearch="an and query"  # will raise an error
    )
FieldError: The 'japonese' is not in article.Article.dictionary choices

pg_fts.aggregates module

Note

Deprecated use pg_fts.ranks instead.

pg_fts.ranks module

Classes to represent the default SQL aggregate functions

class pg_fts.ranks.FTSRankCd(**extra)[source]

Interface for PostgreSQL ts_rank_cd

Provides a interface for
12.3.3. Ranking Search Results *ts_rank_cd*
Parameters:
  • fieldlookup – required
  • normalization – list or tuple of integers PostgreSQL normalization values
Returns:

rank_cd
Raises:

exceptions.FieldError if lookup isn’t valid

Example:

Article.objects.annotate(
    rank=FTSRank(fts_index__search='Hello world',
                 normalization=[1,2]))

SQL equivalent:

SELECT
    ...,
    ts_rank_cd("article"."fts_index" @@ to_tsquery('english', 'Hello & world'), 1|2) AS "rank"
WHERE
    "article"."fts_index" @@ to_tsquery('english', 'Hello & world')
class pg_fts.ranks.FTSRank(**extra)[source]

Interface for PostgreSQL ts_rank

Provides a interface for
12.3.3. Ranking Search Results *ts_rank*

Example:

Article.objects.annotate(rank=FTSRank(fts_index__search='Hello world',
                         normalization=[1,2]))

SQL equivalent:

SELECT
    ...,
    ts_rank("article"."fts_index" @@ to_tsquery('english', 'Hello & world'), 1|2) AS "rank"
WHERE
    "article"."fts_index" @@ to_tsquery('english', 'Hello & world')
Parameters:
  • fieldlookup – required
  • normalization – iterable integer
  • weights – iterable float
Returns:

rank
Raises:

exceptions.FieldError if lookup isn’t valid
class pg_fts.ranks.FTSRankDictionay(**extra)[source]

Interface for PostgreSQL ts_rank with language lookup

Provides a interface for
12.3.3. Ranking Search Results *rank*
Parameters:
  • fieldlookup – required
  • normalization – list or tuple of integers PostgreSQL normalization values
Returns:

rank
Raises:

exceptions.FieldError if lookup isn’t valid

Example:

Article.objects.annotate(
    rank=FTSRankDictionay(fts_index__portuguese__search='Hello world',
                          normalization=[1,2]))

SQL equivalent:

SELECT
    ...,
    ts_rank("article"."fts_index" @@ to_tsquery('portuguese', 'Hello & world'), 1|2) AS "rank"
WHERE
    "article"."fts_index" @@ to_tsquery('portuguese', 'Hello & world')
class pg_fts.ranks.FTSRankCdDictionary(**extra)[source]

Interface for PostgreSQL ts_rank_cd with language lookup

Provides a interface for
12.3.3. Ranking Search Results *rank_cd* with language lookup
Parameters:
  • fieldlookup – required
  • normalization – list or tuple of integers PostgreSQL normalization values
Returns:

rank_cd
Raises:

exceptions.FieldError if lookup isn’t valid

Example:

Article.objects.annotate(
    rank=FTSRankCdDictionary(fts_index__portuguese__search='Hello world',
                             normalization=[1,2]))

SQL equivalent:

SELECT
    ...,
    ts_rank("article"."fts_index" @@ to_tsquery('portuguese', 'Hello & world'), 1|2) AS "rank"
WHERE
    "article"."fts_index" @@ to_tsquery('portuguese', 'Hello & world')

pg_fts.introspection module

class pg_fts.introspection.PgFTSIntrospection[source]

Helper class the introspect the database

get_dictionay_list(cursor)[source]

introspects pg_catalog.pg_ts_config

Returns:A list of dictionaries names installed in postgres
get_functions_list(cursor)[source]

introspects the database for functions

Returns:A list of functions
get_trigger_list(cursor)[source]

introspects the database for triggers

Returns:A list of triggers

pg_fts.migrations module

class pg_fts.migrations.CreateFTSIndexOperation(name, fts_vector, index)[source]

Creates a index for TSVectorField

Parameters:
class pg_fts.migrations.CreateFTSTriggerOperation(name, fts_vector)[source]

Creates a custom trigger for updating the TSVectorField with rank values

Parameters:
  • name – The Model name
  • fts_vector – The TSVectorField field name
class pg_fts.migrations.DeleteFTSIndexOperation(name, fts_vector, index)[source]

Removes index created by CreateFTSIndexOperation

Parameters:
  • name – The Model name
  • fts_vector – The TSVectorField field name
  • index – The type of index ‘gin’ or ‘gist’ for more information go to
class pg_fts.migrations.DeleteFTSTriggerOperation(name, fts_vector)[source]

Deletes trigger generated by CreateFTSTriggerOperation

Parameters:
  • name – The Model name
  • fts_vector – The TSVectorField field name
class pg_fts.migrations.UpdateVectorOperation(name, fts_vector)[source]

Updates changes to TSVectorField for existing models

Parameters:
  • name – The Model name
  • fts_vector – The TSVectorField field name

pg_fts.utils module

class pg_fts.utils.TranslationDictionary(dictionaries=None, default=None)[source]

TranslationDictionary

Module contents