Permalink
Browse files

Issue 54. Add docs for order-by

This also adds API documentation. It's not great because the docstrings
need work, but it's better!
  • Loading branch information...
willkg committed Sep 4, 2012
1 parent 623133e commit 0fb6c14482d5b806e751dfb58c79177b578c320c
Showing with 112 additions and 13 deletions.
  1. +4 −4 docs/es.rst
  2. +82 −0 docs/queries.rst
  3. +26 −9 elasticutils/__init__.py
View
@@ -12,7 +12,7 @@ To access this, you use `get_es()` which builds an `ES`.
.. Warning::
- ElasticUtils works best with ``pyes`` 0.15 and 0.16. The API for
- later versions has changed too drastically. While we'd welcome
- compatibility patches, we feel a better approach would be to remove
- our dependency on ``pyes``.
+ ElasticUtils works with ``pyes`` 0.15 and 0.16. The API for later
+ versions of pyes has changed too much and won't work with
+ ElasticUtils. We're planning to switch to something different in
+ the future.
View
@@ -455,6 +455,29 @@ only to that field name and field action. For example::
will only apply the 4.0 boost to ``title__prefix``.
+Ordering
+========
+
+You can order search results by specified fields::
+
+ q = (S().query(title='trucks')
+ .order_by('title')
+
+This orders search results by the `title` field in ascending order.
+
+If you want to sort by descending order, prepend a ``-``::
+
+ q = (S().query(title='trucks')
+ .order_by('-title')
+
+You can also sort by the computed field ``_score``.
+
+.. seealso::
+
+ http://www.elasticsearch.org/guide/reference/api/search/sort.html
+ ElasticSearch docs on sort parameter in the Search API
+
+
Demoting
========
@@ -909,3 +932,62 @@ This works regardless of what form the search results are in.
http://www.elasticsearch.org/guide/reference/api/search/explain.html
ElasticSearch docs on explain (which are pretty bereft of
details).
+
+
+API
+===
+
+The S class
+-----------
+
+.. autoclass:: elasticutils.S
+
+ .. automethod:: elasticutils.S.__init__
+
+ **Chaining transforms**
+
+ .. automethod:: elasticutils.S.query
+
+ .. automethod:: elasticutils.S.filter
+
+ .. automethod:: elasticutils.S.order_by
+
+ .. automethod:: elasticutils.S.boost
+
+ .. automethod:: elasticutils.S.demote
+
+ .. automethod:: elasticutils.S.facet
+
+ .. automethod:: elasticutils.S.facet_raw
+
+ .. automethod:: elasticutils.S.highlight
+
+ .. automethod:: elasticutils.S.values_list
+
+ .. automethod:: elasticutils.S.values_dict
+
+ .. automethod:: elasticutils.S.es
+
+ .. automethod:: elasticutils.S.es_builder
+
+ .. automethod:: elasticutils.S.indexes
+
+ .. automethod:: elasticutils.S.doctypes
+
+ .. automethod:: elasticutils.S.explain
+
+ **Methods to override if you need different behavior**
+
+ .. automethod:: elasticutils.S.get_es
+
+ .. automethod:: elasticutils.S.get_indexes
+
+ .. automethod:: elasticutils.S.get_doctypes
+
+ **Methods that force evaluation**
+
+ .. automethod:: elasticutils.S.count
+
+ .. automethod:: elasticutils.S.facet_counts
+
+
View
@@ -39,15 +39,23 @@ def get_es(hosts=None, default_indexes=None, timeout=None, dump_curl=None,
Examples:
- >>> get_es()
- >>> get_es(hosts=['localhost:9200'])
- >>> get_es(timeout=30) # good for indexing
- >>> get_es(default_indexes=['sumo_prod_20120627']
+ >>> es = get_es()
+
+
+ >>> es = get_es(hosts=['localhost:9200'])
+
+
+ >>> es = get_es(timeout=30) # good for indexing
+
+
+ >>> es = get_es(default_indexes=['sumo_prod_20120627']
+
+
>>> class CurlDumper(object):
... def write(self, text):
... print text
...
- >>> get_es(dump_curl=CurlDumper())
+ >>> es = get_es(dump_curl=CurlDumper())
"""
# Cheap way of de-None-ifying things
@@ -205,9 +213,18 @@ def _boosted_value(name, action, key, value, boost):
class S(object):
- """
- Represents a lazy ElasticSearch lookup, with a similar api to
- Django's QuerySet.
+ """Represents a lazy ElasticSearch Search API request.
+
+ The API for `S` takes inspiration from Django's QuerySet.
+
+ `S` can be either typed or untyped. An untyped `S` returns dict
+ results by default.
+
+ An `S` is lazy in the sense that it doesn't do an ElasticSearch
+ search request until it's forced to evaluate by either iterating
+ over it, calling ``.count``, doing ``len(s)``, or calling
+ ``.facet_count``.
+
"""
def __init__(self, type_=None):
"""Create and return an S.
@@ -246,7 +263,7 @@ def es(self, **settings):
the search.
:arg settings: the settings you'd use to build the ES---same
- as what you'd pass to :fun:`get_es`.
+ as what you'd pass to :py:func:`get_es`.
"""
return self._clone(next_step=('es', settings))

0 comments on commit 0fb6c14

Please sign in to comment.