You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7f60d98
Browse filesBrowse the repository at this point in the historyBrowse files
docs(go): show Match in the references and the JSON example
The stashgen README's "Encrypted JSON documents" table gains a Match row
with both SQL forms, and a section on the grammar, the refusals and what
Diagnostic's Reason, Construct and At give, the four places the answer
parts from jsonb_path_match, the 22023 bound, and the index the
per-operator form engages that json_tree_match does not. encrypt/README.md
and doc.go say the same in short. The typed-document example finds Bea by
one predicate that combines an ordering with the visit filter. The Go
module's CHANGELOG records Match, the Diagnostic accessors and the
redacted EQL types (#1443).
|`Match(ctx, c, predicate, vars, opts)`|`eql.JSONSearchPredicateQuery`|`col @@ $1::eql_v4.query_json_predicate`, or `eql_v4.json_tree_match(col, $1::eql_v4.query_json_predicate)`|
182
183
183
184
`At` has one accessor per ordered path, named for its keys (`$.visits[*].at` is `At.VisitsAt`, `$.a.1` is `At.A1`); two paths with one name, or one path given twice, stop `stashgen`.
184
185
An ordering compares the value `->` extracts at its path, and EQL's `<` compares ordering terms alone, so take the selector from the same accessor (`At.Age.Selector`) rather than spelling the path again.
@@ -220,6 +221,64 @@ Each comparison is of the member's ordering term, so `MemberEq` is an equality o
220
221
`EqAt` at the member's full path is exact, of any element.
221
222
`Match` reads each array to `opts.WildcardBound` elements, 64 when it is 0, and a row whose array is longer fails the query with SQLSTATE 22023 rather than answer over part of it: set the bound past the longest array.
222
223
The function runs on each row a scan gives it, so narrow the rows first with an indexed predicate, such as `@>` on the same values.
224
+
225
+
`Match` on the field itself takes a whole filter as one parameter: a jsonpath predicate and its variables, the two things plaintext `jsonb_path_match(col, $1, $2)` takes.
226
+
It is generated on every `JsonSearch` field, ordered paths or none: the engine reads the predicate when `Match` is called, and refuses what the field cannot answer then.
227
+
228
+
```go
229
+
q, err:= entities.Fields.CustomFieldValues.Match(ctx, cipher,
SELECT id FROM entity WHERE custom_field_values @@ $1::eql_v4.query_json_predicate
236
+
-- or, the same rows
237
+
SELECT id FROM entity WHEREeql_v4.json_tree_match(custom_field_values, $1::eql_v4.query_json_predicate)
238
+
```
239
+
240
+
`vars` are any value `encoding/json` writes as a JSON object (a map, a struct, or a `json.RawMessage` of one), or `nil` for none; a Go string is refused, as it is for a `Contains` needle.
241
+
The Go side reads nothing of the predicate: the engine parses it and compiles it into a tree of the operands the methods above derive, one leaf per comparison.
242
+
The grammar is the subset of SQL/JSON path that the stored terms can answer, as PostgreSQL reads it:
243
+
244
+
- paths: `$`, then `.key`, `."quoted key"` and `[*]` steps;
245
+
- values: a variable (`$v`, `$"v"`) or a JSON literal (a string, a number, `true`, `false`, `null`);
246
+
- comparisons: `==`, `!=` (or `<>`), `<`, `<=`, `>`, `>=` between a path and a value, either side first;
247
+
-`exists(path)`, and `exists(path ? (@.m == $v && @.n > $w))`, conditions on `@` or `@.member` joined by `&&`;
248
+
-`&&`, `||`, `!(…)`, parentheses and `/* */` comments. Keywords are read in any case.
249
+
250
+
An ordering (`<` and the rest) needs its path in `ordered=`, and so does every member of a filter of more than one condition, which compiles to the element match above.
251
+
Anything else is refused before any term is derived, as an `*encrypt.Diagnostic` wrapping `encrypt.ErrEncoding`.
252
+
`Construct()` names the construct in the grammar's own words (`` `like_regex` ``, `a position (`[2]`)`), and `At()` is the byte offset in the predicate where it starts; neither says anything of the predicate's text or the variables' values.
253
+
`Reason()` says why:
254
+
255
+
-`json_predicate_syntax`: text the grammar does not read.
256
+
-`json_predicate_unsupported`: a jsonpath construct the stored terms cannot answer, such as `like_regex`, arithmetic, a method, `.**`, or a filter outside `exists`.
257
+
-`json_predicate_unknown_variable`: a `$name` that `vars` does not hold.
258
+
-`json_predicate_value_type`: an object or array as a value, or anything but a number or a string under an ordering or in a filter of more than one condition.
259
+
-`json_predicate_not_equal_at_wildcard`: `!=` at a path with `[*]`.
260
+
-`json_predicate_too_deep`: more than 32 levels of nesting, or a path deeper than a document.
261
+
-`json_path_position`: a position (`[2]`) in a path.
262
+
-`json_path_no_wildcard`: a filter on a path with no `[*]`.
263
+
-`json_path_wildcard`: a `[*]` in a filter's member.
264
+
-`json_syntax`: JSON text that does not parse, a literal in the predicate (`1e999`) or `vars` (`{`, or an empty or whitespace-only `json.RawMessage`); with `At()` for a literal, without it for `vars`.
265
+
-`json_input`: `vars` that are not a JSON object (`[1]`, `1`).
266
+
267
+
An ordering at a path the tag does not order is `encrypt.ErrTerm` with the code `stack_encrypt::json_path_not_ordered`.
268
+
269
+
Each row answers as `jsonb_path_match` answers over its plaintext, true, false or NULL, save four cases:
270
+
271
+
- Lax mode's unwrapping of an array the path names no `[*]` for is not applied: `$.tags == "a"` over `{"tags": ["a"]}` is false here. Write `[*]`.
272
+
- Nor is its wrapping of a value that is not an array under `[*]`: `$.tags[*] == "a"` over `{"tags": "a"}` is false here. Keep an array an array.
273
+
- A string compared with a number, which jsonpath calls unknown, is false under `==` and true under `!=`. Keep one kind of value at a path.
274
+
- Orderings, and filters of more than one condition, compare the folded ordering terms: text case- and accent-folded, numbers as float64. So `exists($.c[*] ? (@.r == "sibling" && @.n > 5))` finds a `"Sibling"`; `==` anywhere else is exact.
275
+
276
+
A filter of more than one condition reads each array to `opts.WildcardBound` elements, 64 when it is 0; a row whose array is longer fails the query with SQLSTATE 22023, as the element match does.
277
+
278
+
`Match` costs an index: `eql_v4.json_tree_match` evaluates the tree inside a function, so it filters every row a scan gives it and no index engages.
279
+
The per-operator form engages the GIN index for `@>` (`EqAt`, `Contains`) and a btree on an ordered path's term (`At.<Path>`).
280
+
Where a query needs an index, write those leaves with the per-operator methods, or put one beside `Match` to narrow the rows: `WHERE col @> $1::eql_v4.query_json AND col @@ $2::eql_v4.query_json_predicate`.
281
+
223
282
`OpenOne` reads one value and refuses a read whose path has a wildcard before anything is opened; open a wildcard read with `Open`.
224
283
A needle and a value are Go values: a `json.RawMessage` of JSON text crosses as it is, and anything else is marshalled with `encoding/json`.
225
284
`EqAt` and the orderings take a scalar: a string, a number, a bool, or `nil` for JSON `null`.
0 commit comments