Skip to content

Commit

Permalink
Merge branch '2.0-updates' (explicit connection argument is now *mand…
Browse files Browse the repository at this point in the history 
…atory*)
  • Loading branch information
@michaelklishin
michaelklishin committed Apr 25, 2014
2 parents be52543 + 6caa327 commit 20bad5a
Show file tree
Hide file tree
Showing 6 changed files with 1,000 additions and 675 deletions.
18 changes: 10 additions & 8 deletions articles/aggregation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ This guide covers Elastisch 2.0.x releases, including preview releases.

## Overview

Aggregate functions compute a single result from a set of documents. Naturally in ElasticSearch
the input documents are retrieved using search queries. Aggregation queries (also known as
Aggregate functions compute a single result from a set of
documents. Naturally in ElasticSearch the input documents are
retrieved using search queries. Aggregation queries (also known as
"aggregations") can be used to do the following (some examples):

* Calculate maximum/minimum/average value of a field (e.g. product price) from a set of documents
Expand All @@ -54,9 +55,10 @@ Aggregations are currently only supported in the REST client.
### Using HTTP Client

To perform a query with Elastisch, use the
`clojurewerkz.elastisch.rest.document/search` function and pass it an aggregation
map. For convenience, aggregation maps can be created using functions from
`clojurewerkz.elastisch.aggregation` (similar to `clojurewerkz.elastisch.query`):
`clojurewerkz.elastisch.rest.document/search` function and pass it an
aggregation map. For convenience, aggregation maps can be created
using functions from `clojurewerkz.elastisch.aggregation` (similar to
`clojurewerkz.elastisch.query`):

``` clojure
(ns clojurewerkz.elastisch.docs.examples
Expand All @@ -69,9 +71,9 @@ map. For convenience, aggregation maps can be created using functions from

(defn -main
[& args]
(esr/connect! "http://127.0.0.1:9200")
;; performs a term query using a convenience function
(let [res (esd/search "myapp_development" "person" {:query (q/term :biography "New York")
(let [conn (esr/connect "http://127.0.0.1:9200")
res (esd/search conn "myapp_development" "person" {:query (q/term :biography "New York")
:aggregations {:avg_age (a/avg "age")})]
(println (esrsp/aggregation-from res))))
```
Expand All @@ -92,7 +94,7 @@ is a convenience functions for accessing aggregation response:
(require '[clojurewerkz.elastisch.aggregation :as a])
(require '[clojurewerkz.elastisch.rest.response :as esrsp])

(let [res (esd/search "myapp_development" "person" {:query (q/term :biography "New York")
(let [res (esd/search conn "myapp_development" "person" {:query (q/term :biography "New York")
:aggregations {:avg_age (a/avg "age")})]
(esrsp/aggregation-from res))
```
Expand Down
99 changes: 66 additions & 33 deletions articles/facets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,18 @@ layout: article

## About this guide

This guide covers ElasticSearch search faceting capabilities and explains how Elastisch presents them in the API:
This guide covers ElasticSearch search faceting capabilities and
explains how Elastisch presents them in the API:

* An overview of faceted search
* How to perform queries with facets
* Other topics related to facets

This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available [on Github](https://github.com/clojurewerkz/elastisch.docs).
This work is licensed under a <a rel="license"
href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
Attribution 3.0 Unported License</a> (including images &
stylesheets). The source is available [on
Github](https://github.com/clojurewerkz/elastisch.docs).


## What version of Elastisch does this guide cover?
Expand All @@ -22,30 +27,43 @@ This guide covers Elastisch 2.0.x releases, including preview releases.

## Overview

Faceted search (also called *faceted navigation*) is a feature that lets the user refine search results using data from [faceted classification](http://en.wikipedia.org/wiki/Faceted_classification)
Faceted search (also called *faceted navigation*) is a feature that
lets the user refine search results using data from [faceted
classification](http://en.wikipedia.org/wiki/Faceted_classification)
(categorization or labelling).

It is best demonstrated with an example from a real Web site (amazon.com):

![Faceted Search Example](https://img.skitch.com/20120831-crq5j2ea2yyawbgmgrx7bcjkyx.jpg)

Here a search for "Information Retrieval" in the books section produces 993 results, 12 of which are displayed on the first page (clipped). The left hand side
has a **faceted navigation** UI that lets us refine the query:
Here a search for "Information Retrieval" in the books section
produces 993 results, 12 of which are displayed on the first page
(clipped). The left hand side has a **faceted navigation** UI that
lets us refine the query:

* View only books released in the last 30 days
* View only unreleased books
* View results across deparments (in this case, Kindle Store has only one department to offer)
* Filter out results that have a certain minimum average custom review rating

This feature is useful when dealing with large amounts of data that can be easily classified by different criteria: products in online stores,
correspondence (emails), legal documents, geo and location data are just a few examples.

ElasticSearch lets you build faceted search for your applications using a feature commonly referred to as *facets* or *faceting*. Because facets are
additional information to a query, ElasticSearch implements them as a feature piggiebacked on top of search queries: a few additional parameters are
specified with a search query and ElasticSearch returns information relevant for building faceted navigation with the query response.

The field used for facet calculations must be of type numeric, date/time or be analyzed as a single token (see the [Indexing guide](/articles/indexing.html) on that).
ElasticSearch supports multiple [types of facets](http://www.elasticsearch.org/guide/reference/api/search/facets/):
This feature is useful when dealing with large amounts of data that
can be easily classified by different criteria: products in online
stores, correspondence (emails), legal documents, geo and location
data are just a few examples.

ElasticSearch lets you build faceted search for your applications
using a feature commonly referred to as *facets* or
*faceting*. Because facets are additional information to a query,
ElasticSearch implements them as a feature piggiebacked on top of
search queries: a few additional parameters are specified with a
search query and ElasticSearch returns information relevant for
building faceted navigation with the query response.

The field used for facet calculations must be of type numeric,
date/time or be analyzed as a single token (see the [Indexing
guide](/articles/indexing.html) on that). ElasticSearch supports
multiple [types of
facets](http://www.elasticsearch.org/guide/reference/api/search/facets/):

* [Terms](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-facets-terms-facet.html)
* [Range](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-facets-range-facet.html)
Expand All @@ -62,21 +80,27 @@ Next we will see how it works with Elastisch.

## Performing Queries with Faceting

Facets piggyback on search queries and as such, performed with the `clojurewerkz.elastisch.rest.document/search` function discussed in the [Querying guide](/articles/querying.html).
Facets piggyback on search queries and as such, performed with the
`clojurewerkz.elastisch.rest.document/search` function discussed in
the [Querying guide](/articles/querying.html).

With Elastisch, facet query structure is the same as described in the [ElasticSearch documentation](http://www.elasticsearch.org/guide/reference/api/search/facets/):
With Elastisch, facet query structure is the same as described in the
[ElasticSearch
documentation](http://www.elasticsearch.org/guide/reference/api/search/facets/):

``` clojure
(require '[clojurewerkz.elastisch.rest.document :as doc])
(require '[clojurewerkz.elastisch.query :as q])

(doc/search "articles" "article" :query (q/match-all) :facets {:tags {:terms {:field :tags}}})
(doc/search conn "articles" "article" :query (q/match-all) :facets {:tags {:terms {:field :tags}}})
```

You can give the facet a custom name (in this example, *tags*) and return multiple facets in a single request.
You can give the facet a custom name (in this example, *tags*) and
return multiple facets in a single request.

To retrieve the results, access the `:facets` key on the response (which is just a Clojure map with Elastisch). It will contain a
map of facets:
To retrieve the results, access the `:facets` key on the response
(which is just a Clojure map with Elastisch). It will contain a map of
facets:

``` clojure
{:tags {:_type "terms"
Expand All @@ -100,48 +124,57 @@ The exact structure will vary between different facet types.

## Facet Scope

Facets can have *scope*. By default, facet computation is restricted to the scope of the current query (the so called `main` scope). It is possible to
use `global` scope, in which case it will return values computed across all documents in the index:
Facets can have *scope*. By default, facet computation is restricted
to the scope of the current query (the so called `main` scope). It is
possible to use `global` scope, in which case it will return values
computed across all documents in the index:

``` clojure
(require '[clojurewerkz.elastisch.rest.document :as doc])
(require '[clojurewerkz.elastisch.query :as q])

(doc/search "articles" "article" :query (q/query-string :query "T*") :facets {:tags {:terms {:field :tags} :global true}})
(doc/search conn "articles" "article" :query (q/query-string :query "T*") :facets {:tags {:terms {:field :tags} :global true}})
```

Different facets in a query can use different scopes if needed.


## Facet Filters

All facets can be configured with an additional filter, which will reduce the documents they use for computing results. This
is very similar in purpose to query filters:
All facets can be configured with an additional filter, which will
reduce the documents they use for computing results. This is very
similar in purpose to query filters:

* You need to filter out some results
* You need to narrow results to a particular account

Facet filters can, for example, help you make sure results only contain documents that belong to a particular user account
or organization.
Facet filters can, for example, help you make sure results only
contain documents that belong to a particular user account or
organization.

In the example below we use a filter to limit facets to articles published in a particular time period (range of years):
In the example below we use a filter to limit facets to articles
published in a particular time period (range of years):

``` clojure
(require '[clojurewerkz.elastisch.rest.document :as doc])
(require '[clojurewerkz.elastisch.query :as q])

(doc/search "articles" "article" :query (q/query-string :query "T*") :facets {:tags {:terms {:field :tags}
:facet_filter {:range {:year {:from 1990 :to 2012}}}}})
(doc/search conn "articles" "article" :query (q/query-string :query "T*") :facets {:tags {:terms {:field :tags}
:facet_filter {:range {:year {:from 1990 :to 2012}}}}})
```

Different kinds of filters and their structure are described in the [Querying guide](/articles/querying.html). Their structure is the same
Different kinds of filters and their structure are described in the
[Querying guide](/articles/querying.html). Their structure is the same
for queries and facets.


## Wrapping Up

Faceted search can be a very useful feature for . ElasticSearch has very good faceted search support with multiple kinds of facets, scoping and filtering.
Facets support sits on top of search queries. With Elastisch facet requests have exactly the same structure as JSON in the ElasticSearch documentation.
Faceted search can be a very useful feature for . ElasticSearch has
very good faceted search support with multiple kinds of facets,
scoping and filtering. Facets support sits on top of search
queries. With Elastisch facet requests have exactly the same structure
as JSON in the ElasticSearch documentation.


## What to Read Next
Expand Down
Loading

0 comments on commit 20bad5a

Please sign in to comment.