Merge pull request #287 from cipherstash/drizzle-searchable-jsonb

Add JSONB query operators for drizzle: jsonbPathQueryFirst, jsonbGet, and jsonbPathExists

Author: tobyhede

docs/reference/drizzle/drizzle.md

@@ -274,6 +274,56 @@ return results
 
 ---
 
+## JSONB queries with encrypted data
+
+Protect.js supports querying encrypted JSON columns using JSONB operators. These operators require `searchableJson: true` and `dataType: 'json'` in the column's `encryptedType` config.
+
+> [!TIP]
+> For details on the low-level `encryptQuery` API and JSONB query types (`steVecSelector`, `steVecTerm`), see the [Searchable encryption with PostgreSQL](../searchable-encryption-postgres.md#jsonb-queries-with-searchablejson-recommended) reference.
+
+### Check path existence with `jsonbPathExists`
+
+Use `jsonbPathExists` to check if a JSONPath exists in the JSONB data. This returns a boolean and can be used directly in `WHERE` clauses. This is equivalent to the PostgreSQL `jsonb_path_exists` function.
+
+```typescript
+const results = await db
+  .select()
+  .from(usersTable)
+  .where(await protect.jsonbPathExists(usersTable.profile, '$.bio'))
+```
+
+### Extract value with `jsonbPathQueryFirst`
+
+Use `jsonbPathQueryFirst` to extract the first value at a given JSONPath in a `SELECT` expression. This is equivalent to the PostgreSQL `jsonb_path_query_first` function.
+
+> [!NOTE]
+> `jsonbPathQueryFirst` returns an encrypted value, not a boolean. Use it in `SELECT` expressions, not directly in `WHERE` clauses. Use `jsonbPathExists` to filter rows by path existence.
+
+### Get value with `jsonbGet`
+
+Use `jsonbGet` to get a value using the JSONB `->` operator in a `SELECT` expression.
+
+> [!NOTE]
+> `jsonbGet` returns an encrypted value, not a boolean. Use it in `SELECT` expressions, not directly in `WHERE` clauses. Use `jsonbPathExists` to filter rows by path existence.
+
+### Combine JSONB operators with other conditions
+
+JSONB operators can be combined with other Protect operators using `and` and `or`. Use `jsonbPathExists` for boolean conditions in `WHERE` clauses.
+
+```typescript
+const results = await db
+  .select()
+  .from(usersTable)
+  .where(
+    await protect.and(
+      protect.jsonbPathExists(usersTable.profile, '$.name'),
+      protect.eq(usersTable.email, 'jane@example.com'),
+    ),
+  )
+```
+
+---
+
 ## Aggregation operations
 
 ### Count all transactions

docs/reference/searchable-encryption-postgres.md

@@ -116,6 +116,9 @@ console.log(term.data) // array of search terms
 
 ### JSONB queries with searchableJson (recommended)
 
+> [!TIP]
+> **Using Drizzle ORM?** The `@cipherstash/drizzle` package provides higher-level JSONB operators (`jsonbPathQueryFirst`, `jsonbGet`, `jsonbPathExists`) that handle encryption automatically. See the [Drizzle JSONB query examples](./drizzle/drizzle.md#jsonb-queries-with-encrypted-data).
+
 For columns storing JSON data, `.searchableJson()` is the recommended approach. It enables encrypted JSONB queries and automatically infers the correct query operation from the plaintext value type.
 
 Use `encryptQuery` to create encrypted query terms for JSONB columns:

local/create-ci-table.sql

@@ -4,5 +4,6 @@ CREATE TABLE "protect-ci" (
   age eql_v2_encrypted,
   score eql_v2_encrypted,
   profile eql_v2_encrypted,
-  created_at TIMESTAMP DEFAULT NOW()
+  created_at TIMESTAMP DEFAULT NOW(),
+  test_run_id TEXT
 );

packages/drizzle/README.md

@@ -94,9 +94,10 @@ export const usersTable = pgTable('users', {
     orderAndRange: true,
   }),
 
-  // JSON object with typed structure
+  // JSON object with searchable JSONB queries
   profile: encryptedType<{ name: string; bio: string }>('profile', {
     dataType: 'json',
+    searchableJson: true,
   }),
 
   createdAt: timestamp('created_at').defaultNow(),
@@ -227,6 +228,31 @@ const decrypted = await protectClient.bulkDecryptModels(results)
 > [!IMPORTANT]
 > Sorting with ORE on Supabase and other databases that don't support operator families will not work as expected.
 
+### Query encrypted JSONB data
+
+```typescript
+// Check if a path exists in encrypted JSONB data
+const results = await db
+  .select()
+  .from(usersTable)
+  .where(await protectOps.jsonbPathExists(usersTable.profile, '$.bio'))
+
+// Combine JSONB operators with other conditions
+const results = await db
+  .select()
+  .from(usersTable)
+  .where(
+    await protectOps.and(
+      protectOps.jsonbPathExists(usersTable.profile, '$.name'),
+      protectOps.eq(usersTable.email, 'jane@example.com'),
+    ),
+  )
+```
+
+> [!NOTE]
+> `jsonbPathExists` returns a boolean and can be used directly in `WHERE` clauses.
+> `jsonbPathQueryFirst` and `jsonbGet` return encrypted values, not booleans — use them in `SELECT` expressions, not in `WHERE` clauses.
+
 ### Complex queries with mixed operators
 
 ```typescript
@@ -275,6 +301,14 @@ All operators automatically handle encryption for encrypted columns.
 - `inArray(left, right[])` - In array
 - `notInArray(left, right[])` - Not in array
 
+### JSONB Operators (async)
+- `jsonbPathQueryFirst(column, selector)` - Extract first value at JSONB path
+- `jsonbGet(column, selector)` - Get value using JSONB `->` operator
+- `jsonbPathExists(column, selector)` - Check if path exists in JSONB
+
+> [!IMPORTANT]
+> JSONB operators require `searchableJson: true` and `dataType: 'json'` in the column's `encryptedType` config.
+
 ### Sorting Operators (sync)
 - `asc(column)` - Ascending order
 - `desc(column)` - Descending order
@@ -304,6 +338,7 @@ Creates an encrypted column type for Drizzle schemas.
 - `freeTextSearch?: boolean` - Enable text search (LIKE/ILIKE)
 - `equality?: boolean` - Enable equality queries
 - `orderAndRange?: boolean` - Enable range queries and sorting
+- `searchableJson?: boolean` - Enable JSONB path queries (requires `dataType: 'json'`)
 
 ### `extractProtectSchema(table)`
 

packages/drizzle/__tests__/docs.test.ts

@@ -11,7 +11,7 @@ import {
   createProtectOperators,
   encryptedType,
   extractProtectSchema,
-} from '../src/pg'
+} from '@cipherstash/drizzle/pg'
 import { docSeedData } from './fixtures/doc-seed-data'
 import { type ExecutionContext, executeCodeBlock } from './utils/code-executor'
 import { extractExecutableBlocks } from './utils/markdown-parser'