Full text search with rank ordering. Accepts a list of columns to search in. A list of columns can either be a text or tsvector type. If tsvectors are passed make sure to set stored: true.

Cleans the term, so it can be input directly by the user. The default preset of settings is optimal for most cases.

Full Text Searching (or just text search) provides the capability to identify natural-language documents that satisfy a query, and optionally to sort them by relevance to the query. The most common type of search is to find all documents containing given query terms and return them in order of their similarity to the query. Notions of query and similarity are very flexible and depend on the specific application. The simplest search considers query as a set of words and similarity as the frequency of query words in the document. Read more in PostgreSQL Full Text Search docs.

Options

• :prefix_search - whether to apply prefix search.
  • true (default) - the term is treated as a prefix
  • false - only counts full-word matches
• :stored - whether to use stored tsvector or not.
  • false (default) - columns (or expressions) passed as qualifiers are of type text
  • true - columns (or expressions) passed as qualifiers are tsvectors
• :language - language used for the search. Defaults to "english".
• :term_function - function used to convert the term to ts_query. Can be one of:
  • :websearch_to_tsquery (default) - converts term to a tsquery, normalizing words according to the specified or default configuration. Quoted word sequences are converted to phrase tests. The word “or” is understood as producing an OR operator, and a dash produces a NOT operator; other punctuation is ignored. This approximates the behavior of some common web search tools.
  • :plainto_tsquery - converts term to a tsquery, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches documents containing all non-stopwords in the term.
  • :phraseto_tsquery - converts term to a tsquery, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches phrases containing all non-stopwords in the text.
• :rank_function - function used to rank the results.
  • :ts_rank_cd (default) - computes a score showing how well the vector matches the query, using a cover density algorithm. See Ranking Search Results for more details.
  • :ts_rank - computes a score showing how well the vector matches the query.
• :rank_weights - a list of weights for each column. Defaults to [:A, :B, :C, :D]. The length of weights (if provided) should be the same as the length of the columns we search for. A single weight can be either a string or an atom. Possible values are:
  • :A - 1.0
  • :B - 0.4
  • :C - 0.2
  • :D - 0.1
• :rank_normalization - a string that specifies whether and how a document's length should impact its rank. The integer option controls several behaviors, so it is a bit mask: you can specify one or more behaviors using | (for example, 2|4).
  • 0 (default for ts_rank) - ignores the document length
  • 1 - divides the rank by 1 + the logarithm of the document length
  • 2 - divides the rank by the document length
  • 4 (default for ts_rank_cs) - divides the rank by the mean harmonic distance between extents (this is implemented only by ts_rank_cd)
  • 8 - divides the rank by the number of unique words in document
  • 16 - divides the rank by 1 + the logarithm of the number of unique words in document
  • 32 - divides the rank by itself + 1
• :order - describes the ordering of the results. Possible values are
  • :desc (default) - orders the results by similarity rank in descending order.
  • :asc - orders the results by similarity rank in ascending order.
  • :none - doesn't apply ordering at all.
• :filter_type - filter type
  • :or (default) - uses OR operator to combine different column matches. Selecting this option means that the search term won't match across columns.
  • :concat - joins the columns into a single tsvector and searches for the term in the concatenated string containing all columns.
  • :none - doesn't apply any filtering and returns all results.
• empty_return - whether to return all results when the search term is empty.
  • true (default) - returns all results when the search term is empty.
  • false - returns an empty list when the search term is empty.
• :coalesce - when joining columns via :concat option, adds a COALESCE function to handle NULL values. Choose true when you can't guarantee that all columns are non-null.
  • true (default)- adds COALESCE
  • false - doesn't add COALESCE function to the query. Choose this when you're using filter_type: :concat and can guarantee that all columns are non-null.

Example usage

iex> insert_post!(title: "Hogwarts Shocker", body: "A spell disrupts the Quidditch Cup.")
...> insert_post!(title: "Diagon Bombshell", body: "Secrets uncovered in the heart of Hogwarts.")
...> insert_post!(title: "Completely unrelated", body: "No magic here!")
...>  Post
...> |> Torus.full_text([p], [p.title, p.body], "uncov hogwar")
...> |> select([p], p.title)
...> |> Repo.all()
["Diagon Bombshell"]

Optimizations

• Store precomputed tsvector in a separate column, add a GIN index to it, and use stored: true.

• Add a GIN tsvector index on the column(s) you search in. Use Torus.QueryInspector.tap_sql/2 on your query (with all the options passed) to see the exact search string and add an index to it. For example for nullable title, the GIN index could look like:

  CREATE INDEX index_gin_posts_title
  ON posts USING GIN (to_tsvector('english', COALESCE(title, '')));