pandagg.search module¶
-
class
pandagg.search.
MultiSearch
(**kwargs)[source]¶ Bases:
pandagg.search.Request
Combine multiple
Search
objects into a single request.
-
class
pandagg.search.
Request
(using, index=None)[source]¶ Bases:
object
-
index
(*index)[source]¶ Set the index for the search. If called empty it will remove all information.
Example:
s = Search() s = s.index(‘twitter-2015.01.01’, ‘twitter-2015.01.02’) s = s.index([‘twitter-2015.01.01’, ‘twitter-2015.01.02’])
-
params
(**kwargs)[source]¶ Specify query params to be used when executing the search. All the keyword arguments will override the current values. See https://elasticsearch-py.readthedocs.io/en/master/api.html#elasticsearch.Elasticsearch.search for all available parameters.
Example:
s = Search() s = s.params(routing='user-1', preference='local')
-
-
class
pandagg.search.
Search
(using=None, index=None, mappings=None, nested_autocorrect=False, repr_auto_execute=False)[source]¶ Bases:
pandagg.utils.DSLMixin
,pandagg.search.Request
-
agg
(name, type_or_agg=None, insert_below=None, at_root=False, **body)[source]¶ Insert provided agg clause in copy of initial Aggs.
Accept following syntaxes for type_or_agg argument:
string, with body provided in kwargs >>> Aggs().agg(name=’some_agg’, type_or_agg=’terms’, field=’some_field’)
python dict format: >>> Aggs().agg(name=’some_agg’, type_or_agg={‘terms’: {‘field’: ‘some_field’})
AggClause instance: >>> from pandagg.aggs import Terms >>> Aggs().agg(name=’some_agg’, type_or_agg=Terms(field=’some_field’))
Parameters: - name – inserted agg clause name
- type_or_agg – either agg type (str), or agg clause of dict format, or AggClause instance
- insert_below – name of aggregation below which provided aggs should be inserted
- at_root – if True, aggregation is inserted at root
- body – aggregation clause body when providing string type_of_agg (remaining kwargs)
Returns: copy of initial Aggs with provided agg inserted
-
aggs
(aggs, insert_below=None, at_root=False)[source]¶ Insert provided aggs in copy of initial Aggs.
Accept following syntaxes for provided aggs:
python dict format: >>> Aggs().aggs({‘some_agg’: {‘terms’: {‘field’: ‘some_field’}}, ‘other_agg’: {‘avg’: {‘field’: ‘age’}}})
Aggs instance: >>> Aggs().aggs(Aggs({‘some_agg’: {‘terms’: {‘field’: ‘some_field’}}, ‘other_agg’: {‘avg’: {‘field’: ‘age’}}}))
dict with Agg clauses values: >>> from pandagg.aggs import Terms, Avg >>> Aggs().aggs({‘some_agg’: Terms(field=’some_field’), ‘other_agg’: Avg(field=’age’)})
Parameters: - aggs – aggregations to insert into existing aggregation
- insert_below – name of aggregation below which provided aggs should be inserted
- at_root – if True, aggregation is inserted at root
Returns: copy of initial Aggs with provided aggs inserted
-
bool
(must=None, should=None, must_not=None, filter=None, insert_below=None, on=None, mode='add', **body)[source]¶ >>> Query().bool(must={"term": {"some_field": "yolo"}})
-
count
()[source]¶ Return the number of hits matching the query and filters. Note that only the actual number is returned.
-
exclude
(type_or_query, insert_below=None, on=None, mode='add', **body)[source]¶ Must not wrapped in filter context.
-
classmethod
from_dict
(d)[source]¶ Construct a new Search instance from a raw dict containing the search body. Useful when migrating from raw dictionaries.
Example:
s = Search.from_dict({ "query": { "bool": { "must": [...] } }, "aggs": {...} }) s = s.filter('term', published=True)
-
groupby
(name, type_or_agg=None, insert_below=None, at_root=None, **body)[source]¶ Insert provided aggregation clause in copy of initial Aggs.
Given the initial aggregation:
A──> B └──> C
If insert_below = ‘A’:
A──> new──> B └──> C
>>> Aggs().groupby('per_user_id', 'terms', field='user_id') {"per_user_id":{"terms":{"field":"user_id"}}}
>>> Aggs().groupby('per_user_id', {'terms': {"field": "user_id"}}) {"per_user_id":{"terms":{"field":"user_id"}}}
>>> from pandagg.aggs import Terms >>> Aggs().groupby('per_user_id', Terms(field="user_id")) {"per_user_id":{"terms":{"field":"user_id"}}}
Return type: pandagg.aggs.Aggs
-
highlight
(*fields, **kwargs)[source]¶ Request highlighting of some fields. All keyword arguments passed in will be used as parameters for all the fields in the
fields
parameter. Example:Search().highlight('title', 'body', fragment_size=50)
will produce the equivalent of:
{ "highlight": { "fields": { "body": {"fragment_size": 50}, "title": {"fragment_size": 50} } } }
If you want to have different options for different fields you can call
highlight
twice:Search().highlight('title', fragment_size=50).highlight('body', fragment_size=100)
which will produce:
{ "highlight": { "fields": { "body": {"fragment_size": 100}, "title": {"fragment_size": 50} } } }
-
highlight_options
(**kwargs)[source]¶ Update the global highlighting options used for this request. For example:
s = Search() s = s.highlight_options(order='score')
-
must
(type_or_query, insert_below=None, on=None, mode='add', bool_body=None, **body)[source]¶ Create copy of initial Query and insert provided clause under “bool” query “must”.
>>> Query().must('term', some_field=1) >>> Query().must({'term': {'some_field': 1}}) >>> from pandagg.query import Term >>> Query().must(Term(some_field=1))
Keyword Arguments: - insert_below (
str
) – named query clause under which the inserted clauses should be placed. - compound_param (
str
) – param under which inserted clause will be placed in compound query - on (
str
) – named compound query clause on which the inserted compound clause should be merged. - mode (
str
one of ‘add’, ‘replace’, ‘replace_all’) – merging strategy when inserting clauses on a existing compound clause.- ‘add’ (default) : adds new clauses keeping initial ones
- ‘replace’ : for each parameter (for instance in ‘bool’ case : ‘filter’, ‘must’, ‘must_not’, ‘should’), replace existing clauses under this parameter, by new ones only if declared in inserted compound query
- ‘replace_all’ : existing compound clause is completely replaced by the new one
- insert_below (
-
query
(type_or_query, insert_below=None, on=None, mode='add', **body)[source]¶ Insert provided clause in copy of initial Query.
>>> from pandagg.query import Query >>> Query().query('term', some_field=23) {'term': {'some_field': 23}}
>>> from pandagg.query import Term >>> Query()\ >>> .query({'term': {'some_field': 23})\ >>> .query(Term(other_field=24))\ {'bool': {'must': [{'term': {'some_field': 23}}, {'term': {'other_field': 24}}]}}
Keyword Arguments: - insert_below (
str
) – named query clause under which the inserted clauses should be placed. - compound_param (
str
) – param under which inserted clause will be placed in compound query - on (
str
) – named compound query clause on which the inserted compound clause should be merged. - mode (
str
one of ‘add’, ‘replace’, ‘replace_all’) – merging strategy when inserting clauses on a existing compound clause.- ‘add’ (default) : adds new clauses keeping initial ones
- ‘replace’ : for each parameter (for instance in ‘bool’ case : ‘filter’, ‘must’, ‘must_not’, ‘should’), replace existing clauses under this parameter, by new ones only if declared in inserted compound query
- ‘replace_all’ : existing compound clause is completely replaced by the new one
- insert_below (
-
scan
()[source]¶ Turn the search into a scan search and return a generator that will iterate over all the documents matching the query.
Use
params
method to specify any additional arguments you with to pass to the underlyingscan
helper fromelasticsearch-py
- https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan
-
script_fields
(**kwargs)[source]¶ Define script fields to be calculated on hits. See https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-script-fields.html for more details.
Example:
s = Search() s = s.script_fields(times_two="doc['field'].value * 2") s = s.script_fields( times_three={ 'script': { 'inline': "doc['field'].value * params.n", 'params': {'n': 3} } } )
-
sort
(*keys)[source]¶ Add sorting information to the search request. If called without arguments it will remove all sort requirements. Otherwise it will replace them. Acceptable arguments are:
'some.field' '-some.other.field' {'different.field': {'any': 'dict'}}
so for example:
s = Search().sort( 'category', '-title', {"price" : {"order" : "asc", "mode" : "avg"}} )
will sort by
category
,title
(in descending order) andprice
in ascending order using theavg
mode.The API returns a copy of the Search object and can thus be chained.
-
source
(fields=None, **kwargs)[source]¶ Selectively control how the _source field is returned.
Parameters: fields – wildcard string, array of wildcards, or dictionary of includes and excludes If
fields
is None, the entire document will be returned for each hit. If fields is a dictionary with keys of ‘includes’ and/or ‘excludes’ the fields will be either included or excluded appropriately.Calling this multiple times with the same named parameter will override the previous values with the new ones.
Example:
s = Search() s = s.source(includes=['obj1.*'], excludes=["*.description"]) s = Search() s = s.source(includes=['obj1.*']).source(excludes=["*.description"])
-
suggest
(name, text, **kwargs)[source]¶ Add a suggestions request to the search.
Parameters: - name – name of the suggestion
- text – text to suggest on
All keyword arguments will be added to the suggestions body. For example:
s = Search() s = s.suggest('suggestion-1', 'Elasticsearch', term={'field': 'body'})
-
to_dict
(count=False, **kwargs)[source]¶ Serialize the search into the dictionary that will be sent over as the request’s body.
Parameters: count – a flag to specify if we are interested in a body for count - no aggregations, no pagination bounds etc. All additional keyword arguments will be included into the dictionary.
-