@@ -1,3 +1,13 @@
1+{-|
2+Module: Squeal.PostgreSQL.Expression.TextSearch
3+Description: Text search expressions
4+Copyright: (c) Eitan Chatav, 2019
5+Maintainer: eitan@morphism.tech
6+Stability: experimental
7+
8+Text Search Functions and Operators
9+-}
10+
111{-# LANGUAGE
212 DataKinds
313 , OverloadedStrings
@@ -32,75 +42,116 @@ import Squeal.PostgreSQL.Expression
3242import Squeal.PostgreSQL.List
3343import Squeal.PostgreSQL.Schema
3444
45+-- | `Squeal.PostgreSQL.Expression.Type.tsvector` matches tsquery ?
3546(@@) :: Operator (null 'PGtsvector) (null 'PGtsquery) ('Null 'PGbool)
3647(@@) = unsafeBinaryOp "@@"
3748
49+-- | AND `Squeal.PostgreSQL.Expression.Type.tsquery`s together
3850(.&) :: Operator (null 'PGtsquery) (null 'PGtsquery) (null 'PGtsquery)
3951(.&) = unsafeBinaryOp "&&"
4052
53+-- | OR `Squeal.PostgreSQL.Expression.Type.tsquery`s together
4154(.|) :: Operator (null 'PGtsquery) (null 'PGtsquery) (null 'PGtsquery)
4255(.|) = unsafeBinaryOp "||"
4356
57+-- | negate a `Squeal.PostgreSQL.Expression.Type.tsquery`
4458(.!) :: null 'PGtsquery :--> null 'PGtsquery
4559(.!) = unsafeUnaryOpL "!!"
4660
61+-- | `Squeal.PostgreSQL.Expression.Type.tsquery` followed by
62+-- `Squeal.PostgreSQL.Expression.Type.tsquery`
4763(<->) :: Operator (null 'PGtsquery) (null 'PGtsquery) (null 'PGtsquery)
4864(<->) = unsafeBinaryOp "<->"
4965
66+-- | convert array of lexemes to `Squeal.PostgreSQL.Expression.Type.tsvector`
5067arrayToTSvector
5168 :: null ('PGvararray ('NotNull 'PGtext))
5269 :--> null 'PGtsvector
5370arrayToTSvector = unsafeFunction "array_to_tsvector"
5471
72+-- | number of lexemes in `Squeal.PostgreSQL.Expression.Type.tsvector`
5573tsvectorLength :: null 'PGtsvector :--> null 'PGint4
5674tsvectorLength = unsafeFunction "length"
5775
76+-- | number of lexemes plus operators in `Squeal.PostgreSQL.Expression.Type.tsquery`
5877numnode :: null 'PGtsquery :--> null 'PGint4
5978numnode = unsafeFunction "numnode"
6079
80+-- | produce `Squeal.PostgreSQL.Expression.Type.tsquery` ignoring punctuation
6181plainToTSquery :: null 'PGtext :--> null 'PGtsquery
6282plainToTSquery = unsafeFunction "plainto_tsquery"
6383
84+-- | produce `Squeal.PostgreSQL.Expression.Type.tsquery` that searches for a phrase,
85+-- ignoring punctuation
6486phraseToTSquery :: null 'PGtext :--> null 'PGtsquery
6587phraseToTSquery = unsafeFunction "phraseto_tsquery"
6688
89+-- | produce `Squeal.PostgreSQL.Expression.Type.tsquery` from a web search style query
6790websearchToTSquery :: null 'PGtext :--> null 'PGtsquery
6891websearchToTSquery = unsafeFunction "websearch_to_tsquery"
6992
93+-- | get indexable part of a `Squeal.PostgreSQL.Expression.Type.tsquery`
7094queryTree :: null 'PGtsquery :--> null 'PGtext
7195queryTree = unsafeFunction "query_tree"
7296
97+-- | normalize words and convert to `Squeal.PostgreSQL.Expression.Type.tsquery`
7398toTSquery :: null 'PGtext :--> null 'PGtsquery
7499toTSquery = unsafeFunction "to_tsquery"
75100
101+-- | reduce document text to `Squeal.PostgreSQL.Expression.Type.tsvector`
76102toTSvector
77103 :: ty `In` '[ 'PGtext, 'PGjson, 'PGjsonb]
78104 => null ty :--> null 'PGtsvector
79105toTSvector = unsafeFunction "to_tsvector"
80106
107+-- | assign weight to each element of `Squeal.PostgreSQL.Expression.Type.tsvector`
81108setWeight
82109 :: FunctionN '[null 'PGtsvector, null ('PGchar 1)] (null 'PGtsvector)
83110setWeight = unsafeFunctionN "set_weight"
84111
112+-- | remove positions and weights from `Squeal.PostgreSQL.Expression.Type.tsvector`
85113strip :: null 'PGtsvector :--> null 'PGtsvector
86114strip = unsafeFunction "strip"
87115
116+-- | @jsonToTSvector (document *: filter)@
117+-- reduce each value in the document, specified by filter to a `Squeal.PostgreSQL.Expression.Type.tsvector`,
118+-- and then concatenate those in document order to produce a single `Squeal.PostgreSQL.Expression.Type.tsvector`.
119+-- filter is a `Squeal.PostgreSQL.Expression.Type.json` array, that enumerates what kind of elements
120+-- need to be included into the resulting `Squeal.PostgreSQL.Expression.Type.tsvector`.
121+-- Possible values for filter are "string" (to include all string values),
122+-- "numeric" (to include all numeric values in the string format),
123+-- "boolean" (to include all Boolean values in the string format "true"/"false"),
124+-- "key" (to include all keys) or "all" (to include all above).
125+-- These values can be combined together to include, e.g. all string and numeric values.
88126jsonToTSvector :: FunctionN '[null 'PGjson, null 'PGjson] (null 'PGtsvector)
89127jsonToTSvector = unsafeFunctionN "json_to_tsvector"
90128
129+-- | @jsonbToTSvector (document *: filter)@
130+-- reduce each value in the document, specified by filter to a `Squeal.PostgreSQL.Expression.Type.tsvector`,
131+-- and then concatenate those in document order to produce a single `Squeal.PostgreSQL.Expression.Type.tsvector`.
132+-- filter is a `Squeal.PostgreSQL.Expression.Type.jsonb` array, that enumerates what kind of elements
133+-- need to be included into the resulting `Squeal.PostgreSQL.Expression.Type.tsvector`.
134+-- Possible values for filter are "string" (to include all string values),
135+-- "numeric" (to include all numeric values in the string format),
136+-- "boolean" (to include all Boolean values in the string format "true"/"false"),
137+-- "key" (to include all keys) or "all" (to include all above).
138+-- These values can be combined together to include, e.g. all string and numeric values.
91139jsonbToTSvector :: FunctionN '[null 'PGjsonb, null 'PGjsonb] (null 'PGtsvector)
92140jsonbToTSvector = unsafeFunctionN "jsonb_to_tsvector"
93141
142+-- | remove given lexeme from `Squeal.PostgreSQL.Expression.Type.tsvector`
94143tsDelete :: FunctionN
95144 '[null 'PGtsvector, null ('PGvararray ('NotNull 'PGtext))]
96145 (null 'PGtsvector)
97146tsDelete = unsafeFunctionN "ts_delete"
98147
148+-- | select only elements with given weights from `Squeal.PostgreSQL.Expression.Type.tsvector`
99149tsFilter :: FunctionN
100150 '[null 'PGtsvector, null ('PGvararray ('NotNull ('PGchar 1)))]
101151 (null 'PGtsvector)
102152tsFilter = unsafeFunctionN "ts_filter"
103153
154+-- | display a `Squeal.PostgreSQL.Expression.Type.tsquery` match
104155tsHeadline
105156 :: document `In` '[ 'PGtext, 'PGjson, 'PGjsonb]
106157 => FunctionN '[null document, null 'PGtsquery] (null 'PGtext)