git.iko.soy/typeable/bloodhound
on master help sign in
Improve docs

This exports some type aliases that were previously not being exported and thus weren't linked. This also updates the code samples in the README to reflect the current interface.

commit35219bb9eee7f4b0067b7ab3f8dc3a02df795e3a authorMichael Xavier <michael@michaelxavier.net> dateMon 11 May 2015, 17:30 (11 years ago) parenta59f9a9
3 files changed+54−45
README.md+20−16 src/Database/Bloodhound/Client.hs+27−27 src/Database/Bloodhound/Types.hs+7−2
README.md+20−16
@@ -57,6 +57,7 @@ Index Operations
5757
5858:set -XDeriveGeneric
5959:{
60+import Control.Applicative
6061import Database.Bloodhound
6162import Data.Aeson
6263import Data.Either (Either(..))
@@ -72,14 +73,17 @@ import qualified Network.HTTP.Types.Status as NHTS
7273let testServer = (Server "http://localhost:9200")
7374let testIndex = IndexName "twitter"
7475let testMapping = MappingName "tweet"
76+let withBH' = withBH defaultManagerSettings testServer
7577
7678-- defaultIndexSettings is exported by Database.Bloodhound as well
7779let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)
7880
79−-- createIndex returns IO Reply
81+-- createIndex returns MonadBH m => m Reply. You can use withBH for
82+ one-off commands or you can use runBH to group together commands
83+ and to pass in your own HTTP manager for pipelining.
8084
8185-- response :: Reply, Reply is a synonym for Network.HTTP.Conduit.Response
82−response <- createIndex testServer defaultIndexSettings testIndex
86+response <- withBH' $ createIndex defaultIndexSettings testIndex
8387:}
8488
8589```
@@ -91,7 +95,7 @@ response <- createIndex testServer defaultIndexSettings testIndex
9195``` {.haskell}
9296
9397-- response :: Reply
94−response <- deleteIndex testServer testIndex
98+response <- withBH' $ deleteIndex testIndex
9599
96100```
97101
@@ -125,7 +129,7 @@ Response {responseStatus = Status {statusCode = 404, statusMessage = "Not Found"
125129
126130``` {.haskell}
127131
128−resp <- refreshIndex testServer testIndex
132+resp <- withBH' $ refreshIndex testIndex
129133
130134```
131135
@@ -168,7 +172,7 @@ instance ToJSON TweetMapping where
168172 object ["type" .= ("geo_point" :: Text)]]]]
169173:}
170174
171−resp <- putMapping testServer testIndex testMapping TweetMapping
175+resp <- withBH' $ putMapping testIndex testMapping TweetMapping
172176
173177```
174178
@@ -176,7 +180,7 @@ resp <- putMapping testServer testIndex testMapping TweetMapping
176180
177181``` {.haskell}
178182
179−resp <- deleteMapping testServer testIndex testMapping
183+resp <- withBH' $ deleteMapping testIndex testMapping
180184
181185```
182186
@@ -221,7 +225,7 @@ instance FromJSON Location
221225-- λ> encode $ Location 10.0 10.0
222226-- "{\"lat\":10,\"lon\":10}"
223227
224−resp <- indexDocument testServer testIndex testMapping exampleTweet (DocId "1")
228+resp <- withBH' $ indexDocument testIndex testMapping exampleTweet (DocId "1")
225229
226230```
227231
@@ -243,7 +247,7 @@ Response {responseStatus =
243247
244248``` {.haskell}
245249
246−resp <- deleteDocument testServer testIndex testMapping (DocId "1")
250+resp <- withBH' $ deleteDocument testIndex testMapping (DocId "1")
247251
248252```
249253
@@ -253,7 +257,7 @@ resp <- deleteDocument testServer testIndex testMapping (DocId "1")
253257
254258-- n.b., you'll need the earlier imports. responseBody is from http-conduit
255259
256−resp <- getDocument testServer testIndex testMapping (DocId "1")
260+resp <- withBH' $ getDocument testIndex testMapping (DocId "1")
257261
258262-- responseBody :: Response body -> body
259263let body = responseBody resp
@@ -328,8 +332,8 @@ let sndOp = BulkIndex testIndex
328332let stream = [firstDoc, secondDoc]
329333
330334-- Fire off the actual bulk request
331−-- bulk :: Server -> [BulkOperation] -> IO Reply
332−resp <- bulk testServer stream
335+-- bulk :: Vector BulkOperation -> IO Reply
336+resp <- withBH' $ bulk stream
333337:}
334338
335339```
@@ -363,8 +367,8 @@ let firstDocEncoded = encode firstDoc :: L.ByteString
363367let encodedOperations = encodeBulkOperations stream
364368
365369-- to insert into a particular server
366−-- bulk :: Server -> V.Vector BulkOperation -> IO Reply
367−_ <- bulk testServer stream
370+-- bulk :: V.Vector BulkOperation -> IO Reply
371+_ <- withBH' $ bulk stream
368372
369373```
370374
@@ -393,7 +397,7 @@ let filter = IdentityFilter <&&> IdentityFilter
393397let search = mkSearch (Just query) (Just filter)
394398
395399-- you can also searchByType and specify the mapping name.
396−reply <- searchByIndex testServer testIndex search
400+reply <- withBH' $ searchByIndex testIndex search
397401
398402let result = eitherDecode (responseBody reply) :: Either String (SearchResult Tweet)
399403
@@ -534,7 +538,7 @@ let queryFilter = IdentityFilter <&&> IdentityFilter
534538
535539let search = mkSearch Nothing (Just queryFilter)
536540
537−reply <- searchByType testServer testIndex testMapping search
541+reply <- withBH' $ searchByType testIndex testMapping search
538542
539543```
540544
@@ -748,7 +752,7 @@ Aggregations are part of the reply structure of every search, in the form of
748752-- Lift decode and response body to be in the IO monad.
749753let decode' = liftM decode
750754let responseBody' = liftM responseBody
751−let reply = searchByIndex testServer testIndex search
755+let reply = withBH' $ searchByIndex testIndex search
752756let response = decode' $ responseBody' reply :: IO (Maybe (SearchResult Tweet))
753757
754758-- Now that we have our response, we can extract our terms aggregation result -- which is a list of buckets.
src/Database/Bloodhound/Client.hs+27−27
@@ -77,12 +77,12 @@ import Database.Bloodhound.Types
7777-- >>> import Database.Bloodhound
7878-- >>> import Test.DocTest.Prop (assert)
7979-- >>> let testServer = (Server "http://localhost:9200")
80−-- >>> let runBH = withBH defaultManagerSettings testServer
80+-- >>> let runBH' = withBH defaultManagerSettings testServer
8181-- >>> let testIndex = IndexName "twitter"
8282-- >>> let testMapping = MappingName "tweet"
8383-- >>> let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)
8484-- >>> data TweetMapping = TweetMapping deriving (Eq, Show)
85−-- >>> _ <- runBH $ deleteIndex testIndex >> deleteMapping testIndex testMapping
85+-- >>> _ <- runBH' $ deleteIndex testIndex >> deleteMapping testIndex testMapping
8686-- >>> import GHC.Generics
8787-- >>> import Data.Time.Calendar (Day (..))
8888-- >>> import Data.Time.Clock (UTCTime (..), secondsToDiffTime)
@@ -192,7 +192,7 @@ post = dispatch NHTM.methodPost
192192
193193-- | 'getStatus' fetches the 'Status' of a 'Server'
194194--
195−-- >>> serverStatus <- runBH getStatus
195+-- >>> serverStatus <- runBH' getStatus
196196-- >>> fmap status (serverStatus)
197197-- Just 200
198198getStatus :: MonadBH m => m (Maybe Status)
@@ -205,10 +205,10 @@ getStatus = do
205205
206206-- | 'createIndex' will create an index given a 'Server', 'IndexSettings', and an 'IndexName'.
207207--
208−-- >>> response <- runBH $ createIndex defaultIndexSettings (IndexName "didimakeanindex")
208+-- >>> response <- runBH' $ createIndex defaultIndexSettings (IndexName "didimakeanindex")
209209-- >>> respIsTwoHunna response
210210-- True
211−-- >>> runBH $ indexExists (IndexName "didimakeanindex")
211+-- >>> runBH' $ indexExists (IndexName "didimakeanindex")
212212-- True
213213createIndex :: MonadBH m => IndexSettings -> IndexName -> m Reply
214214createIndex indexSettings (IndexName indexName) =
@@ -218,11 +218,11 @@ createIndex indexSettings (IndexName indexName) =
218218
219219-- | 'deleteIndex' will delete an index given a 'Server', and an 'IndexName'.
220220--
221−-- >>> _ <- runBH $ createIndex defaultIndexSettings (IndexName "didimakeanindex")
222−-- >>> response <- runBH $ deleteIndex (IndexName "didimakeanindex")
221+-- >>> _ <- runBH' $ createIndex defaultIndexSettings (IndexName "didimakeanindex")
222+-- >>> response <- runBH' $ deleteIndex (IndexName "didimakeanindex")
223223-- >>> respIsTwoHunna response
224224-- True
225−-- >>> runBH $ indexExists testIndex
225+-- >>> runBH' $ indexExists testIndex
226226-- False
227227deleteIndex :: MonadBH m => IndexName -> m Reply
228228deleteIndex (IndexName indexName) =
@@ -242,7 +242,7 @@ existentialQuery url = do
242242-- | 'indexExists' enables you to check if an index exists. Returns 'Bool'
243243-- in IO
244244--
245−-- >>> exists <- runBH $ indexExists testIndex
245+-- >>> exists <- runBH' $ indexExists testIndex
246246indexExists :: MonadBH m => IndexName -> m Bool
247247indexExists (IndexName indexName) = do
248248 (_, exists) <- existentialQuery =<< joinPath [indexName]
@@ -251,8 +251,8 @@ indexExists (IndexName indexName) = do
251251-- | 'refreshIndex' will force a refresh on an index. You must
252252-- do this if you want to read what you wrote.
253253--
254−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex
255−-- >>> _ <- runBH $ refreshIndex testIndex
254+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex
255+-- >>> _ <- runBH' $ refreshIndex testIndex
256256refreshIndex :: MonadBH m => IndexName -> m Reply
257257refreshIndex (IndexName indexName) =
258258 bindM2 post url (return Nothing)
@@ -272,22 +272,22 @@ openOrCloseIndexes oci (IndexName indexName) =
272272-- | 'openIndex' opens an index given a 'Server' and an 'IndexName'. Explained in further detail at
273273-- <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html>
274274--
275−-- >>> reply <- runBH $ openIndex testIndex
275+-- >>> reply <- runBH' $ openIndex testIndex
276276openIndex :: MonadBH m => IndexName -> m Reply
277277openIndex = openOrCloseIndexes OpenIndex
278278
279279-- | 'closeIndex' closes an index given a 'Server' and an 'IndexName'. Explained in further detail at
280280-- <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html>
281281--
282−-- >>> reply <- runBH $ closeIndex testIndex
282+-- >>> reply <- runBH' $ closeIndex testIndex
283283closeIndex :: MonadBH m => IndexName -> m Reply
284284closeIndex = openOrCloseIndexes CloseIndex
285285
286286-- | 'putMapping' is an HTTP PUT and has upsert semantics. Mappings are schemas
287287-- for documents in indexes.
288288--
289−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex
290−-- >>> resp <- runBH $ putMapping testIndex testMapping TweetMapping
289+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex
290+-- >>> resp <- runBH' $ putMapping testIndex testMapping TweetMapping
291291-- >>> print resp
292292-- Response {responseStatus = Status {statusCode = 200, statusMessage = "OK"}, responseVersion = HTTP/1.1, responseHeaders = [("Content-Type","application/json; charset=UTF-8"),("Content-Length","21")], responseBody = "{\"acknowledged\":true}", responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose}
293293putMapping :: (MonadBH m, ToJSON a) => IndexName
@@ -300,9 +300,9 @@ putMapping (IndexName indexName) (MappingName mappingName) mapping =
300300-- | 'deleteMapping' is an HTTP DELETE and deletes a mapping for a given index.
301301-- Mappings are schemas for documents in indexes.
302302--
303−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex
304−-- >>> _ <- runBH $ putMapping testIndex testMapping TweetMapping
305−-- >>> resp <- runBH $ deleteMapping testIndex testMapping
303+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex
304+-- >>> _ <- runBH' $ putMapping testIndex testMapping TweetMapping
305+-- >>> resp <- runBH' $ deleteMapping testIndex testMapping
306306-- >>> print resp
307307-- Response {responseStatus = Status {statusCode = 200, statusMessage = "OK"}, responseVersion = HTTP/1.1, responseHeaders = [("Content-Type","application/json; charset=UTF-8"),("Content-Length","21")], responseBody = "{\"acknowledged\":true}", responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose}
308308deleteMapping :: MonadBH m => IndexName -> MappingName -> m Reply
@@ -315,7 +315,7 @@ deleteMapping (IndexName indexName)
315315-- convert into a JSON 'Value'. The 'DocId' will function as the
316316-- primary key for the document.
317317--
318−-- >>> resp <- runBH $ indexDocument testIndex testMapping exampleTweet (DocId "1")
318+-- >>> resp <- runBH' $ indexDocument testIndex testMapping exampleTweet (DocId "1")
319319-- >>> print resp
320320-- Response {responseStatus = Status {statusCode = 201, statusMessage = "Created"}, responseVersion = HTTP/1.1, responseHeaders = [("Content-Type","application/json; charset=UTF-8"),("Content-Length","74")], responseBody = "{\"_index\":\"twitter\",\"_type\":\"tweet\",\"_id\":\"1\",\"_version\":1,\"created\":true}", responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose}
321321indexDocument :: (ToJSON doc, MonadBH m) => IndexName -> MappingName
@@ -328,7 +328,7 @@ indexDocument (IndexName indexName)
328328
329329-- | 'deleteDocument' is the primary way to delete a single document.
330330--
331−-- >>> _ <- runBH $ deleteDocument testIndex testMapping (DocId "1")
331+-- >>> _ <- runBH' $ deleteDocument testIndex testMapping (DocId "1")
332332deleteDocument :: MonadBH m => IndexName -> MappingName
333333 -> DocId -> m Reply
334334deleteDocument (IndexName indexName)
@@ -343,8 +343,8 @@ deleteDocument (IndexName indexName)
343343-- server to be performed. I changed from [BulkOperation] to a Vector due to memory overhead.
344344--
345345-- >>> let stream = V.fromList [BulkIndex testIndex testMapping (DocId "2") (toJSON (BulkTest "blah"))]
346−-- >>> _ <- runBH $ bulk stream
347−-- >>> _ <- runBH $ refreshIndex testIndex
346+-- >>> _ <- runBH' $ bulk stream
347+-- >>> _ <- runBH' $ refreshIndex testIndex
348348bulk :: MonadBH m => V.Vector BulkOperation -> m Reply
349349bulk bulkOps = bindM2 post url (return body)
350350 where url = joinPath ["_bulk"]
@@ -408,7 +408,7 @@ encodeBulkOperation (BulkUpdate (IndexName indexName)
408408-- Elasticsearch using a 'Server', 'IndexName', 'MappingName', and a 'DocId'.
409409-- The 'DocId' is the primary key for your Elasticsearch document.
410410--
411−-- >>> yourDoc <- runBH $ getDocument testIndex testMapping (DocId "1")
411+-- >>> yourDoc <- runBH' $ getDocument testIndex testMapping (DocId "1")
412412getDocument :: MonadBH m => IndexName -> MappingName
413413 -> DocId -> m Reply
414414getDocument (IndexName indexName)
@@ -418,7 +418,7 @@ getDocument (IndexName indexName)
418418-- | 'documentExists' enables you to check if a document exists. Returns 'Bool'
419419-- in IO
420420--
421−-- >>> exists <- runBH $ documentExists testIndex testMapping (DocId "1")
421+-- >>> exists <- runBH' $ documentExists testIndex testMapping (DocId "1")
422422documentExists :: MonadBH m => IndexName -> MappingName
423423 -> DocId -> m Bool
424424documentExists (IndexName indexName)
@@ -435,7 +435,7 @@ dispatchSearch url search = post url (Just (encode search))
435435--
436436-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing
437437-- >>> let search = mkSearch (Just query) Nothing
438−-- >>> reply <- runBH $ searchAll search
438+-- >>> reply <- runBH' $ searchAll search
439439searchAll :: MonadBH m => Search -> m Reply
440440searchAll = bindM2 dispatchSearch url . return
441441 where url = joinPath ["_search"]
@@ -445,7 +445,7 @@ searchAll = bindM2 dispatchSearch url . return
445445--
446446-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing
447447-- >>> let search = mkSearch (Just query) Nothing
448−-- >>> reply <- runBH $ searchByIndex testIndex search
448+-- >>> reply <- runBH' $ searchByIndex testIndex search
449449searchByIndex :: MonadBH m => IndexName -> Search -> m Reply
450450searchByIndex (IndexName indexName) = bindM2 dispatchSearch url . return
451451 where url = joinPath [indexName, "_search"]
@@ -455,7 +455,7 @@ searchByIndex (IndexName indexName) = bindM2 dispatchSearch url . return
455455--
456456-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing
457457-- >>> let search = mkSearch (Just query) Nothing
458−-- >>> reply <- runBH $ searchByType testIndex testMapping search
458+-- >>> reply <- runBH' $ searchByType testIndex testMapping search
459459searchByType :: MonadBH m => IndexName -> MappingName -> Search
460460 -> m Reply
461461searchByType (IndexName indexName)
src/Database/Bloodhound/Types.hs+7−2
@@ -60,6 +60,9 @@ module Database.Bloodhound.Types
6060 , Search(..)
6161 , SearchResult(..)
6262 , SearchHits(..)
63+ , TrackSortScores
64+ , From
65+ , Size
6366 , ShardResult(..)
6467 , Hit(..)
6568 , Filter(..)
@@ -147,6 +150,8 @@ module Database.Bloodhound.Types
147150 , IgnoreTermFrequency(..)
148151 , MaxQueryTerms(..)
149152 , ScoreType(..)
153+ , Score
154+ , Cache
150155 , TypeName(..)
151156 , BoostTerms(..)
152157 , MaxWordLength(..)
@@ -203,7 +208,7 @@ module Database.Bloodhound.Types
203208 ) where
204209
205210import Control.Applicative
206−import Control.Monad.Error
211+import Control.Monad.Except
207212import Control.Monad.Reader
208213import Control.Monad.State
209214import Control.Monad.Writer
@@ -257,7 +262,7 @@ newtype BH m a = BH {
257262 , MonadIO
258263 , MonadState s
259264 , MonadWriter w
260− , MonadError e
265+ , MonadErrorw e
261266 , Alternative
262267 , MonadPlus
263268 , MonadFix)