Skip to content

Commit 774ee76

Browse files
CahidArdaCahidArda
authored
DX-2186: document redis stream commands (#551)
* feat: document redis stream commands * fix: review * fix: xadd command docs * fix: update ts commands * fix: update python commands * fix: update parameter types and response descriptions in stream command docs * fix: update response field type in XRANGE command documentation * fix: remove quotes from default values in XRANGE command documentation
1 parent 5519ed5 commit 774ee76

36 files changed

+1879
-87
lines changed

‎docs.json‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,8 +340,20 @@
340340
{
341341
"group": "Stream",
342342
"pages": [
343+
"redis/sdks/ts/commands/stream/xack",
343344
"redis/sdks/ts/commands/stream/xadd",
344-
"redis/sdks/ts/commands/stream/xrange"
345+
"redis/sdks/ts/commands/stream/xautoclaim",
346+
"redis/sdks/ts/commands/stream/xclaim",
347+
"redis/sdks/ts/commands/stream/xdel",
348+
"redis/sdks/ts/commands/stream/xgroup",
349+
"redis/sdks/ts/commands/stream/xinfo",
350+
"redis/sdks/ts/commands/stream/xlen",
351+
"redis/sdks/ts/commands/stream/xpending",
352+
"redis/sdks/ts/commands/stream/xrange",
353+
"redis/sdks/ts/commands/stream/xread",
354+
"redis/sdks/ts/commands/stream/xreadgroup",
355+
"redis/sdks/ts/commands/stream/xrevrange",
356+
"redis/sdks/ts/commands/stream/xtrim"
345357
]
346358
},
347359
{
@@ -583,6 +595,30 @@
583595
"redis/sdks/py/commands/zset/zunionstore"
584596
]
585597
},
598+
{
599+
"group": "Stream",
600+
"pages": [
601+
"redis/sdks/py/commands/stream/xack",
602+
"redis/sdks/py/commands/stream/xadd",
603+
"redis/sdks/py/commands/stream/xautoclaim",
604+
"redis/sdks/py/commands/stream/xclaim",
605+
"redis/sdks/py/commands/stream/xdel",
606+
"redis/sdks/py/commands/stream/xgroup_create",
607+
"redis/sdks/py/commands/stream/xgroup_createconsumer",
608+
"redis/sdks/py/commands/stream/xgroup_delconsumer",
609+
"redis/sdks/py/commands/stream/xgroup_destroy",
610+
"redis/sdks/py/commands/stream/xgroup_setid",
611+
"redis/sdks/py/commands/stream/xinfo_consumers",
612+
"redis/sdks/py/commands/stream/xinfo_groups",
613+
"redis/sdks/py/commands/stream/xlen",
614+
"redis/sdks/py/commands/stream/xpending",
615+
"redis/sdks/py/commands/stream/xrange",
616+
"redis/sdks/py/commands/stream/xread",
617+
"redis/sdks/py/commands/stream/xreadgroup",
618+
"redis/sdks/py/commands/stream/xrevrange",
619+
"redis/sdks/py/commands/stream/xtrim"
620+
]
621+
},
586622
{
587623
"group": "String",
588624
"pages": [

‎redis/sdks/py/commands/overview.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -463,6 +463,68 @@ Publish messages to many clients
463463
Get the length of the value stored in a key.
464464
</Card>
465465

466+
</CardGroup></Accordion>
467+
<Accordion title="Stream">
468+
<CardGroup cols={3}>
469+
470+
<Card title="XACK" href="/redis/sdks/py/commands/stream/xack">
471+
Acknowledge one or multiple messages as processed for a consumer group.
472+
</Card>
473+
<Card title="XADD" href="/redis/sdks/py/commands/stream/xadd">
474+
Append a new entry to a stream.
475+
</Card>
476+
<Card title="XAUTOCLAIM" href="/redis/sdks/py/commands/stream/xautoclaim">
477+
Transfer ownership of pending messages to another consumer automatically.
478+
</Card>
479+
<Card title="XCLAIM" href="/redis/sdks/py/commands/stream/xclaim">
480+
Transfer ownership of pending messages to another consumer.
481+
</Card>
482+
<Card title="XDEL" href="/redis/sdks/py/commands/stream/xdel">
483+
Remove one or multiple entries from a stream.
484+
</Card>
485+
<Card title="XGROUP CREATE" href="/redis/sdks/py/commands/stream/xgroup_create">
486+
Create a new consumer group for a stream.
487+
</Card>
488+
<Card title="XGROUP CREATECONSUMER" href="/redis/sdks/py/commands/stream/xgroup_createconsumer">
489+
Create a new consumer in a consumer group.
490+
</Card>
491+
<Card title="XGROUP DELCONSUMER" href="/redis/sdks/py/commands/stream/xgroup_delconsumer">
492+
Delete a consumer from a consumer group.
493+
</Card>
494+
<Card title="XGROUP DESTROY" href="/redis/sdks/py/commands/stream/xgroup_destroy">
495+
Delete an entire consumer group.
496+
</Card>
497+
<Card title="XGROUP SETID" href="/redis/sdks/py/commands/stream/xgroup_setid">
498+
Set the last delivered ID for a consumer group.
499+
</Card>
500+
<Card title="XINFO CONSUMERS" href="/redis/sdks/py/commands/stream/xinfo_consumers">
501+
List all consumers in a consumer group.
502+
</Card>
503+
<Card title="XINFO GROUPS" href="/redis/sdks/py/commands/stream/xinfo_groups">
504+
List all consumer groups for a stream.
505+
</Card>
506+
<Card title="XLEN" href="/redis/sdks/py/commands/stream/xlen">
507+
Get the number of entries in a stream.
508+
</Card>
509+
<Card title="XPENDING" href="/redis/sdks/py/commands/stream/xpending">
510+
Get information about pending messages in a consumer group.
511+
</Card>
512+
<Card title="XRANGE" href="/redis/sdks/py/commands/stream/xrange">
513+
Get entries from a stream within a range of IDs.
514+
</Card>
515+
<Card title="XREAD" href="/redis/sdks/py/commands/stream/xread">
516+
Read data from one or multiple streams.
517+
</Card>
518+
<Card title="XREADGROUP" href="/redis/sdks/py/commands/stream/xreadgroup">
519+
Read data from streams as part of a consumer group.
520+
</Card>
521+
<Card title="XREVRANGE" href="/redis/sdks/py/commands/stream/xrevrange">
522+
Get entries from a stream within a range of IDs in reverse order.
523+
</Card>
524+
<Card title="XTRIM" href="/redis/sdks/py/commands/stream/xtrim">
525+
Trim a stream to a specified size.
526+
</Card>
527+
466528
</CardGroup></Accordion>
467529
<Accordion title="Transactions">
468530
<Card title="TRANSACTION" href="/redis/sdks/py/features#pipelines-and-transactions">

‎redis/sdks/py/commands/stream/xack.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: XACK
3+
description: Removes one or multiple messages from the pending entries list of a stream consumer group.
4+
---
5+
6+
## Arguments
7+
8+
<ParamField body="key" type="str" required>
9+
The key of the stream.
10+
</ParamField>
11+
12+
<ParamField body="group" type="str" required>
13+
The consumer group name.
14+
</ParamField>
15+
16+
<ParamField body="ids" type="str" required>
17+
The ID(s) of the message(s) to acknowledge. Can be multiple IDs as separate arguments.
18+
</ParamField>
19+
20+
## Response
21+
22+
<ResponseField type="int">
23+
The number of messages successfully acknowledged.
24+
</ResponseField>
25+
26+
<RequestExample>
27+
```py Single message
28+
result = redis.xack("mystream", "mygroup", "1638360173533-0")
29+
```
30+
31+
```py Multiple messages
32+
result = redis.xack("mystream", "mygroup", "1638360173533-0", "1638360173533-1")
33+
```
34+
</RequestExample>

‎redis/sdks/py/commands/stream/xadd.mdx‎

Lines changed: 21 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -14,51 +14,45 @@ description: Appends one or more new entries to a stream.
1414
automatically.
1515
</ParamField>
1616

17-
<ParamField body="entries" type="Record<str, unknown>" required>
17+
<ParamField body="data" type="Dict[str, Any]" required>
1818
Key-value data to be appended to the stream.
1919
</ParamField>
2020

21-
<ParamField body="options" >
22-
<ParamField body="nomkStream" type="boolean">
23-
Prevent creating the stream if it does not exist.
24-
</ParamField>
25-
<ParamField body="trim">
26-
<ParamField body="type" type="'MAXLEN' | 'MINID'" required>
27-
The trim mode.
28-
</ParamField>
21+
<ParamField body="maxlen" type="int">
22+
The maximum number of entries to keep in the stream. Mutually exclusive with `minid`.
23+
</ParamField>
2924

30-
{" "}
31-
<ParamField body="threshold" type="number | str" required>
32-
The threshold value for the trim mode.
25+
<ParamField body="approximate_trim" type="bool" default="True">
26+
Use approximate trimming (more efficient). When `True`, Redis may keep slightly more entries than specified. Defaults to `True`.
3327
</ParamField>
34-
<ParamField body="comparison" type="~ | =" required>
35-
The comparison operator for the trim mode.
28+
29+
<ParamField body="nomkstream" type="bool" default="False">
30+
Prevent creating the stream if it does not exist. Defaults to `False`.
3631
</ParamField>
37-
<ParamField body="limit" type="number">
38-
Limit how many entries will be trimmed at most.
32+
33+
<ParamField body="minid" type="str">
34+
The minimum ID to keep. Entries with IDs lower than this will be removed. Mutually exclusive with `maxlen`.
3935
</ParamField>
4036

41-
</ParamField>
37+
<ParamField body="limit" type="int">
38+
Limit how many entries will be trimmed at most (only valid with approximate trimming).
4239
</ParamField>
4340

4441
## Response
4542

4643
<ResponseField type="str">The ID of the newly added entry.</ResponseField>
4744

4845
<RequestExample>
49-
```py Example
50-
redis.xadd(key, "*", { name: "John Doe", age: 30 })
46+
```py Basic Example
47+
redis.xadd("mystream", "*", {"name": "John Doe", "age": 30})
48+
```
5149

50+
```py With Custom ID
51+
redis.xadd("mystream", "1634567890123-0", {"temperature": 25.5, "humidity": 60})
5252
```
53-
```py Trimming
54-
redis.xadd(key, "*", { name: "John Doe", age: 30 }, {
55-
trim: {
56-
type: "MAXLEN",
57-
threshold: 1000,
58-
comparison: "=",
59-
},
60-
})
6153

54+
```py Approximate trim with maxlen
55+
redis.xadd("mystream", "*", {"log_level": "error", "message": "Database connection failed"}, maxlen=100)
6256
```
6357
</RequestExample>
6458

‎redis/sdks/py/commands/stream/xautoclaim.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: XAUTOCLAIM
3+
description: Changes the ownership of pending messages from one consumer to another in a stream consumer group automatically.
4+
---
5+
6+
## Arguments
7+
8+
<ParamField body="key" type="str" required>
9+
The key of the stream.
10+
</ParamField>
11+
12+
<ParamField body="group" type="str" required>
13+
The consumer group name.
14+
</ParamField>
15+
16+
<ParamField body="consumer" type="str" required>
17+
The consumer name that will claim the messages.
18+
</ParamField>
19+
20+
<ParamField body="min_idle_time" type="int" required>
21+
The minimum idle time in milliseconds for messages to be claimed.
22+
</ParamField>
23+
24+
<ParamField body="start" type="str" required>
25+
The stream entry ID to start claiming from.
26+
</ParamField>
27+
28+
<ParamField body="count" type="int">
29+
The maximum number of messages to claim.
30+
</ParamField>
31+
32+
<ParamField body="justid" type="bool">
33+
Return only the message IDs instead of the full message data.
34+
</ParamField>
35+
36+
## Response
37+
38+
<ResponseField type="Tuple[str, List[Any], List[str]]">
39+
Returns a list containing:
40+
- Next start ID for pagination
41+
- List of claimed messages. If `justid` option is used, returns only message IDs.
42+
- List of deleted message IDs
43+
</ResponseField>
44+
45+
<RequestExample>
46+
```py Example
47+
# Auto-claim messages that have been idle for more than 60 seconds
48+
result = redis.xautoclaim(
49+
"mystream",
50+
"mygroup",
51+
"consumer1",
52+
60000, # 60 seconds
53+
start="0-0"
54+
)
55+
```
56+
57+
```py With count and justid
58+
result = redis.xautoclaim(
59+
"mystream",
60+
"mygroup",
61+
"consumer1",
62+
60000,
63+
start="0-0",
64+
count=5,
65+
justid=True
66+
)
67+
```
68+
</RequestExample>
69+
70+
<ResponseExample>
71+
```py
72+
[
73+
"1638360173533-1", # next start ID
74+
[["1638360173533-0", ["field1", "value1", "field2", "value2"]]], # claimed messages
75+
[] # deleted message IDs
76+
]
77+
```
78+
</ResponseExample>

‎redis/sdks/py/commands/stream/xclaim.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: XCLAIM
3+
description: Changes the ownership of pending messages from one consumer to another in a stream consumer group.
4+
---
5+
6+
## Arguments
7+
8+
<ParamField body="key" type="str" required>
9+
The key of the stream.
10+
</ParamField>
11+
12+
<ParamField body="group" type="str" required>
13+
The consumer group name.
14+
</ParamField>
15+
16+
<ParamField body="consumer" type="str" required>
17+
The consumer name that will claim the messages.
18+
</ParamField>
19+
20+
<ParamField body="min_idle_time" type="int" required>
21+
The minimum idle time in milliseconds for messages to be claimed.
22+
</ParamField>
23+
24+
<ParamField body="ids" type="str" required>
25+
The ID(s) of the message(s) to claim. Can be multiple IDs as separate arguments.
26+
</ParamField>
27+
28+
<ParamField body="justid" type="bool">
29+
Return only the message IDs instead of the full message data.
30+
</ParamField>
31+
32+
## Response
33+
34+
<ResponseField type="Union[List[List[Any]], List[str]]">
35+
Returns a list of claimed messages. If `justid` option is used, returns only message IDs.
36+
</ResponseField>
37+
38+
<RequestExample>
39+
```py Example
40+
# Claim messages that have been idle for more than 60 seconds
41+
result = redis.xclaim(
42+
"mystream",
43+
"mygroup",
44+
"consumer1",
45+
60000, # 60 seconds
46+
"1638360173533-0", "1638360173533-1"
47+
)
48+
```
49+
50+
```py With justid option
51+
result = redis.xclaim(
52+
"mystream",
53+
"mygroup",
54+
"consumer1",
55+
60000,
56+
"1638360173533-0",
57+
justid=True
58+
)
59+
```
60+
</RequestExample>
61+
62+
<ResponseExample>
63+
```py
64+
[
65+
["1638360173533-0", ["field1", "value1", "field2", "value2"]],
66+
["1638360173533-1", ["field1", "value3", "field2", "value4"]]
67+
]
68+
```
69+
</ResponseExample>

0 commit comments

Comments
 (0)