35219bb · typeable/bloodhound

git.iko.soy/typeable/bloodhound

on master help sign in

Improve docs

35219bbMichael Xavier11 years ago

README.md+20−16

compare with master

unifiedsplit

@@ -57,6 +57,7 @@ Index Operations

58:set -XDeriveGeneric

59:{

60+import Control.Applicative

60import Database.Bloodhound

61import Database.Bloodhound

61import Data.Aeson

62import Data.Aeson

62import Data.Either (Either(..))

63import Data.Either (Either(..))

@@ -72,14 +73,17 @@ import qualified Network.HTTP.Types.Status as NHTS

72let testServer = (Server "http://localhost:9200")

73let testServer = (Server "http://localhost:9200")

73let testIndex = IndexName "twitter"

74let testIndex = IndexName "twitter"

74let testMapping = MappingName "tweet"

75let testMapping = MappingName "tweet"

76+let withBH' = withBH defaultManagerSettings testServer

76-- defaultIndexSettings is exported by Database.Bloodhound as well

78-- defaultIndexSettings is exported by Database.Bloodhound as well

77let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)

79let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)

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.

81-- response :: Reply, Reply is a synonym for Network.HTTP.Conduit.Response

85-- response :: Reply, Reply is a synonym for Network.HTTP.Conduit.Response

82−response <- createIndex testServer defaultIndexSettings testIndex

86+response <- withBH' $ createIndex defaultIndexSettings testIndex

83:}

87:}

85```

89```

@@ -91,7 +95,7 @@ response <- createIndex testServer defaultIndexSettings testIndex

91``` {.haskell}

95``` {.haskell}

93-- response :: Reply

97-- response :: Reply

94−response <- deleteIndex testServer testIndex

98+response <- withBH' $ deleteIndex testIndex

96```

100```

101

@@ -125,7 +129,7 @@ Response {responseStatus = Status {statusCode = 404, statusMessage = "Not Found"

125

129

126``` {.haskell}

130``` {.haskell}

127

131

128−resp <- refreshIndex testServer testIndex

132+resp <- withBH' $ refreshIndex testIndex

129

133

130```

134```

131

135

@@ -168,7 +172,7 @@ instance ToJSON TweetMapping where

168 object ["type" .= ("geo_point" :: Text)]]]]

172 object ["type" .= ("geo_point" :: Text)]]]]

169:}

173:}

170

174

171−resp <- putMapping testServer testIndex testMapping TweetMapping

175+resp <- withBH' $ putMapping testIndex testMapping TweetMapping

172

176

173```

177```

174

178

@@ -176,7 +180,7 @@ resp <- putMapping testServer testIndex testMapping TweetMapping

176

180

177``` {.haskell}

181``` {.haskell}

178

182

179−resp <- deleteMapping testServer testIndex testMapping

183+resp <- withBH' $ deleteMapping testIndex testMapping

180

184

181```

185```

182

186

@@ -221,7 +225,7 @@ instance FromJSON Location

221-- λ> encode $ Location 10.0 10.0

225-- λ> encode $ Location 10.0 10.0

222-- "{\"lat\":10,\"lon\":10}"

226-- "{\"lat\":10,\"lon\":10}"

223

227

224−resp <- indexDocument testServer testIndex testMapping exampleTweet (DocId "1")

228+resp <- withBH' $ indexDocument testIndex testMapping exampleTweet (DocId "1")

225

229

226```

230```

227

231

@@ -243,7 +247,7 @@ Response {responseStatus =

243

247

244``` {.haskell}

248``` {.haskell}

245

249

246−resp <- deleteDocument testServer testIndex testMapping (DocId "1")

250+resp <- withBH' $ deleteDocument testIndex testMapping (DocId "1")

247

251

248```

252```

249

253

@@ -253,7 +257,7 @@ resp <- deleteDocument testServer testIndex testMapping (DocId "1")

253

257

254-- n.b., you'll need the earlier imports. responseBody is from http-conduit

258-- n.b., you'll need the earlier imports. responseBody is from http-conduit

255

259

256−resp <- getDocument testServer testIndex testMapping (DocId "1")

260+resp <- withBH' $ getDocument testIndex testMapping (DocId "1")

257

261

258-- responseBody :: Response body -> body

262-- responseBody :: Response body -> body

259let body = responseBody resp

263let body = responseBody resp

@@ -328,8 +332,8 @@ let sndOp = BulkIndex testIndex

328let stream = [firstDoc, secondDoc]

332let stream = [firstDoc, secondDoc]

329

333

330-- Fire off the actual bulk request

334-- Fire off the actual bulk request

331−-- bulk :: Server -> [BulkOperation] -> IO Reply

335+-- bulk :: Vector BulkOperation -> IO Reply

332−resp <- bulk testServer stream

336+resp <- withBH' $ bulk stream

333:}

337:}

334

338

335```

339```

@@ -363,8 +367,8 @@ let firstDocEncoded = encode firstDoc :: L.ByteString

363let encodedOperations = encodeBulkOperations stream

367let encodedOperations = encodeBulkOperations stream

364

368

365-- to insert into a particular server

369-- to insert into a particular server

366−-- bulk :: Server -> V.Vector BulkOperation -> IO Reply

370+-- bulk :: V.Vector BulkOperation -> IO Reply

367−_ <- bulk testServer stream

371+_ <- withBH' $ bulk stream

368

372

369```

373```

370

374

@@ -393,7 +397,7 @@ let filter = IdentityFilter <&&> IdentityFilter

393let search = mkSearch (Just query) (Just filter)

397let search = mkSearch (Just query) (Just filter)

394

398

395-- you can also searchByType and specify the mapping name.

399-- you can also searchByType and specify the mapping name.

396−reply <- searchByIndex testServer testIndex search

400+reply <- withBH' $ searchByIndex testIndex search

397

401

398let result = eitherDecode (responseBody reply) :: Either String (SearchResult Tweet)

402let result = eitherDecode (responseBody reply) :: Either String (SearchResult Tweet)

399

403

@@ -534,7 +538,7 @@ let queryFilter = IdentityFilter <&&> IdentityFilter

534

538

535let search = mkSearch Nothing (Just queryFilter)

539let search = mkSearch Nothing (Just queryFilter)

536

540

537−reply <- searchByType testServer testIndex testMapping search

541+reply <- withBH' $ searchByType testIndex testMapping search

538

542

539```

543```

540

544

@@ -748,7 +752,7 @@ Aggregations are part of the reply structure of every search, in the form of

748-- Lift decode and response body to be in the IO monad.

752-- Lift decode and response body to be in the IO monad.

749let decode' = liftM decode

753let decode' = liftM decode

750let responseBody' = liftM responseBody

754let responseBody' = liftM responseBody

751−let reply = searchByIndex testServer testIndex search

755+let reply = withBH' $ searchByIndex testIndex search

752let response = decode' $ responseBody' reply :: IO (Maybe (SearchResult Tweet))

756let response = decode' $ responseBody' reply :: IO (Maybe (SearchResult Tweet))

753

757

754-- Now that we have our response, we can extract our terms aggregation result -- which is a list of buckets.

758-- 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

77-- >>> import Database.Bloodhound

78-- >>> import Test.DocTest.Prop (assert)

79-- >>> let testServer = (Server "http://localhost:9200")

80−-- >>> let runBH = withBH defaultManagerSettings testServer

80+-- >>> let runBH' = withBH defaultManagerSettings testServer

81-- >>> let testIndex = IndexName "twitter"

82-- >>> let testMapping = MappingName "tweet"

83-- >>> let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)

84-- >>> data TweetMapping = TweetMapping deriving (Eq, Show)

85−-- >>> _ <- runBH $ deleteIndex testIndex >> deleteMapping testIndex testMapping

85+-- >>> _ <- runBH' $ deleteIndex testIndex >> deleteMapping testIndex testMapping

86-- >>> import GHC.Generics

87-- >>> import Data.Time.Calendar (Day (..))

88-- >>> import Data.Time.Clock (UTCTime (..), secondsToDiffTime)

@@ -192,7 +192,7 @@ post = dispatch NHTM.methodPost

192

193-- | 'getStatus' fetches the 'Status' of a 'Server'

194--

195−-- >>> serverStatus <- runBH getStatus

195+-- >>> serverStatus <- runBH' getStatus

196-- >>> fmap status (serverStatus)

197-- Just 200

198getStatus :: MonadBH m => m (Maybe Status)

@@ -205,10 +205,10 @@ getStatus = do

205

206-- | 'createIndex' will create an index given a 'Server', 'IndexSettings', and an 'IndexName'.

207--

208−-- >>> response <- runBH $ createIndex defaultIndexSettings (IndexName "didimakeanindex")

208+-- >>> response <- runBH' $ createIndex defaultIndexSettings (IndexName "didimakeanindex")

209-- >>> respIsTwoHunna response

210-- True

211−-- >>> runBH $ indexExists (IndexName "didimakeanindex")

211+-- >>> runBH' $ indexExists (IndexName "didimakeanindex")

212-- True

213createIndex :: MonadBH m => IndexSettings -> IndexName -> m Reply

214createIndex indexSettings (IndexName indexName) =

@@ -218,11 +218,11 @@ createIndex indexSettings (IndexName indexName) =

218

219-- | 'deleteIndex' will delete an index given a 'Server', and an 'IndexName'.

220--

221−-- >>> _ <- runBH $ createIndex defaultIndexSettings (IndexName "didimakeanindex")

221+-- >>> _ <- runBH' $ createIndex defaultIndexSettings (IndexName "didimakeanindex")

222−-- >>> response <- runBH $ deleteIndex (IndexName "didimakeanindex")

222+-- >>> response <- runBH' $ deleteIndex (IndexName "didimakeanindex")

223-- >>> respIsTwoHunna response

224-- True

225−-- >>> runBH $ indexExists testIndex

225+-- >>> runBH' $ indexExists testIndex

226-- False

227deleteIndex :: MonadBH m => IndexName -> m Reply

228deleteIndex (IndexName indexName) =

@@ -242,7 +242,7 @@ existentialQuery url = do

242-- | 'indexExists' enables you to check if an index exists. Returns 'Bool'

243-- in IO

244--

245−-- >>> exists <- runBH $ indexExists testIndex

245+-- >>> exists <- runBH' $ indexExists testIndex

246indexExists :: MonadBH m => IndexName -> m Bool

247indexExists (IndexName indexName) = do

248 (_, exists) <- existentialQuery =<< joinPath [indexName]

@@ -251,8 +251,8 @@ indexExists (IndexName indexName) = do

251-- | 'refreshIndex' will force a refresh on an index. You must

252-- do this if you want to read what you wrote.

253--

254−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex

254+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex

255−-- >>> _ <- runBH $ refreshIndex testIndex

255+-- >>> _ <- runBH' $ refreshIndex testIndex

256refreshIndex :: MonadBH m => IndexName -> m Reply

257refreshIndex (IndexName indexName) =

258 bindM2 post url (return Nothing)

@@ -272,22 +272,22 @@ openOrCloseIndexes oci (IndexName indexName) =

272-- | 'openIndex' opens an index given a 'Server' and an 'IndexName'. Explained in further detail at

273-- <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html>

274--

275−-- >>> reply <- runBH $ openIndex testIndex

275+-- >>> reply <- runBH' $ openIndex testIndex

276openIndex :: MonadBH m => IndexName -> m Reply

277openIndex = openOrCloseIndexes OpenIndex

278

279-- | 'closeIndex' closes an index given a 'Server' and an 'IndexName'. Explained in further detail at

280-- <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html>

281--

282−-- >>> reply <- runBH $ closeIndex testIndex

282+-- >>> reply <- runBH' $ closeIndex testIndex

283closeIndex :: MonadBH m => IndexName -> m Reply

284closeIndex = openOrCloseIndexes CloseIndex

285

286-- | 'putMapping' is an HTTP PUT and has upsert semantics. Mappings are schemas

287-- for documents in indexes.

288--

289−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex

289+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex

290−-- >>> resp <- runBH $ putMapping testIndex testMapping TweetMapping

290+-- >>> resp <- runBH' $ putMapping testIndex testMapping TweetMapping

291-- >>> print resp

292-- 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}

293putMapping :: (MonadBH m, ToJSON a) => IndexName

@@ -300,9 +300,9 @@ putMapping (IndexName indexName) (MappingName mappingName) mapping =

300-- | 'deleteMapping' is an HTTP DELETE and deletes a mapping for a given index.

301-- Mappings are schemas for documents in indexes.

302--

303−-- >>> _ <- runBH $ createIndex defaultIndexSettings testIndex

303+-- >>> _ <- runBH' $ createIndex defaultIndexSettings testIndex

304−-- >>> _ <- runBH $ putMapping testIndex testMapping TweetMapping

304+-- >>> _ <- runBH' $ putMapping testIndex testMapping TweetMapping

305−-- >>> resp <- runBH $ deleteMapping testIndex testMapping

305+-- >>> resp <- runBH' $ deleteMapping testIndex testMapping

306-- >>> print resp

307-- 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}

308deleteMapping :: MonadBH m => IndexName -> MappingName -> m Reply

@@ -315,7 +315,7 @@ deleteMapping (IndexName indexName)

315-- convert into a JSON 'Value'. The 'DocId' will function as the

316-- primary key for the document.

317--

318−-- >>> resp <- runBH $ indexDocument testIndex testMapping exampleTweet (DocId "1")

318+-- >>> resp <- runBH' $ indexDocument testIndex testMapping exampleTweet (DocId "1")

319-- >>> print resp

320-- 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}

321indexDocument :: (ToJSON doc, MonadBH m) => IndexName -> MappingName

@@ -328,7 +328,7 @@ indexDocument (IndexName indexName)

328

329-- | 'deleteDocument' is the primary way to delete a single document.

330--

331−-- >>> _ <- runBH $ deleteDocument testIndex testMapping (DocId "1")

331+-- >>> _ <- runBH' $ deleteDocument testIndex testMapping (DocId "1")

332deleteDocument :: MonadBH m => IndexName -> MappingName

333 -> DocId -> m Reply

334deleteDocument (IndexName indexName)

@@ -343,8 +343,8 @@ deleteDocument (IndexName indexName)

343-- server to be performed. I changed from [BulkOperation] to a Vector due to memory overhead.

344--

345-- >>> let stream = V.fromList [BulkIndex testIndex testMapping (DocId "2") (toJSON (BulkTest "blah"))]

346−-- >>> _ <- runBH $ bulk stream

346+-- >>> _ <- runBH' $ bulk stream

347−-- >>> _ <- runBH $ refreshIndex testIndex

347+-- >>> _ <- runBH' $ refreshIndex testIndex

348bulk :: MonadBH m => V.Vector BulkOperation -> m Reply

349bulk bulkOps = bindM2 post url (return body)

350 where url = joinPath ["_bulk"]

@@ -408,7 +408,7 @@ encodeBulkOperation (BulkUpdate (IndexName indexName)

408-- Elasticsearch using a 'Server', 'IndexName', 'MappingName', and a 'DocId'.

409-- The 'DocId' is the primary key for your Elasticsearch document.

410--

411−-- >>> yourDoc <- runBH $ getDocument testIndex testMapping (DocId "1")

411+-- >>> yourDoc <- runBH' $ getDocument testIndex testMapping (DocId "1")

412getDocument :: MonadBH m => IndexName -> MappingName

413 -> DocId -> m Reply

414getDocument (IndexName indexName)

@@ -418,7 +418,7 @@ getDocument (IndexName indexName)

418-- | 'documentExists' enables you to check if a document exists. Returns 'Bool'

419-- in IO

420--

421−-- >>> exists <- runBH $ documentExists testIndex testMapping (DocId "1")

421+-- >>> exists <- runBH' $ documentExists testIndex testMapping (DocId "1")

422documentExists :: MonadBH m => IndexName -> MappingName

423 -> DocId -> m Bool

424documentExists (IndexName indexName)

@@ -435,7 +435,7 @@ dispatchSearch url search = post url (Just (encode search))

435--

436-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing

437-- >>> let search = mkSearch (Just query) Nothing

438−-- >>> reply <- runBH $ searchAll search

438+-- >>> reply <- runBH' $ searchAll search

439searchAll :: MonadBH m => Search -> m Reply

440searchAll = bindM2 dispatchSearch url . return

441 where url = joinPath ["_search"]

@@ -445,7 +445,7 @@ searchAll = bindM2 dispatchSearch url . return

445--

446-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing

447-- >>> let search = mkSearch (Just query) Nothing

448−-- >>> reply <- runBH $ searchByIndex testIndex search

448+-- >>> reply <- runBH' $ searchByIndex testIndex search

449searchByIndex :: MonadBH m => IndexName -> Search -> m Reply

450searchByIndex (IndexName indexName) = bindM2 dispatchSearch url . return

451 where url = joinPath [indexName, "_search"]

@@ -455,7 +455,7 @@ searchByIndex (IndexName indexName) = bindM2 dispatchSearch url . return

455--

456-- >>> let query = TermQuery (Term "user" "bitemyapp") Nothing

457-- >>> let search = mkSearch (Just query) Nothing

458−-- >>> reply <- runBH $ searchByType testIndex testMapping search

458+-- >>> reply <- runBH' $ searchByType testIndex testMapping search

459searchByType :: MonadBH m => IndexName -> MappingName -> Search

460 -> m Reply

461searchByType (IndexName indexName)

src/Database/Bloodhound/Types.hs+7−2

@@ -60,6 +60,9 @@ module Database.Bloodhound.Types

60 , Search(..)

61 , SearchResult(..)

62 , SearchHits(..)

63+ , TrackSortScores

64+ , From

65+ , Size

63 , ShardResult(..)

66 , ShardResult(..)

64 , Hit(..)

67 , Hit(..)

65 , Filter(..)

68 , Filter(..)

@@ -147,6 +150,8 @@ module Database.Bloodhound.Types

147 , IgnoreTermFrequency(..)

150 , IgnoreTermFrequency(..)

148 , MaxQueryTerms(..)

151 , MaxQueryTerms(..)

149 , ScoreType(..)

152 , ScoreType(..)

153+ , Score

154+ , Cache

150 , TypeName(..)

155 , TypeName(..)

151 , BoostTerms(..)

156 , BoostTerms(..)

152 , MaxWordLength(..)

157 , MaxWordLength(..)

@@ -203,7 +208,7 @@ module Database.Bloodhound.Types

203 ) where

208 ) where

204

209

205import Control.Applicative

210import Control.Applicative

206−import Control.Monad.Error

211+import Control.Monad.Except

207import Control.Monad.Reader

212import Control.Monad.Reader

208import Control.Monad.State

213import Control.Monad.State

209import Control.Monad.Writer

214import Control.Monad.Writer

@@ -257,7 +262,7 @@ newtype BH m a = BH {

257 , MonadIO

262 , MonadIO

258 , MonadState s

263 , MonadState s

259 , MonadWriter w

264 , MonadWriter w

260− , MonadError e

265+ , MonadErrorw e

261 , Alternative

266 , Alternative

262 , MonadPlus

267 , MonadPlus

263 , MonadFix)

268 , MonadFix)