Skip to content

Commit a837782

Browse files
joshrotenbergjoshrotenberg
authored
docs: add real-world JMESPath examples to docs and slides (#498)
- Add 'Real-World Examples' section to jmespath-queries.md with actual Cloud API outputs (counting, aggregation, projections, filtering) - Add examples for extended functions: unique, upper, replace, levenshtein - Update presentation slides with live query examples and outputs - Add new slides for Projections and String Functions - Reorganize extended functions slide into two-column layout
1 parent 1ad54e7 commit a837782

File tree

2 files changed

+234
-149
lines changed

2 files changed

+234
-149
lines changed

‎docs/src/common-features/jmespath-queries.md‎

Lines changed: 151 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,123 @@ redisctl cloud database get 123:456 -q 'security.ssl_client_authentication'
1515
redisctl enterprise database get 1 -q '{name: name, memory: memory_size, port: port}'
1616
```
1717

18+
## Real-World Examples
19+
20+
These examples work with actual Redis Cloud API responses:
21+
22+
### Counting and Aggregation
23+
24+
```bash
25+
# Count all subscriptions
26+
redisctl cloud subscription list -o json -q 'length(@)'
27+
# Output: 192
28+
29+
# Aggregate statistics across all subscriptions
30+
redisctl cloud subscription list -o json \
31+
-q '{total_subscriptions: length(@), total_size_gb: sum([*].cloudDetails[0].totalSizeInGb), avg_size_gb: avg([*].cloudDetails[0].totalSizeInGb)}'
32+
# Output:
33+
# {
34+
# "avg_size_gb": 1.96,
35+
# "total_size_gb": 23.56,
36+
# "total_subscriptions": 192
37+
# }
38+
```
39+
40+
### Projections - Reshaping Data
41+
42+
```bash
43+
# Extract specific fields from each subscription
44+
redisctl cloud subscription list -o json \
45+
-q '[*].{id: id, name: name, provider: cloudDetails[0].provider, region: cloudDetails[0].regions[0].region} | [:5]'
46+
# Output:
47+
# [
48+
# {"id": 2983053, "name": "time-series-demo", "provider": "AWS", "region": "ap-southeast-1"},
49+
# {"id": 2988697, "name": "workshop-sub", "provider": "AWS", "region": "us-east-1"},
50+
# ...
51+
# ]
52+
```
53+
54+
### Unique Values and Sorting
55+
56+
```bash
57+
# Get unique cloud providers
58+
redisctl cloud subscription list -o json -q '[*].cloudDetails[0].provider | unique(@)'
59+
# Output: ["AWS", "GCP"]
60+
61+
# Get unique regions, sorted
62+
redisctl cloud subscription list -o json \
63+
-q '[*].cloudDetails[0].regions[0].region | unique(@) | sort(@)'
64+
# Output: ["ap-northeast-1", "ap-south-1", "ap-southeast-1", "europe-west1", ...]
65+
66+
# Sort subscription names alphabetically
67+
redisctl cloud subscription list -o json -q '[*].name | sort(@) | [:10]'
68+
```
69+
70+
### Filtering with Patterns
71+
72+
```bash
73+
# Find subscriptions containing 'demo'
74+
redisctl cloud subscription list -o json \
75+
-q "[*].name | [?contains(@, 'demo')] | [:5]"
76+
# Output: ["xw-time-series-demo", "gabs-redis-streams-demo", "anton-live-demo", ...]
77+
78+
# Filter by prefix
79+
redisctl cloud subscription list -o json \
80+
-q "[*].name | [?starts_with(@, 'gabs')] | [:5]"
81+
# Output: ["gabs-aws-workshop-sub", "gabs-santander-rdi", "gabs-redis-streams-demo", ...]
82+
83+
# Filter by suffix
84+
redisctl cloud subscription list -o json \
85+
-q "[*].name | [?ends_with(@, 'demo')] | [:5]"
86+
```
87+
88+
### String Transformations
89+
90+
```bash
91+
# Convert names to uppercase
92+
redisctl cloud subscription list -o json -q 'map(&upper(name), [*]) | [:3]'
93+
# Output: ["XW-TIME-SERIES-DEMO", "GABS-AWS-WORKSHOP-SUB", "BAMOS-TEST"]
94+
95+
# Replace substrings
96+
redisctl cloud subscription list -o json \
97+
-q "[*].{name: name, replaced: replace(name, 'demo', 'DEMO')} | [?contains(name, 'demo')] | [:3]"
98+
# Output:
99+
# [
100+
# {"name": "xw-time-series-demo", "replaced": "xw-time-series-DEMO"},
101+
# {"name": "gabs-redis-streams-demo", "replaced": "gabs-redis-streams-DEMO"},
102+
# ...
103+
# ]
104+
```
105+
106+
### Fuzzy Matching with Levenshtein Distance
107+
108+
```bash
109+
# Find subscriptions with names similar to "production"
110+
redisctl cloud subscription list -o json \
111+
-q "[*].{name: name, distance: levenshtein(name, 'production')} | sort_by(@, &distance) | [:5]"
112+
# Output:
113+
# [
114+
# {"distance": 8.0, "name": "piyush-db"},
115+
# {"distance": 8.0, "name": "erni-rdi-1"},
116+
# ...
117+
# ]
118+
```
119+
120+
### Sorting by Computed Values
121+
122+
```bash
123+
# Sort by name length (shortest first)
124+
redisctl cloud subscription list -o json \
125+
-q "[*].{name: name, len: length(name)} | sort_by(@, &len) | [:5]"
126+
# Output:
127+
# [
128+
# {"len": 5, "name": "bgiri"},
129+
# {"len": 6, "name": "abhidb"},
130+
# {"len": 6, "name": "CM-rag"},
131+
# ...
132+
# ]
133+
```
134+
18135
## Array Operations
19136

20137
```bash
@@ -41,24 +158,16 @@ redisctl cloud database list -q "[?memoryLimitInGb > `1`].{name: name, memory: m
41158
redisctl enterprise database list -q "[?status=='active' && memory_size > `1073741824`]"
42159
```
43160

44-
## Sorting and Slicing
45-
46-
```bash
47-
# Sort by field
48-
redisctl enterprise database list -q "sort_by(@, &name)"
49-
50-
# Reverse sort
51-
redisctl cloud subscription list -q "reverse(sort_by(@, &id))"
52-
53-
# Get first 5
54-
redisctl enterprise database list -q '[:5]'
55-
```
56-
57161
## Pipelines
58162

59163
Chain operations together with `|` for complex transformations:
60164

61165
```bash
166+
# Get unique regions -> sort -> count
167+
redisctl cloud subscription list -o json \
168+
-q '[*].cloudDetails[0].regions[0].region | unique(@) | sort(@) | length(@)'
169+
# Output: 7
170+
62171
# Filter -> Sort -> Take top 3 -> Reshape
63172
redisctl enterprise database list -q '
64173
[?status==`active`]
@@ -68,38 +177,6 @@ redisctl enterprise database list -q '
68177
| [*].{name: name, memory_gb: to_string(memory_size / `1073741824`)}'
69178
```
70179

71-
## Common Patterns
72-
73-
### Extract Single Value
74-
75-
```bash
76-
# Get cluster name as plain text
77-
redisctl enterprise cluster get -q 'name'
78-
# Output: my-cluster
79-
```
80-
81-
### Build Custom Objects
82-
83-
```bash
84-
redisctl enterprise database list -q '[].{
85-
database: name,
86-
size_gb: to_string(memory_size / `1073741824`),
87-
endpoints: endpoints[0].addr
88-
}'
89-
```
90-
91-
### Count Items
92-
93-
```bash
94-
redisctl enterprise database list -q 'length(@)'
95-
```
96-
97-
### Check if Empty
98-
99-
```bash
100-
redisctl cloud subscription list -q 'length(@) == `0`'
101-
```
102-
103180
## Extended Functions
104181

105182
redisctl includes 300+ extended JMESPath functions. Here are the most useful categories:
@@ -108,14 +185,14 @@ redisctl includes 300+ extended JMESPath functions. Here are the most useful cat
108185

109186
```bash
110187
# Case conversion
111-
redisctl enterprise database list -q '[].{name: upper(name)}'
188+
redisctl cloud subscription list -o json -q '[*].{name: name, upper_name: upper(name)} | [:3]'
112189

113-
# String manipulation
114-
redisctl enterprise cluster get -q 'split(name, `-`)'
190+
# Trim whitespace
115191
redisctl enterprise database list -q '[].{name: trim(name)}'
116192

117-
# Case transformations
118-
redisctl api cloud get /subscriptions -q '[].{id: id, name: snake_case(name)}'
193+
# Replace substrings
194+
redisctl cloud subscription list -o json \
195+
-q "[*].{original: name, modified: replace(name, '-', '_')} | [:3]"
119196
```
120197

121198
### Formatting Functions
@@ -128,40 +205,18 @@ redisctl enterprise database list -q '[].{name: name, memory: format_bytes(memor
128205
# Format duration
129206
redisctl enterprise database list -q '[].{name: name, uptime: format_duration(uptime_seconds)}'
130207
# Output: [{"name": "cache", "uptime": "2d 5h 30m"}]
131-
132-
# Parse bytes
133-
redisctl api cloud get /subscriptions -q '[].{name: name, bytes: parse_bytes(memory_limit)}'
134208
```
135209

136210
### Date/Time Functions
137211

138212
```bash
213+
# Current timestamp
214+
redisctl cloud subscription list -o json -q '{count: length(@), timestamp: now()}'
215+
# Output: {"count": 192, "timestamp": 1765661197.0}
216+
139217
# Human-readable relative time
140218
redisctl cloud task list -q '[].{id: id, created: time_ago(created_time)}'
141219
# Output: [{"id": "task-123", "created": "2 hours ago"}]
142-
143-
# Format timestamps
144-
redisctl cloud subscription list -q '[].{name: name, created: format_date(createdAt, `"%Y-%m-%d"`)}'
145-
146-
# Current timestamp
147-
redisctl enterprise cluster get -q '{name: name, checked_at: now()}'
148-
149-
# Check if weekend/weekday
150-
redisctl cloud task list -q '[?is_weekday(created_timestamp)]'
151-
152-
# Time calculations
153-
redisctl enterprise database list -q '[].{name: name, age_days: date_diff(now(), created_at, `"days"`)}'
154-
```
155-
156-
### Duration Functions
157-
158-
```bash
159-
# Convert seconds to human format
160-
redisctl enterprise database list -q '[].{name: name, uptime: format_duration(uptime_seconds)}'
161-
162-
# Parse duration strings
163-
redisctl api enterprise get /v1/cluster -q '{timeout: parse_duration(`"1h30m"`)}'
164-
# Output: {"timeout": 5400}
165220
```
166221

167222
### Network Functions
@@ -172,22 +227,14 @@ redisctl enterprise node list -q '[?is_private_ip(addr)].addr'
172227

173228
# Check CIDR containment
174229
redisctl enterprise node list -q '[?cidr_contains(`"10.0.0.0/8"`, addr)]'
175-
176-
# Get network info
177-
redisctl api enterprise get /v1/cluster -q '{
178-
network: cidr_network(deployment_cidr),
179-
broadcast: cidr_broadcast(deployment_cidr)
180-
}'
181230
```
182231

183232
### Math Functions
184233

185234
```bash
186-
# Rounding
187-
redisctl enterprise database list -q '[].{name: name, memory_gb: round(memory_size / `1073741824`, `2`)}'
188-
189-
# Min/max
190-
redisctl enterprise database list -q 'max_by(@, &memory_size).name'
235+
# Get max value
236+
redisctl cloud subscription list -o json -q '[*].cloudDetails[0].totalSizeInGb | max(@)'
237+
# Output: 23.2027
191238

192239
# Statistics
193240
redisctl enterprise database list -q '{
@@ -214,7 +261,12 @@ redisctl enterprise node list -q '[?semver_satisfies(redis_version, `">=7.0.0"`)
214261

215262
```bash
216263
# Type checking
217-
redisctl enterprise database get 1 -q '{name: name, type: type_of(memory_size)}'
264+
redisctl cloud subscription list -o json -q '[*].{name: name, type: type_of(id)} | [:3]'
265+
# Output:
266+
# [
267+
# {"name": "xw-time-series-demo", "type": "number"},
268+
# ...
269+
# ]
218270

219271
# Default values for missing fields
220272
redisctl cloud database get 123:456 -q '{name: name, region: default(region, `"unknown"`)}'
@@ -226,36 +278,30 @@ redisctl enterprise database get 1 -q '{name: name, has_endpoints: not(is_empty(
226278
### Utility Functions
227279

228280
```bash
229-
# Conditional output
230-
redisctl enterprise database list -q '[].{name: name, healthy: if(status == `"active"`, `"YES"`, `"NO"`)}'
281+
# Unique values
282+
redisctl cloud subscription list -o json -q 'unique([*].status)'
283+
# Output: ["active"]
231284

232285
# Coalesce (first non-null)
233286
redisctl cloud database get 123:456 -q '{region: coalesce(region, cloud_region, `"default"`)}'
234-
235-
# Unique values
236-
redisctl enterprise database list -q 'unique([].status)'
237287
```
238288

239-
### Validation Functions
289+
### Fuzzy Matching
240290

241291
```bash
242-
# Validate formats
243-
redisctl enterprise database list -q '[].{
244-
name: name,
245-
valid_endpoint: is_ipv4(endpoints[0].addr),
246-
valid_uuid: is_uuid(database_id)
247-
}'
292+
# Levenshtein distance for fuzzy search
293+
redisctl cloud subscription list -o json \
294+
-q "[*].{name: name, distance: levenshtein(name, 'cache')} | sort_by(@, &distance) | [:5]"
248295

249-
# Email validation
250-
redisctl api cloud get /users -q '[?is_email(email)].email'
296+
# Find similar names (distance < 3)
297+
redisctl enterprise database list -q '[?levenshtein(name, `"cache"`) < `3`]'
251298
```
252299

253300
### Encoding Functions
254301

255302
```bash
256303
# Base64 encode/decode
257304
redisctl enterprise cluster get -q '{encoded: base64_encode(name)}'
258-
redisctl api enterprise get /v1/cluster -q '{decoded: base64_decode(encoded_field)}'
259305

260306
# URL encode/decode
261307
redisctl api cloud get /subscriptions -q '[].{safe_name: url_encode(name)}'
@@ -266,37 +312,23 @@ redisctl api cloud get /subscriptions -q '[].{safe_name: url_encode(name)}'
266312
```bash
267313
# Generate hashes
268314
redisctl enterprise database list -q '[].{name: name, hash: sha256(name)}'
269-
redisctl api cloud get /subscriptions -q '[].{id: id, checksum: md5(to_string(@))}'
270315
```
271316

272317
### JSON Patch Functions
273318

274319
```bash
275320
# Compare two configs
276321
redisctl enterprise database get 1 -q 'json_diff(current_config, desired_config)'
277-
278-
# Apply patches
279-
redisctl api enterprise get /v1/bdbs/1 -q 'json_patch(@, `[{"op": "add", "path": "/tags", "value": ["prod"]}]`)'
280-
```
281-
282-
### Fuzzy Matching
283-
284-
```bash
285-
# Levenshtein distance
286-
redisctl enterprise database list -q '[?levenshtein(name, `"cache"`) < `3`]'
287-
288-
# Phonetic matching
289-
redisctl api cloud get /users -q '[?sounds_like(name, `"Smith"`)]'
290322
```
291323

292324
## Function Categories Reference
293325

294326
| Category | Example Functions |
295327
|----------|-------------------|
296-
| String | `upper`, `lower`, `trim`, `split`, `snake_case`, `camel_case` |
328+
| String | `upper`, `lower`, `trim`, `replace`, `split`, `snake_case`, `camel_case` |
297329
| Array | `unique`, `flatten`, `chunk`, `zip`, `intersection` |
298330
| Object | `keys`, `values`, `pick`, `omit`, `deep_merge` |
299-
| Math | `round`, `floor`, `ceil`, `sum`, `avg`, `stddev` |
331+
| Math | `round`, `floor`, `ceil`, `sum`, `avg`, `max`, `min`, `stddev` |
300332
| Type | `type_of`, `is_array`, `is_string`, `to_boolean` |
301333
| Utility | `if`, `coalesce`, `default`, `now` |
302334
| DateTime | `format_date`, `time_ago`, `relative_time`, `is_weekend` |

0 commit comments

Comments
 (0)