skip to content

In Redis's JSON commands, how does a JSONPath `$` path differ from a legacy `.` path in what it matches and replies?

level: middleimportance: should knowfreq 38%

answer

  1. first character picks the syntax
  2. same data, different reply shape
  3. one match still gets wrapped
  4. a miss is empty or an error
  5. RESP version changes some replies

basics

~20 s

In Redis JSON commands, a JSONPath such as $.a returns every match wrapped in an array, and an empty array on a miss. A legacy path such as .a reads the first match as a bare value and errors on a miss.

solid answer

~40 s

Redis picks the contract from how the path starts: `$` alone, `$.` or `$[` is JSONPath, and `.a` or a bare `a` is legacy. `JSON.GET doc $.a` returns an array, `"[2]"`, even for one match, and `"[]"` when nothing matches. `JSON.GET doc .a` returns the bare value `"2"` and fails with `ERR Path does not exist` on a miss. If a legacy path matches several values, `JSON.GET` returns the first, but writes such as `JSON.NUMINCRBY` update all of them and reply with the last new value. Write replies change too: `JSON.ARRAPPEND` returns a list of lengths with `$` and a single integer with `.`. New code should use `$`, because it treats zero, one and many matches the same way, and it should always parse the array.

code

plaintext · 10 lines
plaintext
> JSON.SET doc $ '{"a":"b","list":[1,2]}'
OK
> JSON.ARRAPPEND doc $.list 3
1) (integer) 3
> JSON.ARRAPPEND doc .list 4
(integer) 4
> JSON.ARRAPPEND doc $.a 5
1) (nil)
> JSON.ARRAPPEND doc .a 5
(error) ERR Path does not exist or not an array

go deeper

for a junior

Remember that a path starting with a dollar sign returns an array, and a legacy path starting with a dot returns a bare value. The root is written as either symbol.

for a middle

Predict the reply for one match, several matches and no match under both syntaxes, for a read and for a write. That table is exactly what interviewers probe here.

for a senior

Point out that JSONPath writes report a miss in the reply instead of raising an error, so calling code has to inspect replies, and that RESP3 changes the shape of some of them.

for a principal

Standardise on one syntax and a thin client helper, so reply parsing is written once and a protocol or Redis upgrade has one place to be tested.

## Two contracts on one document A **path** tells a Redis JSON command which part of a document it means. Two syntaxes exist. **JSONPath** is the current one, and the **legacy path** dates from the first version of the JSON module and is still accepted. Redis chooses from the start of the string. `$` on its own, `$.` and `$[` mean JSONPath, as do the computed expressions Redis 8.10 added. Anything else, such as `.a`, `a.b` or `["a"]`, is legacy. A bare `$a` also stays legacy, because the module treats it as a field literally named `$a`. In the 8.10 source a legacy path is rewritten with a leading `$` and compiled by the same parser, so `..a` works in both spellings. What really separates them is the **reply contract**: how many matches you get, what shape they arrive in, and what a miss looks like. ## What a read returns ```text > JSON.SET doc $ '{"a":2,"nested":{"a":4}}' OK > JSON.GET doc $..a "[2,4]" > JSON.GET doc ..a "2" > JSON.GET doc $.missing "[]" > JSON.GET doc .missing (error) ERR Path does not exist ``` | Case | JSONPath `$` | Legacy `.` | |---|---|---| | One match with `JSON.GET` | array holding it, `"[2]"` | the bare value, `"2"` | | Several matches with `JSON.GET` | array of all | the first only | | No match with `JSON.GET` | empty array, `"[]"` | error | | No match with `JSON.MGET` | `"[]"` for that key | nil for that key | With no path at all, `JSON.GET doc` uses the legacy root and returns the document without the outer array. Several paths on one `JSON.GET` return an object with one member per path. If **all** paths are legacy, each member is a single value. If **any** path is JSONPath, every member is an array. `JSON.MGET` has a further quirk worth knowing: a key holding another type comes back as nil, like a missing key, instead of failing with `WRONGTYPE`. ## What a write returns Writes differ as well, and this is where the docs need care. The path page says legacy queries operate only on the first path. For `JSON.GET` that holds. For writes it does not: the 8.10 source shows `JSON.NUMINCRBY` and `JSON.ARRAPPEND` changing **every** match and reporting the last result, and the `JSON.NUMINCRBY` page says the same. - `JSON.NUMINCRBY` with `$`, on RESP2: one bulk string holding a JSON array, such as `"[3]"`, with `null` for a non-number and `"[]"` for no match. - `JSON.NUMINCRBY` with `.`, on RESP2: the last new value as a string, or an error if no match is a number. - `JSON.ARRAPPEND` with `$`: an array of new lengths, with nil for a match that is not an array. - `JSON.ARRAPPEND` with `.`: one integer, or an error when no array is found. The practical difference is **failure style**. A legacy write fails loudly when it finds nothing. A JSONPath write reports it in the reply, so your code has to read the reply. ## RESP3 changes some of this On a RESP3 connection `JSON.NUMINCRBY` returns a real array of numbers whichever path syntax you use. A client written against RESP2's `"[3]"` string can break when its library changes protocol, so test the replies your client actually receives. `redis-cli` uses RESP2 unless you pass `-3`. ## What JSONPath offers beyond this The syntax selects by structure and by condition: `..` descends recursively, `[*]` takes all elements, `[start:end:step]` slices, and `?()` filters, as in `$.items[?(@.qty>1)]`. Since **Redis 8.10** a query can also compute a value through a **projection**, such as `JSON.GET doc '$.arr.length()'`, which returns `"[3]"` for a three-element array. Projections are read-only, so write commands reject them. Quote a path in `redis-cli` whenever it contains double quotes, spaces or filter operators, so the shell and the parser see the same string. ## Which one to use For new code the choice is simple, and the reasons are practical: - **One reply shape.** A `$` path returns an array for zero, one or many matches, so the same parsing handles all three. - **A documented direction.** The docs present JSONPath as the current syntax, and new operators arrive there. - **A cost to remember.** Misses stop being errors, so the code must check the reply. Keep legacy paths only where old code depends on the bare value, and change that code when it is next touched.

  • A client calls `JSON.GET doc` with no path and later adds `$`. Why does its JSON parsing break?
    With no path, `JSON.GET` uses the legacy root and returns the document itself. With `$` it returns an array that contains the document, so `{"a":1}` becomes `[{"a":1}]`. Code expecting an object now receives a one-element array. Read element zero, or choose one path style per codebase and wrap it in a small helper.
  • What changed in path parsing in Redis 8.10 that could affect existing queries?
    Redis 8.10 reserves words such as `in`, `nin`, `size`, `sizeof` and `empty` as operators, and the docs say to reach a field with one of those names as `$.size` or `$["size"]`. A tilde is no longer valid in a dot-notation field name, so `a~b` must be written `$["a~b"]`. Run existing path strings against 8.10 before upgrading.

  • A dollar-sign path returns the bare value when only one thing matches.
  • A legacy path that matches several numbers only ever updates the first one.
  • A miss on a dollar-sign path always raises an error.
  • RESP version has no effect on what JSON commands reply.
  • A JSONPath projection can be used to update the document.

Assumes Redis 8.10: its JSONPath adds projections and new operators, while the wrapping and miss behaviour shown here was checked against the 8.10 source.