API

class RedisEngine(prefix='ac', stop_words=None, cache_timeout=300, **conn_kwargs)
Parameters:
  • prefix (string) – a prefix used for all keys stored in Redis to allow multiple “indexes” to exist and to make deletion easier.
  • stop_words (set) – a set of stop words to remove from index/search data
  • cache_timeout (integer) – how long to keep around search results
  • conn_kwargs – any named parameters that should be used when connecting to Redis, e.g. host='localhost', port=6379

RedisEngine is responsible for storing and searching data suitable for autocompletion. There are many different options you can use to configure how autocomplete behaves, but the defaults are intended to provide good general performance for searching things like blog post titles and the like.

The underlying data structure used to provide autocompletion is a sorted set, details are described in this post.

Usage:

from redis_completion import RedisEngine
engine = RedisEngine()
store(obj_id[, title=None[, data=None[, obj_type=None]]])
Parameters:
  • obj_id – a unique identifier for the object
  • title – a string to store in the index and allow autocompletion on, which, if not provided defaults to the given obj_id
  • data – any data you wish to store and return when a given title is searched for. If not provided, defaults to the given title (or obj_id)
  • obj_type – an additional identifier for this object if multiple types are stored

Store an object in the index and allow it to be searched for.

Examples:

engine.store('some phrase')
engine.store('some other phrase')

In the following example a list of blog entries is being stored in the index. Note that arbitrary data can be stored in the index. When a search is performed this data will be returned.

for entry in Entry.select():
    engine.store(entry.id, entry.title, json.dumps({
        'id': entry.id,
        'published': entry.published,
        'title': entry.title,
        'url': entry.url,
    })
store_json(obj_id, title, data[, obj_type=None])

Like store() except data is automatically serialized as JSON before being stored in the index. Best when used in conjunction with search_json().

exists(obj_id[, obj_type=None])
Parameters:
  • obj_id – a unique identifier for the object
  • obj_type – an additional identifier for this object if multiple types are stored

Checks if the given object exists in the index

remove(obj_id[, obj_type=None])
Parameters:
  • obj_id – a unique identifier for the object
  • obj_type – an additional identifier for this object if multiple types are stored

Removes the given object from the index.

boost(obj_id[, multiplier=1.1[, negative=False]])
Parameters:
  • obj_id – a unique identifier for the object
  • multiplier (float) – a float indicating how much to boost obj_id by, where greater than one will push to the front, less than will push to the back
  • negative (boolean) – whether to push forward or backward (if negative, will simply inverse the multiplier)

Boost the score of the given obj_id by the multiplier, then store the result in a special hash. These stored “boosts” can later be recalled when searching by specifying autoboost=True.

search(phrase[, limit=None[, filters=None[, mappers=None[, boosts=None[, autoboost=False]]]]])
Parameters:
  • phrase – search the index for the given phrase
  • limit – an integer indicating the number of results to limit the search to.
  • filters – a list of callables which will be used to filter the search results before returning to the user. Filters should take a single parameter, the data associated with a given object and should return either True or False. A False value returned by any of the filters will prevent a result from being returned.
  • mappers – a list of callables which will be used to transform the raw data returned from the index.
  • boosts (dict) – a mapping of type identifier -> float value – if provided, results of a given id/type will have their scores multiplied by the corresponding float value, e.g. {'id1': 1.1, 'id2': 1.3, 'id3': .9}
  • autoboost (boolean) – automatically prepopulate boosts by looking at the stored boost information created using the boost() api
Return type:

A list containing data returned by the index

Note

Mappers act upon data before it is passed to the filters

Assume we have stored some interesting blog posts, encoding some metadata using JSON:

>>> engine.search('python', mappers=[json.loads])
[{'published': True, 'title': 'an entry about python', 'url': '/blog/1/'},
 {'published': False, 'title': 'using redis with python', 'url': '/blog/3/'}]
search_json(phrase[, limit=None[, filters=None[, mappers=None[, boosts=None[, autoboost=False]]]]])

Like search() except json.loads is inserted as the very first mapper. Best when used in conjunction with store_json().

flush([everything=False[, batch_size=1000]])

Clears all data from the database. By default will only delete keys that are associated with the given engine (based on its prefix), but if everything is True, then the entire database will be flushed. The latter is faster.

Parameters:
  • everything (boolean) – whether to delete the entire current redis db
  • batch_size (int) – number of keys to delete at-a-time