e5a9884 · typeable/bloodhound

git.iko.soy/typeable/bloodhound

on master help sign in

began expansion of docs

e5a9884Chris Allen12 years ago

Database/Bloodhound/Client.hs+1−1

compare with master

unifiedsplit

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

82-- http://hackage.haskell.org/package/http-client-lens-0.1.0/docs/Network-HTTP-Client-Lens.html

83-- https://github.com/supki/libjenkins/blob/master/src/Jenkins/Rest/Internal.hs

85−getStatus :: Server -> IO (Maybe (Status Version))

85+getStatus :: Server -> IO (Maybe Status)

86getStatus (Server server) = do

87 request <- parseUrl $ joinPath [server]

88 response <- withManager $ httpLbs request

Database/Bloodhound/Types.hs+88−9

@@ -1,5 +1,12 @@

1{-# LANGUAGE DeriveGeneric #-}

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

3module Database.Bloodhound.Types

10module Database.Bloodhound.Types

4 ( defaultCache

11 ( defaultCache

5 , defaultIndexSettings

12 , defaultIndexSettings

@@ -131,31 +138,48 @@ import GHC.Generics (Generic)

131import Network.HTTP.Conduit

138import Network.HTTP.Conduit

132import qualified Network.HTTP.Types.Method as NHTM

139import qualified Network.HTTP.Types.Method as NHTM

133

140

141+

142+{-| 'Version' is embedded in 'Status' -}

134data Version = Version { number :: Text

143data Version = Version { number :: Text

135 , build_hash :: Text

144 , build_hash :: Text

136 , build_timestamp :: UTCTime

145 , build_timestamp :: UTCTime

137 , build_snapshot :: Bool

146 , 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+-}

139

154

140−data Status a = Status { ok :: Bool

155+data Status = Status { ok :: Bool

141− , status :: Int

156+ , status :: Int

142− , name :: Text

157+ , name :: Text

143− , version :: a

158+ , version :: Version

144− , tagline :: Text } deriving (Eq, Show)

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

145

166

146data IndexSettings =

167data IndexSettings =

147 IndexSettings { indexShards :: ShardCount

168 IndexSettings { indexShards :: ShardCount

148 , indexReplicas :: ReplicaCount } deriving (Eq, Show)

169 , indexReplicas :: ReplicaCount } deriving (Eq, Show)

149

170

171+{-| 'defaultIndexSettings' is an 'IndexSettings' with 3 shards and 2 replicas. -}

150defaultIndexSettings :: IndexSettings

172defaultIndexSettings :: IndexSettings

151defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)

173defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)

152

174

153−data Strategy = RoundRobinStrat | RandomStrat | HeadStrat deriving (Eq, Show)

175+{-| 'Reply' and 'Method' are type synonyms from 'Network.HTTP.Types.Method' -}

154−

155−

156type Reply = Network.HTTP.Conduit.Response L.ByteString

176type Reply = Network.HTTP.Conduit.Response L.ByteString

157type Method = NHTM.Method

177type Method = NHTM.Method

158

178

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

159data OpenCloseIndex = OpenIndex | CloseIndex deriving (Eq, Show)

183data OpenCloseIndex = OpenIndex | CloseIndex deriving (Eq, Show)

160

184

161data FieldType = GeoPointType

185data FieldType = GeoPointType

@@ -173,15 +197,24 @@ data MappingField =

173 MappingField { mappingFieldName :: FieldName

197 MappingField { mappingFieldName :: FieldName

174 , fieldDefinition :: FieldDefinition } deriving (Eq, Show)

198 , fieldDefinition :: FieldDefinition } deriving (Eq, Show)

175

199

200+{-| Support for type reification of 'Mapping's is currently incomplete, for now the mapping API verbiage expects a 'ToJSON'able blob. -}

176data Mapping = Mapping { typeName :: TypeName

201data Mapping = Mapping { typeName :: TypeName

177 , mappingFields :: [MappingField] } deriving (Eq, Show)

202 , mappingFields :: [MappingField] } deriving (Eq, Show)

178

203

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

179data BulkOperation =

210data BulkOperation =

180 BulkIndex IndexName MappingName DocId Value

211 BulkIndex IndexName MappingName DocId Value

181 | BulkCreate IndexName MappingName DocId Value

212 | BulkCreate IndexName MappingName DocId Value

182 | BulkDelete IndexName MappingName DocId

213 | BulkDelete IndexName MappingName DocId

183 | BulkUpdate IndexName MappingName DocId Value deriving (Eq, Show)

214 | BulkUpdate IndexName MappingName DocId Value deriving (Eq, Show)

184

215

216+{-| 'EsResult' describes the standard wrapper JSON document that you see in successful Elasticsearch responses.

217+-}

185data EsResult a = EsResult { _index :: Text

218data EsResult a = EsResult { _index :: Text

186 , _type :: Text

219 , _type :: Text

187 , _id :: Text

220 , _id :: Text

@@ -189,11 +222,22 @@ data EsResult a = EsResult { _index :: Text

189 , found :: Maybe Bool

222 , found :: Maybe Bool

190 , _source :: a } deriving (Eq, Show)

223 , _source :: a } deriving (Eq, Show)

191

224

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

192type Sort = [SortSpec]

227type Sort = [SortSpec]

193

228

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

194data SortSpec = DefaultSortSpec DefaultSort

233data SortSpec = DefaultSortSpec DefaultSort

195 | GeoDistanceSortSpec SortOrder GeoPoint DistanceUnit deriving (Eq, Show)

234 | GeoDistanceSortSpec SortOrder GeoPoint DistanceUnit deriving (Eq, Show)

196

235

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

197data DefaultSort =

241data DefaultSort =

198 DefaultSort { sortFieldName :: FieldName

242 DefaultSort { sortFieldName :: FieldName

199 , sortOrder :: SortOrder

243 , sortOrder :: SortOrder

@@ -203,37 +247,72 @@ data DefaultSort =

203 , missingSort :: Maybe Missing

247 , missingSort :: Maybe Missing

204 , nestedFilter :: Maybe Filter } deriving (Eq, Show)

248 , nestedFilter :: Maybe Filter } deriving (Eq, Show)

205

249

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

206data SortOrder = Ascending

254data SortOrder = Ascending

207 | Descending deriving (Eq, Show)

255 | Descending deriving (Eq, Show)

208

256

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

209data Missing = LastMissing

261data Missing = LastMissing

210 | FirstMissing

262 | FirstMissing

211 | CustomMissing Text deriving (Eq, Show)

263 | CustomMissing Text deriving (Eq, Show)

212

264

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

213data SortMode = SortMin

269data SortMode = SortMin

214 | SortMax

270 | SortMax

215 | SortSum

271 | SortSum

216 | SortAvg deriving (Eq, Show)

272 | SortAvg deriving (Eq, Show)

217

273

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

218mkSort :: FieldName -> SortOrder -> DefaultSort

276mkSort :: FieldName -> SortOrder -> DefaultSort

219mkSort fieldName sOrder = DefaultSort fieldName sOrder False Nothing Nothing Nothing

277mkSort fieldName sOrder = DefaultSort fieldName sOrder False Nothing Nothing Nothing

220

278

279+{-| 'Cache' is for telling ES whether it should cache a 'Filter' not.

280+ 'Query's cannot be cached.

281+-}

221type Cache = Bool -- caching on/off

282type Cache = Bool -- caching on/off

222defaultCache :: Cache

283defaultCache :: Cache

223defaultCache = False

284defaultCache = False

224

285

286+{-| 'PrefixValue' is used in 'PrefixQuery' as the main query component. -}

225type PrefixValue = Text

287type PrefixValue = Text

226

288

289+{-| 'BooleanOperator' is the usual And/Or operators with an ES compatible

290+ JSON encoding baked in. Used all over the place.

291+-}

227data BooleanOperator = And | Or deriving (Eq, Show)

292data BooleanOperator = And | Or deriving (Eq, Show)

228

293

294+{-| 'ShardCount' is part of 'IndexSettings' -}

229newtype ShardCount = ShardCount Int deriving (Eq, Show, Generic)

295newtype ShardCount = ShardCount Int deriving (Eq, Show, Generic)

296+{-| 'ReplicaCount' is part of 'IndexSettings' -}

230newtype ReplicaCount = ReplicaCount Int deriving (Eq, Show, Generic)

297newtype ReplicaCount = ReplicaCount Int deriving (Eq, Show, Generic)

298+{-| 'Server' is used with the client functions to point at the ES instance -}

231newtype Server = Server String deriving (Eq, Show)

299newtype Server = Server String deriving (Eq, Show)

300+{-| 'IndexName' is used to describe which index to query/create/delete -}

232newtype IndexName = IndexName String deriving (Eq, Generic, Show)

301newtype 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. -}

233newtype MappingName = MappingName String deriving (Eq, Generic, Show)

304newtype 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. -}

234newtype DocId = DocId String deriving (Eq, Generic, Show)

308newtype DocId = DocId String deriving (Eq, Generic, Show)

309+{-| 'QueryString' is used to wrap query text bodies, be they human written or not. -}

235newtype QueryString = QueryString Text deriving (Eq, Show)

310newtype 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. -}

236newtype FieldName = FieldName Text deriving (Eq, Show)

313newtype FieldName = FieldName Text deriving (Eq, Show)

314+{-| 'CacheName' is used in 'RegexpQuery' and 'RegexpFilter' for describing the

315+ 'CacheKey' keyed caching behavior. -}

237newtype CacheName = CacheName Text deriving (Eq, Show)

316newtype CacheName = CacheName Text deriving (Eq, Show)

238newtype CacheKey = CacheKey Text deriving (Eq, Show)

317newtype CacheKey = CacheKey Text deriving (Eq, Show)

239newtype Existence = Existence Bool deriving (Eq, Show)

318newtype Existence = Existence Bool deriving (Eq, Show)

Database/Bloodhound/Types/Instances.hs+1−1

@@ -465,7 +465,7 @@ instance FromJSON MappingName

465instance FromJSON DocId

466

467

468−instance (FromJSON a) => FromJSON (Status a) where

468+instance FromJSON Status where

469 parseJSON (Object v) = Status <$>

470 v .: "ok" <*>

471 v .: "status" <*>