Skip to content

Commit 3e68575

Browse files
CDThomasCDThomas
committed
Group sections on ->>/-> with both ints and text together
1 parent 538ac13 commit 3e68575

File tree

1 file changed

+99
-99
lines changed

1 file changed

+99
-99
lines changed

‎NATIVE_POSTGRES_JSON_COMPARED_TO_EQL.md

Lines changed: 99 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -87,45 +87,45 @@ WHERE cs_ste_vec_term_v1(examples.encrypted_jsonb, $1) > cs_ste_vec_term_v1($2)
8787
}
8888
```
8989

90-
## `json #>> text[]` → `text` and `json #> text[]` → `jsonb`/`json`
90+
## `json ->> int` → `text` and `json -> int` → `jsonb`/`json`
9191

9292
### Native Postgres JSON(B)
9393

9494
```sql
95-
-- `#>` (returns JSON(B))
96-
SELECT plaintext_jsonb#>'{field_a,field_b}' FROM examples;
95+
-- `->` (returns JSON(B))
96+
SELECT plaintext_jsonb->0 FROM examples;
9797

98-
-- `#>>` (returns text)
99-
SELECT plaintext_jsonb#>>'{field_a,field_b}' FROM examples;
98+
-- `->>` (returns text)
99+
SELECT plaintext_jsonb->>0 FROM examples;
100100
```
101101

102102
### EQL
103103

104-
EQL JSONB functions accept an eJSONPath as an argument (instead of using `#>`/`#>>`) for lookups.
105-
106-
Note that these are similar to the examples for `->`/`->>`. The difference in these examples is that the path does a lookup multiple levels deep.
104+
EQL JSONB functions accept an eJSONPath as an argument (instead of using `->`/`->>`) for lookups.
107105

108106
#### Decryption example
109107

110-
`cs_ste_vec_value_v1` returns the Plaintext EQL payload to the client.
108+
EQL currently doesn't support returning a specific array element for decryption, but `cs_ste_vec_value_v1` can be used to return an array to the client to process.
109+
110+
The query...
111111

112112
```sql
113-
SELECT cs_ste_vec_value_v1(encrypted_jsonb, $1) FROM examples;
113+
SELECT cs_ste_vec_value_v1(encrypted_jsonb, $1) AS val FROM examples;
114114
```
115115

116+
With the params...
117+
116118
```javascript
117119
// Assume that examples.encrypted_jsonb has JSON objects with
118120
// the shape:
119121
{
120-
"field_a": {
121-
"field_b": 100
122-
}
122+
"field_a": [1, 2, 3]
123123
}
124124

125-
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a.field_b`:
125+
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a`:
126126
{
127127
"k": "pt",
128-
"p": "$.field_a.field_b",
128+
"p": "$.field_a",
129129
"i": {
130130
"t": "examples",
131131
"c": "encrypted_jsonb"
@@ -135,28 +135,50 @@ SELECT cs_ste_vec_value_v1(encrypted_jsonb, $1) FROM examples;
135135
}
136136
```
137137

138+
Would return the EQL plaintext payload with an array (`[1, 2, 3]` for example):
139+
140+
```javascript
141+
// Example result for a single row
142+
{
143+
"k": "pt",
144+
"p": "[1, 2, 3]",
145+
"i": {
146+
"t": "examples",
147+
"c": "encrypted_jsonb"
148+
},
149+
"v": 1,
150+
"q": null
151+
}
152+
```
153+
138154
#### Comparison example
139155

140-
`cs_ste_vec_term_v1` returns an ORE term for comparison.
156+
`cs_ste_vec_terms_v1` can be used with the native Postgres array access operator to get a term for comparison by array index.
157+
158+
The eJSONPath used with `cs_ste_vec_terms_v1` needs to end with `[*]` (`$.some_array_field[*]` for example).
159+
160+
> [!IMPORTANT]
161+
> Array access with `cs_ste_vec_terms_v1` only works when the given eJSONPath only matches a single array.
162+
> Accessing array elements from `cs_ste_vec_terms_v1` when the eJSONPath matches multiple arrays (for example, when there are nested arrays or multiple arrays at the same depth) can return unexpected results.
163+
164+
The following query compares the first item in the array at the eJSONPath in $1 to the value in $2.
141165

142166
```sql
143167
SELECT * FROM examples
144-
WHERE cs_ste_vec_term_v1(examples.encrypted_jsonb, $1) > cs_ste_vec_term_v1($2)
168+
WHERE (cs_ste_vec_terms_v1(examples.encrypted_jsonb, $1))[1] > cs_ste_vec_term_v1($2)
145169
```
146170

147171
```javascript
148172
// Assume that examples.encrypted_jsonb has JSON objects with
149173
// the shape:
150174
{
151-
"field_a": {
152-
"field_b": 100
153-
}
175+
"field_a": [4, 5, 6]
154176
}
155177

156-
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a.field_b`:
178+
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a[*]`:
157179
{
158180
"k": "pt",
159-
"p": "$.field_a.field_b",
181+
"p": "$.field_a[*]",
160182
"i": {
161183
"t": "examples",
162184
"c": "encrypted_jsonb"
@@ -165,10 +187,10 @@ WHERE cs_ste_vec_term_v1(examples.encrypted_jsonb, $1) > cs_ste_vec_term_v1($2)
165187
"q": "ejson_path"
166188
}
167189

168-
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `123`):
190+
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `3`):
169191
{
170192
"k": "pt",
171-
"p": "123",
193+
"p": "3",
172194
"i": {
173195
"t": "examples",
174196
"c": "encrypted_jsonb"
@@ -178,53 +200,45 @@ WHERE cs_ste_vec_term_v1(examples.encrypted_jsonb, $1) > cs_ste_vec_term_v1($2)
178200
}
179201
```
180202

181-
## `json_array_elements`, `jsonb_array_elements`, `json_array_elements_text`, and `jsonb_array_elements_text`
203+
## `json #>> text[]` → `text` and `json #> text[]` → `jsonb`/`json`
182204

183205
### Native Postgres JSON(B)
184206

185207
```sql
186-
-- Each returns the results...
187-
--
188-
-- Value
189-
-- _____
190-
-- a
191-
-- b
192-
--
193-
-- The only difference is that the input is either json or jsonb (depending
194-
-- on the prefix of the function name) and the output is either json,
195-
-- jsonb, or text (depending on both the prefix and the suffix).
208+
-- `#>` (returns JSON(B))
209+
SELECT plaintext_jsonb#>'{field_a,field_b}' FROM examples;
196210

197-
SELECT * from json_array_elements('["a", "b"]');
198-
SELECT * from jsonb_array_elements('["a", "b"]');
199-
SELECT * from json_array_elements_text('["a", "b"]');
200-
SELECT * from jsonb_array_elements_text('["a", "b"]');
211+
-- `#>>` (returns text)
212+
SELECT plaintext_jsonb#>>'{field_a,field_b}' FROM examples;
201213
```
202214

203215
### EQL
204216

205-
#### Decryption example
217+
EQL JSONB functions accept an eJSONPath as an argument (instead of using `#>`/`#>>`) for lookups.
206218

207-
EQL currently doesn't support returning a `SETOF` values for decryption (for returning a row per item in an array), but `cs_ste_vec_value_v1` can be used to return an array to the client to process.
219+
Note that these are similar to the examples for `->`/`->>`. The difference in these examples is that the path does a lookup multiple levels deep.
208220

209-
The query...
221+
#### Decryption example
222+
223+
`cs_ste_vec_value_v1` returns the Plaintext EQL payload to the client.
210224

211225
```sql
212-
SELECT cs_ste_vec_value_v1(encrypted_jsonb, $1) AS val FROM examples;
226+
SELECT cs_ste_vec_value_v1(encrypted_jsonb, $1) FROM examples;
213227
```
214228

215-
With the params...
216-
217229
```javascript
218230
// Assume that examples.encrypted_jsonb has JSON objects with
219231
// the shape:
220232
{
221-
"field_a": [1, 2, 3]
233+
"field_a": {
234+
"field_b": 100
235+
}
222236
}
223237

224-
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a`:
238+
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a.field_b`:
225239
{
226240
"k": "pt",
227-
"p": "$.field_a",
241+
"p": "$.field_a.field_b",
228242
"i": {
229243
"t": "examples",
230244
"c": "encrypted_jsonb"
@@ -234,50 +248,28 @@ With the params...
234248
}
235249
```
236250

237-
Would return the EQL plaintext payload with an array (`[1, 2, 3]` for example):
238-
239-
```javascript
240-
// Example result for a single row
241-
{
242-
"k": "pt",
243-
"p": "[1, 2, 3]",
244-
"i": {
245-
"t": "examples",
246-
"c": "encrypted_jsonb"
247-
},
248-
"v": 1,
249-
"q": null
250-
}
251-
```
252-
253251
#### Comparison example
254252

255-
`cs_ste_vec_terms_v1` (note that terms is plural) can be used to return an array of ORE terms for comparison. The array can be `unnest`ed to work with a `SETOF` ORE terms for comparison.
256-
257-
The eJSONPath used with `cs_ste_vec_terms_v1` needs to end with `[*]` (`$.some_array_field[*]` for example).
258-
259-
Example query:
253+
`cs_ste_vec_term_v1` returns an ORE term for comparison.
260254

261255
```sql
262-
SELECT id FROM examples e
263-
WHERE EXISTS (
264-
SELECT 1
265-
FROM unnest(cs_ste_vec_terms_v1(e.encrypted_jsonb, $1)) AS term
266-
WHERE term > cs_ste_vec_term_v1($2)
267-
);
256+
SELECT * FROM examples
257+
WHERE cs_ste_vec_term_v1(examples.encrypted_jsonb, $1) > cs_ste_vec_term_v1($2)
268258
```
269259

270260
```javascript
271261
// Assume that examples.encrypted_jsonb has JSON objects with
272262
// the shape:
273263
{
274-
"field_a": [1, 2, 3]
264+
"field_a": {
265+
"field_b": 100
266+
}
275267
}
276268

277-
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a[*]`:
269+
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a.field_b`:
278270
{
279271
"k": "pt",
280-
"p": "$.field_a[*]",
272+
"p": "$.field_a.field_b",
281273
"i": {
282274
"t": "examples",
283275
"c": "encrypted_jsonb"
@@ -286,10 +278,10 @@ WHERE EXISTS (
286278
"q": "ejson_path"
287279
}
288280

289-
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `2`):
281+
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `123`):
290282
{
291283
"k": "pt",
292-
"p": "2",
284+
"p": "123",
293285
"i": {
294286
"t": "examples",
295287
"c": "encrypted_jsonb"
@@ -299,25 +291,33 @@ WHERE EXISTS (
299291
}
300292
```
301293

302-
## `json ->> int` → `text` and `json -> int` → `jsonb`/`json`
294+
## `json_array_elements`, `jsonb_array_elements`, `json_array_elements_text`, and `jsonb_array_elements_text`
303295

304296
### Native Postgres JSON(B)
305297

306298
```sql
307-
-- `->` (returns JSON(B))
308-
SELECT plaintext_jsonb->0 FROM examples;
299+
-- Each returns the results...
300+
--
301+
-- Value
302+
-- _____
303+
-- a
304+
-- b
305+
--
306+
-- The only difference is that the input is either json or jsonb (depending
307+
-- on the prefix of the function name) and the output is either json,
308+
-- jsonb, or text (depending on both the prefix and the suffix).
309309

310-
-- `->>` (returns text)
311-
SELECT plaintext_jsonb->>0 FROM examples;
310+
SELECT * from json_array_elements('["a", "b"]');
311+
SELECT * from jsonb_array_elements('["a", "b"]');
312+
SELECT * from json_array_elements_text('["a", "b"]');
313+
SELECT * from jsonb_array_elements_text('["a", "b"]');
312314
```
313315

314316
### EQL
315317

316-
EQL JSONB functions accept an eJSONPath as an argument (instead of using `->`/`->>`) for lookups.
317-
318318
#### Decryption example
319319

320-
EQL currently doesn't support returning a specific array element for decryption, but `cs_ste_vec_value_v1` can be used to return an array to the client to process.
320+
EQL currently doesn't support returning a `SETOF` values for decryption (for returning a row per item in an array), but `cs_ste_vec_value_v1` can be used to return an array to the client to process.
321321

322322
The query...
323323

@@ -365,26 +365,26 @@ Would return the EQL plaintext payload with an array (`[1, 2, 3]` for example):
365365

366366
#### Comparison example
367367

368-
`cs_ste_vec_terms_v1` can be used with the native Postgres array access operator to get a term for comparison by array index.
368+
`cs_ste_vec_terms_v1` (note that terms is plural) can be used to return an array of ORE terms for comparison. The array can be `unnest`ed to work with a `SETOF` ORE terms for comparison.
369369

370370
The eJSONPath used with `cs_ste_vec_terms_v1` needs to end with `[*]` (`$.some_array_field[*]` for example).
371371

372-
> [!IMPORTANT]
373-
> Array access with `cs_ste_vec_terms_v1` only works when the given eJSONPath only matches a single array.
374-
> Accessing array elements from `cs_ste_vec_terms_v1` when the eJSONPath matches multiple arrays (for example, when there are nested arrays or multiple arrays at the same depth) can return unexpected results.
375-
376-
The following query compares the first item in the array at the eJSONPath in $1 to the value in $2.
372+
Example query:
377373

378374
```sql
379-
SELECT * FROM examples
380-
WHERE (cs_ste_vec_terms_v1(examples.encrypted_jsonb, $1))[1] > cs_ste_vec_term_v1($2)
375+
SELECT id FROM examples e
376+
WHERE EXISTS (
377+
SELECT 1
378+
FROM unnest(cs_ste_vec_terms_v1(e.encrypted_jsonb, $1)) AS term
379+
WHERE term > cs_ste_vec_term_v1($2)
380+
);
381381
```
382382

383383
```javascript
384384
// Assume that examples.encrypted_jsonb has JSON objects with
385385
// the shape:
386386
{
387-
"field_a": [4, 5, 6]
387+
"field_a": [1, 2, 3]
388388
}
389389

390390
// `$1` is the EQL plaintext payload for the eJSONPath `$.field_a[*]`:
@@ -399,10 +399,10 @@ WHERE (cs_ste_vec_terms_v1(examples.encrypted_jsonb, $1))[1] > cs_ste_vec_term_v
399399
"q": "ejson_path"
400400
}
401401

402-
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `3`):
402+
// `$2` is the EQL plaintext payload for the ORE term to compare against (in this case, the ORE term for the integer `2`):
403403
{
404404
"k": "pt",
405-
"p": "3",
405+
"p": "2",
406406
"i": {
407407
"t": "examples",
408408
"c": "encrypted_jsonb"

0 commit comments

Comments
 (0)