Skip to content

Commit ebb480d

Browse files
authored
JSON.md edits
1 parent 229cb9c commit ebb480d

File tree

1 file changed

+30
-33
lines changed

1 file changed

+30
-33
lines changed

docs/reference/JSON.md

Lines changed: 30 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,19 @@
22

33
EQL supports encrypting, decrypting, and searching JSON and JSONB objects.
44

5-
## Table of contents
6-
7-
- [Configuring the Index](#configuring-the-index)
8-
- [Inserting JSON Data](#inserting-json-data)
9-
- [Reading JSON Data](#reading-json-data)
10-
- [Querying JSONB Data with EQL](#querying-jsonb-data-with-eql)
11-
- [Containment Queries (`cs_ste_vec_v1`)](#containment-queries-cs_ste_vec_v1)
12-
- [Field Extraction (`cs_ste_vec_value_v1`)](#field-extraction-cs_ste_vec_value_v1)
13-
- [Field Comparison (`cs_ste_vec_term_v1`)](#field-comparison-cs_ste_vec_term_v1)
14-
- [Grouping Data](#grouping-data)
15-
- [Reference](#reference)
16-
- [EQL Functions for JSONB and `ste_vec`](#eql-functions-for-jsonb-and-ste_vec)
17-
- [EJSON Paths](#ejson-paths)
18-
- [Native PostgreSQL JSON(B) Compared to EQL](#native-postgresql-jsonb-compared-to-eql)
5+
## On this page
6+
7+
- [Configuring the index](#configuring-the-index)
8+
- [Inserting JSON data](#inserting-json-data)
9+
- [Reading JSON data](#reading-json-data)
10+
- [Querying JSONB data with EQL](#querying-jsonb-data-with-eql)
11+
- [Containment queries (`cs_ste_vec_v1`)](#containment-queries-cs_ste_vec_v1)
12+
- [Field extraction (`cs_ste_vec_value_v1`)](#field-extraction-cs_ste_vec_value_v1)
13+
- [Field comparison (`cs_ste_vec_term_v1`)](#field-comparison-cs_ste_vec_term_v1)
14+
- [Grouping data](#grouping-data)
15+
- [EQL functions for JSONB and `ste_vec`](#eql-functions-for-jsonb-and-ste_vec)
16+
- [EJSON paths](#ejson-paths)
17+
- [Native PostgreSQL JSON(B) compared to EQL](#native-postgresql-jsonb-compared-to-eql)
1918
- [`json ->> text``text` and `json -> text``jsonb`/`json`](#json--text--text-and-json---text--jsonbjson)
2019
- [Decryption Example](#decryption-example)
2120
- [Comparison Example](#comparison-example)
@@ -116,15 +115,15 @@ Data is returned as:
116115
}
117116
```
118117

119-
## Querying JSONB Data with EQL
118+
## Querying JSONB data with EQL
120119

121120
EQL provides specialized functions to interact with encrypted JSONB data, supporting operations like containment queries, field extraction, and comparisons.
122121

123-
### Containment Queries (`cs_ste_vec_v1`)
122+
### Containment queries (`cs_ste_vec_v1`)
124123

125124
Retrieve the Structured Encryption Vector for JSONB containment queries.
126125

127-
**Example: Containment Query**
126+
**Example: Containment query**
128127

129128
Suppose we have the following encrypted JSONB data:
130129

@@ -138,7 +137,7 @@ Suppose we have the following encrypted JSONB data:
138137

139138
We can query records that contain a specific structure.
140139

141-
**SQL Query:**
140+
**SQL query:**
142141

143142
```sql
144143
SELECT * FROM examples
@@ -162,11 +161,11 @@ WHERE jsonb_column @> '{"top":{"nested":["a"]}}';
162161

163162
**Note:** The `@>` operator checks if the left JSONB value contains the right JSONB value.
164163

165-
**Negative Example:**
164+
**Negative example:**
166165

167166
If we query for a value that does not exist in the data:
168167

169-
**SQL Query:**
168+
**SQL query:**
170169

171170
```sql
172171
SELECT * FROM examples
@@ -183,7 +182,7 @@ WHERE cs_ste_vec_v1(encrypted_json) @> cs_ste_vec_v1(
183182

184183
This query would return no results, as the value `"d"` is not present in the `"nested"` array.
185184

186-
### Field Extraction (`cs_ste_vec_value_v1`)
185+
### Field extraction (`cs_ste_vec_value_v1`)
187186

188187
Extract a field from an encrypted JSONB object.
189188

@@ -201,7 +200,7 @@ Suppose we have the following encrypted JSONB data:
201200

202201
We can extract the value of the `"top"` key.
203202

204-
**SQL Query:**
203+
**SQL query:**
205204

206205
```sql
207206
SELECT cs_ste_vec_value_v1(encrypted_json,
@@ -231,7 +230,7 @@ FROM examples;
231230
}
232231
```
233232

234-
### Field Comparison (`cs_ste_vec_term_v1`)
233+
### Field comparison (`cs_ste_vec_term_v1`)
235234

236235
Select rows based on a field value in an encrypted JSONB object.
237236

@@ -247,7 +246,7 @@ Suppose we have encrypted JSONB data with a numeric field:
247246

248247
We can query records where the `"num"` field is greater than `2`.
249248

250-
**SQL Query:**
249+
**SQL query:**
251250

252251
```sql
253252
SELECT * FROM examples
@@ -277,7 +276,7 @@ SELECT * FROM examples
277276
WHERE (jsonb_column->>'num')::int > 2;
278277
```
279278

280-
### Grouping Data
279+
### Grouping data
281280

282281
Use `cs_ste_vec_term_v1` along with `cs_grouped_value_v1` to group by a field in an encrypted JSONB column.
283282

@@ -296,7 +295,7 @@ Suppose we have records with a `"color"` field:
296295

297296
We can group the data by the `"color"` field and count occurrences.
298297

299-
**SQL Query:**
298+
**SQL query:**
300299

301300
```sql
302301
SELECT cs_grouped_value_v1(cs_ste_vec_value_v1(encrypted_json,
@@ -336,24 +335,22 @@ GROUP BY jsonb_column->>'color';
336335
| green | 2 |
337336
| red | 1 |
338337

339-
## Reference
338+
## EQL Functions for JSONB and `ste_vec`
340339

341-
### EQL Functions for JSONB and `ste_vec`
342-
343-
- **Index Management**
340+
- **Index management**
344341

345342
- `cs_add_index_v1(table_name text, column_name text, 'ste_vec', 'jsonb', opts jsonb)`: Adds an `ste_vec` index configuration.
346343
- `opts` must include the `"context"` key.
347344

348-
- **Query Functions**
345+
- **Query functions**
349346

350347
- `cs_ste_vec_v1(val jsonb)`: Retrieves the STE vector for JSONB containment queries.
351348
- `cs_ste_vec_term_v1(val jsonb, epath jsonb)`: Retrieves the encrypted term associated with an encrypted JSON path.
352349
- `cs_ste_vec_value_v1(val jsonb, epath jsonb)`: Retrieves the decrypted value associated with an encrypted JSON path.
353350
- `cs_ste_vec_terms_v1(val jsonb, epath jsonb)`: Retrieves an array of encrypted terms for elements in an array at the given JSON path (used for comparisons).
354351
- `cs_grouped_value_v1(val jsonb)`: Used with `ste_vec` indexes for grouping.
355352

356-
### EJSON Paths
353+
## EJSON paths
357354

358355
EQL uses an extended JSONPath syntax called EJSONPath for specifying paths in JSONB data.
359356

@@ -363,7 +360,7 @@ EQL uses an extended JSONPath syntax called EJSONPath for specifying paths in JS
363360
- Wildcards are supported: `$.some_array_field[*]`
364361
- Array indexing is **not** supported: `$.some_array_field[0]`
365362

366-
**Example Paths:**
363+
**Example paths:**
367364

368365
- `$.top.nested` selects the `"nested"` key within the `"top"` object.
369366
- `$.array[*]` selects all elements in the `"array"` array.

0 commit comments

Comments
 (0)