git.iko.soy/typeable/bloodhound
on 42b0e92 help sign in
typeable/bloodhound/README.md
976 lines 28 kB history raw
1Bloodhound [![TravisCI](https://travis-ci.org/bitemyapp/bloodhound.svg)](https://travis-ci.org/bitemyapp/bloodhound) [![Hackage](https://img.shields.io/hackage/v/bloodhound.svg?style=flat)](https://hackage.haskell.org/package/bloodhound)
2==========
4![Bloodhound (dog)](./bloodhound.jpg)
6Elasticsearch client and query DSL for Haskell
7==============================================
9Why?
10----
12Search doesn't have to be hard. Let the dog do it.
14Endorsements
15------------
17"Bloodhound makes Elasticsearch almost tolerable!" - Almost-gruntled user
19"ES is a nightmare but Bloodhound at least makes it tolerable." - Same user, later opinion.
21Version compatibility
22---------------------
24Elasticsearch \>= 1.0 is recommended. Bloodhound mostly works with 0.9.x, but I don't recommend it if you expect everything to work. As of Bloodhound 0.3 all \>=1.0 versions of Elasticsearch work.
26Current versions we test against are 1.0.3, 1.1.2, 1.2.3, 1.3.2, and 1.4.0. We also check that GHC 7.6 and 7.8 both build and pass tests. See our [TravisCI](https://travis-ci.org/bitemyapp/bloodhound) to learn more.
28Stability
29---------
31Bloodhound is stable for production use. I will strive to avoid breaking API compatibility from here on forward, but dramatic features like a type-safe, fully integrated mapping API may require breaking things in the future.
33Hackage page and Haddock documentation
34======================================
36<http://hackage.haskell.org/package/bloodhound>
38Elasticsearch Tutorial
39======================
41It's not using Bloodhound, but if you need an introduction to or overview of Elasticsearch and how to use it, you can use [this screencast](http://vimeo.com/106463167).
43Examples
44========
46Index Operations
47----------------
49### Create Index
51``` {.haskell}
53-- Formatted for use in ghci, so there are "let"s in front of the decls.
55-- if you see :{ and :}, they're so you can copy-paste
56-- the multi-line examples into your ghci REPL.
58:set -XDeriveGeneric
59:{
60import Control.Applicative
61import Database.Bloodhound
62import Data.Aeson
63import Data.Either (Either(..))
64import Data.Maybe (fromJust)
65import Data.Time.Calendar (Day(..))
66import Data.Time.Clock (secondsToDiffTime, UTCTime(..))
67import Data.Text (Text)
68import GHC.Generics (Generic)
69import Network.HTTP.Client
70import qualified Network.HTTP.Types.Status as NHTS
72-- no trailing slashes in servers, library handles building the path.
73let testServer = (Server "http://localhost:9200")
74let testIndex = IndexName "twitter"
75let testMapping = MappingName "tweet"
76let withBH' = withBH defaultManagerSettings testServer
78-- defaultIndexSettings is exported by Database.Bloodhound as well
79let defaultIndexSettings = IndexSettings (ShardCount 3) (ReplicaCount 2)
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.
85-- response :: Reply, Reply is a synonym for Network.HTTP.Conduit.Response
86response <- withBH' $ createIndex defaultIndexSettings testIndex
87:}
89```
91### Delete Index
93#### Code
95``` {.haskell}
97-- response :: Reply
98response <- withBH' $ deleteIndex testIndex
100```
102#### Example Response
104``` {.haskell}
106-- print response if it was a success
107Response {responseStatus = Status {statusCode = 200, statusMessage = "OK"}
108 , responseVersion = HTTP/1.1
109 , responseHeaders = [("Content-Type", "application/json; charset=UTF-8")
110 , ("Content-Length", "21")]
111 , responseBody = "{\"acknowledged\":true}"
112 , responseCookieJar = CJ {expose = []}
113 , responseClose' = ResponseClose}
115-- if the index to be deleted didn't exist anyway
116Response {responseStatus = Status {statusCode = 404, statusMessage = "Not Found"}
117 , responseVersion = HTTP/1.1
118 , responseHeaders = [("Content-Type", "application/json; charset=UTF-8")
119 , ("Content-Length","65")]
120 , responseBody = "{\"error\":\"IndexMissingException[[twitter] missing]\",\"status\":404}"
121 , responseCookieJar = CJ {expose = []}
122 , responseClose' = ResponseClose}
124```
126### Refresh Index
128#### Note, you **have** to do this if you expect to read what you just wrote
130``` {.haskell}
132resp <- withBH' $ refreshIndex testIndex
134```
136#### Example Response
138``` {.haskell}
140-- print resp on success
141Response {responseStatus = Status {statusCode = 200, statusMessage = "OK"}
142 , responseVersion = HTTP/1.1
143 , responseHeaders = [("Content-Type", "application/json; charset=UTF-8")
144 , ("Content-Length","50")]
145 , responseBody = "{\"_shards\":{\"total\":10,\"successful\":5,\"failed\":0}}"
146 , responseCookieJar = CJ {expose = []}
147 , responseClose' = ResponseClose}
149```
151Mapping Operations
152------------------
154### Create Mapping
156``` {.haskell}
158-- don't forget imports and the like at the top.
160data TweetMapping = TweetMapping deriving (Eq, Show)
162-- I know writing the JSON manually sucks.
163-- I don't have a proper data type for Mappings yet.
164-- Let me know if this is something you need.
166:{
167instance ToJSON TweetMapping where
168 toJSON TweetMapping =
169 object ["tweet" .=
170 object ["properties" .=
171 object ["location" .=
172 object ["type" .= ("geo_point" :: Text)]]]]
173:}
175resp <- withBH' $ putMapping testIndex testMapping TweetMapping
177```
179### Delete Mapping
181``` {.haskell}
183resp <- withBH' $ deleteMapping testIndex testMapping
185```
187Document Operations
188-------------------
190### Indexing Documents
192``` {.haskell}
194-- don't forget the imports and derive generic setting for ghci
195-- at the beginning of the examples.
197:{
198data Location = Location { lat :: Double
199 , lon :: Double } deriving (Eq, Generic, Show)
201data Tweet = Tweet { user :: Text
202 , postDate :: UTCTime
203 , message :: Text
204 , age :: Int
205 , location :: Location } deriving (Eq, Generic, Show)
207exampleTweet = Tweet { user = "bitemyapp"
208 , postDate = UTCTime
209 (ModifiedJulianDay 55000)
210 (secondsToDiffTime 10)
211 , message = "Use haskell!"
212 , age = 10000
213 , location = Location 40.12 (-71.34) }
215-- automagic (generic) derivation of instances because we're lazy.
216instance ToJSON Tweet
217instance FromJSON Tweet
218instance ToJSON Location
219instance FromJSON Location
220:}
222-- Should be able to toJSON and encode the data structures like this:
223-- λ> toJSON $ Location 10.0 10.0
224-- Object fromList [("lat",Number 10.0),("lon",Number 10.0)]
225-- λ> encode $ Location 10.0 10.0
226-- "{\"lat\":10,\"lon\":10}"
228resp <- withBH' $ indexDocument testIndex testMapping defaultIndexDocumentSettings exampleTweet (DocId "1")
230```
232#### Example Response
234``` {.haskell}
236Response {responseStatus =
237 Status {statusCode = 200, statusMessage = "OK"}
238 , responseVersion = HTTP/1.1, responseHeaders =
239 [("Content-Type","application/json; charset=UTF-8"),
240 ("Content-Length","75")]
241 , responseBody = "{\"_index\":\"twitter\",\"_type\":\"tweet\",\"_id\":\"1\",\"_version\":2,\"created\":false}"
242 , responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose}
244```
246### Deleting Documents
248``` {.haskell}
250resp <- withBH' $ deleteDocument testIndex testMapping (DocId "1")
252```
254### Getting Documents
256``` {.haskell}
258-- n.b., you'll need the earlier imports. responseBody is from http-conduit
260resp <- withBH' $ getDocument testIndex testMapping (DocId "1")
262-- responseBody :: Response body -> body
263let body = responseBody resp
265-- you have two options, you use decode and just get Maybe (EsResult Tweet)
266-- or you can use eitherDecode and get Either String (EsResult Tweet)
268let maybeResult = decode body :: Maybe (EsResult Tweet)
269-- the explicit typing is so Aeson knows how to parse the JSON.
271-- use either if you want to know why something failed to parse.
272-- (string errors, sadly)
273let eitherResult = eitherDecode body :: Either String (EsResult Tweet)
275-- print eitherResult should look like:
276Right (EsResult {_index = "twitter"
277 , _type = "tweet"
278 , _id = "1"
279 , _version = 2
280 , found = Just True
281 , _source = Tweet {user = "bitemyapp"
282 , postDate = 2009-06-18 00:00:10 UTC
283 , message = "Use haskell!"
284 , age = 10000
285 , location = Location {lat = 40.12, lon = -71.34}}})
287-- _source in EsResult is parametric, we dispatch the type by passing in what we expect (Tweet) as a parameter to EsResult.
289-- use the _source record accessor to get at your document
290fmap _source eitherResult
291Right (Tweet {user = "bitemyapp"
292 , postDate = 2009-06-18 00:00:10 UTC
293 , message = "Use haskell!"
294 , age = 10000
295 , location = Location {lat = 40.12, lon = -71.34}})
297```
299Bulk Operations
300---------------
302### Bulk create, index
304``` {.haskell}
306-- don't forget the imports and derive generic setting for ghci
307-- at the beginning of the examples.
309:{
310-- Using the earlier Tweet datatype and exampleTweet data
312-- just changing up the data a bit.
313let bulkTest = exampleTweet { user = "blah" }
314let bulkTestTwo = exampleTweet { message = "woohoo!" }
316-- create only bulk operation
317-- BulkCreate :: IndexName -> MappingName -> DocId -> Value -> BulkOperation
318let firstOp = BulkCreate testIndex
319 testMapping (DocId "3") (toJSON bulkTest)
321-- index operation "create or update"
322let sndOp = BulkIndex testIndex
323 testMapping (DocId "4") (toJSON bulkTestTwo)
325-- Some explanation, the final "Value" type that BulkIndex,
326-- BulkCreate, and BulkUpdate accept is the actual document
327-- data that your operation applies to. BulkDelete doesn't
328-- take a value because it's just deleting whatever DocId
329-- you pass.
331-- list of bulk operations
332let stream = [firstDoc, secondDoc]
334-- Fire off the actual bulk request
335-- bulk :: Vector BulkOperation -> IO Reply
336resp <- withBH' $ bulk stream
337:}
339```
341### Encoding individual bulk API operations
343``` {.haskell}
344-- the following functions are exported in Bloodhound so
345-- you can build up bulk operations yourself
346encodeBulkOperations :: V.Vector BulkOperation -> L.ByteString
347encodeBulkOperation :: BulkOperation -> L.ByteString
349-- How to use the above:
350data BulkTest = BulkTest { name :: Text } deriving (Eq, Generic, Show)
351instance FromJSON BulkTest
352instance ToJSON BulkTest
354_ <- insertData
355let firstTest = BulkTest "blah"
356let secondTest = BulkTest "bloo"
357let firstDoc = BulkIndex testIndex
358 testMapping (DocId "2") (toJSON firstTest)
359let secondDoc = BulkCreate testIndex
360 testMapping (DocId "3") (toJSON secondTest)
361let stream = V.fromList [firstDoc, secondDoc] :: V.Vector BulkOperation
363-- to encode yourself
364let firstDocEncoded = encode firstDoc :: L.ByteString
366-- to encode a vector of bulk operations
367let encodedOperations = encodeBulkOperations stream
369-- to insert into a particular server
370-- bulk :: V.Vector BulkOperation -> IO Reply
371_ <- withBH' $ bulk streamp
373```
375Search
376------
378### Querying
380#### Term Query
382``` {.haskell}
384-- exported by the Client module, just defaults some stuff.
385-- mkSearch :: Maybe Query -> Maybe Filter -> Search
386-- mkSearch query filter = Search query filter Nothing False (From 0) (Size 10) Nothing
388let query = TermQuery (Term "user" "bitemyapp") Nothing
390-- AND'ing identity filter with itself and then tacking it onto a query
391-- search should be a null-operation. I include it for the sake of example.
392-- <||> (or/plus) should make it into a search that returns everything.
394let filter = IdentityFilter <&&> IdentityFilter
396-- constructing the search object the searchByIndex function dispatches on.
397let search = mkSearch (Just query) (Just filter)
399-- you can also searchByType and specify the mapping name.
400reply <- withBH' $ searchByIndex testIndex search
402let result = eitherDecode (responseBody reply) :: Either String (SearchResult Tweet)
404λ> fmap (hits . searchHits) result
405Right [Hit {hitIndex = IndexName "twitter"
406 , hitType = MappingName "tweet"
407 , hitDocId = DocId "1"
408 , hitScore = 0.30685282
409 , hitSource = Tweet {user = "bitemyapp"
410 , postDate = 2009-06-18 00:00:10 UTC
411 , message = "Use haskell!"
412 , age = 10000
413 , location = Location {lat = 40.12, lon = -71.34}}}]
415```
417#### Match Query
419``` {.haskell}
421let query = QueryMatchQuery $ mkMatchQuery (FieldName "user") (QueryString "bitemyapp")
422let search = mkSearch (Just query) Nothing
424```
426#### Multi-Match Query
428``` {.haskell}
430let fields = [FieldName "user", FieldName "message"]
431let query = QueryMultiMatchQuery $ mkMultiMatchQuery fields (QueryString "bitemyapp")
432let search = mkSearch (Just query) Nothing
434```
436#### Bool Query
438``` {.haskell}
440let innerQuery = QueryMatchQuery $
441 mkMatchQuery (FieldName "user") (QueryString "bitemyapp")
442let query = QueryBoolQuery $
443 mkBoolQuery [innerQuery] [] []
444let search = mkSearch (Just query) Nothing
446```
448#### Boosting Query
450``` {.haskell}
452let posQuery = QueryMatchQuery $
453 mkMatchQuery (FieldName "user") (QueryString "bitemyapp")
454let negQuery = QueryMatchQuery $
455 mkMatchQuery (FieldName "user") (QueryString "notmyapp")
456let query = QueryBoostingQuery $
457 BoostingQuery posQuery negQuery (Boost 0.2)
459```
461#### Rest of the query/filter types
463Just follow the pattern you've seen here and check the Hackage API documentation.
465### Sorting
467``` {.haskell}
469let sortSpec = DefaultSortSpec $ mkSort (FieldName "age") Ascending
471-- mkSort is a shortcut function that takes a FieldName and a SortOrder
472-- to generate a vanilla DefaultSort.
473-- checkt the DefaultSort type for the full list of customizable options.
475-- From and size are integers for pagination.
477-- When sorting on a field, scores are not computed. By setting TrackSortScores to true, scores will still be computed and tracked.
479-- type Sort = [SortSpec]
480-- type TrackSortScores = Bool
481-- type From = Int
482-- type Size = Int
484-- Search takes Maybe Query
485-- -> Maybe Filter
486-- -> Maybe Sort
487-- -> TrackSortScores
488-- -> From -> Size
489-- -> Maybe [FieldName]
491-- just add more sortspecs to the list if you want tie-breakers.
492let search = Search Nothing (Just IdentityFilter) (Just [sortSpec]) False (From 0) (Size 10) Nothing
494```
496### Field selection
498If you only want certain fields from the source document returned, you can
499set the "fields" field of the Search record.
501``` {.haskell}
503let search' = mkSearch (Just (MatchAllQuery Nothing)) Nothing
504 search = search' { fields = Just [FieldName "updated"] }
506```
508### Filtering
510#### And, Not, and Or filters
512Filters form a monoid and seminearring.
514``` {.haskell}
516instance Monoid Filter where
517 mempty = IdentityFilter
518 mappend a b = AndFilter [a, b] defaultCache
520instance Seminearring Filter where
521 a <||> b = OrFilter [a, b] defaultCache
523-- AndFilter and OrFilter take [Filter] as an argument.
525-- This will return anything, because IdentityFilter returns everything
526OrFilter [IdentityFilter, someOtherFilter] False
528-- This will return exactly what someOtherFilter returns
529AndFilter [IdentityFilter, someOtherFilter] False
531-- Thanks to the seminearring and monoid, the above can be expressed as:
533-- "and"
534IdentityFilter <&&> someOtherFilter
536-- "or"
537IdentityFilter <||> someOtherFilter
539-- Also there is a NotFilter, it only accepts a single filter, not a list.
541NotFilter someOtherFilter False
543```
545#### Identity Filter
547``` {.haskell}
549-- And'ing two Identity
550let queryFilter = IdentityFilter <&&> IdentityFilter
552let search = mkSearch Nothing (Just queryFilter)
554reply <- withBH' $ searchByType testIndex testMapping search
556```
558#### Boolean Filter
560Similar to boolean queries.
562``` {.haskell}
564-- Will return only items whose "user" field contains the term "bitemyapp"
565let queryFilter = BoolFilter (MustMatch (Term "user" "bitemyapp") False)
567-- Will return only items whose "user" field does not contain the term "bitemyapp"
568let queryFilter = BoolFilter (MustNotMatch (Term "user" "bitemyapp") False)
570-- The clause (query) should appear in the matching document.
571-- In a boolean query with no must clauses, one or more should
572-- clauses must match a document. The minimum number of should
573-- clauses to match can be set using the minimum_should_match parameter.
574let queryFilter = BoolFilter (ShouldMatch [(Term "user" "bitemyapp")] False)
576```
578#### Exists Filter
580``` {.haskell}
582-- Will filter for documents that have the field "user"
583let existsFilter = ExistsFilter (FieldName "user")
585```
587#### Geo BoundingBox Filter
589``` {.haskell}
591-- topLeft and bottomRight
592let box = GeoBoundingBox (LatLon 40.73 (-74.1)) (LatLon 40.10 (-71.12))
594let constraint = GeoBoundingBoxConstraint (FieldName "tweet.location") box False GeoFilterMemory
596```
598#### Geo Distance Filter
600``` {.haskell}
602let geoPoint = GeoPoint (FieldName "tweet.location") (LatLon 40.12 (-71.34))
604-- coefficient and units
605let distance = Distance 10.0 Miles
607-- GeoFilterType or NoOptimizeBbox
608let optimizeBbox = OptimizeGeoFilterType GeoFilterMemory
610-- SloppyArc is the usual/default optimization in Elasticsearch today
611-- but pre-1.0 versions will need to pick Arc or Plane.
613let geoFilter = GeoDistanceFilter geoPoint distance SloppyArc optimizeBbox False
615```
617#### Geo Distance Range Filter
619Think of a donut and you won't be far off.
621``` {.haskell}
623let geoPoint = GeoPoint (FieldName "tweet.location") (LatLon 40.12 (-71.34))
625let distanceRange = DistanceRange (Distance 0.0 Miles) (Distance 10.0 Miles)
627let geoFilter = GeoDistanceRangeFilter geoPoint distanceRange
629```
631#### Geo Polygon Filter
633``` {.haskell}
635-- I think I drew a square here.
636let points = [LatLon 40.0 (-70.00),
637 LatLon 40.0 (-72.00),
638 LatLon 41.0 (-70.00),
639 LatLon 41.0 (-72.00)]
641let geoFilter = GeoPolygonFilter (FieldName "tweet.location") points
643```
645#### Document IDs filter
647``` {.haskell}
649-- takes a mapping name and a list of DocIds
650IdsFilter (MappingName "tweet") [DocId "1"]
652```
654#### Range Filter
656``` {.haskell}
658-- RangeFilter :: FieldName
659-- -> RangeValue
660-- -> RangeExecution
661-- -> Cache -> Filter
663let filter = RangeFilter (FieldName "age")
664 (RangeGtLt (GreaterThan 1000.0) (LessThan 100000.0))
665 RangeExecutionIndex False
667```
669``` {.haskell}
671let filter = RangeFilter (FieldName "age")
672 (RangeLte (LessThanEq 100000.0))
673 RangeExecutionIndex False
675```
677##### Date Ranges
679Date ranges are expressed in UTCTime. Date ranges use the same range bound constructors as numerics, except that they end in "D".
681Note that compatibility with ES is tested only down to seconds.
683``` {.haskell}
685let filter = RangeFilter (FieldName "postDate")
686 (RangeDateGtLte
687 (GreaterThanD (UTCTime
688 (ModifiedJulianDay 55000)
689 (secondsToDiffTime 9)))
690 (LessThanEqD (UTCTime
691 (ModifiedJulianDay 55000)
692 (secondsToDiffTime 11))))
693 RangeExecutionIndex False
694```
696#### Regexp Filter
698``` {.haskell}
700-- RegexpFilter
701-- :: FieldName
702-- -> Regexp
703-- -> RegexpFlags
704-- -> CacheName
705-- -> Cache
706-- -> CacheKey
707-- -> Filter
708let filter = RegexpFilter (FieldName "user") (Regexp "bite.*app")
709 AllRegexpFlags (CacheName "test") False (CacheKey "key")
711-- n.b.
712-- data RegexpFlags = AllRegexpFlags
713-- | NoRegexpFlags
714-- | SomeRegexpFlags (NonEmpty RegexpFlag) deriving (Eq, Show)
716-- data RegexpFlag = AnyString
717-- | Automaton
718-- | Complement
719-- | Empty
720-- | Intersection
721-- | Interval deriving (Eq, Show)
723```
725### Aggregations
727#### Adding aggregations to search
729Aggregations can now be added to search queries, or made on their own.
731``` {.haskell}
732type Aggregations = M.Map Text Aggregation
733data Aggregation
734 = TermsAgg TermsAggregation
735 | DateHistogramAgg DateHistogramAggregation
736```
738For convenience, \`\`\`mkAggregations\`\`\` exists, that will create an \`\`\`Aggregations\`\`\` with the aggregation provided.
740For example:
742``` {.haskell}
743 let a = mkAggregations "users" $ TermsAgg $ mkTermsAggregation "user"
744 let search = mkAggregateSearch Nothing a
745```
747Aggregations can be added to an existing search, using the \`\`\`aggBody\`\`\` field
749``` {.haskell}
750 let search = mkSearch (Just (MatchAllQuery Nothing)) Nothing
751 let search' = search {aggBody = Just a}
752```
754Since the \`\`\`Aggregations\`\`\` structure is just a Map Text Aggregation, M.insert can be used to add additional aggregations.
756``` {.haskell}
757 let a' = M.insert "age" (TermsAgg $ mkTermsAggregation "age") a
758```
760#### Extracting aggregations from results
762Aggregations are part of the reply structure of every search, in the form of
764``` {.haskell}
765-- Lift decode and response body to be in the IO monad.
766let decode' = liftM decode
767let responseBody' = liftM responseBody
768let reply = withBH' $ searchByIndex testIndex search
769let response = decode' $ responseBody' reply :: IO (Maybe (SearchResult Tweet))
771-- Now that we have our response, we can extract our terms aggregation result -- which is a list of buckets.
773let terms = do { response' <- response; return $ response' >>= aggregations >>= toTerms "users" }
774terms
775Just (Bucket {buckets = [TermsResult {termKey = "bitemyapp", termsDocCount = 1, termsAggs = Nothing}]})
776```
778Note that bucket aggregation results, such as the TermsResult is a member of the type class :
780``` {.haskell}
781class BucketAggregation a where
782 key :: a -> Text
783 docCount :: a -> Int
784 aggs :: a -> Maybe AggregationResults
785```
787haskell
789You can use the function to get any nested results, if there were any. For example, if there were a nested terms aggregation keyed to "age" in a TermsResult named , you would call
791#### Terms Aggregation
793``` {.haskell}
794data TermsAggregation
795 = TermsAggregation {term :: Either Text Text,
796 termInclude :: Maybe TermInclusion,
797 termExclude :: Maybe TermInclusion,
798 termOrder :: Maybe TermOrder,
799 termMinDocCount :: Maybe Int,
800 termSize :: Maybe Int,
801 termShardSize :: Maybe Int,
802 termCollectMode :: Maybe CollectionMode,
803 termExecutionHint :: Maybe ExecutionHint,
804 termAggs :: Maybe Aggregations}
805```
807Term Aggregations have two factory functions, , and , and can be used as follows:
809``` {.haskell}
810let ta = TermsAgg $ mkTermsAggregation "user"
811```
813There are of course other options that can be added to a Terms Aggregation, such as the collection mode:
815``` {.haskell}
816let ta = mkTermsAggregation "user"
817let ta' = ta { termCollectMode = Just BreadthFirst }
818let ta'' = TermsAgg ta'
819```
821For more documentation on how the Terms Aggregation works, see <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html>
823#### Date Histogram Aggregation
825``` {.haskell}
826data DateHistogramAggregation
827 = DateHistogramAggregation {dateField :: FieldName,
828 dateInterval :: Interval,
829 dateFormat :: Maybe Text,
830 datePreZone :: Maybe Text,
831 datePostZone :: Maybe Text,
832 datePreOffset :: Maybe Text,
833 datePostOffset :: Maybe Text,
834 dateAggs :: Maybe Aggregations}
835```
837haskell
839The Date Histogram Aggregation works much the same as the Terms Aggregation.
841Relevant functions include , and
843``` {.haskell}
844let dh = DateHistogramAgg (mkDateHistogram (FieldName "postDate") Minute)
845```
847Date histograms also accept a :
849``` {.haskell}
850FractionalInterval :: Float -> TimeInterval -> Interval
851-- TimeInterval is the following:
852data TimeInterval = Weeks | Days | Hours | Minutes | Seconds
853```
855It can be used as follows:
857``` {.haskell}
858let dh = DateHistogramAgg (mkDateHistogram (FieldName "postDate") (FractionalInterval 1.5 Minutes))
859```
861The is defined as:
863``` {.haskell}
864data DateHistogramResult
865 = DateHistogramResult {dateKey :: Int,
866 dateKeyStr :: Maybe Text,
867 dateDocCount :: Int,
868 dateHistogramAggs :: Maybe AggregationResults}
869```
871It is an instance of , and can have nested aggregations in each bucket.
873Buckets can be extracted from a using
875For more information on the Date Histogram Aggregation, see: <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html>
878Contributors
879============
881* [Chris Allen](https://github.com/bitemyapp)
882* [Liam Atkinson](https://github.com/latkins)
883* [Christopher Guiney](https://github.com/chrisguiney)
884* [Curtis Carter](https://github.com/ccarter)
885* [Michael Xavier](https://github.com/MichaelXavier)
886* [Bob Long](https://github.com/bobjflong)
887* [Maximilian Tagher](https://github.com/MaxGabriel)
888* [Anna Kopp](https://github.com/annakopp)
889* [Matvey B. Aksenov](https://github.com/supki)
891Possible future functionality
892=============================
894Span Queries
895------------
897Beginning here: <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-span-first-query.html>
899Function Score Query
900--------------------
902<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html>
904Node discovery and failover
905---------------------------
907Might require TCP support.
909Support for TCP access to Elasticsearch
910---------------------------------------
912Pretend to be a transport client?
914Bulk cluster-join merge
915-----------------------
917Might require making a lucene index on disk with the appropriate format.
919GeoShapeQuery
920-------------
922<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-geo-shape-query.html>
924GeoShapeFilter
925--------------
927<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-geo-shape-filter.html>
929Geohash cell filter
930-------------------
932<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-geohash-cell-filter.html>
934HasChild Filter
935---------------
937<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-has-child-filter.html>
939HasParent Filter
940----------------
942<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-has-parent-filter.html>
944Indices Filter
945--------------
947<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-indices-filter.html>
949Query Filter
950------------
952<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-filter.html>
954Script based sorting
955--------------------
957<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html#_script_based_sorting>
959Collapsing redundantly nested and/or structures
960-----------------------------------------------
962The Seminearring instance, if deeply nested can possibly produce nested structure that is redundant. Depending on how this affects ES performance, reducing this structure might be valuable.
964Runtime checking for cycles in data structures
965----------------------------------------------
967check for n \> 1 occurrences in DFS:
969<http://hackage.haskell.org/package/stable-maps-0.0.5/docs/System-Mem-StableName-Dynamic.html>
971<http://hackage.haskell.org/package/stable-maps-0.0.5/docs/System-Mem-StableName-Dynamic-Map.html>
973Photo Origin
974============
976Photo from HA! Designs: <https://www.flickr.com/photos/hadesigns/>