feat(data-model): custom-indexes management UI and mutations (#20846)

## Summary Brings indexes management into the per-object Settings tab as a section under Search (no feature flag, advanced mode only). Admins can create / delete non-unique indexes with the UI; apps can declare indexes in code with `defineIndex`. Composite-typed fields are now indexable by picking a specific sub-column (e.g. `Address > City`). A few related polish items also land here (invite-user dropdown lands on the Invite tab; standard warning callout above the new-index form). ## What ships ### UI — custom indexes on per-object Settings - New section directly under Search, wrapped in `AdvancedSettingsWrapper`. - Filter dropdown on the search bar toggles system-index visibility (shown by default since advanced mode). - **+ Add Index** button (disabled with tooltip once the per-object cap is reached) navigates to a dedicated `SettingsObjectNewIndex` page (matches the field-creation pattern, not a modal): - Field picker mirrors the webhook event-form layout (rows of dropdowns, implicit trailing empty row). - Composite fields surface their sub-properties (`Address > City`, `Currency > Amount`, …). - BTREE / GIN type selector. - Standard warning Callout: "Use indexes sparingly — each one speeds reads but slows writes." - Trash icon on `isCustom: true` rows → confirmation modal → `deleteOneIndex`. ### Server — `createOneIndex` / `deleteOneIndex` mutations - Gated by `SettingsPermissionGuard(DATA_MODEL)`. - `IndexMetadataService` wraps the existing migration runner via `WorkspaceMigrationValidateBuildAndRunService` so the metadata row and the SQL index land atomically. - Validation: rejects empty fields, duplicate `(fieldMetadataId, subFieldName)` pairs, fields not on the object, requires `subFieldName` for composite parents, forbids `subFieldName` on scalar/relation, enforces `MAX_CUSTOM_INDEXES_PER_OBJECT = 10`. - Delete refuses on `isCustom: false` rows so system indexes can't be removed via this API. - Dedicated GraphQL exception handler maps each typed error to the right transport error class. ### Composite sub-field indexing - Adds `subFieldName: string | null` column to `IndexFieldMetadataEntity` (fast instance command). - The flat-entity flow (`UniversalFlatIndexFieldMetadata`, `FlatIndexFieldMetadata`, `from-universal-flat-index-to-flat-index`, runner column resolution) all carry `subFieldName` through. - For composite parents, the runner uses `computeCompositeColumnName({...}, property)` for the picked sub-column; for non-composite parents, behavior is unchanged. - The `'::'` separator encodes `(fieldMetadataId, subFieldName)` for dedup on the wire; the frontend uses the same separator inside the Select component's string value. ### Apps can declare indexes in code (`defineIndex`) - New `IndexManifest` + `IndexFieldManifest` types in `twenty-shared/application` wired into the `Manifest` type. - `defineIndex` SDK helper + `IndexConfig`. CLI manifest builder + extractor recognize `defineIndex` / `ManifestEntityKey.Indexes`. - Server: `from-index-manifest-to-universal-flat-index` converter resolves field IDs, validates composite/scalar `subFieldName` rules, and delegates to `generateFlatIndexMetadataWithNameOrThrow` for the deterministic name. - Orchestrator wires the loop after the field-resolution pass; per-object cap enforced inline against the manifest. - Cascade on uninstall is automatic — when an app disappears its indexes drop with it (universal-flat-entity diff handles it). - Rich-app fixture ships a real `defineIndex` on `PostCard.status`, exercising the full manifest → install path in CI. ### Closed for now (open later if needed) - Apps cannot declare `isUnique` indexes — unique constraints stay with the field-creation flow. - Apps cannot use a partial-`indexWhereClause` — the UI surface keeps the framework's hardcoded allowlist. - UI cannot create unique or partial indexes either; same reasons. ### Cleanups along the way - Reused the existing `getCompositeSubFieldLabel` + `COMPOSITE_FIELD_SUB_FIELD_LABELS` (deleted the duplicates I'd created early in the PR). - Moved `MAX_CUSTOM_INDEXES_PER_OBJECT` to `twenty-shared/constants` (single source for FE + BE). - Replaced inline `isDefined(x) && x !== ''` with `isNonEmptyString` (from `@sniptt/guards`). - Hoisted the per-object fields Map + inlined the cap counter into the indexes orchestrator loop (drops the install scan from O(indexes × totalFields) to O(totalFields + indexes)). - Per design-feedback: page-based create flow (not a modal), filter dropdown on the SearchInput (not a separate toggle), webhook-style picker, field icons. ### Unrelated polish that lands here - "Invite user" link in the multi-workspace dropdown now lands on the Invite tab directly (`#invite`) instead of the first tab of the members page. ## Test plan - [ ] `npx nx typecheck twenty-server / twenty-front / twenty-sdk / twenty-shared` — passes - [ ] `npx nx lint:diff-with-main twenty-server / twenty-front` — clean - [ ] `npx jest index-metadata.service.spec` — green - [ ] `npx jest from-index-manifest-to-universal-flat-index` — green (new converter spec, 8 cases) - [ ] `npx vitest run src/sdk/define/indexes/__tests__/define-index.spec.ts` (twenty-sdk) — green (6 cases) - [ ] `npx vitest run --config vitest.integration.config.ts -t "rich-app"` — green (rich-app app-dev integration exercises the new manifest path with the PostCard.status index) - [ ] Advanced mode → Settings → any object → Settings tab → Indexes section is visible under Search - [ ] Create a single-field BTREE index, confirm SQL index exists (verify via `pg_indexes`) - [ ] Create a composite-field index (`Address > City`) and confirm the column is `addressAddressCity` - [ ] Create an index spanning two columns; column order matches the picker order - [ ] Attempt to create an 11th custom index → button is disabled with tooltip - [ ] Delete a custom index → confirmation modal → row disappears, PG index dropped - [ ] System indexes have no trash icon and are hidden by default
2026-05-25 17:47:09 +02:00
parent 69d89f8cfc
commit d602f35cbd
98 changed files with 3742 additions and 387 deletions
@@ -37,6 +37,7 @@ export const OBJECT_METADATA_FRAGMENT = gql`
      indexFieldMetadataList {
        id
        fieldMetadataId
+        subFieldName
        createdAt
        updatedAt
        order
@@ -260,3 +260,35 @@ export const DELETE_ONE_FIELD_METADATA_ITEM = gql`
    }
  }
 `;
+
+export const CREATE_ONE_INDEX_METADATA_ITEM = gql`
+  mutation CreateOneIndexMetadataItem($input: CreateOneIndexInput!) {
+    createOneIndex(input: $input) {
+      id
+      name
+      indexType
+      isUnique
+      isCustom
+      indexWhereClause
+      createdAt
+      updatedAt
+      indexFieldMetadataList {
+        id
+        fieldMetadataId
+        subFieldName
+        createdAt
+        updatedAt
+        order
+      }
+    }
+  }
+`;
+
+export const DELETE_ONE_INDEX_METADATA_ITEM = gql`
+  mutation DeleteOneIndexMetadataItem($idToDelete: UUID!) {
+    deleteOneIndex(input: { id: $idToDelete }) {
+      id
+      name
+    }
+  }
+`;
@@ -0,0 +1,91 @@
+import { useMutation } from '@apollo/client/react';
+import { CombinedGraphQLErrors } from '@apollo/client/errors';
+import { t } from '@lingui/core/macro';
+import { isDefined } from 'twenty-shared/utils';
+import { CrudOperationType } from 'twenty-shared/types';
+
+import { useMetadataErrorHandler } from '@/metadata-error-handler/hooks/useMetadataErrorHandler';
+import { useUpdateMetadataStoreDraft } from '@/metadata-store/hooks/useUpdateMetadataStoreDraft';
+import { type FlatIndexMetadataItem } from '@/metadata-store/types/FlatIndexMetadataItem';
+import { type IndexFieldMetadataItem } from '@/object-metadata/types/IndexFieldMetadataItem';
+import { type MetadataRequestResult } from '@/object-metadata/types/MetadataRequestResult.type';
+import { useSnackBar } from '@/ui/feedback/snack-bar-manager/hooks/useSnackBar';
+import {
+  type CreateIndexInput,
+  CreateOneIndexMetadataItemDocument,
+} from '~/generated-metadata/graphql';
+
+export const useCreateOneIndexMetadataItem = () => {
+  const [createOneIndexMetadataItemMutation] = useMutation(
+    CreateOneIndexMetadataItemDocument,
+  );
+
+  const { handleMetadataError } = useMetadataErrorHandler();
+  const { enqueueErrorSnackBar } = useSnackBar();
+  const { addToDraft, applyChanges } = useUpdateMetadataStoreDraft();
+
+  const createOneIndexMetadataItem = async (
+    input: CreateIndexInput,
+  ): Promise<
+    MetadataRequestResult<
+      Awaited<ReturnType<typeof createOneIndexMetadataItemMutation>>
+    >
+  > => {
+    try {
+      const response = await createOneIndexMetadataItemMutation({
+        variables: {
+          input: {
+            index: input,
+          },
+        },
+      });
+
+      const createdIndex = response.data?.createOneIndex;
+
+      if (isDefined(createdIndex)) {
+        const { __typename, indexFieldMetadataList, ...indexData } =
+          createdIndex;
+
+        const indexFieldMetadatas: IndexFieldMetadataItem[] =
+          indexFieldMetadataList.map(
+            ({ __typename: _, ...rest }) => rest as IndexFieldMetadataItem,
+          );
+
+        addToDraft({
+          key: 'indexMetadataItems',
+          items: [
+            {
+              ...indexData,
+              indexFieldMetadatas,
+              objectMetadataId: input.objectMetadataId,
+            } as FlatIndexMetadataItem,
+          ],
+        });
+        applyChanges();
+      }
+
+      return {
+        status: 'successful',
+        response,
+      };
+    } catch (error) {
+      if (CombinedGraphQLErrors.is(error)) {
+        handleMetadataError(error, {
+          primaryMetadataName: 'index',
+          operationType: CrudOperationType.CREATE,
+        });
+      } else {
+        enqueueErrorSnackBar({ message: t`An error occurred.` });
+      }
+
+      return {
+        status: 'failed',
+        error,
+      };
+    }
+  };
+
+  return {
+    createOneIndexMetadataItem,
+  };
+};
@@ -0,0 +1,64 @@
+import { useMutation } from '@apollo/client/react';
+import { CombinedGraphQLErrors } from '@apollo/client/errors';
+import { t } from '@lingui/core/macro';
+import { CrudOperationType } from 'twenty-shared/types';
+
+import { useMetadataErrorHandler } from '@/metadata-error-handler/hooks/useMetadataErrorHandler';
+import { useUpdateMetadataStoreDraft } from '@/metadata-store/hooks/useUpdateMetadataStoreDraft';
+import { type MetadataRequestResult } from '@/object-metadata/types/MetadataRequestResult.type';
+import { useSnackBar } from '@/ui/feedback/snack-bar-manager/hooks/useSnackBar';
+import { DeleteOneIndexMetadataItemDocument } from '~/generated-metadata/graphql';
+
+export const useDeleteOneIndexMetadataItem = () => {
+  const [deleteOneIndexMetadataItemMutation] = useMutation(
+    DeleteOneIndexMetadataItemDocument,
+  );
+
+  const { handleMetadataError } = useMetadataErrorHandler();
+  const { enqueueErrorSnackBar } = useSnackBar();
+  const { removeFromDraft, applyChanges } = useUpdateMetadataStoreDraft();
+
+  const deleteOneIndexMetadataItem = async ({
+    idToDelete,
+  }: {
+    idToDelete: string;
+  }): Promise<
+    MetadataRequestResult<
+      Awaited<ReturnType<typeof deleteOneIndexMetadataItemMutation>>
+    >
+  > => {
+    try {
+      const response = await deleteOneIndexMetadataItemMutation({
+        variables: {
+          idToDelete,
+        },
+      });
+
+      removeFromDraft({ key: 'indexMetadataItems', itemIds: [idToDelete] });
+      applyChanges();
+
+      return {
+        status: 'successful',
+        response,
+      };
+    } catch (error) {
+      if (CombinedGraphQLErrors.is(error)) {
+        handleMetadataError(error, {
+          primaryMetadataName: 'index',
+          operationType: CrudOperationType.DELETE,
+        });
+      } else {
+        enqueueErrorSnackBar({ message: t`An error occurred.` });
+      }
+
+      return {
+        status: 'failed',
+        error,
+      };
+    }
+  };
+
+  return {
+    deleteOneIndexMetadataItem,
+  };
+};