From ad5860bea66fb0eeea072c95394ed58b394efa5d Mon Sep 17 00:00:00 2001 From: Honza Kral Date: Wed, 7 Aug 2013 01:34:17 +0200 Subject: [PATCH] Formatting and docstrings --- elasticsearch/client/__init__.py | 281 +++++++++++++++--------- elasticsearch/client/cluster.py | 68 +++--- elasticsearch/client/indices.py | 357 +++++++++++++++++++------------ 3 files changed, 447 insertions(+), 259 deletions(-) diff --git a/elasticsearch/client/__init__.py b/elasticsearch/client/__init__.py index 62fa3c03..c9af5446 100644 --- a/elasticsearch/client/__init__.py +++ b/elasticsearch/client/__init__.py @@ -79,13 +79,15 @@ class Elasticsearch(object): @query_params() def info(self, params=None): """ Get the basic info from the current cluster. """ - status, data = self.transport.perform_request('GET', _make_path(), params=params) + _, data = self.transport.perform_request('GET', _make_path(), params=params) return data - @query_params('consistency', 'id', 'parent', 'percolate', 'refresh', 'replication', 'routing', 'timeout', 'timestamp', 'ttl', 'version', 'version_type') + @query_params('consistency', 'id', 'parent', 'percolate', 'refresh', + 'replication', 'routing', 'timeout', 'timestamp', 'ttl', 'version', 'version_type') def create(self, index, doc_type, body, id=None, params=None): """ - The index API adds or updates a typed JSON document in a specific index, making it searchable. + Adds a typed JSON document in a specific index, making it searchable. + Behind the scenes this method calls index(..., op_type='create') http://elasticsearch.org/guide/reference/api/index_/ :arg index: The name of the index @@ -97,7 +99,7 @@ class Elasticsearch(object): :arg parent: ID of the parent document :arg percolate: Percolator queries to execute while indexing the document :arg refresh: Refresh the index after performing the operation - :arg replication: Specific replication type, default u'sync' + :arg replication: Specific replication type (default: sync) :arg routing: Specific routing value :arg timeout: Explicit operation timeout :arg timestamp: Explicit timestamp for the document @@ -107,10 +109,11 @@ class Elasticsearch(object): """ return self.index(index, doc_type, body, id=id, params=params, op_type='create') - @query_params('consistency', 'op_type', 'parent', 'percolate', 'refresh', 'replication', 'routing', 'timeout', 'timestamp', 'ttl', 'version', 'version_type') + @query_params('consistency', 'op_type', 'parent', 'percolate', 'refresh', + 'replication', 'routing', 'timeout', 'timestamp', 'ttl', 'version', 'version_type') def index(self, index, doc_type, body, id=None, params=None): """ - The index API adds or updates a typed JSON document in a specific index, making it searchable. + Adds or updates a typed JSON document in a specific index, making it searchable. http://elasticsearch.org/guide/reference/api/index_/ :arg index: The name of the index @@ -118,11 +121,11 @@ class Elasticsearch(object): :arg id: Document ID :arg body: The document :arg consistency: Explicit write consistency setting for the operation - :arg op_type: Explicit operation type, default u'index' + :arg op_type: Explicit operation type (default: index) :arg parent: ID of the parent document :arg percolate: Percolator queries to execute while indexing the document :arg refresh: Refresh the index after performing the operation - :arg replication: Specific replication type, default u'sync' + :arg replication: Specific replication type (default: sync) :arg routing: Specific routing value :arg timeout: Explicit operation timeout :arg timestamp: Explicit timestamp for the document @@ -130,13 +133,14 @@ class Elasticsearch(object): :arg version: Explicit version number for concurrency control :arg version_type: Specific version type """ - status, data = self.transport.perform_request('PUT' if id else 'POST', _make_path(index, doc_type, id), params=params, body=body) + _, data = self.transport.perform_request('PUT' if id else 'POST', + _make_path(index, doc_type, id), params=params, body=body) return data @query_params('parent', 'preference', 'realtime', 'refresh', 'routing') def exists(self, index, id, doc_type='_all', params=None): """ - The get API allows to get a typed JSON document from the index based on its id. + Returns a boolean indicating whether or not given document exists in Elasticsearch. http://elasticsearch.org/guide/reference/api/get/ :arg index: The name of the index @@ -144,9 +148,12 @@ class Elasticsearch(object): :arg doc_type: The type of the document (uses `_all` by default to fetch the first document matching the ID across all types) :arg parent: The ID of the parent document - :arg preference: Specify the node or shard the operation should be performed on (default: random) - :arg realtime: Specify whether to perform the operation in realtime or search mode - :arg refresh: Refresh the shard containing the document before performing the operation + :arg preference: Specify the node or shard the operation should be + performed on (default: random) + :arg realtime: Specify whether to perform the operation in realtime or + search mode + :arg refresh: Refresh the shard containing the document before + performing the operation :arg routing: Specific routing value """ try: @@ -158,7 +165,7 @@ class Elasticsearch(object): @query_params('fields', 'parent', 'preference', 'realtime', 'refresh', 'routing') def get(self, index, id, doc_type='_all', ignore_missing=False, params=None): """ - The get API allows to get a typed JSON document from the index based on its id. + Get a typed JSON document from the index based on its id. http://elasticsearch.org/guide/reference/api/get/ :arg index: The name of the index @@ -168,13 +175,17 @@ class Elasticsearch(object): :arg ignore_missing: if True will not raise an exception on 404 :arg fields: A comma-separated list of fields to return in the response :arg parent: The ID of the parent document - :arg preference: Specify the node or shard the operation should be performed on (default: random) - :arg realtime: Specify whether to perform the operation in realtime or search mode - :arg refresh: Refresh the shard containing the document before performing the operation + :arg preference: Specify the node or shard the operation should be + performed on (default: random) + :arg realtime: Specify whether to perform the operation in realtime or + search mode + :arg refresh: Refresh the shard containing the document before + performing the operation :arg routing: Specific routing value """ try: - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, id), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, id), + params=params) except NotFoundError: if ignore_missing: return @@ -184,22 +195,25 @@ class Elasticsearch(object): @query_params('parent', 'preference', 'realtime', 'refresh', 'routing') def get_source(self, index, id, doc_type='_all', ignore_missing=False, params=None): """ - The get API allows to get the document source from the index based on its id. + Get the source of a document by it's index, type and id. http://elasticsearch.org/guide/reference/api/get/ :arg index: The name of the index :arg doc_type: The type of the document (uses `_all` by default to fetch the first document matching the ID across all types) :arg id: The document ID - :arg ignore_missing: if True will not raise an exception on 404 + :arg ignore_missing: if True will not raise an exception on 404 and just return `None` :arg parent: The ID of the parent document - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg realtime: Specify whether to perform the operation in realtime or search mode - :arg refresh: Refresh the shard containing the document before performing the operation + :arg refresh: Refresh the shard containing the document before + performing the operation :arg routing: Specific routing value """ try: - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_source'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_source'), + params=params) except NotFoundError: if ignore_missing: return @@ -209,41 +223,50 @@ class Elasticsearch(object): @query_params('fields', 'parent', 'preference', 'realtime', 'refresh', 'routing') def mget(self, body, index=None, doc_type=None, params=None): """ - Multi GET API allows to get multiple documents based on an index, type (optional) and id (and possibly routing). + Get multiple documents based on an index, type (optional) and ids. http://elasticsearch.org/guide/reference/api/multi-get/ - :arg body: Document identifiers; can be either `docs` (containing full document information) or `ids` (when index and type is provided in the URL. + :arg body: Document identifiers; can be either `docs` (containing full + document information) or `ids` (when index and type is provided in the URL. :arg index: The name of the index :arg doc_type: The type of the document :arg fields: A comma-separated list of fields to return in the response :arg parent: The ID of the parent document - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg realtime: Specify whether to perform the operation in realtime or search mode - :arg refresh: Refresh the shard containing the document before performing the operation + :arg refresh: Refresh the shard containing the document before + performing the operation :arg routing: Specific routing value """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_mget'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_mget'), + params=params, body=body) return data - @query_params('consistency', 'fields', 'lang', 'parent', 'percolate', 'refresh', 'replication', 'retry_on_conflict', 'routing', 'script', 'timeout', 'timestamp', 'ttl', 'version', 'version_type') + @query_params('consistency', 'fields', 'lang', 'parent', 'percolate', + 'refresh', 'replication', 'retry_on_conflict', 'routing', 'script', + 'timeout', 'timestamp', 'ttl', 'version', 'version_type') def update(self, index, doc_type, id, body=None, ignore_missing=False, params=None): """ - The update API allows to update a document based on a script or partial data provided. + Update a document based on a script or partial data provided. http://elasticsearch.org/guide/reference/api/update/ :arg index: The name of the index :arg doc_type: The type of the document :arg id: Document ID :arg body: The request definition using either `script` or partial `doc` - :arg ignore_missing: if True will not raise an exception on 404 + :arg ignore_missing: if True will not raise an exception on 404 and + just return `None` :arg consistency: Explicit write consistency setting for the operation :arg fields: A comma-separated list of fields to return in the response :arg lang: The script language (default: mvel) :arg parent: ID of the parent document - :arg percolate: Perform percolation during the operation; use specific registered query name, attribute, or wildcard + :arg percolate: Perform percolation during the operation; use specific + registered query name, attribute, or wildcard :arg refresh: Refresh the index after performing the operation - :arg replication: Specific replication type, default u'sync' - :arg retry_on_conflict: Specify how many times should the operation be retried when a conflict occurs (default: 0) + :arg replication: Specific replication type (default: sync) + :arg retry_on_conflict: Specify how many times should the operation be + retried when a conflict occurs (default: 0) :arg routing: Specific routing value :arg script: The URL-encoded script definition (instead of using request body) :arg timeout: Explicit operation timeout @@ -253,44 +276,61 @@ class Elasticsearch(object): :arg version_type: Explicit version number for concurrency control """ try: - status, data = self.transport.perform_request('POST', _make_path(index, doc_type, id, '_update'), params=params, body=body) + _, data = self.transport.perform_request('POST', _make_path(index, doc_type, id, '_update'), + params=params, body=body) except NotFoundError: if ignore_missing: return raise return data - @query_params('analyze_wildcard', 'analyzer', 'default_operator', 'df', 'explain', 'fields', 'ignore_indices', 'indices_boost', 'lenient', 'lowercase_expanded_terms', 'offset', 'preference', 'q', 'routing', 'scroll', 'search_type', 'size', 'sort', 'source', 'stats', 'suggest_field', 'suggest_mode', 'suggest_size', 'suggest_text', 'timeout', 'version') + @query_params('analyze_wildcard', 'analyzer', 'default_operator', 'df', + 'explain', 'fields', 'ignore_indices', 'indices_boost', 'lenient', + 'lowercase_expanded_terms', 'offset', 'preference', 'q', 'routing', + 'scroll', 'search_type', 'size', 'sort', 'source', 'stats', + 'suggest_field', 'suggest_mode', 'suggest_size', 'suggest_text', 'timeout', + 'version') def search(self, index=None, doc_type=None, body=None, params=None): """ - The search API allows to execute a search query and get back search hits that match the query. + Execute a search query and get back search hits that match the query. http://www.elasticsearch.org/guide/reference/api/search/ - :arg index: A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices - :arg doc_type: A comma-separated list of document types to search; leave empty to perform the operation on all types + :arg index: A comma-separated list of index names to search; use `_all` + or empty string to perform the operation on all indices + :arg doc_type: A comma-separated list of document types to search; + leave empty to perform the operation on all types :arg body: The search definition using the Query DSL - :arg analyze_wildcard: Specify whether wildcard and prefix queries should be analyzed (default: false) + :arg analyze_wildcard: Specify whether wildcard and prefix queries + should be analyzed (default: false) :arg analyzer: The analyzer to use for the query string - :arg default_operator: The default operator for query string query (AND or OR), default u'OR' - :arg df: The field to use as default where no field prefix is given in the query string - :arg explain: Specify whether to return detailed information about score computation as part of a hit + :arg default_operator: The default operator for query string query (AND + or OR) (default: OR) + :arg df: The field to use as default where no field prefix is given in + the query string + :arg explain: Specify whether to return detailed information about + score computation as part of a hit :arg fields: A comma-separated list of fields to return as part of a hit - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg indices_boost: Comma-separated list of index boosts - :arg lenient: Specify whether format-based query failures (such as providing text to a numeric field) should be ignored + :arg lenient: Specify whether format-based query failures (such as + providing text to a numeric field) should be ignored :arg lowercase_expanded_terms: Specify whether query terms should be lowercased :arg offset: Starting offset (default: 0) - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg q: Query in the Lucene query string syntax :arg routing: A comma-separated list of specific routing values - :arg scroll: Specify how long a consistent view of the index should be maintained for scrolled search + :arg scroll: Specify how long a consistent view of the index should be + maintained for scrolled search :arg search_type: Search operation type :arg size: Number of hits to return (default: 10) :arg sort: A comma-separated list of : pairs - :arg source: The URL-encoded request definition using the Query DSL (instead of using request body) + :arg source: The URL-encoded request definition using the Query DSL + (instead of using request body) :arg stats: Specific 'tag' of the request for logging and statistical purposes :arg suggest_field: Specify which field to use for suggestions - :arg suggest_mode: Specify suggest mode, default u'missing' + :arg suggest_mode: Specify suggest mode (default: missing) :arg suggest_size: How many suggestions to return in response :arg suggest_text: The source text for which the suggestions should be returned :arg timeout: Explicit operation timeout @@ -298,25 +338,29 @@ class Elasticsearch(object): """ if doc_type and not index: index = '_all' - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_search'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_search'), + params=params, body=body) return data @query_params('scroll') def scroll(self, scroll_id, params=None): """ - A search request can be scrolled by specifying the scroll parameter. + Scroll a search request created by specifying the scroll parameter. http://www.elasticsearch.org/guide/reference/api/search/scroll/ :arg scroll_id: The scroll ID - :arg scroll: Specify how long a consistent view of the index should be maintained for scrolled search + :arg scroll: Specify how long a consistent view of the index should be + maintained for scrolled search """ - status, data = self.transport.perform_request('GET', _make_path('_search', 'scroll', scroll_id), params=params) + _, data = self.transport.perform_request('GET', _make_path('_search', 'scroll', scroll_id), + params=params) return data - @query_params('consistency', 'parent', 'refresh', 'replication', 'routing', 'timeout', 'version', 'version_type') + @query_params('consistency', 'parent', 'refresh', 'replication', 'routing', + 'timeout', 'version', 'version_type') def delete(self, index, doc_type, id, ignore_missing=False, params=None): """ - The delete API allows to delete a typed JSON document from a specific index based on its id. + Delete a typed JSON document from a specific index based on its id. http://elasticsearch.org/guide/reference/api/delete/ :arg index: The name of the index @@ -326,14 +370,14 @@ class Elasticsearch(object): :arg consistency: Specific write consistency setting for the operation :arg parent: ID of parent document :arg refresh: Refresh the index after performing the operation - :arg replication: Specific replication type, default u'sync' + :arg replication: Specific replication type (default: sync) :arg routing: Specific routing value :arg timeout: Explicit operation timeout :arg version: Explicit version number for concurrency control :arg version_type: Specific version type """ try: - status, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, id), params=params) + _, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, id), params=params) except NotFoundError: if ignore_missing: return @@ -343,25 +387,28 @@ class Elasticsearch(object): @query_params('ignore_indices', 'min_score', 'preference', 'routing', 'source') def count(self, index=None, doc_type=None, body=None, params=None): """ - The count API allows to easily execute a query and get the number of matches for that query. + Execute a query and get the number of matches for that query. http://elasticsearch.org/guide/reference/api/count/ :arg index: A comma-separated list of indices to restrict the results :arg doc_type: A comma-separated list of types to restrict the results :arg body: A query to restrict the results (optional) - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg min_score: Include only documents with a specific `_score` value in the result - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg routing: Specific routing value :arg source: The URL-encoded query definition (instead of using the request body) """ - status, data = self.transport.perform_request('POST', _make_path(index, doc_type, '_count'), params=params, body=body) + _, data = self.transport.perform_request('POST', _make_path(index, doc_type, '_count'), + params=params, body=body) return data @query_params('consistency', 'refresh', 'replication') def bulk(self, body, index=None, doc_type=None, params=None): """ - The bulk API makes it possible to perform many index/delete operations in a single API call. + Perform many index/delete operations in a single API call. http://elasticsearch.org/guide/reference/api/bulk/ :arg body: The operation definition and data (action-data pairs) @@ -370,130 +417,166 @@ class Elasticsearch(object): :arg consistency: Explicit write consistency setting for the operation :arg doc_type: Default document type for items which don't provide one :arg refresh: Refresh the index after performing the operation - :arg replication: Explicitely set the replication type, default u'sync' + :arg replication: Explicitly set the replication type (efault: sync) """ - status, data = self.transport.perform_request('POST', _make_path(index, doc_type, '_bulk'), params=params, body=self._bulk_body(body)) + _, data = self.transport.perform_request('POST', _make_path(index, doc_type, '_bulk'), + params=params, body=self._bulk_body(body)) return data @query_params('search_type') def msearch(self, body, index=None, doc_type=None, params=None): """ - The multi search API allows to execute several search requests within the same API. + Execute several search requests within the same API. http://www.elasticsearch.org/guide/reference/api/multi-search/ - :arg body: The request definitions (metadata-search request definition pairs), separated by newlines + :arg body: The request definitions (metadata-search request definition + pairs), separated by newlines :arg index: A comma-separated list of index names to use as default :arg doc_type: A comma-separated list of document types to use as default :arg search_type: Search operation type """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_msearch'), params=params, body=self._bulk_body(body)) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_msearch'), + params=params, body=self._bulk_body(body)) return data @query_params('consistency', 'ignore_indices', 'replication', 'routing', 'source', 'timeout') def delete_by_query(self, index, doc_type=None, body=None, params=None): """ - The delete by query API allows to delete documents from one or more indices and one or more types based on a query. + Delete documents from one or more indices and one or more types based on a query. http://www.elasticsearch.org/guide/reference/api/delete-by-query/ :arg index: A comma-separated list of indices to restrict the operation :arg doc_type: A comma-separated list of types to restrict the operation :arg body: A query to restrict the operation :arg consistency: Specific write consistency setting for the operation - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' - :arg replication: Specific replication type, default u'sync' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) + :arg replication: Specific replication type (default: sync) :arg routing: Specific routing value :arg source: The URL-encoded query definition (instead of using the request body) :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_query'), params=params, body=body) + _, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_query'), + params=params, body=body) return data @query_params('ignore_indices', 'preference', 'routing', 'source') def suggest(self, index=None, body=None, params=None): """ - The suggest feature suggests similar looking terms based on a provided text by using a suggester. + The suggest feature suggests similar looking terms based on a provided + text by using a suggester. http://elasticsearch.org/guide/reference/api/search/suggest/ - :arg index: A comma-separated list of index names to restrict the operation; use `_all` or empty string to perform the operation on all indices + :arg index: A comma-separated list of index names to restrict the operation; + use `_all` or empty string to perform the operation on all indices :arg body: The request definition - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg routing: Specific routing value :arg source: The URL-encoded request definition (instead of using request body) """ - status, data = self.transport.perform_request('POST', _make_path(index, '_suggest'), params=params, body=body) + _, data = self.transport.perform_request('POST', _make_path(index, '_suggest'), + params=params, body=body) return data @query_params('prefer_local') def percolate(self, index, doc_type, body, params=None): """ - The percolator allows to register queries against an index, and then send percolate requests which include a doc, and getting back the queries that match on that doc out of the set of registered queries. + Send a percolate request which include a doc, and get back the queries + that match on that doc out of the set of registered queries. http://elasticsearch.org/guide/reference/api/percolate/ :arg index: The name of the index with a registered percolator query :arg doc_type: The document type - :arg body: The document (`doc`) to percolate against registered queries; optionally also a `query` to limit the percolation to specific registered queries - :arg prefer_local: With `true`, specify that a local shard should be used if available, with `false`, use a random shard (default: true) + :arg body: The document (`doc`) to percolate against registered queries; + optionally also a `query` to limit the percolation to specific registered queries + :arg prefer_local: With `true`, specify that a local shard should be + used if available, with `false`, use a random shard (default: true) """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_percolate'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_percolate'), + params=params, body=body) return data - @query_params('boost_terms', 'max_doc_freq', 'max_query_terms', 'max_word_len', 'min_doc_freq', 'min_term_freq', 'min_word_len', 'mlt_fields', 'percent_terms_to_match', 'routing', 'search_from', 'search_indices', 'search_query_hint', 'search_scroll', 'search_size', 'search_source', 'search_type', 'search_types', 'stop_words') + @query_params('boost_terms', 'max_doc_freq', 'max_query_terms', + 'max_word_len', 'min_doc_freq', 'min_term_freq', 'min_word_len', + 'mlt_fields', 'percent_terms_to_match', 'routing', 'search_from', + 'search_indices', 'search_query_hint', 'search_scroll', 'search_size', + 'search_source', 'search_type', 'search_types', 'stop_words') def mlt(self, index, doc_type, id, body=None, params=None): """ - The more like this (mlt) API allows to get documents that are "like" a specified document. + Get documents that are "like" a specified document. http://elasticsearch.org/guide/reference/api/more-like-this/ :arg index: The name of the index - :arg doc_type: The type of the document (use `_all` to fetch the first document matching the ID across all types) + :arg doc_type: The type of the document (use `_all` to fetch the first + document matching the ID across all types) :arg id: The document ID :arg body: A specific search request definition :arg boost_terms: The boost factor - :arg max_doc_freq: The word occurrence frequency as count: words with higher occurrence in the corpus will be ignored + :arg max_doc_freq: The word occurrence frequency as count: words with + higher occurrence in the corpus will be ignored :arg max_query_terms: The maximum query terms to be included in the generated query :arg max_word_len: The minimum length of the word: longer words will be ignored - :arg min_doc_freq: The word occurrence frequency as count: words with lower occurrence in the corpus will be ignored - :arg min_term_freq: The term frequency as percent: terms with lower occurence in the source document will be ignored + :arg min_doc_freq: The word occurrence frequency as count: words with + lower occurrence in the corpus will be ignored + :arg min_term_freq: The term frequency as percent: terms with lower + occurence in the source document will be ignored :arg min_word_len: The minimum length of the word: shorter words will be ignored :arg mlt_fields: Specific fields to perform the query against - :arg percent_terms_to_match: How many terms have to match in order to consider the document a match (default: 0.3) + :arg percent_terms_to_match: How many terms have to match in order to + consider the document a match (default: 0.3) :arg routing: Specific routing value :arg search_from: The offset from which to return results - :arg search_indices: A comma-separated list of indices to perform the query against (default: the index containing the document) + :arg search_indices: A comma-separated list of indices to perform the + query against (default: the index containing the document) :arg search_query_hint: The search query hint :arg search_scroll: A scroll search request definition :arg search_size: The number of documents to return (default: 10) - :arg search_source: A specific search request definition (instead of using the request body) + :arg search_source: A specific search request definition (instead of + using the request body) :arg search_type: Specific search type (eg. `dfs_then_fetch`, `count`, etc) - :arg search_types: A comma-separated list of types to perform the query against (default: the same type as the document) + :arg search_types: A comma-separated list of types to perform the query + against (default: the same type as the document) :arg stop_words: A list of stop words to be ignored """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_mlt'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_mlt'), + params=params, body=body) return data - @query_params('analyze_wildcard', 'analyzer', 'default_operator', 'df', 'fields', 'lenient', 'lowercase_expanded_terms', 'parent', 'preference', 'q', 'routing', 'source') + @query_params('analyze_wildcard', 'analyzer', 'default_operator', 'df', + 'fields', 'lenient', 'lowercase_expanded_terms', 'parent', 'preference', + 'q', 'routing', 'source') def explain(self, index, doc_type, id, body, params=None): """ - The explain api computes a score explanation for a query and a specific document. + Computes a score explanation for a query and a specific document and + presents the calculation. http://elasticsearch.org/guide/reference/api/explain/ :arg index: The name of the index :arg doc_type: The type of the document :arg id: The document ID :arg body: The query definition using the Query DSL - :arg analyze_wildcard: Specify whether wildcards and prefix queries in the query string query should be analyzed (default: false) + :arg analyze_wildcard: Specify whether wildcards and prefix queries in + the query string query should be analyzed (default: false) :arg analyzer: The analyzer for the query string query - :arg default_operator: The default operator for query string query (AND or OR), default u'OR' + :arg default_operator: The default operator for query string query (AND + or OR) (default: OR) :arg df: The default field for query string query (default: _all) :arg fields: A comma-separated list of fields to return in the response - :arg lenient: Specify whether format-based query failures (such as providing text to a numeric field) should be ignored + :arg lenient: Specify whether format-based query failures (such as + providing text to a numeric field) should be ignored :arg lowercase_expanded_terms: Specify whether query terms should be lowercased :arg parent: The ID of the parent document - :arg preference: Specify the node or shard the operation should be performed on (default: random) + :arg preference: Specify the node or shard the operation should be + performed on (default: random) :arg q: Query in the Lucene query string syntax :arg routing: Specific routing value - :arg source: The URL-encoded query definition (instead of using the request body) + :arg source: The URL-encoded query definition (instead of using the + request body) """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_explain'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, id, '_explain'), + params=params, body=body) return data diff --git a/elasticsearch/client/cluster.py b/elasticsearch/client/cluster.py index 3372aa03..8aa9511b 100644 --- a/elasticsearch/client/cluster.py +++ b/elasticsearch/client/cluster.py @@ -1,10 +1,12 @@ from .utils import NamespacedClient, query_params, _make_path class ClusterClient(NamespacedClient): - @query_params('level', 'local', 'master_timeout', 'timeout', 'wait_for_active_shards', 'wait_for_nodes', 'wait_for_relocating_shards', 'wait_for_status') + @query_params('level', 'local', 'master_timeout', 'timeout', + 'wait_for_active_shards', 'wait_for_nodes', 'wait_for_relocating_shards', + 'wait_for_status') def health(self, index=None, params=None): """ - The cluster health API allows to get a very simple status on the health of the cluster. + Get a very simple status on the health of the cluster. http://elasticsearch.org/guide/reference/api/admin-cluster-health/ :arg index: Limit the information returned to a specific index @@ -17,13 +19,16 @@ class ClusterClient(NamespacedClient): :arg wait_for_relocating_shards: Wait until the specified number of relocating shards is finished :arg wait_for_status: Wait until cluster is in a specific state, default None """ - status, data = self.transport.perform_request('GET', _make_path('_cluster', 'health', index), params=params) + _, data = self.transport.perform_request('GET', _make_path('_cluster', 'health', index), + params=params) return data - @query_params('filter_blocks', 'filter_index_templates', 'filter_indices', 'filter_metadata', 'filter_nodes', 'filter_routing_table', 'local', 'master_timeout') + @query_params('filter_blocks', 'filter_index_templates', 'filter_indices', + 'filter_metadata', 'filter_nodes', 'filter_routing_table', 'local', + 'master_timeout') def state(self, params=None): """ - The cluster state API allows to get a comprehensive state information of the whole cluster. + Get a comprehensive state information of the whole cluster. http://elasticsearch.org/guide/reference/api/admin-cluster-state/ :arg filter_blocks: Do not return information about blocks @@ -35,52 +40,57 @@ class ClusterClient(NamespacedClient): :arg local: Return local information, do not retrieve the state from master node (default: false) :arg master_timeout: Specify timeout for connection to master """ - status, data = self.transport.perform_request('GET', _make_path('_cluster', 'state'), params=params) + _, data = self.transport.perform_request('GET', '/_cluster/state', params=params) return data @query_params('dry_run', 'filter_metadata') def reroute(self, body=None, params=None): """ - The reroute command allows to explicitly execute a cluster reroute allocation command including specific commands. + Explicitly execute a cluster reroute allocation command including specific commands. http://elasticsearch.org/guide/reference/api/admin-cluster-reroute/ :arg body: The definition of `commands` to perform (`move`, `cancel`, `allocate`) :arg dry_run: Simulate the operation only and return the resulting state :arg filter_metadata: Don't return cluster state metadata (default: false) """ - status, data = self.transport.perform_request('POST', _make_path('_cluster', 'reroute'), params=params, body=body) + _, data = self.transport.perform_request('POST', '/_cluster/reroute', params=params, body=body) return data @query_params() def get_settings(self, params=None): """ - Allows to update cluster wide specific settings. + Get cluster settings. http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/ """ - status, data = self.transport.perform_request('GET', _make_path('_cluster', 'settings'), params=params) + _, data = self.transport.perform_request('GET', '/_cluster/settings', params=params) return data @query_params() def put_settings(self, body, params=None): """ - Allows to update cluster wide specific settings. + Update cluster wide specific settings. http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/ - :arg body: The settings to be updated. Can be either `transient` or `persistent` (survives cluster restart). + :arg body: The settings to be updated. Can be either `transient` or + `persistent` (survives cluster restart). """ - status, data = self.transport.perform_request('PUT', _make_path('_cluster', 'settings'), params=params, body=body) + _, data = self.transport.perform_request('PUT', '/_cluster/settings', params=params, body=body) return data - @query_params('all', 'clear', 'fields', 'fs', 'http', 'indices', 'jvm', 'network', 'os', 'process', 'thread_pool', 'transport') + @query_params('all', 'clear', 'fields', 'fs', 'http', 'indices', 'jvm', + 'network', 'os', 'process', 'thread_pool', 'transport') def node_stats(self, node_id=None, metric=None, fields=None, params=None): """ - The cluster nodes stats API allows to retrieve one or more (or all) of the cluster nodes statistics. + Retrieve one or more (or all) of the cluster nodes statistics. http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-stats/ - :arg node_id: A comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes + :arg node_id: A comma-separated list of node IDs or names to limit the + returned information; use `_local` to return information from the node + you're connecting to, leave empty to get information from all nodes :arg metric: Limit the information returned for `indices` family to a specific metric - :arg fields: A comma-separated list of fields to return detailed information for, when returning the `indices` metric family (supports wildcards) + :arg fields: A comma-separated list of fields to return detailed information + for, when returning the `indices` metric family (supports wildcards) :arg all: Return all available information :arg clear: Reset the default level of detail :arg fields: A comma-separated list of fields for `fielddata` metric (supports wildcards) @@ -94,16 +104,20 @@ class ClusterClient(NamespacedClient): :arg thread_pool: Return information about the thread pool :arg transport: Return information about transport """ - status, data = self.transport.perform_request('GET', _make_path('_nodes', node_id, 'stats', metric, fields), params=params) + _, data = self.transport.perform_request('GET', + _make_path('_nodes', node_id, 'stats', metric, fields), params=params) return data - @query_params('all', 'clear', 'http', 'jvm', 'network', 'os', 'plugin', 'process', 'settings', 'thread_pool', 'timeout', 'transport') + @query_params('all', 'clear', 'http', 'jvm', 'network', 'os', 'plugin', + 'process', 'settings', 'thread_pool', 'timeout', 'transport') def node_info(self, node_id=None, params=None): """ - The cluster nodes info API allows to retrieve one or more (or all) of the cluster nodes information. + Retrieve one or more (or all) of the cluster nodes' information. http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-info/ - :arg node_id: A comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes + :arg node_id: A comma-separated list of node IDs or names to limit the + returned information; use `_local` to return information from the node + you're connecting to, leave empty to get information from all nodes :arg all: Return all available information :arg clear: Reset the default settings :arg http: Return information about HTTP @@ -117,19 +131,23 @@ class ClusterClient(NamespacedClient): :arg timeout: Explicit operation timeout :arg transport: Return information about transport """ - status, data = self.transport.perform_request('GET', _make_path('_cluster', 'nodes', node_id), params=params) + _, data = self.transport.perform_request('GET', + _make_path('_cluster', 'nodes', node_id), params=params) return data @query_params('delay', 'exit') def node_shutdown(self, node_id=None, params=None): """ - The nodes shutdown API allows to shutdown one or more (or all) nodes in the cluster. + Shutdown one or more (or all) nodes in the cluster. http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-shutdown/ - :arg node_id: A comma-separated list of node IDs or names to perform the operation on; use `_local` to perform the operation on the node you're connected to, leave empty to perform the operation on all nodes + :arg node_id: A comma-separated list of node IDs or names to perform + the operation on; use `_local` to perform the operation on the node + you're connected to, leave empty to perform the operation on all nodes :arg delay: Set the delay for the operation (default: 1s) :arg exit: Exit the JVM as well (default: true) """ - status, data = self.transport.perform_request('POST', _make_path('_cluster', 'nodes', node_id, '_shutdown'), params=params) + _, data = self.transport.perform_request('POST', + _make_path('_cluster', 'nodes', node_id, '_shutdown'), params=params) return data diff --git a/elasticsearch/client/indices.py b/elasticsearch/client/indices.py index 21ca0a38..6fd8144d 100644 --- a/elasticsearch/client/indices.py +++ b/elasticsearch/client/indices.py @@ -2,57 +2,69 @@ from .utils import NamespacedClient, query_params, _make_path from ..exceptions import NotFoundError class IndicesClient(NamespacedClient): - @query_params('analyzer', 'field', 'filters', 'format', 'index', 'prefer_local', 'text', 'tokenizer') + @query_params('analyzer', 'field', 'filters', 'format', 'index', + 'prefer_local', 'text', 'tokenizer') def analyze(self, index=None, body=None, params=None): """ - Performs the analysis process on a text and return the tokens breakdown of the text. + Perform the analysis process on a text and return the tokens breakdown of the text. http://www.elasticsearch.org/guide/reference/api/admin-indices-analyze/ :arg index: The name of the index to scope the operation :arg body: The text on which the analysis should be performed :arg analyzer: The name of the analyzer to use - :arg field: Use the analyzer configured for this field (instead of passing the analyzer name) + :arg field: Use the analyzer configured for this field (instead of + passing the analyzer name) :arg filters: A comma-separated list of filters to use for the analysis :arg format: Format of the output, default u'detailed' :arg index: The name of the index to scope the operation - :arg prefer_local: With `true`, specify that a local shard should be used if available, with `false`, use a random shard (default: true) - :arg text: The text on which the analysis should be performed (when request body is not used) + :arg prefer_local: With `true`, specify that a local shard should be + used if available, with `false`, use a random shard (default: true) + :arg text: The text on which the analysis should be performed (when + request body is not used) :arg tokenizer: The name of the tokenizer to use for the analysis """ - status, data = self.transport.perform_request('GET', _make_path(index, '_analyze'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, '_analyze'), + params=params, body=body) return data @query_params('ignore_indices') def refresh(self, index=None, params=None): """ - The refresh API allows to explicitly refresh one or more index, making all operations performed since the last refresh available for search. + Explicitly refresh one or more index, making all operations performed + since the last refresh available for search. http://www.elasticsearch.org/guide/reference/api/admin-indices-refresh/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones, default u'none' """ - status, data = self.transport.perform_request('POST', _make_path(index, '_refresh'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_refresh'), + params=params) return data @query_params('force', 'full', 'ignore_indices', 'refresh') def flush(self, index=None, params=None): """ - The flush API allows to flush one or more indices through an API. + Explicitly flush one or more indices. http://www.elasticsearch.org/guide/reference/api/admin-indices-flush/ - :arg index: A comma-separated list of index names; use `_all` or empty string for all indices + :arg index: A comma-separated list of index names; use `_all` or empty + string for all indices :arg force: TODO: ? :arg full: TODO: ? - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg refresh: Refresh the index after performing the operation """ - status, data = self.transport.perform_request('POST', _make_path(index, '_flush'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_flush'), + params=params) return data @query_params('timeout', 'master_timeout') def create(self, index, body=None, params=None): """ - Create index in Elasticsearch. + Create an index in Elasticsearch. http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index/ :arg index: The name of the index @@ -60,51 +72,58 @@ class IndicesClient(NamespacedClient): :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('PUT', _make_path(index), params=params, body=body) + _, data = self.transport.perform_request('PUT', _make_path(index), + params=params, body=body) return data @query_params('timeout', 'master_timeout') def open(self, index, params=None): """ - The open and close index APIs allow to close an index, and later on opening it. + Open a closed index to make it available for search. http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/ :arg index: The name of the index :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('POST', _make_path(index, '_open'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_open'), + params=params) return data @query_params('timeout', 'master_timeout') def close(self, index, params=None): """ - The open and close index APIs allow to close an index, and later on opening it. + Close an index to remove it's overhead from the cluster. Closed index + is blocked for read/write operations. http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/ :arg index: The name of the index :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('POST', _make_path(index, '_close'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_close'), + params=params) return data @query_params('timeout', 'master_timeout') def delete(self, index=None, params=None): """ - Delete index in Elasticsearch + Delete an index in Elasticsearch http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-index/ - :arg index: A comma-separated list of indices to delete; use `_all` or empty string to delete all indices + :arg index: A comma-separated list of indices to delete; use `_all` or + empty string to delete all indices :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('DELETE', _make_path(index), params=params) + _, data = self.transport.perform_request('DELETE', _make_path(index), + params=params) return data @query_params() def exists(self, index, params=None): """ + Return a boolean indicating whether given index exists. http://www.elasticsearch.org/guide/reference/api/admin-indices-indices-exists/ :arg index: A list of indices to check @@ -118,12 +137,14 @@ class IndicesClient(NamespacedClient): @query_params('ignore_indices') def exists_type(self, index, doc_type, params=None): """ - Used to check if a type/types exists in an index/indices (available since 0. + Check if a type/types exists in an index/indices. http://www.elasticsearch.org/guide/reference/api/admin-indices-types-exists/ - :arg index: A comma-separated list of index names; use `_all` to check the types across all indices + :arg index: A comma-separated list of index names; use `_all` to check + the types across all indices :arg doc_type: A comma-separated list of document types to check - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) """ try: self.transport.perform_request('HEAD', _make_path(index, doc_type), params=params) @@ -134,60 +155,69 @@ class IndicesClient(NamespacedClient): @query_params('ignore_indices') def snapshot_index(self, index=None, params=None): """ - The gateway snapshot API allows to explicitly perform a snapshot through the gateway of one or more indices (backup them). + Explicitly perform a snapshot through the gateway of one or more indices (backup them). http://www.elasticsearch.org/guide/reference/api/admin-indices-gateway-snapshot/ - :arg index: A comma-separated list of index names; use `_all` or empty string for all indices - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg index: A comma-separated list of index names; use `_all` or empty + string for all indices + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) """ - status, data = self.transport.perform_request('POST', _make_path(index, '_gateway', 'snapshot'), params=params) + _, data = self.transport.perform_request('POST', + _make_path(index, '_gateway', 'snapshot'), params=params) return data @query_params('ignore_conflicts', 'timeout', 'master_timeout') def put_mapping(self, index, doc_type, body, params=None): """ - The put mapping API allows to register specific mapping definition for a specific type. + Register specific mapping definition for a specific type. http://www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/ - :arg index: A comma-separated list of index names; use `_all` to perform the operation on all indices + :arg index: A comma-separated list of index names; use `_all` to + perform the operation on all indices :arg doc_type: The name of the document type :arg body: The mapping definition - :arg ignore_conflicts: Specify whether to ignore conflicts while updating the mapping (default: false) + :arg ignore_conflicts: Specify whether to ignore conflicts while + updating the mapping (default: false) :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('PUT', _make_path(index, doc_type, '_mapping'), params=params, body=body) + _, data = self.transport.perform_request('PUT', _make_path(index, doc_type, '_mapping'), + params=params, body=body) return data @query_params() def get_mapping(self, index=None, doc_type=None, params=None): """ - The get mapping API allows to retrieve mapping definition of index or index/type. + Retrieve mapping definition of index or index/type. http://www.elasticsearch.org/guide/reference/api/admin-indices-get-mapping/ - :arg index: A comma-separated list of index names; use `_all` or empty string for all indices + :arg index: A comma-separated list of index names; use `_all` or empty + string for all indices :arg doc_type: A comma-separated list of document types """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_mapping'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_mapping'), + params=params) return data @query_params('master_timeout') def delete_mapping(self, index, doc_type, params=None): """ - Allow to delete a mapping (type) along with its data. + Delete a mapping (type) along with its data. http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-mapping/ :arg index: A comma-separated list of index names; use `_all` for all indices :arg doc_type: The name of the document type to delete :arg master_timeout: Specify timeout for connection to master """ - status, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_mapping'), params=params) + _, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_mapping'), + params=params) return data @query_params('timeout', 'master_timeout') def put_alias(self, index, name, body=None, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Create an alias for a specific index/indices. http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg index: The name of the index with an alias @@ -196,21 +226,24 @@ class IndicesClient(NamespacedClient): :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit timestamp for the document """ - status, data = self.transport.perform_request('PUT', _make_path(index, '_alias', name), params=params, body=body) + _, data = self.transport.perform_request('PUT', _make_path(index, '_alias', name), + params=params, body=body) return data @query_params('ignore_indices') def exists_alias(self, name, index=None, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Return a boolean indicating whether given alias exists. http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg name: A comma-separated list of alias names to return :arg index: A comma-separated list of index names to filter aliases - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) """ try: - self.transport.perform_request('HEAD', _make_path(index, '_alias', name), params=params) + self.transport.perform_request('HEAD', _make_path(index, '_alias', name), + params=params) except NotFoundError: return False return True @@ -218,45 +251,49 @@ class IndicesClient(NamespacedClient): @query_params('ignore_indices') def get_alias(self, name, index=None, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Retrieve a specified alias. http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg name: A comma-separated list of alias names to return :arg index: A comma-separated list of index names to filter aliases - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones, default u'none' """ - status, data = self.transport.perform_request('GET', _make_path(index, '_alias', name), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_alias', name), + params=params) return data @query_params('timeout') def get_aliases(self, index=None, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Retrieve specified aliases http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg index: A comma-separated list of index names to filter aliases :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('GET', _make_path(index, '_aliases'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_aliases'), + params=params) return data @query_params('timeout', 'master_timeout') def update_aliases(self, body, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Update specified aliases. http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg body: The definition of `actions` to perform :arg master_timeout: Specify timeout for connection to master :arg timeout: Request timeout """ - status, data = self.transport.perform_request('POST', _make_path('_aliases'), params=params, body=body) + _, data = self.transport.perform_request('POST', '/_aliases', + params=params, body=body) return data @query_params('timeout', 'master_timeout') def delete_alias(self, index, name, params=None): """ - APIs in elasticsearch accept an index name when working against a specific index, and several indices when applicable. + Delete specific alias. http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/ :arg index: The name of the index with an alias @@ -264,57 +301,65 @@ class IndicesClient(NamespacedClient): :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit timestamp for the document """ - status, data = self.transport.perform_request('DELETE', _make_path(index, '_alias', name), params=params) - return data - - @query_params('timeout', 'master_timeout') - def delete_template(self, name, params=None): - """ - Index templates allow to define templates that will automatically be applied to new indices created. - http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/ - - :arg name: The name of the template - :arg master_timeout: Specify timeout for connection to master - :arg timeout: Explicit operation timeout - """ - status, data = self.transport.perform_request('DELETE', _make_path('_template', name), params=params) + _, data = self.transport.perform_request('DELETE', _make_path(index, '_alias', name), + params=params) return data @query_params('order', 'timeout', 'master_timeout') def put_template(self, name, body, params=None): """ - Index templates allow to define templates that will automatically be applied to new indices created. + Create an index template that will automatically be applied to new + indices created. http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/ :arg name: The name of the template :arg body: The template definition - :arg order: The order for this template when merging multiple matching ones (higher numbers are merged later, overriding the lower numbers) + :arg order: The order for this template when merging multiple matching + ones (higher numbers are merged later, overriding the lower numbers) :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout """ - status, data = self.transport.perform_request('PUT', _make_path('_template', name), params=params, body=body) + _, data = self.transport.perform_request('PUT', _make_path('_template', name), + params=params, body=body) return data @query_params() def get_template(self, name, params=None): """ - Index templates allow to define templates that will automatically be applied to new indices created. + Retrieve an index template by its name. http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/ :arg name: The name of the template """ - status, data = self.transport.perform_request('GET', _make_path('_template', name), params=params) + _, data = self.transport.perform_request('GET', _make_path('_template', name), + params=params) + return data + + @query_params('timeout', 'master_timeout') + def delete_template(self, name, params=None): + """ + Delete an index template by its name. + http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/ + + :arg name: The name of the template + :arg master_timeout: Specify timeout for connection to master + :arg timeout: Explicit operation timeout + """ + _, data = self.transport.perform_request('DELETE', _make_path('_template', name), + params=params) return data @query_params() def get_settings(self, index=None, params=None): """ - The get settings API allows to retrieve settings of index/indices. + Retrieve settings for one or more (or all) indices. http://www.elasticsearch.org/guide/reference/api/admin-indices-get-settings/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices """ - status, data = self.transport.perform_request('GET', _make_path(index, '_settings'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_settings'), + params=params) return data @query_params('master_timeout') @@ -323,97 +368,118 @@ class IndicesClient(NamespacedClient): Change specific index level settings in real time. http://www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices :arg master_timeout: Specify timeout for connection to master :arg body: The index settings to be updated """ - status, data = self.transport.perform_request('PUT', _make_path(index, '_settings'), params=params, body=body) + _, data = self.transport.perform_request('PUT', _make_path(index, '_settings'), + params=params, body=body) return data @query_params('master_timeout') def put_warmer(self, index, name, body, doc_type=None, params=None): """ - Index warming allows to run registered search requests to warm up the index before it is available for search. + Create an index warmer to run registered search requests to warm up the + index before it is available for search. http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/ - :arg index: A comma-separated list of index names to register the warmer for; use `_all` or empty string to perform the operation on all indices + :arg index: A comma-separated list of index names to register the warmer for; + use `_all` or empty string to perform the operation on all indices :arg name: The name of the warmer - :arg doc_type: A comma-separated list of document types to register the warmer for; leave empty to perform the operation on all types + :arg doc_type: A comma-separated list of document types to register the + warmer for; leave empty to perform the operation on all types :arg body: The search request definition for the warmer (query, filters, facets, sorting, etc) :arg master_timeout: Specify timeout for connection to master """ - status, data = self.transport.perform_request('PUT', _make_path(index, doc_type, '_warmer', name), params=params, body=body) - return data - - @query_params('master_timeout') - def delete_warmer(self, index, doc_type=None, name=None, params=None): - """ - Index warming allows to run registered search requests to warm up the index before it is available for search. - http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/ - - :arg index: A comma-separated list of index names to register warmer for; use `_all` or empty string to perform the operation on all indices - :arg doc_type: A comma-separated list of document types to register warmer for; use `_all` or empty string to perform the operation on all types - :arg name: The name of the warmer (supports wildcards); leave empty to delete all warmers - :arg master_timeout: Specify timeout for connection to master - """ - status, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_warmer', name), params=params) + _, data = self.transport.perform_request('PUT', _make_path(index, doc_type, '_warmer', name), + params=params, body=body) return data @query_params() def get_warmer(self, index, doc_type=None, name=None, params=None): """ - Index warming allows to run registered search requests to warm up the index before it is available for search. + Retreieve an index warmer. http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/ - :arg index: A comma-separated list of index names to restrict the operation; use `_all` to perform the operation on all indices - :arg doc_type: A comma-separated list of document types to restrict the operation; leave empty to perform the operation on all types + :arg index: A comma-separated list of index names to restrict the + operation; use `_all` to perform the operation on all indices + :arg doc_type: A comma-separated list of document types to restrict the + operation; leave empty to perform the operation on all types :arg name: The name of the warmer (supports wildcards); leave empty to get all warmers """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_warmer', name), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_warmer', name), params=params) + return data + + @query_params('master_timeout') + def delete_warmer(self, index, doc_type=None, name=None, params=None): + """ + Delete an index warmer. + http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/ + + :arg index: A comma-separated list of index names to register warmer + for; use `_all` or empty string to perform the operation on all indices + :arg doc_type: A comma-separated list of document types to register warmer for; + use `_all` or empty string to perform the operation on all types + :arg name: The name of the warmer (supports wildcards); leave empty to delete all warmers + :arg master_timeout: Specify timeout for connection to master + """ + _, data = self.transport.perform_request('DELETE', _make_path(index, doc_type, '_warmer', name), + params=params) return data @query_params('ignore_indices', 'operation_threading', 'recovery', 'snapshot') def status(self, index=None, params=None): """ - The indices status API allows to get a comprehensive status information of one or more indices. - http://elasticsearch.org/guide/reference/api/admin-indices-status/ + Get a comprehensive status information of one or more indices. + http://elasticsearch.org/guide/reference/api/admin-indices-_/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones, default u'none' :arg operation_threading: TODO: ? :arg recovery: Return information about shard recovery :arg snapshot: TODO: ? """ - status, data = self.transport.perform_request('GET', _make_path(index, '_status'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_status'), + params=params) return data - @query_params('all', 'clear', 'docs', 'fielddata', 'fields', 'filter_cache', 'flush', 'get', 'groups', 'id_cache', 'ignore_indices', 'indexing', 'merge', 'refresh', 'search', 'store', 'warmer') + @query_params('all', 'clear', 'docs', 'fielddata', 'fields', + 'filter_cache', 'flush', 'get', 'groups', 'id_cache', 'ignore_indices', + 'indexing', 'merge', 'refresh', 'search', 'store', 'warmer') def stats(self, index=None, metric_family=None, params=None): """ - Indices level stats provide statistics on different operations happening on an index. + Retrieve statistics on different operations happening on an index. http://elasticsearch.org/guide/reference/api/admin-indices-stats/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices :arg metric_family: Limit the information returned to a specific metric :arg all: Return all available information :arg clear: Reset the default level of detail :arg docs: Return information about indexed and deleted documents :arg fielddata: Return information about field data - :arg fields: A comma-separated list of fields for `fielddata` metric (supports wildcards) + :arg fields: A comma-separated list of fields for `fielddata` metric + (supports wildcards) :arg filter_cache: Return information about filter cache :arg flush: Return information about flush operations :arg get: Return information about get operations :arg groups: A comma-separated list of search groups for `search` statistics :arg id_cache: Return information about ID cache - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg indexing: Return information about indexing operations :arg merge: Return information about merge operations :arg refresh: Return information about refresh operations - :arg search: Return information about search operations; use the `groups` parameter to include information for specific search groups + :arg search: Return information about search operations; use the + `groups` parameter to include information for specific search groups :arg store: Return information about the size of the index :arg warmer: Return information about warmers """ - status, data = self.transport.perform_request('GET', _make_path(index, '_stats', metric_family), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_stats', metric_family), + params=params) return data @query_params('ignore_indices', 'operation_threading') @@ -422,68 +488,89 @@ class IndicesClient(NamespacedClient): Provide low level segments information that a Lucene index (shard level) is built with. http://elasticsearch.org/guide/reference/api/admin-indices-segments/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones, default u'none' :arg operation_threading: TODO: ? """ - status, data = self.transport.perform_request('GET', _make_path(index, '_segments'), params=params) + _, data = self.transport.perform_request('GET', _make_path(index, '_segments'), params=params) return data - @query_params('flush', 'ignore_indices', 'max_num_segments', 'only_expunge_deletes', 'operation_threading', 'refresh', 'wait_for_merge') + @query_params('flush', 'ignore_indices', 'max_num_segments', + 'only_expunge_deletes', 'operation_threading', 'refresh', 'wait_for_merge') def optimize(self, index=None, params=None): """ - The optimize API allows to optimize one or more indices through an API. + Explicitly optimize one or more indices through an API. http://www.elasticsearch.org/guide/reference/api/admin-indices-optimize/ - :arg index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :arg flush: Specify whether the index should be flushed after performing the operation (default: true) - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' - :arg max_num_segments: The number of segments the index should be merged into (default: dynamic) - :arg only_expunge_deletes: Specify whether the operation should only expunge deleted documents + :arg index: A comma-separated list of index names; use `_all` or empty + string to perform the operation on all indices + :arg flush: Specify whether the index should be flushed after + performing the operation (default: true) + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones, default u'none' + :arg max_num_segments: The number of segments the index should be + merged into (default: dynamic) + :arg only_expunge_deletes: Specify whether the operation should only + expunge deleted documents :arg operation_threading: TODO: ? - :arg refresh: Specify whether the index should be refreshed after performing the operation (default: true) - :arg wait_for_merge: Specify whether the request should block until the merge process is finished (default: true) + :arg refresh: Specify whether the index should be refreshed after + performing the operation (default: true) + :arg wait_for_merge: Specify whether the request should block until the + merge process is finished (default: true) """ - status, data = self.transport.perform_request('POST', _make_path(index, '_optimize'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_optimize'), params=params) return data @query_params('explain', 'ignore_indices', 'operation_threading', 'q', 'source') def validate_query(self, index=None, doc_type=None, body=None, params=None): """ - The validate API allows a user to validate a potentially expensive query without executing it. + Validate a potentially expensive query without executing it. http://www.elasticsearch.org/guide/reference/api/validate/ - :arg index: A comma-separated list of index names to restrict the operation; use `_all` or empty string to perform the operation on all indices - :arg doc_type: A comma-separated list of document types to restrict the operation; leave empty to perform the operation on all types + :arg index: A comma-separated list of index names to restrict the operation; + use `_all` or empty string to perform the operation on all indices + :arg doc_type: A comma-separated list of document types to restrict the + operation; leave empty to perform the operation on all types :arg body: The query definition :arg explain: Return detailed information about the error - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg operation_threading: TODO: ? :arg q: Query in the Lucene query string syntax - :arg source: The URL-encoded query definition (instead of using the request body) + :arg source: The URL-encoded query definition (instead of using the + request body) """ - status, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_validate', 'query'), params=params, body=body) + _, data = self.transport.perform_request('GET', _make_path(index, doc_type, '_validate', 'query'), + params=params, body=body) return data - @query_params('field_data', 'fielddata', 'fields', 'filter', 'filter_cache', 'filter_keys', 'id', 'id_cache', 'ignore_indices', 'index', 'recycler') + @query_params('field_data', 'fielddata', 'fields', 'filter', + 'filter_cache', 'filter_keys', 'id', 'id_cache', 'ignore_indices', 'index', + 'recycler') def clear_cache(self, index=None, params=None): """ - The clear cache API allows to clear either all caches or specific cached associated with one ore more indices. + Clear either all caches or specific cached associated with one ore more indices. http://www.elasticsearch.org/guide/reference/api/admin-indices-clearcache/ :arg index: A comma-separated list of index name to limit the operation :arg field_data: Clear field data :arg fielddata: Clear field data - :arg fields: A comma-separated list of fields to clear when using the `field_data` parameter (default: all) + :arg fields: A comma-separated list of fields to clear when using the + `field_data` parameter (default: all) :arg filter: Clear filter caches :arg filter_cache: Clear filter caches - :arg filter_keys: A comma-separated list of keys to clear when using the `filter_cache` parameter (default: all) + :arg filter_keys: A comma-separated list of keys to clear when using + the `filter_cache` parameter (default: all) :arg id: Clear ID caches for parent/child :arg id_cache: Clear ID caches for parent/child - :arg ignore_indices: When performed on multiple indices, allows to ignore `missing` ones, default u'none' + :arg ignore_indices: When performed on multiple indices, allows to + ignore `missing` ones (default: none) :arg index: A comma-separated list of index name to limit the operation :arg recycler: Clear the recycler cache """ - status, data = self.transport.perform_request('POST', _make_path(index, '_cache', 'clear'), params=params) + _, data = self.transport.perform_request('POST', _make_path(index, '_cache', 'clear'), + params=params) return data