Skip to content
This repository has been archived by the owner on Feb 20, 2019. It is now read-only.

Commit

Permalink
Updated docs to use elastisearch-py
Browse files Browse the repository at this point in the history
  • Loading branch information
@honzakral @willkg
honzakral authored and willkg committed Nov 20, 2013
1 parent 11ea794 commit 41b926c
Show file tree
Hide file tree
Showing 11 changed files with 139 additions and 138 deletions.
50 changes: 31 additions & 19 deletions docs/debugging.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down
11 changes: 0 additions & 11 deletions docs/dev_documentation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
=================
Expand Down
4 changes: 2 additions & 2 deletions docs/dev_releaseprocess.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
5 changes: 3 additions & 2 deletions docs/django.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
============================
Expand Down
109 changes: 59 additions & 50 deletions docs/indexing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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::
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Requirements

ElasticUtils requires:

* pyelasticsearch == 0.6
* elasticsearch >= 0.4.3


Installation
Expand Down
Loading

0 comments on commit 41b926c

Please sign in to comment.