Skip to content

The open alternative to Salesforce, designed for AI.

Build the find tool orderBy schema from the object's fields (#27010)

Félix Malfaitc441cac01a2a
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.ts
new file mode 100644
index 00000000000..944ac3eec3d
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.ts
@@ -0,0 +1,125 @@
+import { FieldMetadataType, RelationType } from 'twenty-shared/types';
+
+import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';
+import { toToolJsonSchema } from 'src/engine/core-modules/record-crud/utils/to-tool-json-schema.util';
+import { generateFindToolInputSchema } from 'src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema';
+
+const buildCompanyLikeObjectMetadata = (): ObjectMetadataForToolSchema => {
+ return {
+ fields: [
+ {
+ id: 'field-id-name',
+ name: 'name',
+ type: FieldMetadataType.TEXT,
+ isSystem: false,
+ },
+ {
+ id: 'field-id-address',
+ name: 'address',
+ type: FieldMetadataType.ADDRESS,
+ isSystem: false,
+ },
+ {
+ id: 'field-id-account-owner',
+ name: 'accountOwner',
+ type: FieldMetadataType.RELATION,
+ isSystem: false,
+ settings: { relationType: RelationType.MANY_TO_ONE },
+ },
+ {
+ id: 'field-id-created-at',
+ name: 'createdAt',
+ type: FieldMetadataType.DATE_TIME,
+ isSystem: true,
+ },
+ {
+ id: 'field-id-deleted-at',
+ name: 'deletedAt',
+ type: FieldMetadataType.DATE_TIME,
+ isSystem: true,
+ },
+ {
+ id: 'field-id-people',
+ name: 'people',
+ type: FieldMetadataType.RELATION,
+ isSystem: false,
+ settings: { relationType: RelationType.ONE_TO_MANY },
+ },
+ ],
+ } as unknown as ObjectMetadataForToolSchema;
+};
+
+const parseOrderBy = (orderBy: unknown, restrictedFields = {}) =>
+ generateFindToolInputSchema(
+ buildCompanyLikeObjectMetadata(),
+ restrictedFields,
+ ).safeParse({ select: ['*'], orderBy });
+
+describe('generateFindToolInputSchema orderBy', () => {
+ it.each([
+ [[{ name: 'AscNullsFirst' }]],
+ [[{ address: { addressCity: 'DescNullsLast' } }]],
+ [[{ accountOwnerId: 'AscNullsLast' }]],
+ [[{ createdAt: 'DescNullsLast' }]],
+ [
+ [
+ { name: 'DescNullsLast' },
+ { address: { addressCountry: 'AscNullsFirst' } },
+ ],
+ ],
+ ])('accepts %j', (orderBy) => {
+ expect(parseOrderBy(orderBy).success).toBe(true);
+ });
+
+ it.each([
+ [[{ name: { firstName: 'AscNullsFirst' } }]],
+ [[{ address: 'AscNullsFirst' }]],
+ [[{ address: { unknownSubField: 'AscNullsFirst' } }]],
+ [[{ people: 'AscNullsFirst' }]],
+ [[{ unknownField: 'AscNullsFirst' }]],
+ [[{ deletedAt: 'AscNullsFirst' }]],
+ [[{ name: 'AscNullsFirst', address: { addressCity: 'AscNullsFirst' } }]],
+ [[{ 'name.firstName': 'AscNullsFirst' }]],
+ ])('rejects %j', (orderBy) => {
+ expect(parseOrderBy(orderBy).success).toBe(false);
+ });
+
+ it('does not offer sorting on unreadable fields', () => {
+ expect(
+ parseOrderBy([{ name: 'AscNullsFirst' }], {
+ 'field-id-name': { canRead: false },
+ }).success,
+ ).toBe(false);
+ });
+
+ it('advertises a direction for scalar fields and sub-fields for composite fields', () => {
+ type JsonSchemaNode = {
+ $ref?: string;
+ enum?: string[];
+ properties?: Record<string, JsonSchemaNode>;
+ items?: JsonSchemaNode;
+ };
+
+ const jsonSchema = toToolJsonSchema(
+ generateFindToolInputSchema(buildCompanyLikeObjectMetadata()),
+ ) as JsonSchemaNode & { $defs: Record<string, JsonSchemaNode> };
+
+ const resolve = (node: JsonSchemaNode | undefined) =>
+ node?.$ref ? jsonSchema.$defs[node.$ref.replace('#/$defs/', '')] : node;
+
+ const orderByItemProperties =
+ jsonSchema.properties?.orderBy.items?.properties ?? {};
+
+ expect(resolve(orderByItemProperties.name)?.enum).toContain(
+ 'AscNullsFirst',
+ );
+ expect(resolve(orderByItemProperties.name)?.properties).toBeUndefined();
+ expect(
+ Object.keys(resolve(orderByItemProperties.address)?.properties ?? {}),
+ ).toEqual(expect.arrayContaining(['addressCity', 'addressCountry']));
+ expect(resolve(orderByItemProperties.accountOwnerId)?.enum).toContain(
+ 'DescNullsLast',
+ );
+ expect(orderByItemProperties.people).toBeUndefined();
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts
index 7b23f671ce8..b85e737cfe3 100644
--- a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts
@@ -2,7 +2,7 @@ import { type RestrictedFieldsPermissions } from 'twenty-shared/types';
import { z } from 'zod';
import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';
-import { ObjectRecordOrderBySchema } from 'src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema';
+import { generateRecordOrderBySchema } from 'src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema';
import { generateRecordFilterSchema } from 'src/engine/core-modules/record-crud/zod-schemas/record-filter.zod-schema';
export const generateFindToolInputSchema = (
@@ -29,13 +29,7 @@ export const generateFindToolInputSchema = (
.nonnegative()
.default(0)
.describe('Number of records to skip (default: 0)'),
- orderBy: ObjectRecordOrderBySchema.describe(
- 'Sort by field(s). ' +
- 'Scalar fields: [{fieldName: "DescNullsLast"}]. ' +
- 'Composite fields (name, address, currency, …): [{fieldName: {subFieldName: "AscNullsFirst"}}] — e.g. [{"name": {"firstName": "AscNullsFirst"}}]. ' +
- 'Never use dot-notation keys like "name.firstName". ' +
- 'Use DescNullsLast for top/largest, AscNullsFirst for bottom/smallest.',
- ),
+ orderBy: generateRecordOrderBySchema({ objectMetadata, restrictedFields }),
select: z
.array(z.string())
.nonempty()
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts
index 3ac0af0853c..13373e4868c 100644
--- a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts
+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts
@@ -1,36 +1,105 @@
+import {
+ compositeTypeDefinitions,
+ FieldMetadataType,
+ RelationType,
+ type RestrictedFieldsPermissions,
+} from 'twenty-shared/types';
+import {
+ isDefined,
+ shouldExcludeFieldFromAgentToolSchema,
+} from 'twenty-shared/utils';
import { z } from 'zod';
+import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';
+import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';
+import { isFieldMetadataEntityOfType } from 'src/engine/utils/is-field-metadata-of-type.util';
+
export const OrderByDirectionEnum = z.enum([
'AscNullsFirst',
'AscNullsLast',
'DescNullsFirst',
'DescNullsLast',
]);
-export const OrderByFieldValueSchema = z.union([
- OrderByDirectionEnum,
- z.record(z.string(), OrderByDirectionEnum),
-]);
-export const ObjectRecordOrderByItemSchema = z
- .object({})
- .catchall(OrderByFieldValueSchema)
- .refine((obj) => Object.keys(obj).length === 1, {
- message: 'Each orderBy item must specify exactly one field',
- })
- .describe(
- 'Object with exactly ONE property. ' +
- 'For scalar fields use a direction string: {"employees": "DescNullsLast"}. ' +
- 'For composite fields (e.g. name, address, currency) use a nested object with the sub-field: {"name": {"firstName": "AscNullsFirst"}}. ' +
- 'Never use dot-notation keys like "name.firstName".',
- );
-
-export const ObjectRecordOrderBySchema = z
- .array(ObjectRecordOrderByItemSchema)
- .optional()
- .describe(
- 'Array of sort criteria. Each item sorts by one field. ' +
- 'Scalar fields: [{"employees": "DescNullsLast"}]. ' +
- 'Composite fields (name, address, currency, …): [{"name": {"firstName": "AscNullsFirst"}}]. ' +
- 'Use "DescNullsLast" for descending (top/largest), "AscNullsFirst" for ascending (bottom/smallest). ' +
- 'Never use dot-notation keys like "name.firstName".',
- );
+// Mirrors the GraphQL orderBy input, so the shape advertised for each field
+// (direction for scalars, sub-fields for composites) is the one the orderBy
+// resolver accepts for this object
+export const generateRecordOrderBySchema = ({
+ objectMetadata,
+ restrictedFields,
+}: {
+ objectMetadata: ObjectMetadataForToolSchema;
+ restrictedFields?: RestrictedFieldsPermissions;
+}): z.ZodTypeAny => {
+ const orderByItemShape: Record<string, z.ZodTypeAny> = {};
+
+ for (const field of objectMetadata.fields) {
+ // System fields stay sortable: agents sort by createdAt, updatedAt and
+ // position to get recent or first records
+ if (
+ shouldExcludeFieldFromAgentToolSchema({
+ fieldName: field.name,
+ isSystem: false,
+ excludeId: false,
+ })
+ ) {
+ continue;
+ }
+
+ if (restrictedFields?.[field.id]?.canRead === false) {
+ continue;
+ }
+
+ const isRelationField =
+ isFieldMetadataEntityOfType(field, FieldMetadataType.RELATION) ||
+ isFieldMetadataEntityOfType(field, FieldMetadataType.MORPH_RELATION);
+
+ if (isRelationField) {
+ if (field.settings?.relationType === RelationType.MANY_TO_ONE) {
+ orderByItemShape[`${field.name}Id`] = OrderByDirectionEnum.optional();
+ }
+
+ continue;
+ }
+
+ if (isCompositeFieldMetadataType(field.type)) {
+ const compositeType = compositeTypeDefinitions.get(field.type);
+
+ if (!isDefined(compositeType)) {
+ continue;
+ }
+
+ const subFieldShape = Object.fromEntries(
+ compositeType.properties
+ .filter((property) => property.hidden !== true)
+ .map((property) => [property.name, OrderByDirectionEnum.optional()]),
+ );
+
+ orderByItemShape[field.name] = z
+ .object(subFieldShape)
+ .strict()
+ .optional();
+
+ continue;
+ }
+
+ orderByItemShape[field.name] = OrderByDirectionEnum.optional();
+ }
+
+ const orderByItemSchema = z
+ .object(orderByItemShape)
+ .strict()
+ .refine((item) => Object.keys(item).length === 1, {
+ message: 'Each orderBy item must specify exactly one field',
+ })
+ .describe(
+ 'Object with exactly ONE property. Scalar fields take a direction string; composite fields take an object with one sub-field. Never use dot-notation keys.',
+ );
+
+ return z
+ .array(orderByItemSchema)
+ .optional()
+ .describe(
+ 'Array of sort criteria, one field per item. Use "DescNullsLast" for descending (top/largest), "AscNullsFirst" for ascending (bottom/smallest).',
+ );
+};
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
index dda980e6ce1..e5a22a41e1b 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts
@@ -199,7 +199,7 @@ export class DatabaseToolProvider implements ToolProvider {
this.i18nService,
context.locale,
),
- description: `Search for ${objectMetadata.labelPlural} records using flexible filtering criteria. Supports exact matches, pattern matching, ranges, and null checks. Use limit/offset for pagination and orderBy for sorting. Filter fields are top-level arguments — pass each field as its own key (e.g. { id: { eq: "record-id" } }, or { name: { firstName: { ilike: "%ada%" } } }); do NOT wrap them in a "filter" object and do NOT place a bare operator like "ilike"/"eq" at the top level. Combine conditions with and/or/not. Returns an array of matching records with their full data, plus a "count" of total matches and a "hasNextPage" flag. When "hasNextPage" is true, more records match than were returned: continue with a higher offset (or increase the limit) before concluding a record is absent or answering count/enumeration questions.`,
+ description: `Search for ${objectMetadata.labelPlural} records using flexible filtering criteria. Supports exact matches, pattern matching, ranges, and null checks. Use limit/offset for pagination and orderBy for sorting. Filter fields are top-level arguments — pass each field as its own key (e.g. { id: { eq: "record-id" } }; composite fields take their sub-field: { <field>: { <subField>: { ilike: "%ada%" } } }); do NOT wrap them in a "filter" object and do NOT place a bare operator like "ilike"/"eq" at the top level. Combine conditions with and/or/not. Returns an array of matching records with their full data, plus a "count" of total matches and a "hasNextPage" flag. When "hasNextPage" is true, more records match than were returned: continue with a higher offset (or increase the limit) before concluding a record is absent or answering count/enumeration questions.`,
category: ToolCategory.DATABASE_CRUD,
...(shouldIncludeSchema(`find_many_${snakePlural}`) && {
inputSchema: toToolJsonSchema(