The database functions in the django.contrib.postgres.search module ease\nthe use of PostgreSQL’s full text search engine.
For the examples in this document, we’ll use the models defined in\nWykonywanie zapytań.
\n\nsearch lookupLink to this heading#A common way to use full text search is to search a single term against a\nsingle column in the database. For example:
\n>>> Entry.objects.filter(body_text__search='Cheese')\n[<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]\nThis creates a to_tsvector in the database from the body_text field\nand a plainto_tsquery from the search term 'Cheese', both using the\ndefault database search configuration. The results are obtained by matching the\nquery and the vector.
To use the search lookup, 'django.contrib.postgres' must be in your\nINSTALLED_APPS.
SearchVectorLink to this heading#Searching against a single field is great but rather limiting. The Entry\ninstances we’re searching belong to a Blog, which has a tagline field.\nTo query against both fields, use a SearchVector:
>>> from django.contrib.postgres.search import SearchVector\n>>> Entry.objects.annotate(\n... search=SearchVector('body_text', 'blog__tagline'),\n... ).filter(search='Cheese')\n[<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]\nThe arguments to SearchVector can be any\nExpression or the name of a field. Multiple\narguments will be concatenated together using a space so that the search\ndocument includes them all.
SearchVector objects can be combined together, allowing you to reuse them.\nFor example:
>>> Entry.objects.annotate(\n... search=SearchVector('body_text') + SearchVector('blog__tagline'),\n... ).filter(search='Cheese')\n[<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>]\nSee Changing the search configuration and\nWeighting queries for an explanation of the config\nand weight parameters.
SearchQueryLink to this heading#SearchQuery translates the terms the user provides into a search query\nobject that the database compares to a search vector. By default, all the words\nthe user provides are passed through the stemming algorithms, and then it\nlooks for matches for all of the resulting terms.
If search_type is 'plain', which is the default, the terms are treated\nas separate keywords. If search_type is 'phrase', the terms are treated\nas a single phrase. If search_type is 'raw', then you can provide a\nformatted search query with terms and operators. Read PostgreSQL’s Full Text\nSearch docs to learn about differences and syntax. Examples:
>>> from django.contrib.postgres.search import SearchQuery\n>>> SearchQuery('red tomato') # two keywords\n>>> SearchQuery('tomato red') # same results as above\n>>> SearchQuery('red tomato', search_type='phrase') # a phrase\n>>> SearchQuery('tomato red', search_type='phrase') # a different phrase\n>>> SearchQuery("'tomato' & ('red' | 'green')", search_type='raw') # boolean operators\nSearchQuery terms can be combined logically to provide more flexibility:
>>> from django.contrib.postgres.search import SearchQuery\n>>> SearchQuery('meat') & SearchQuery('cheese') # AND\n>>> SearchQuery('meat') | SearchQuery('cheese') # OR\n>>> ~SearchQuery('meat') # NOT\nSee Changing the search configuration for an explanation of the\nconfig parameter.
SearchRankLink to this heading#So far, we’ve returned the results for which any match between the vector and\nthe query are possible. It’s likely you may wish to order the results by some\nsort of relevancy. PostgreSQL provides a ranking function which takes into\naccount how often the query terms appear in the document, how close together\nthe terms are in the document, and how important the part of the document is\nwhere they occur. The better the match, the higher the value of the rank. To\norder by relevancy:
\n>>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector\n>>> vector = SearchVector('body_text')\n>>> query = SearchQuery('cheese')\n>>> Entry.objects.annotate(rank=SearchRank(vector, query)).order_by('-rank')\n[<Entry: Cheese on Toast recipes>, <Entry: Pizza recipes>]\nSee Weighting queries for an explanation of the\nweights parameter.
You can specify the config attribute to a SearchVector and\nSearchQuery to use a different search configuration. This allows using\ndifferent language parsers and dictionaries as defined by the database:
>>> from django.contrib.postgres.search import SearchQuery, SearchVector\n>>> Entry.objects.annotate(\n... search=SearchVector('body_text', config='french'),\n... ).filter(search=SearchQuery('œuf', config='french'))\n[<Entry: Pain perdu>]\nThe value of config could also be stored in another column:
>>> from django.db.models import F\n>>> Entry.objects.annotate(\n... search=SearchVector('body_text', config=F('blog__language')),\n... ).filter(search=SearchQuery('œuf', config=F('blog__language')))\n[<Entry: Pain perdu>]\nEvery field may not have the same relevance in a query, so you can set weights\nof various vectors before you combine them:
\n>>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector\n>>> vector = SearchVector('body_text', weight='A') + SearchVector('blog__tagline', weight='B')\n>>> query = SearchQuery('cheese')\n>>> Entry.objects.annotate(rank=SearchRank(vector, query)).filter(rank__gte=0.3).order_by('rank')\nThe weight should be one of the following letters: D, C, B, A. By default,\nthese weights refer to the numbers 0.1, 0.2, 0.4, and 1.0,\nrespectively. If you wish to weight them differently, pass a list of four\nfloats to SearchRank as weights in the same order above:
>>> rank = SearchRank(vector, query, weights=[0.2, 0.4, 0.6, 0.8])\n>>> Entry.objects.annotate(rank=rank).filter(rank__gte=0.3).order_by('-rank')\nSpecial database configuration isn’t necessary to use any of these functions,\nhowever, if you’re searching more than a few hundred records, you’re likely to\nrun into performance problems. Full text search is a more intensive process\nthan comparing the size of an integer, for example.
\nIn the event that all the fields you’re querying on are contained within one\nparticular model, you can create a functional index which matches the search\nvector you wish to use. The PostgreSQL documentation has details on\ncreating indexes for full text search.
\nSearchVectorFieldLink to this heading#If this approach becomes too slow, you can add a SearchVectorField to your\nmodel. You’ll need to keep it populated with triggers, for example, as\ndescribed in the PostgreSQL documentation. You can then query the field as\nif it were an annotated SearchVector:
>>> Entry.objects.update(search_vector=SearchVector('body_text'))\n>>> Entry.objects.filter(search_vector='cheese')\n[<Entry: Cheese on Toast recipes>, <Entry: Pizza recipes>]\nAnother approach to searching is trigram similarity. A trigram is a group of\nthree consecutive characters. In addition to the trigram_similar\nlookup, you can use a couple of other expressions.
To use them, you need to activate the pg_trgm extension on PostgreSQL. You can\ninstall it using the\nTrigramExtension migration\noperation.
TrigramSimilarityLink to this heading#Accepts a field name or expression, and a string or expression. Returns the\ntrigram similarity between the two arguments.
\nUsage example:
\n>>> from django.contrib.postgres.search import TrigramSimilarity\n>>> Author.objects.create(name='Katy Stevens')\n>>> Author.objects.create(name='Stephen Keats')\n>>> test = 'Katie Stephens'\n>>> Author.objects.annotate(\n... similarity=TrigramSimilarity('name', test),\n... ).filter(similarity__gt=0.3).order_by('-similarity')\n[<Author: Katy Stevens>, <Author: Stephen Keats>]\nTrigramDistanceLink to this heading#Accepts a field name or expression, and a string or expression. Returns the\ntrigram distance between the two arguments.
\nUsage example:
\n>>> from django.contrib.postgres.search import TrigramDistance\n>>> Author.objects.create(name='Katy Stevens')\n>>> Author.objects.create(name='Stephen Keats')\n>>> test = 'Katie Stephens'\n>>> Author.objects.annotate(\n... distance=TrigramDistance('name', test),\n... ).filter(distance__lte=0.7).order_by('distance')\n[<Author: Katy Stevens>, <Author: Stephen Keats>]\n