@@ -1,5 +1,12 @@
11{-# LANGUAGE DeriveGeneric #-}
22
3+{-| Data types for describing actions and data structures performed to interact with
4+ Elasticsearch. The two main buckets your queries against Elasticsearch will fall
5+ into are 'Query's and 'Filter's. 'Filter's are more like traditional database
6+ constraints and often have preferable performance properties. 'Query's support
7+ human-written textual queries, such as fuzzy queries.
8+-}
9+
310module Database.Bloodhound.Types
411 ( defaultCache
512 , defaultIndexSettings
@@ -131,31 +138,48 @@ import GHC.Generics (Generic)
131138import Network.HTTP.Conduit
132139import qualified Network.HTTP.Types.Method as NHTM
133140
141+
142+{-| 'Version' is embedded in 'Status' -}
134143data Version = Version { number :: Text
135144 , build_hash :: Text
136145 , build_timestamp :: UTCTime
137146 , build_snapshot :: Bool
138− , lucene_version :: Text } deriving (Show, Generic)
147+ , lucene_version :: Text } deriving (Eq, Show, Generic)
148+
149+{-| 'Status' is a data type for describing the JSON body returned by Elasticsearch when you
150+ query its status. This was deprecated in 1.2.0.
151+
152+ <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-status.html#indices-status>
153+-}
139154
140−data Status a = Status { ok :: Bool
141− , status :: Int
142− , name :: Text
143− , version :: a
144− , tagline :: Text } deriving (Eq, Show)
155+data Status = Status { ok :: Bool
156+ , status :: Int
157+ , name :: Text
158+ , version :: Version
159+ , tagline :: Text } deriving (Eq, Show)
160+
161+{-| 'IndexSettings' is used to configure the shards and replicas when you create
162+ an Elasticsearch Index.
163+
164+ <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-create-index.html>
165+-}
145166
146167data IndexSettings =
147168 IndexSettings { indexShards :: ShardCount
148169 , indexReplicas :: ReplicaCount } deriving (Eq, Show)
149170
171+{-| 'defaultIndexSettings' is an 'IndexSettings' with 3 shards and 2 replicas. -}
150172defaultIndexSettings :: IndexSettings
151173defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)
152174
153−data Strategy = RoundRobinStrat | RandomStrat | HeadStrat deriving (Eq, Show)
154−
155−
175+{-| 'Reply' and 'Method' are type synonyms from 'Network.HTTP.Types.Method' -}
156176type Reply = Network.HTTP.Conduit.Response L.ByteString
157177type Method = NHTM.Method
158178
179+{-| 'OpenCloseIndex' is a sum type for opening and closing indices.
180+
181+ <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html>
182+-}
159183data OpenCloseIndex = OpenIndex | CloseIndex deriving (Eq, Show)
160184
161185data FieldType = GeoPointType
@@ -173,15 +197,24 @@ data MappingField =
173197 MappingField { mappingFieldName :: FieldName
174198 , fieldDefinition :: FieldDefinition } deriving (Eq, Show)
175199
200+{-| Support for type reification of 'Mapping's is currently incomplete, for now the mapping API verbiage expects a 'ToJSON'able blob. -}
176201data Mapping = Mapping { typeName :: TypeName
177202 , mappingFields :: [MappingField] } deriving (Eq, Show)
178203
204+{-| 'BulkOperation' is a sum type for expressing the four kinds of bulk operation index,
205+ create, delete, and update. 'BulkIndex' behaves like an "upsert", 'BulkCreate' will fail
206+ if a document already exists at the DocId.
207+
208+ <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs-bulk.html#docs-bulk>
209+-}
179210data BulkOperation =
180211 BulkIndex IndexName MappingName DocId Value
181212 | BulkCreate IndexName MappingName DocId Value
182213 | BulkDelete IndexName MappingName DocId
183214 | BulkUpdate IndexName MappingName DocId Value deriving (Eq, Show)
184215
216+{-| 'EsResult' describes the standard wrapper JSON document that you see in successful Elasticsearch responses.
217+-}
185218data EsResult a = EsResult { _index :: Text
186219 , _type :: Text
187220 , _id :: Text
@@ -189,11 +222,22 @@ data EsResult a = EsResult { _index :: Text
189222 , found :: Maybe Bool
190223 , _source :: a } deriving (Eq, Show)
191224
225+{-| 'Sort' is a synonym for a list of 'SortSpec's. Sort behavior is order dependent with later sorts acting as tie-breakers for earlier sorts.
226+-}
192227type Sort = [SortSpec]
193228
229+{-| The two main kinds of 'SortSpec' are 'DefaultSortSpec' and 'GeoDistanceSortSpec'. The latter takes a 'SortOrder', 'GeoPoint', and 'DistanceUnit' to express "nearness" to a single geographical point as a sort specification.
230+
231+<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#search-request-sort>
232+-}
194233data SortSpec = DefaultSortSpec DefaultSort
195234 | GeoDistanceSortSpec SortOrder GeoPoint DistanceUnit deriving (Eq, Show)
196235
236+{-| 'DefaultSort' is usually the kind of 'SortSpec' you'll want. There's a 'mkSort' convenience
237+ function for when you want to specify only the most common parameters.
238+
239+<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#search-request-sort>
240+-}
197241data DefaultSort =
198242 DefaultSort { sortFieldName :: FieldName
199243 , sortOrder :: SortOrder
@@ -203,37 +247,72 @@ data DefaultSort =
203247 , missingSort :: Maybe Missing
204248 , nestedFilter :: Maybe Filter } deriving (Eq, Show)
205249
250+{-| 'SortOrder' is 'Ascending' or 'Descending', as you might expect. These get encoded into "asc" or "desc" when turned into JSON.
251+
252+<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#search-request-sort>
253+-}
206254data SortOrder = Ascending
207255 | Descending deriving (Eq, Show)
208256
257+{-| 'Missing' prescribes how to handle missing fields. A missing field can be sorted last, first, or using a custom value as a substitute.
258+
259+<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#_missing_values>
260+-}
209261data Missing = LastMissing
210262 | FirstMissing
211263 | CustomMissing Text deriving (Eq, Show)
212264
265+{-| 'SortMode' prescribes how to handle sorting array/multi-valued fields.
266+
267+http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#_sort_mode_option
268+-}
213269data SortMode = SortMin
214270 | SortMax
215271 | SortSum
216272 | SortAvg deriving (Eq, Show)
217273
274+{-| 'mkSort' defaults everything but the 'FieldName' and the 'SortOrder' so that you can concisely describe the usual kind of 'SortSpec's you want.
275+-}
218276mkSort :: FieldName -> SortOrder -> DefaultSort
219277mkSort fieldName sOrder = DefaultSort fieldName sOrder False Nothing Nothing Nothing
220278
279+{-| 'Cache' is for telling ES whether it should cache a 'Filter' not.
280+ 'Query's cannot be cached.
281+-}
221282type Cache = Bool -- caching on/off
222283defaultCache :: Cache
223284defaultCache = False
224285
286+{-| 'PrefixValue' is used in 'PrefixQuery' as the main query component. -}
225287type PrefixValue = Text
226288
289+{-| 'BooleanOperator' is the usual And/Or operators with an ES compatible
290+ JSON encoding baked in. Used all over the place.
291+-}
227292data BooleanOperator = And | Or deriving (Eq, Show)
228293
294+{-| 'ShardCount' is part of 'IndexSettings' -}
229295newtype ShardCount = ShardCount Int deriving (Eq, Show, Generic)
296+{-| 'ReplicaCount' is part of 'IndexSettings' -}
230297newtype ReplicaCount = ReplicaCount Int deriving (Eq, Show, Generic)
298+{-| 'Server' is used with the client functions to point at the ES instance -}
231299newtype Server = Server String deriving (Eq, Show)
300+{-| 'IndexName' is used to describe which index to query/create/delete -}
232301newtype IndexName = IndexName String deriving (Eq, Generic, Show)
302+{-| 'MappingName' is part of mappings which are how ES describes and schematizes
303+ the data in the indices. -}
233304newtype MappingName = MappingName String deriving (Eq, Generic, Show)
305+{-| 'DocId' is a generic wrapper value for expressing unique Document IDs. Can be set
306+ by the user or created by ES itself. Often used in client functions for poking
307+ at specific documents. -}
234308newtype DocId = DocId String deriving (Eq, Generic, Show)
309+{-| 'QueryString' is used to wrap query text bodies, be they human written or not. -}
235310newtype QueryString = QueryString Text deriving (Eq, Show)
311+{-| 'FieldName' is used all over the place wherever a specific field within a document
312+ needs to be specified, usually in 'Query's or 'Filter's. -}
236313newtype FieldName = FieldName Text deriving (Eq, Show)
314+{-| 'CacheName' is used in 'RegexpQuery' and 'RegexpFilter' for describing the
315+ 'CacheKey' keyed caching behavior. -}
237316newtype CacheName = CacheName Text deriving (Eq, Show)
238317newtype CacheKey = CacheKey Text deriving (Eq, Show)
239318newtype Existence = Existence Bool deriving (Eq, Show)