def click_stats(hashid: str,
dfid: str,
session_id: str,
query: Optional[str] = None,
**opts):
"""
Save click event on Doofinder statistics
Args:
hashid: Unique search engine id. Indicates to which search engine we are doing the query.
dfid: Doofinder item id. It comes in every Doofinder results for every item.
It has the form {hashid}@{index}@{md5id}
i.e. 6a96504dc173514cab1e0198af92e6e9@product@e19347e1c3ca0c0b97de5fb3b690855a
session_id (<= 32 characters): The current session ID, must be unique for each user.
query (<= 200 characters): The search term. It must be escaped.
"""
query_params = parse_query_params({
'dfid': dfid,
'session_id': session_id,
'query': query
})
api_client = SearchAPIClient(**opts)
return api_client.put(f'/6/{hashid}/stats/click',
query_params=query_params)
def test_can_parse_dicts(self):
"""Dict values can be parsed."""
result = parse_query_params({
'dict0': {
'dict1': {
'a': 'a',
'b': 'b'
},
'list': [{
'a': 'a'
}, {
'b': 'b'
}],
'string': 'String',
'none': None
}
})
self.assertEqual(
result, {
'dict0[dict1][a]': 'a',
'dict0[dict1][b]': 'b',
'dict0[list][0][a]': 'a',
'dict0[list][1][b]': 'b',
'dict0[string]': 'String'
})
def suggest(hashid: str, query: str = '', indices: List[str] = None, stats: bool = None, session_id: str = None, **opts):
"""
Fetch suggestions for terms based on the items indexed in a search engine.
Args:
hashid (str): Unique search engine id. Indicates to which search engine
we are doing the query.
query (str): The terms we are looking for in the items of the search engine. Default to ''.
indices (List[str], optional): With the indices parameter you can specify to search within one specific Index.
If this parameter is not provided, the search will work with all Indices.
Note that [ and ] characters should be escaped (%5B and %5D) in all cases.
Example: indices[]=product&indices[]=page; indices=products
stats (boolean, optional): Enable/Disable this search in stats reports.
Default: None.
session_id (str, optional, <= 32 characters): The current session ID, must be unique for each user.
"""
query_params = parse_query_params({
'query': query,
'indices': indices,
'stats': stats,
'session_id': session_id
})
api_client = SearchAPIClient(**opts)
return api_client.get(
f'/6/{hashid}/_suggest',
query_params=query_params
)
def searches_top(from_,
to,
hashids=None,
device=None,
query_name=None,
exclude=None,
total_hits=None,
tz=None,
format_=None,
**opts):
"""
Returns list of most common searches in a period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'device': device,
'query_name': query_name,
'exclude': exclude,
'total_hits': total_hits,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/searches/top', query_params)
def searches(from_,
to,
hashids=None,
device=None,
query_name=None,
source=None,
total_hits=None,
tz=None,
format_=None,
**opts):
"""
Return number of searches in a period grouped by date.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'device': device,
'query_name': query_name,
'source': source,
'total_hits': total_hits,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/searches', query_params)
def test_can_parse_iterables(self):
"""Non-string iterables can be parsed."""
result = parse_query_params({
'iterable': ['a', 'b', 'c', 'd'],
'string': 'String'
})
self.assertEqual(result, {
'iterable[]': ['a', 'b', 'c', 'd'],
'string': 'String'
})
def query_log_iter(from_, to, hashids=None, **opts):
"""
Returns an iterator with all the queries done to the search API in a
period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids
})
api_client = ManagementAPIClient(stream=True, **opts)
return api_client.request('GET', '/api/v2/stats/query_log', query_params)
def usage(from_, to, hashids=None, type_=None, format_=None, **opts):
"""
Returns usage to search engines during a period.
It sums the query and API requests made to the service.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'type': type_,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/usage', query_params)
def inits(from_, to, hashids=None, device=None, tz=None, format_=None, **opts):
"""
Returns number of total unique search sessions in a period group by date.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'device': device,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/inits', query_params)
def facets_top(from_, to, hashids=None, tz=None, format_=None, **opts):
"""
Returns most common facets filters used, how many times they have been
used, and which filter has been applied in a period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/facets/top', query_params)
def facets(from_, to, hashids=None, tz=None, format_=None, **opts):
"""
Returns how many times facets filters have been used in a period, grouped
by facet field name.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/facets', query_params)
def sales(from_, to, hashids=None, tz=None, format_=None, **opts):
"""
Returns the total price for sales checkouts in a period, where session_id
identifies every sale.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/sales', query_params)
def init_session(hashid: str, session_id: str, **opts):
"""
Returns number of total unique search sessions in a period group by date.
Args:
hashid: Unique search engine id. Indicates to which search engine we are doing the query.
session_id (<= 32 characters): The current session ID, must be unique for each user.
"""
query_params = parse_query_params({
'session_id': session_id,
})
api_client = SearchAPIClient(**opts)
return api_client.put(f'/6/{hashid}/stats/init', query_params=query_params)
def log_checkout(hashid: str, session_id: str, **opts):
"""
That is the event for when a customer complete a checkout.
The info of the items that were in her session when she completes the checkout are logged in the event.
Args:
hashid: Unique search engine id. Indicates to which search engine we are doing the query.
session_id (<= 32 characters): The current session ID, must be unique for each user.
"""
query_params = parse_query_params({'session_id': session_id})
api_client = SearchAPIClient(**opts)
return api_client.put(f'/6/{hashid}/stats/checkout',
query_params=query_params)
def clicks(from_,
to,
hashids=None,
device=None,
tz=None,
format_=None,
**opts):
"""
Returns number of times a user clicked an item in a period grouped by date.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'device': device,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/clicks', query_params)
def inits_locations(from_,
to,
hashids=None,
device=None,
tz=None,
format_=None,
**opts):
"""
Returns all unique sessions geolocation(longituted and latitude pairs) for
a period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'device': device,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/inits/locations', query_params)
def banners(from_,
to,
hashids=None,
banner_id=None,
tz=None,
format_=None,
**opts):
"""
Returns how many times banners have been displayed and clicked in a period,
grouped by banner id.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'id': banner_id,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/banners', query_params)
def redirects(from_,
to,
hashids=None,
redirect_id=None,
tz=None,
format_=None,
**opts):
"""
Returns how many times users have been redirected by a custom redirections,
and to which url in a period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'id': redirect_id,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/redirects', query_params)
def log_redirect(hashid: str,
redirection_id: str,
session_id: str,
query: Optional[str] = None,
**opts):
"""
Logs a "redirection triggered" event in stats logs.
Args:
hashid: Unique search engine id. Indicates to which search engine we are doing the query.
redirection_id: Id of redirection. This id is obtained in the search response that has redirect information.
session_id (<= 32 characters): The current session ID, must be unique for each user.
query (<= 200 characters): The search term. It must be escaped.
"""
query_params = parse_query_params({
'id': redirection_id,
'session_id': session_id,
'query': query
})
api_client = SearchAPIClient(**opts)
return api_client.put(f'/6/{hashid}/stats/redirect',
query_params=query_params)
def log_banner_image_click(hashid: str,
id: str,
session_id: str,
query: Optional[str] = None,
**opts):
"""
Logs a "click on banner image" event in stats logs.
Args:
hashid: Unique search engine id. Indicates to which search engine we are doing the query.
id: id of image displayed in banner. This id is obtained in the search response that has banner information.
session_id (<= 32 characters): The current session ID, must be unique for each user.
query (<= 200 characters): The search term. It must be escaped.
"""
query_params = parse_query_params({
'id': id,
'session_id': session_id,
'query': query
})
api_client = SearchAPIClient(**opts)
return api_client.put(f'/6/{hashid}/stats/image',
query_params=query_params)
def clicked_items_searches(from_,
to,
dfid,
hashids=None,
device=None,
tz=None,
format_=None,
**opts):
"""
Returns the most common searched for a clicked item, and how many times it
has been clicked from those searches.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'dfid': dfid,
'hashid': hashids,
'device': device,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/clicked_items/searches', query_params)
def clicked_items(from_,
to,
hashids=None,
query=None,
device=None,
limit=None,
tz=None,
format_=None,
**opts):
"""
Returns most commonly clicked items in a period.
"""
query_params = parse_query_params({
'from': from_,
'to': to,
'hashid': hashids,
'query': query,
'device': device,
'limit': limit,
'tz': tz,
'format': format_
})
api_client = ManagementAPIClient(**opts)
return api_client.get('/api/v2/stats/clicked_items', query_params)
def test_can_parse_booleans(self):
"""Boolean values can be parsed to lower case string."""
result = parse_query_params({'stats': False, 'another_param': True})
self.assertEqual(result, {'stats': 'false', 'another_param': 'true'})
def query(hashid: str, query: str = '', auto_filters: bool = None, custom_results: bool = None,
excluded_results: bool = None, filter: Dict[str, Any] = None,
exclude: Dict[str, Any] = None,
indices: List[str] = None, query_name: QueryNames = None,
sort: List[Dict[str, str]] = None, page: int = None, rpp: int = None,
facets: List[Dict[str, Any]] = None, filter_execution: SearchFilterExecution = None,
session_id: str = None, stats: bool = None, skip_auto_filters: List[str] = None,
skip_top_facet: List[str] = None, title_facet: bool = None, top_facet: bool = None, **opts):
"""
Queries items indexed in a search engine.
Args:
hashid (str): Unique search engine id. Indicates to which search engine
we are doing the query.
query (str): The terms we are looking for in the items of the search engine. Default to ''
auto_filters (boolean, optional): Enable/Disable the automatic filters in search.
Default: None.
custom_results (boolean, optional): Enable/Disable the custom results in search.
Default: None.
excluded_results (boolean, optional): Enable/Disable the excluded results in search.
Default: None.
filter (dict, optional): A dictionary that indicates a filter for
items. For instance, look for those items of color "blue".
Default to None.
exclude (dict, optional): A dictionary that indicates an exclude rule
for items. For instance, exclude those items that belong to `Foo`
category. Default to None
indices (list, optional): With the indices parameter you can specify to search within one specific Index.
Default: None
query_name (str, optional): Indicates a query name to used. It could be
one of "match_and", "match_or", "fuzzy", or "phonetic_text". If you
do not provide one, search API will select the best one. Default to
None.
sort (lst, optional): Indicates a sorting rule for results. If
sort is a list of strings, each element will define a field to sort
by in ascending order. If sort is a list of dictionaries, you can
set the order. For instance, sort: [{'color': 'desc'}] will sort
results by color name in descending order. If you do not provided
one, results will be ordered by score in descending order. Default
to None.
page (int, optional): Indicates a page of results. If you provide a
page, `query` will return the results from that page. Default to
None.
rpp (int, optional): Indicates how many results to fetch by page,
minimum 1, maximum 100. Default to None.
facets (list, optional): Indicates a list with dicts of facets to fetch.
An object with field is required, size is optional (max 100).
filter_execution (SearchQueryName, optional): If you want you can change it to "or".
Default to None.
stats (bool, optional): Enable/Disable this search in stats reports.
Default: None
skip_auto_filters (list, optional): A list of fields to be skipped from auto_filters feature.
skip_top_facet (list, optional): A list of fields to be skipped from top_facet feature.
title_facet (bool, optional): Enable/Disable title_facet feature.
Default: None.
top_facet (bool, optional): Enable/Disable top_facet feature.
Default: None.
"""
query_params = parse_query_params({
'query': query,
'auto_filters': auto_filters,
'custom_results': custom_results,
'excluded_results': excluded_results,
'filter': filter,
'exclude': exclude,
'query_name': query_name,
'indices': indices,
'sort': sort,
'page': page,
'rpp': rpp,
'facets': facets,
'filter_execution': filter_execution,
'session_id': session_id,
'stats': stats,
'skip_auto_filters': skip_auto_filters,
'skip_top_facet': skip_top_facet,
'title_facet': title_facet,
'top_facet': top_facet
})
api_client = SearchAPIClient(**opts)
return api_client.get(
f'/6/{hashid}/_search',
query_params=query_params
)
def test_discards_none_values(self):
"""Parameters with 'None' values are discarded."""
result = parse_query_params({'foo': True, 'None': None, 'bar': False})
self.assertEqual(result, {'foo': 'true', 'bar': 'false'})
def facets_terms(searchengine_hashid, fields, **opts):
api_client = ManagementAPIClient(**opts)
return api_client.get(_get_searchengine_url(searchengine_hashid) +
'/facets_terms',
query_params=parse_query_params({'fields': fields}))
def test_can_parse_dates(self):
"""'Date' values can be parsed."""
result = parse_query_params({'date': datetime(2020, 2, 12, 8, 32, 54)})
self.assertEqual(result, {'date': '20200212'})
def searchengine_mappings(searchengine_hashid, indices=None, **opts):
api_client = ManagementAPIClient(**opts)
return api_client.get(
_get_searchengine_url(searchengine_hashid) + '/mappings',
query_params=parse_query_params({'indices': indices}))
