Permalink
Browse files

Updated docs to use elastisearch-py

  • Loading branch information...
1 parent 11ea794 commit 41b926c69ed850baebd30ae6fd950d848c5d944e @HonzaKral HonzaKral committed with willkg Nov 3, 2013
View
@@ -17,14 +17,20 @@ Want to see how a score for a search result was calculated? See
Logging
=======
-pyelasticsearch logs to the ``pyelasticsearch`` logger using the
-Python logging module. If you configure that to show DEBUG-level
-messages, then it'll show the requests in curl form, responses, and
-when it marks servers as dead.
+elasticsearch-py logs to the ``elasticsearch`` and ``elasticsearch.trace``
+loggers using the Python logging module.
-Additionally, pyelasticsearch uses Requests which logs to the
-``requests`` logger using the Python logging module. If you configure
-that to show INFO-level messages, then you'll see all that stuff.
+If you configure ``elasticsearch.trace`` to show INFO-level messages, then
+it'll show the requests in curl form, responses if you enable DEBUG.
+
+``elasticsearch`` logger will give you information about node failures
+(WARNING-level), their resurrection (INFO) and every request in a short form
+(DEBUG). Additionally it will log a WARNING for any failed request.
+
+Elasticsearch-py uses urllib3 by default which logs to the ``urllib3`` logger
+using the Python logging module. If you configure that to show INFO-level
+messages, then you'll see all that stuff. If you configured your
+elasticsearch-py client to use other transport use it's logging capabilities.
First set up logging using something like this:
@@ -37,30 +43,36 @@ First set up logging using something like this:
logging.basicConfig()
-Then set the logging level for the pyelasticsearch and requests loggers
+Then set the logging level for the elasticsearch-py and urllib3 loggers
to ``logging.DEBUG``:
.. code-block:: python
- logging.getLogger('pyelasticsearch').setLevel(logging.DEBUG)
- logging.getLogger('requests').setLevel(logging.DEBUG)
+ logging.getLogger('elasticsearch').setLevel(logging.DEBUG)
+ logging.getLogger('urllib3').setLevel(logging.DEBUG)
+
+elasticsearch-py will log lines like::
-pyelasticsearch will log lines like::
+ INFO:elasticsearch:GET http://localhost:9200/_search [status:200
+ request:0.001s]
- DEBUG:pyelasticsearch:Making a request equivalent to this: curl
- -XGET 'http://localhost:9200/fooindex/testdoc/_search' -d '{"fa
- cets": {"topics": {"terms": {"field": "topics"}}}}'
+Or you can enable the ``elasticsearch.trace`` logger and have it log a shell
+transcript of your session using curl:
+
+.. code-block:: python
+
+ tracer = logging.getLogger('elasticsearch.trace')
+ tracer.setLevel(logging.DEBUG)
+ tracer.addHandler(logging.FileHandler('/tmp/elasticsearch-py.sh'))
-You can copy and paste the curl line and it'll work on the command
-line.
.. Note::
- If you add a ``pretty=1`` to the query string of the url that
- you're curling, then Elasticsearch will return a prettified
- response that's easier to read.
+ The trace logger will always point to localhost:9200 and add ``?pretty`` to
+ the query string of the url so that you're curling, then Elasticsearch will
+ return a prettified response that's easier to read.
Seeing the query
View
@@ -14,17 +14,6 @@ The documentation is available in HTML and PDF forms at
in the master branch of the git repository. Because of this, it is
always up to date.
-Also, of extreme high-priority hyperbole-ignoring importance:
-
-*ElasticSearch* (camel-case)
-
- Refers to the pyelasticsearch ElasticSearch
- class and instances.
-
-*Elasticsearch* (no camel-case)
-
- The Elasticsearch software.
-
Building the docs
=================
@@ -5,8 +5,8 @@
1. Checkout master tip.
2. Check to make sure ``setup.py``, requirements files, and
- ``odcs/installation.rst`` have correct version of
- pyelasticsearch.
+ ``docs/installation.rst`` have correct version of
+ elasticsearch-py.
3. Update version numbers in ``elasticutils/_version.py``.
View
@@ -103,12 +103,13 @@ file:
The timeout in seconds for creating the Elasticsearch connection.
-ElasticSearch
+Elasticsearch
=============
The `get_es()` in the Django contrib will use Django settings listed
-above to build the pyelasticsearch ElasticSearch object.
+above to build the elasticsearch-py Elasticsearch_ object.
+.. _Elasticsearch: http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch
Using with Django ORM models
============================
View
@@ -13,16 +13,16 @@ ElasticUtils is primarily an API for searching. However, before you
can search, you need to create an index and index your documents.
This chapter covers the indexing side of things. It does so
-lightly---for more details, read through the `pyelasticsearch
-documentation <http://pyelasticsearch.readthedocs.org/en/latest/>`_
+lightly---for more details, read through the `elasticsearch-py
+documentation <http://elasticsearch-py.readthedocs.org/en/latest/>`_
and the `Elasticsearch guide <http://www.elasticsearch.org/guide/>`_.
-Getting an ElasticSearch object
+Getting an Elasticsearch object
===============================
-ElasticUtils uses `pyelasticsearch` which comes with a handy
-`ElasticSearch` object. This lets you:
+ElasticUtils uses `elasticsearch-py` which comes with a handy
+`Elasticsearch` object. This lets you:
* create indexes
* create mappings
@@ -31,15 +31,15 @@ ElasticUtils uses `pyelasticsearch` which comes with a handy
* etc.
To access this, you use :py:func:`elasticutils.get_es` which creates
-an `ElasticSearch` object for you.
+an `Elasticsearch` object for you.
See :py:func:`elasticutils.get_es` for more details.
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/
- pyelasticsearch ElasticSearch documentation.
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch
+ elasticsearch-py Elasticsearch documentation.
Indexes
@@ -48,31 +48,31 @@ Indexes
An `index` is a collection of documents.
Before you do anything, you need to have an index. You can create one
-with `.create_index()`.
+with `.indices.create()`.
For example:
.. code-block:: python
es = get_es()
- es.create_index('blog-index')
+ es.indices.create(index='blog-index')
You can pass in settings, too. For example, you can set the refresh
interval when creating the index:
.. code-block:: python
- es.create_index('blog-index', settings={'refresh_interval': '5s'})
+ es.indices.create(index='blog-index', body{'refresh_interval': '5s'})
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.create_index
- pyelasticsearch create_index API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.client.IndicesClient.create
+ elasticsearch-py indices.create API documentation
http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index/
- Elasticsearch create_index API documentation
+ Elasticsearch create index API documentation
.. _indexing-types-and-mappings:
@@ -93,42 +93,49 @@ type with a defined mapping" because that's a mouthful.
Elasticsearch can infer mappings to some degree, but you get a lot
more value by specifying mappings explicitly.
-To define a mapping, you use `.put_mapping()`.
+To define a mapping, you use `.indices.put_mapping()`.
For example:
.. code-block:: python
es = get_es()
- es.put_mapping('blog-index', 'blog-entry-type', {
- 'blog-entry-type': {
- 'properties': {
- 'id': {'type': 'integer'},
- 'title': {'type': 'string'},
- 'content': {'type': 'string'},
- 'tags': {'type': 'string'},
- 'created': {'type': 'date'}
+ es.indices.put_mapping(
+ index='blog-index',
+ doc_type='blog-entry-type',
+ body={
+ 'blog-entry-type': {
+ 'properties': {
+ 'id': {'type': 'integer'},
+ 'title': {'type': 'string'},
+ 'content': {'type': 'string'},
+ 'tags': {'type': 'string'},
+ 'created': {'type': 'date'}
+ }
}
}
- })
+ )
You can also define mappings when you create the index:
.. code-block:: python
es = get_es()
- es.create_index('blog-index', settings={
- 'mappings': {
- 'blog-entry-type': {
- 'properties': {
+ es.indices.create(
+ index='blog-index',
+ body={
+ 'mappings': {
+ 'blog-entry-type': {
'id': {'type': 'integer'},
'title': {'type': 'string'},
'content': {'type': 'string'},
'tags': {'type': 'string'},
'created': {'type': 'date'}
}
- }}})
+ }
+ }
+ )
.. Note::
@@ -141,8 +148,8 @@ You can also define mappings when you create the index:
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.put_mapping
- pyelasticsearch put_mapping API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.client.IndicesClient.put_mapping
+ elasticsearch-py indices.put_mapping API documentation
http://www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/
Elasticsearch put_mapping API documentation
@@ -169,30 +176,32 @@ For example:
'created': '20130423T16:50:22'
}
- es.index('blog-index', 'blog-entry-type', entry, 1)
+ es.index(index='blog-index', doc_type='blog-entry-type', body=entry, id=1)
If you're indexing a bunch of documents at the same time, you should
-use `.bulk_index()`.
+use `elasticsearch.helpers.bulk_index()`.
For example:
.. code-block:: python
+ from elasticsearch.helpers import bulk_index
+
es = get_es()
- entries = { ... }
+ entries = [{ '_id': 42, ... }, { '_id': 47, ... }]
- es.bulk_index('blog-index', 'blog-entry-type', entries, id_field='id')
+ bulk_index(es, entries, index='blog-index', doc_type='blog-entry-type')
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.index
- pyelasticsearch index API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.Elasticsearch.index
+ elasticsearch-py index API documentation
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.bulk_index
- pyelasticsearch bulk_index API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/helpers.html#elasticsearch.helpers.bulk_index
+ elasticsearch-py bulk_index API documentation
http://www.elasticsearch.org/guide/reference/api/index\_/
Elasticsearch index API documentation
@@ -212,13 +221,13 @@ For example:
es = get_es()
- es.delete('blog-index', 'blog-entry-type', 1)
+ es.delete(index='blog-index', doc_type='blog-entry-type', id=1)
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.delete
- pyelasticsearch delete API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.Elasticsearch.delete
+ elasticsearch-py delete API documentation
http://www.elasticsearch.org/guide/reference/api/delete/
Elasticsearch delete API documentation
@@ -230,21 +239,21 @@ Refreshing
After you index documents, they're not available for searches until
after the index is refreshed. By default, the index refreshes every
second. If you need the documents to show up in searches before that,
-call `.refresh()`.
+call `indices.refresh()`.
For example:
.. code-block:: python
es = get_es()
- es.refresh('blog-index')
+ es.indices.refresh(index='blog-index')
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.refresh
- pyelasticsearch refresh API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.client.IndicesClient.refresh
+ elasticsearch-py indices.refresh API documentation
http://www.elasticsearch.org/guide/reference/api/admin-indices-refresh/
Elasticsearch refresh API documentation
@@ -253,21 +262,21 @@ For example:
Delete indexes
==============
-You can delete indexes with `.delete_index()`.
+You can delete indexes with `.indices.delete()`.
For example:
.. code-block:: python
es = get_es()
- es.delete_index('blog-index')
+ es.indices.delete(index='blog-index')
.. seealso::
- http://pyelasticsearch.readthedocs.org/en/latest/api/#pyelasticsearch.ElasticSearch.delete_index
- pyelasticsearch delete_index API documentation
+ http://elasticsearch-py.readthedocs.org/en/latest/api.html#elasticsearch.client.IndicesClient.delete
+ elasticsearch-py indices.delete API documentation
http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-index/
Elasticsearch delete index API documentation
View
@@ -18,7 +18,7 @@ Requirements
ElasticUtils requires:
-* pyelasticsearch == 0.6
+* elasticsearch >= 0.4.3
Installation
Oops, something went wrong.

0 comments on commit 41b926c

Please sign in to comment.