@@ -640,6 +640,163 @@ let filter = RegexpFilter (FieldName "user") (Regexp "bite.*app")
644+**** Adding aggregations to search
645+Aggregations can now be added to search queries, or made on their own.
647+type Aggregations = M.Map Text Aggregation
649+ = TermsAgg TermsAggregation
650+ | DateHistogramAgg DateHistogramAggregation
653+For convenience, ```mkAggregations``` exists, that will create an
654+```Aggregations``` with the aggregation provided.
658+ let a = mkAggregations "users" $ TermsAgg $ mkTermsAggregation "user"
659+ let search = mkAggregateSearch Nothing a
662+Aggregations can be added to an existing search, using the
666+ let search = mkSearch (Just (MatchAllQuery Nothing)) Nothing
667+ let search' = search {aggBody = Just a}
670+Since the ```Aggregations``` structure is just a Map Text
671+Aggregation, M.insert can be used to add additional aggregations.
674+ let a' = M.insert "age" (TermsAgg $ mkTermsAggregation "age") a
677+**** Extracting aggregations from results
678+Aggregations are part of the reply structure of every search, in the
679+form of ~Maybe AggregationResults~
682+-- Lift decode and response body to be in the IO monad.
683+let decode' = liftM decode
684+let responseBody' = liftM responseBody
685+let reply = searchByIndex testServer testIndex search
686+let response = decode' $ responseBody' reply :: IO (Maybe (SearchResult Tweet))
688+-- Now that we have our response, we can extract our terms aggregation result -- which is a list of buckets.
690+let terms = do { response' <- response; return $ response' >>= aggregations >>= toTerms "users" }
692+Just (Bucket {buckets = [TermsResult {termKey = "bitemyapp", termsDocCount = 1, termsAggs = Nothing}]})
695+Note that bucket aggregation results, such as the TermsResult is a
696+member of the type class ~BucketAggregation~:
699+class BucketAggregation a where
701+ docCount :: a -> Int
702+ aggs :: a -> Maybe AggregationResults
705+You can use the ~aggs~ function to get any nested results, if
706+there were any. For example, if there were a nested terms
707+aggregation keyed to "age" in a TermsResult named ~termresult~, you would call ~aggs termresult >>=
710+**** Terms Aggregation
712+data TermsAggregation
713+ = TermsAggregation {term :: Either Text Text,
714+ termInclude :: Maybe TermInclusion,
715+ termExclude :: Maybe TermInclusion,
716+ termOrder :: Maybe TermOrder,
717+ termMinDocCount :: Maybe Int,
718+ termSize :: Maybe Int,
719+ termShardSize :: Maybe Int,
720+ termCollectMode :: Maybe CollectionMode,
721+ termExecutionHint :: Maybe ExecutionHint,
722+ termAggs :: Maybe Aggregations}
725+Term Aggregations have two factory functions,
726+~mkTermsAggregation~, and ~mkTermsScriptAggregation~, and can
730+let ta = TermsAgg $ mkTermsAggregation "user"
733+There are of course other options that can be added to a Terms
734+Aggregation, such as the collection mode:
736+let ta = mkTermsAggregation "user"
737+let ta' = ta { termCollectMode = Just BreadthFirst }
738+let ta'' = TermsAgg ta'
741+For more documentation on how the Terms Aggregation works, see
742+http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html
744+**** Date Histogram Aggregation
747+data DateHistogramAggregation
748+ = DateHistogramAggregation {dateField :: FieldName,
749+ dateInterval :: Interval,
750+ dateFormat :: Maybe Text,
751+ datePreZone :: Maybe Text,
752+ datePostZone :: Maybe Text,
753+ datePreOffset :: Maybe Text,
754+ datePostOffset :: Maybe Text,
755+ dateAggs :: Maybe Aggregations}
758+The Date Histogram Aggregation works much the same as the Terms
761+Relevant functions include ~mkDateHistogram~, and ~toDateHistogram~
764+let dh = DateHistogramAgg (mkDateHistogram (FieldName "postDate") Minute)
767+Date histograms also accept a ~FractionalInterval~:
770+FractionalInterval :: Float -> TimeInterval -> Interval
771+-- TimeInterval is the following:
772+data TimeInterval = Weeks | Days | Hours | Minutes | Seconds
775+It can be used as follows:
778+let dh = DateHistogramAgg (mkDateHistogram (FieldName "postDate") (FractionalInterval 1.5 Minutes))
781+The ~DateHistogramResult~ is defined as:
784+data DateHistogramResult
785+ = DateHistogramResult {dateKey :: Int,
786+ dateKeyStr :: Maybe Text,
787+ dateDocCount :: Int,
788+ dateHistogramAggs :: Maybe AggregationResults}
791+It is an instance of ~BucketAggregation~, and can have nested
792+aggregations in each bucket.
794+Buckets can be extracted from a ~AggregationResult~ using
795+~toDateHistogram name~
797+For more information on the Date Histogram Aggregation, see:
798+http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html
643* Possible future functionality
800* Possible future functionality
645** Span Queries
802** Span Queries