system-udfs: make search filter clauses an array (#40632)

Nicolapps · Convex, Inc. · commit 5b7f77b0436a · 2025-09-04T19:30:19.000Z
I realized when working on the UI that it’s more convenient for SearchIndexFilters.clauses to be an array rather than an object. In particular, it ensures that the order is stable, and allows users to define multiple filters for the same field (but enable only one of them).

There are no worries about backwards compatibility since the feature isn’t live yet.

GitOrigin-RevId: 2b7f029cded4cc89d83c40a8499300e8243f9eb1
diff --git a/npm-packages/system-udfs/convex/_system/frontend/lib/filters.test.ts b/npm-packages/system-udfs/convex/_system/frontend/lib/filters.test.ts
@@ -548,10 +548,10 @@ describe("filters", () => {
     it("should apply search index filters correctly", () => {
       const mockBuilder = new MockSearchBuilder();
       const searchString = "test search";
-      const searchIndexFilters = {
-        userId: { enabled: true, value: "user123" },
-        organizationId: { enabled: true, value: 42 },
-      };
+      const searchIndexFilters = [
+        { field: "userId", enabled: true, value: "user123" },
+        { field: "organizationId", enabled: true, value: 42 },
+      ];
       const selectedIndex: SearchIndex = {
         indexDescriptor: "testSearchIndex",
         searchField: "description",
@@ -572,38 +572,13 @@ describe("filters", () => {
       ]);
     });
 
-    it("should handle empty filters object", () => {
-      const mockBuilder = new MockSearchBuilder();
-      const searchString = "test search";
-      const searchIndexFilters = {};
-      const selectedIndex: SearchIndex = {
-        indexDescriptor: "testSearchIndex",
-        searchField: "description",
-        filterFields: ["userId", "organizationId"],
-      };
-
-      applySearchIndexFilters(
-        mockBuilder as any,
-        searchString,
-        searchIndexFilters,
-        selectedIndex,
-      );
-
-      expect(mockBuilder.operations).toEqual([
-        { op: "search", field: "description", value: "test search" },
-      ]);
-    });
-
     it("should only apply filters for fields that exist in the filter", () => {
       const mockBuilder = new MockSearchBuilder();
       const searchString = "test search";
-      const searchIndexFilters = {
-        userId: {
-          enabled: true,
-          value: "user123",
-        },
+      const searchIndexFilters = [
+        { field: "userId", enabled: true, value: "user123" },
         // organizationId is missing
-      };
+      ];
       const selectedIndex: SearchIndex = {
         indexDescriptor: "testSearchIndex",
         searchField: "description",
@@ -626,16 +601,18 @@ describe("filters", () => {
     it("should only apply filters for enabled fields", () => {
       const mockBuilder = new MockSearchBuilder();
       const searchString = "test search";
-      const searchIndexFilters = {
-        userId: {
+      const searchIndexFilters = [
+        {
+          field: "userId",
           enabled: true,
           value: "user123",
         },
-        organizationId: {
+        {
+          field: "organizationId",
           enabled: false,
           value: "org123",
         },
-      };
+      ];
       const selectedIndex: SearchIndex = {
         indexDescriptor: "testSearchIndex",
         searchField: "description",
@@ -658,7 +635,6 @@ describe("filters", () => {
     it("should handle search index with no filter fields", () => {
       const mockBuilder = new MockSearchBuilder();
       const searchString = "test search";
-      const searchIndexFilters = {};
       const selectedIndex: SearchIndex = {
         indexDescriptor: "testSearchIndex",
         searchField: "description",
@@ -668,7 +644,7 @@ describe("filters", () => {
       applySearchIndexFilters(
         mockBuilder as any,
         searchString,
-        searchIndexFilters,
+        [],
         selectedIndex,
       );
 
@@ -805,10 +781,10 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {
-          userId: { enabled: true, value: BigInt(123) },
-          organization: { enabled: true, value: "exampleOrg" },
-        },
+        [
+          { field: "userId", enabled: true, value: BigInt(123) },
+          { field: "organization", enabled: true, value: "exampleOrg" },
+        ],
         selectedIndex,
         "asc",
       );
@@ -821,7 +797,7 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {},
+        [],
         selectedIndex,
         "asc",
       );
@@ -841,15 +817,15 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {
-          userId: { enabled: true, value: BigInt(123) },
-          organization: { enabled: true, value: "exampleOrg" },
-        },
+        [
+          { field: "userId", enabled: true, value: BigInt(123) },
+          { field: "organization", enabled: true, value: "exampleOrg" },
+        ],
         selectedIndex,
         "asc",
       );
       expect(result).toEqual({
-        filter: -1,
+        filter: 1,
         error:
           "Invalid index filter selection: found a filter for field `organization` which is not part of the filter fields of the search index `testIndex`.",
       });
@@ -865,17 +841,17 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {
-          userId: { enabled: true, value: BigInt(123) },
-          organization: { enabled: false, value: "exampleOrg" },
-        },
+        [
+          { field: "userId", enabled: true, value: BigInt(123) },
+          { field: "organization", enabled: false, value: "exampleOrg" },
+        ],
         selectedIndex,
         "asc",
       );
       expect(result).toEqual(undefined);
     });
 
-    it("should return error when a search index filter references the search field", () => {
+    it("should return an error when a search index filter references the search field", () => {
       const indexName = "testIndex";
       const selectedIndex: SearchIndex = {
         indexDescriptor: "testSearchIndex",
@@ -885,19 +861,66 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {
-          description: { enabled: true, value: "test" },
-        },
+        [
+          {
+            field: "description",
+            enabled: true,
+            value: "test",
+          },
+        ],
         selectedIndex,
         "asc",
       );
       expect(result).toEqual({
-        filter: -1,
+        filter: 0,
         error:
           "Invalid index filter selection: found a filter for field `description` which is not part of the filter fields of the search index `testIndex`.",
       });
     });
 
+    it("should return error when there are two indexes for the same field", () => {
+      const indexName = "testIndex";
+      const selectedIndex: SearchIndex = {
+        indexDescriptor: "testSearchIndex",
+        searchField: "description",
+        filterFields: ["userId"],
+      };
+
+      const result = validateSearchIndexFilter(
+        indexName,
+        [
+          { field: "userId", enabled: true, value: BigInt(123) },
+          { field: "userId", enabled: true, value: BigInt(123) },
+        ],
+        selectedIndex,
+        "asc",
+      );
+      expect(result).toEqual({
+        filter: 0,
+        error: "Invalid filter: there are multiple filters for field `userId`.",
+      });
+    });
+
+    it("should not return an error when there are two indexes for the same field but only one is enabled", () => {
+      const indexName = "testIndex";
+      const selectedIndex: SearchIndex = {
+        indexDescriptor: "testSearchIndex",
+        searchField: "description",
+        filterFields: ["userId", "organizationId"],
+      };
+
+      const result = validateSearchIndexFilter(
+        indexName,
+        [
+          { field: "userId", enabled: true, value: BigInt(123) },
+          { field: "userId", enabled: false, value: BigInt(456) },
+        ],
+        selectedIndex,
+        "asc",
+      );
+      expect(result).toEqual(undefined);
+    });
+
     it("should return error when querying a search index in descending order", () => {
       const indexName = "testIndex";
       const selectedIndex: SearchIndex = {
@@ -908,7 +931,7 @@ describe("filters", () => {
 
       const result = validateSearchIndexFilter(
         indexName,
-        {},
+        [],
         selectedIndex,
         "desc",
       );
diff --git a/npm-packages/system-udfs/convex/_system/frontend/lib/filters.ts b/npm-packages/system-udfs/convex/_system/frontend/lib/filters.ts
@@ -42,13 +42,12 @@ type DatabaseIndexFilter = {
 type SearchIndexFilter = {
   name: string;
   search: string;
-  filters: Record<
-    string,
-    {
-      enabled: boolean;
-      value: Value;
-    }
-  >;
+  /** The clauses on the filter fields of the search index */
+  clauses: {
+    field: string;
+    enabled: boolean;
+    value: Value;
+  }[];
 };
 
 export type FilterCommon = {
@@ -377,13 +376,13 @@ export function applySearchIndexFilters<
 >(
   q: SearchFilterBuilder<Document, SearchIndexConfig>,
   search: string,
-  filters: Record<string, { enabled: boolean; value: Value }>,
+  filters: Array<{ field: string; enabled: boolean; value: Value }>,
   selectedIndex: SearchIndex,
 ): SearchFilterFinalizer<Document, SearchIndexConfig> {
   let builder = q.search(selectedIndex.searchField, search);
 
   // Apply filters
-  for (const [field, { enabled, value }] of Object.entries(filters)) {
+  for (const { field, enabled, value } of filters) {
     if (enabled) {
       builder = builder.eq(field, value as any);
     }
@@ -467,7 +466,7 @@ export function validateIndexFilter(
  */
 export function validateSearchIndexFilter(
   indexName: string,
-  filters: Record<string, { enabled: boolean; value: Value }>,
+  filters: Array<{ field: string; enabled: boolean; value: Value }>,
   selectedIndex: Index | SearchIndex | undefined,
   order: "asc" | "desc",
 ) {
@@ -493,11 +492,29 @@ export function validateSearchIndexFilter(
     };
   }
 
-  for (const [key, value] of Object.entries(filters)) {
-    if (value.enabled && !selectedIndex.filterFields.includes(key)) {
+  for (const [filterIndex, filter] of filters.entries()) {
+    if (!filter.enabled) continue;
+
+    // Field not a filter field?
+    if (!selectedIndex.filterFields.includes(filter.field)) {
       return {
-        filter: -1,
-        error: `Invalid index filter selection: found a filter for field \`${key}\` which is not part of the filter fields of the search index \`${indexName}\`.`,
+        filter: filterIndex,
+        error: `Invalid index filter selection: found a filter for field \`${filter.field}\` which is not part of the filter fields of the search index \`${indexName}\`.`,
+      };
+    }
+
+    // Duplicated filter for field?
+    if (
+      filters.some(
+        (otherFilter, otherFilterIndex) =>
+          filterIndex !== otherFilterIndex &&
+          otherFilter.enabled &&
+          filter.field === otherFilter.field,
+      )
+    ) {
+      return {
+        filter: filterIndex,
+        error: `Invalid filter: there are multiple filters for field \`${filter.field}\`.`,
       };
     }
   }
diff --git a/npm-packages/system-udfs/convex/_system/frontend/paginatedTableDocuments.ts b/npm-packages/system-udfs/convex/_system/frontend/paginatedTableDocuments.ts
@@ -111,7 +111,7 @@ export default queryGeneric({
       const validationError = isSearchIndex
         ? validateSearchIndexFilter(
             indexFilter.name,
-            indexFilter.filters,
+            indexFilter.clauses,
             selectedIndex,
             order,
           )
@@ -134,7 +134,7 @@ export default queryGeneric({
             applySearchIndexFilters(
               q,
               indexFilter.search,
-              indexFilter.filters,
+              indexFilter.clauses,
               selectedIndex as SearchIndex,
             ),
           )
