1# Document Payloads
2
3!!! note
4    The payload feature is deprecated in 2.0
5
6Usually, RediSearch stores documents as hash keys. But if you want to access some data for aggregation or scoring functions, we might want to store that data as an inline payload. This will allow us to evaluate properties of a document for scoring purposes at very low cost.
7
8Since the scoring functions already have access to the DocumentMetaData, which contains document flags and score, We can add custom payloads that can be evaluated in run-time.
9
10Payloads are NOT indexed and are not treated by the engine in any way. They are simply there for the purpose of evaluating them in query time, and optionally retrieving them. They can be JSON objects, strings, or preferably, if you are interested in fast evaluation, some sort of binary encoded data which is fast to decode.
11
12## Adding payloads for documents
13
14When inserting a document using FT.ADD, you can ask RediSearch to store an arbitrary binary safe string as the document payload. This is done with the `PAYLOAD` keyword:
15
16```
17FT.ADD {index_name} {doc_id} {score} PAYLOAD {payload} FIELDS {field} {data}...
18```
19
20## Evaluating payloads in query time
21
22When implementing a scoring function, the signature of the function exposed is:
23
24```c
25double (*ScoringFunction)(DocumentMetadata *dmd, IndexResult *h);
26```
27
28!!! note
29    Currently, scoring functions cannot be dynamically added, and forking the engine and replacing them is required.
30
31DocumentMetaData includes a few fields, one of them being the payload. It wraps a simple byte array with arbitrary length:
32
33```c
34typedef struct  {
35    char *data,
36    uint32_t len;
37} DocumentPayload;
38```
39
40If no payload was set to the document, it is simply NULL. If it is not, you can go ahead and decode it. It is recommended to encode some metadata about the payload inside it, like a leading version number, etc.
41
42## Retrieving payloads from documents
43
44When searching, it is possible to request the document payloads from the engine.
45
46This is done by adding the keyword `WITHPAYLOADS` to `FT.SEARCH`.
47
48If `WITHPAYLOADS` is set, the payloads follow the document id in the returned result.
49If `WITHSCORES` is set as well, the payloads follow the scores. e.g.:
50
51```
52127.0.0.1:6379> FT.CREATE foo SCHEMA bar TEXT
53OK
54127.0.0.1:6379> FT.ADD foo doc2 1.0 PAYLOAD "hi there!" FIELDS bar "hello"
55OK
56127.0.0.1:6379> FT.SEARCH foo "hello" WITHPAYLOADS WITHSCORES
571) (integer) 1
582) "doc2"           # id
593) "1"              # score
604) "hi there!"      # payload
615) 1) "bar"         # fields
62   2) "hello"
63```
64