doc: v3 beta.29 release (#525)

ymc9 · web-flow · commit b3c00960639c · 2025-12-13T17:30:23.000+08:00
* doc: v3 beta.29 release

* add submodule changes
diff --git a/code-repos/zenstackhq/v3-doc-orm b/code-repos/zenstackhq/v3-doc-orm
@@ -1 +1 @@
-Subproject commit ed333f6978625f201f2250075ec5ad74c06d9809
+Subproject commit a3f7b09fa6b4c39d6582b3dae0504e95aab7cc21
diff --git a/code-repos/zenstackhq/v3-doc-orm-computed-fields b/code-repos/zenstackhq/v3-doc-orm-computed-fields
@@ -1 +1 @@
-Subproject commit e3e28ed50d26f069a6fbae2b3de94ad7bdf34492
+Subproject commit 05c609c716ea30f7a30b094f828f51d0157ab2bd
diff --git a/code-repos/zenstackhq/v3-doc-orm-policy b/code-repos/zenstackhq/v3-doc-orm-policy
@@ -1 +1 @@
-Subproject commit 5d1ecc37ee5f32b8f8be51c5ba1e6a7083354118
+Subproject commit 33aec4f07bccc094d202321c13393ddf356a10ac
diff --git a/code-repos/zenstackhq/v3-doc-orm-polymorphism b/code-repos/zenstackhq/v3-doc-orm-polymorphism
@@ -1 +1 @@
-Subproject commit 19b16db342d1174d996fc1d4352bf712b36ffe0d
+Subproject commit a1b3e19f5f911beee57181211c7bc4dc748ce8b6
diff --git a/code-repos/zenstackhq/v3-doc-orm-typed-json b/code-repos/zenstackhq/v3-doc-orm-typed-json
@@ -1 +1 @@
-Subproject commit 78beb330036e63051bbab086ae538faabbcc51af
+Subproject commit f04a076f104703a312510f943dedc831466b6139
diff --git a/code-repos/zenstackhq/v3-doc-orm-validation b/code-repos/zenstackhq/v3-doc-orm-validation
@@ -1 +1 @@
-Subproject commit 823addfc483da683dfaa41f7b452993df97dd406
+Subproject commit 42aa1d6e4ae1c1b6cffcca911a5c4fea365506c9
diff --git a/code-repos/zenstackhq/v3-doc-quick-start b/code-repos/zenstackhq/v3-doc-quick-start
@@ -1 +1 @@
-Subproject commit ae6206685f1920c989a9ea3c7e361955f8169d3c
+Subproject commit f0d2f9f415d37463a6425077b78a7b81212215ee
diff --git a/code-repos/zenstackhq/v3-doc-server-adapter b/code-repos/zenstackhq/v3-doc-server-adapter
@@ -1 +1 @@
-Subproject commit d4ad9aa4bc6889b9c49cb34d703c7f346ab48778
+Subproject commit 229984e1298c9fb94a55c94f2ccb242f4f67f8ae
diff --git a/code-repos/zenstackhq/v3-doc-tanstack-query b/code-repos/zenstackhq/v3-doc-tanstack-query
@@ -1 +1 @@
-Subproject commit 52a9816e6eba1ba7d96e499b062c2c9f539a850d
+Subproject commit b57abffec66d168bd3918b81776ddd1bb24fbeec
diff --git a/src/components/StackBlitzGithub.tsx b/src/components/StackBlitzGithub.tsx
@@ -29,13 +29,9 @@ const StackBlitzGithub: React.FC<StackBlitzGithubProps> = ({
 
     return (
         <>
-            <div className="mb-1 italic text-sm">
-                Click{' '}
-                <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}>
-                    here
-                </a>{' '}
-                to open an interactive playground.
-            </div>
+            <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}>
+                <img alt="Open in StackBlitz" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" />
+            </a>
             {plainCodeFiles.map((file) => (
                 <GithubCodeBlock key={file} repoPath={repoPath} file={file} />
             ))}
diff --git a/versioned_docs/version-3.x/orm/api/filter.md b/versioned_docs/version-3.x/orm/api/filter.md
@@ -63,10 +63,52 @@ await db.post.findMany({
 
 ## Json filters
 
-:::info WORK IN PROGRESS
-Filtering on Json fields is work in progress and will be available soon.
+The query API supports flexible filtering on `Json` fields and allows you to reach into nested structures in the JSON data.
+
+### Generic Json filters
+
+Generic Json filters doesn't assume a predefined structure of the JSON data, and allows you to use JSON path to specify the location of the data you want to filter on. Such filters can be used on both plain `Json` and [Typed Json](../../modeling/typed-json) fields. The following fields can be used in the filter body (all fields are optional):
+
+- `path`
+
+    JSON path string for selecting data to filter on. If not provided, the root of the JSON data is used.
+
+    <ZenStackVsPrisma>
+    While for Prisma the "path" field's format depends on the database type, ZenStack unified it to a JSON path string.
+    </ZenStackVsPrisma>
+
+- `equals`
+
+    Checks if the selected data equals the given value. The value can be primitive types, arrays, or objects.
+
+- `not`
+
+    Checks if the selected data does not equal the given value. The value can be primitive types, arrays, or objects.
+
+- `string_contains`, `string_starts_with`, `string_ends_with`
+
+    String matching operators. If the selected data is not a string, the filter evaluates to false.
+
+- `mode`
+
+    Specifies if the string matching should be case sensitive or insensitive. Possible values are "default" (use default database behavior) and "insensitive" (case insensitive). Default is "default". Case insensitive matching is only supported on databases that support it natively (e.g., PostgreSQL).
+
+- `array_contains`, `array_starts_with`, `array_ends_with`
+
+    Array matching operators. If the selected data is not an array, the filter evaluates to false.
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="filter/json.ts" startScript="generate,filter:json" />
+
+### Typed Json filters
+
+Typed Json fields, with their structure well defined in the schema, allow for a more powerful way to filter. Instead of using JSON path, you can directly use fields to build-up the filter, similar to how you would filter with relations.
+
+:::tip
+You can still use generic Json filters on Typed Json fields if needed.
 :::
 
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-typed-json" openFile="filter.ts" startScript="generate,filter" />
+
 ## Relation filters
 
 Filters can be defined on conditions over relations. For one-to-one relations, you can filter on their fields directly. For one-to-many relations, use the "some", "every", or "none" operators to build a condition over a list of records.
diff --git a/versioned_docs/version-3.x/orm/polymorphism.md b/versioned_docs/version-3.x/orm/polymorphism.md
@@ -19,7 +19,7 @@ ZenStack natively supports polymorphic models. As we have seen in the [Polymorph
 Polymorphic models' CRUD behavior is similar to that of regular models, with two major differences:
 
 1. Base model entities cannot be created directly as they cannot exist without an associated concrete model entity.
-2. When querying a base model (either top-level or nested), the result will include all fields of the associated concrete model (unless fields are explicitly selected). The result's type is a discriminated union, so you can use TypeScript's type narrowing to access the concrete model's specific fields.
+2. When querying a base model (either top-level or nested), the result will include all fields of the associated concrete model (unless fields are explicitly selected).
 
 The ORM query API hides all the complexity of managing polymorphic models for you:
 - When creating a concrete model entity, its base entity is automatically created.
