REST Redis Service provides an easy-to-use and powerful way to create REST API calls to the Redis server.

1 What Are RESTful Web Services

REST, or REpresentational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other.

  • Resource identification through URI: A RESTful web service exposes a set of resources that identify the targets of the interaction with its clients. Resources are identified by URIs, which provide a global addressing space for resource and service discovery
  • Uniform interface: Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE. POST creates a new resource, which can be then deleted by using DELETE. GET retrieves the current state of a resource in some representation. PUT transfers a new state onto a resource
  • Self-descriptive messages: Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, XLS, JSON, and others.
  • Stateful interactions through hyperlinks: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer.

REST requires that a client make a request to the server in order to retrieve or modify data on the server. A request generally consists of:

  • an HTTP verb, which defines what kind of operation to perform
  • a header, which allows the client to pass along information about the request
  • a path or URI to a resource
  • an optional message body containing data

2 What is Redis and RedisSearch

2.1 Redis

Redis (Remote Dictionary Server) is an in-memory data structure project implementing a distributed, in-memory key-value database with optional durability. Redis supports different kinds of abstract data structures, such as strings, lists, maps, sets, sorted sets, HyperLogLogs, bitmaps, streams, and spatial indexes.

You can read more in redis:

2.2 RediSearch

RediSearch is a powerful text search and secondary indexing engine, built on top of Redis as a Redis module.

Unlike Redis search libraries, it does not use Redis’ internal data structures. Using its own highly optimized data structures and algorithms, RediSearch allows for advanced search features, with high performance and a small memory footprint. It can perform simple text searches as well as complex structured queries, filtering by numeric properties and geographical distances

You can read more in RediSearch:

2.3 Available Redis endpoints

RediSearch documentation explain a los of comands that can be used in here
Some of this comands have been implementated to be easily used from a REST API Endpoint:

2.3.1 FT.SUGGET

FT.SUGGET command is used to get completion suggestions for a prefix.

Redis FT.SUGGET documentation

The available endpoint to do a FT.SUGGET query is: "/sugget/{key}/{prefix}".
key the suggestion dictionary KEY.
prefix the prefix to complete on.

QueryParams

Param Param type Required Default Description
fuzzy Boolean   false If set, a fuzzy prefix search will be done, including prefixes at Levenshtein distance of 1 from the prefix sent
max Integer   5 Limit the results to a maximum of
withscores Boolean   false If set, redis will also return the score of each suggestion. this can be used to merge results from multiple instances
withpayloads Boolean   false If set, redis will return optional payloads saved along with the suggestions. If no payload is present for an entry, return will be null

2.3.2 FT.SEARCH

FT.SEARCH command is used to search the index with a textual query and can return either documents or just ids.

Redis FT.SEARCH documentation

The available endpoint to do a FT.SEARCH query is: "/search/{index}"
index is telling the INDEX where the query will be applied.

QueryParams

Param Param type Required Default Description
q String   the text query to search. Info here
limit Integer   10 Limit the number of results to return
offset Integer   0 Apply an offset ove the results to return
nocontent Boolean   false If set, only the document ids will be returned and not the content. This is useful if RediSearch is only an index on an external document collection
verbatim Boolean   false if set, redis will not try to use stemming for query expansion but search the query terms verbatim.
nostop Boolean   false If set, redis will not filter stopwords from the query
withscores Boolean   false If set, the response will have the relative internal score of each document. this can be used to merge results from multiple instances
withpayloads Boolean   false If set, the rsponse will have the optional document payloads (see FT.ADD).
sort String  

Define how to sort the resuts.

Sentence will be defined like: {COLUMN_NAME}={SORT_DIRECTION}

  • COLUMN_NAME: Name of the column to sort
  • SORT_DIRECTION: Sort direction can be asc (ascendent) or desc (descendent)

2.3.3 FT.AGGREGATE

FT.AGGREGATE command runs a search query on an index, and performs aggregate transformations on the results, extracting statistics and other data from them.

Redis FT.AGGREGATE documentation

The available endpoint to do a FT.AGGREGATE query is: "/aggregate/{index}".
index is telling the INDEX where the query will be applied.

Pipeline

QueryParams

Param Param type Required Default Description
q String   the text query to search. Info here
fields[] List<String>  

Define the columns of the GROUPBY to define the groups

Array with the column names of the columns that will be in the GROUPBY list
reducers[] List<String>  

Reduce the matching results in each group into a single record, using a reduction function

Sentence will be defined like: {NEW_COLUMN_NAME}={REDUCE_TYPE} [{COLUMN_NAME} [{ARG} [{SORT_DIRECTION}]]]

  • NEW_COLUMN_NAME: Name of the new column calculated with the reducer
  • REDUCE_TYPE: Calculation that will be done:
    1. COUNT: Count the number of records in each group.
    2. COUNT_DISTINCT: Count the number of distinct values for COLUMN_NAME.
    3. COUNT_DISTINCTISH: Return an aproximation of the number of distinct values for COLUMN_NAME, same idea of COUNT_DISTINCT but giving an approximation instead of an exact count, at the expense of less memory and CPU in big groups.
    4. SUM: Return the sum of all numeric values for COLUMN_NAME in a group. Non numeric values if the group are counted as 0.
    5. MIN: Return the minimal value for COLUMN_NAME, whether it is a string, number or NULL.
    6. MAX: Return the maximal value for COLUMN_NAME, whether it is a string, number or NULL.
    7. AVG: Return the average value for COLUMN_NAME. COLUMN_NAME values must be numeric.
    8. STDDEV: Return the standard deviation COLUMN_NAME in the group. COLUMN_NAME values must be numeric.
    9. QUANTILE: Return the value at a given quantile for the values of COLUMN_NAME. COLUMN_NAME values must be numeric. The quantil percentage will be defined in ARG, integer between [0-100]
    10. TOLIST: Merge all distinct values for COLUMN_NAME into a single array.
    11. FIRST_VALUE: Return the first or top value of for COLUMN_NAME in the group, optionally defining how to sort the elements inside the group. If deciding to sort ARG will be the column to be sorted and SORT_DIRECTION the sort direction asc or desc
    12. RANDOM_SAMPLE: Return an array with values for COLUMN_NAME with an even distribution. ARG is an integer defining how many samples will be in the array
  • COLUMN_NAME: Column name used to do the REDUCE_TYPE operation. Must be defined in all the operations with exception of COUNT
  • ARG: Argument to explain how to do the REDUCE_TYPE operation. Check the info about the selected reducer type to see how to define ARG or if ARG should not be defined
  • SORT_DIRECTION: Sort direction can be asc (ascendent) or desc (descendent). This parameter can only be defined for REDUCE_TYPE = FIRST_VALUE and the optional column ARG is defined too
apply[] List<String>  

Apply a 1-to-1 transformation on one or more properties, and either store the result as a new property down the pipeline, or replace any property using this transformation

Sentence will be defined like: {COLUMN_NAME}={APPLY_SENTENCE}

  • COLUMN_NAME: Name of the new column calculated or name of the column to modify
  • APPLY_SENTENCE: Sentence used to calculate the value to save. Info here
sorters[] List<String>  

Define how to sort the resuts.

Sentence will be defined like: {COLUMN_NAME}={SORT_DIRECTION}

  • COLUMN_NAME: Name of the column to sort
  • SORT_DIRECTION: Sort direction can be asc (ascendent) or desc (descendent)
sortmax Integer   Used within the sorters to optimize the query sorting only for the n-largest elements. If not defined will sort all the elements
filter String   Filter the results using predicate expressions relating to values in each result
limit Integer   10 Limit the number of results to return
offset Integer   0 Apply an offset ove the results to return