skip to navigation
skip to content

Not Logged In

rawes 0.2

rawes elasticsearch driver

Latest Version: 0.5.5

rawes
=====

About
-----
rawes is an elasticsearch driver for Python.  It provides a small level of abstraction above the requests library - just enough to be useful, but not enough to obscure elasticsearch's great [native api](http://www.elasticsearch.org/guide/reference/api/)

Features
--------
* elasticsearch native API support
* gzip over HTTP support
* Thrift support

Installation
------------
```bash
$ pip install rawes
```

Usage
-----
Create a connection to elasticsearch
```python
import rawes
es = rawes.Elastic('localhost:9200')
```

Search for a document
```python
es.get('tweets/tweet/_search', data={
    'query' : {
        'match_all' : {}
    }
})
```

The rawes.Elastic constructor takes the following parameters (defaults shown):
```python
rawes.Elastic(
    url='localhost:9200', # Path and port to elasticsearch service.  Ports 9500-9600 will use thrift; others http
    path='', # http url path (for example, 'tweets/tweet/_search')
    timeout=30, # Timeout in seconds
    connection_type=None, # Set to 'http' or 'thrift' to explicitly set a protocol
)
```

An instance of rawes.Elastic ('es' in this case) has methods for get, post, put, delete, and head (for each http verb).  Each method takes the following parameters (defaults shown):
```python
es.get(
    path='', # HTTP URL path
    data='', # http body.  can be either a string or a python dictionary (will automatically be converted to JSON)
    params={}, # HTTP URL params passed as a python dictionary
    headers={}, # HTTP headers as a python dictionary
    **kwargs # HTTP only: any additional parameters you wish to pass to the python 'requests' library (for example, basic auth)
)
```

Create a new document in the twitter index of type tweet with id 1
```python
es.put('tweets/tweet/1', data={
    'user' : 'dwnoble',
    'post_date' : '2012-8-27T08:00:30',
    'message' : 'Tweeting about elasticsearch'
})
es.put('blogs/post/2', data={
    'user' : 'dan',
    'post_date' : '2012-8-27T09:30:03',
    'title' : 'Elasticsearch',
    'body' : 'Blogging about elasticsearch'
})
```

Search for a document, specifying http params
```python
es.get('tweets/tweet/_search', data={
    'query' : {
        'match_all' : {}
    }
}, params= {
    'size': 2
})
```

Search for a document with a JSON string
```python
es.get('tweets,blogs/_search', data="""
{
    "query" : {
        "match_all" : {}
    }
}
""")
```

Update a document
```python
es.put('someindex/sometype/123', data={
    'value' : 100,
    'other' : 'stuff'
})
es.post('someindex/sometype/123/_update', data={
    'script' : 'ctx._source.value += value',
    'params' : {
        'value' : 50
    }
})
```

Delete a document
```python
es.delete('tweets/tweet/1')
```


Alternate Syntax
----------------
Instead of setting the first argument of a es.<http verb> call to the HTTP URL path, you can also use python attributes and items to build up the url path. For example:
```python
es.post('tweets/tweet/', data={
    'user' : 'dwnoble',
    'post_date' : '2012-8-27T09:15:59',
    'message' : 'More tweets about elasticsearch'
})
```

Becomes:
```python
es.tweets.tweet.post(data={
    'user' : 'dwnoble',
    'post_date' : '2012-8-27T09:15:59',
    'message' : 'More tweets about elasticsearch'
})
```

Or using [] notation.  This can be useful for characters that are not allowed in python attributes:
```python
es['tweets']['tweet'].post(data={
    'user' : 'dwnoble',
    'post_date' : '2012-8-27T09:15:59',
    'message' : 'More tweets about elasticsearch'
})
```

More examples:

Searching tweets index for documents of type tweets
```python
es.tweets.tweet._search.get(data={'query' : {'match_all' : {} }})
```

Searching tweets and blogs index for documents of any type using a JSON strings
```python
es['tweets,blogs']._search.get(data='{"query" : {"match_all" : {}}}')
```

Thrift support
--------------
Before thrift will work with rawes, you must install the thrift python module
```bash
$ pip install thrift
```

By default, connections on ports between 9500 and 9600 will use thrift
```python
import rawes
es_thrift = rawes.Elastic('localhost:9500')
```

If you are using thrift on a non standard port, specify connection_type='thrift' as a parameter
```python
import rawes
es_thrift = rawes.Elastic('localhost:8500', connection_type='thrift')
```

Run Unit Tests
--------------
rawes' unit tests require the python thrift module to run:
```bash
$ pip install thrift
```

Run tests:
```bash
$ python -m unittest tests
```

Contact
-------
[@dwnoble](https://twitter.com/dwnoble)
 
File Type Py Version Uploaded on Size
rawes-0.2.tar.gz (md5) Source 2012-08-27 9KB
  • Downloads (All Versions):
  • 83 downloads in the last day
  • 475 downloads in the last week
  • 2774 downloads in the last month