Skip to content

The open alternative to Salesforce, designed for AI.

feat(server): support cursor pagination with relation-field ordering (#24356)

Félix Malfaitd86986cf112f
diff --git a/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts b/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
index 6c96d510598..a469112f877 100644
--- a/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
+++ b/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
@@ -39,6 +39,7 @@ import { type ReadRecordQueryBuilder } from 'src/engine/api/graphql/graphql-quer
import { buildColumnsToSelect } from 'src/engine/api/graphql/graphql-query-runner/utils/build-columns-to-select';
import { buildOrderByColumnsToSelect } from 'src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select';
import { getCursor } from 'src/engine/api/graphql/graphql-query-runner/utils/cursors.util';
+import { buildOrderByValuesByRecordId } from 'src/engine/api/utils/build-order-by-values-by-record-id.util';
import { computeCursorArgFilter } from 'src/engine/api/utils/compute-cursor-arg-filter.utils';
import {
buildOrderByFromLeaves,
@@ -94,17 +95,17 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
// Normalizing to deduplicated leaves makes the appended id tie-breaker
// yield to a caller-provided id ordering, and guarantees the SQL scan
// order and the keyset conditions derive from the same list
- const orderByWithIdCondition = buildOrderByFromLeaves(
- resolveOrderByLeaves({
- orderBy: [
- ...(args.orderBy ?? []),
- { id: OrderByDirection.AscNullsFirst },
- ] as ObjectRecordOrderBy,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- strictValidation: true,
- }),
- );
+ const orderByLeaves = resolveOrderByLeaves({
+ orderBy: [
+ ...(args.orderBy ?? []),
+ { id: OrderByDirection.AscNullsFirst },
+ ] as ObjectRecordOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ strictValidation: true,
+ });
+ const orderByWithIdCondition = buildOrderByFromLeaves(orderByLeaves);
const isForwardPagination = !isDefined(args.before);
@@ -115,6 +116,7 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
cursor,
orderBy: orderByWithIdCondition,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination,
});
@@ -199,8 +201,20 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
columnsToSelect,
);
- const fetchedObjectRecords =
- (await queryBuilder.getMany()) as ObjectRecord[];
+ // Raw rows travel along the entities: the ordered join columns already
+ // selected for the relation ordering are read out of them, so cursors get
+ // their relation values whatever the client selected (or the REST depth)
+ const { entities: fetchedObjectRecords, raw: fetchedRawRows } =
+ (await queryBuilder.getRawAndEntities()) as {
+ entities: ObjectRecord[];
+ raw: Record<string, unknown>[];
+ };
+ const orderByValuesByRecordId = buildOrderByValuesByRecordId({
+ orderByLeaves,
+ records: fetchedObjectRecords,
+ rawRows: fetchedRawRows,
+ objectNameSingular: flatObjectMetadata.nameSingular,
+ });
const { items: objectRecords, pageInfo: cursorPageInfo } = buildCursorPage({
fetchedItems: fetchedObjectRecords,
limit,
@@ -215,9 +229,10 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
orderBy: orderByWithIdCondition,
pageInfo: cursorPageInfo,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
+ orderByValuesByRecordId,
});
-
const hasAggregatedFields =
Object.keys(args.selectedFieldsResult.aggregate ?? {}).length > 0;
@@ -251,6 +266,7 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
aggregatedValues: parentObjectRecordsAggregatedValues,
totalCount: parentObjectRecordsAggregatedValues?.totalCount,
pageInfo,
+ orderByValuesByRecordId,
selectedFieldsResult: args.selectedFieldsResult,
};
}
diff --git a/packages/twenty-server/src/engine/api/common/types/common-find-many-output.type.ts b/packages/twenty-server/src/engine/api/common/types/common-find-many-output.type.ts
index a518d0537be..71a76b68891 100644
--- a/packages/twenty-server/src/engine/api/common/types/common-find-many-output.type.ts
+++ b/packages/twenty-server/src/engine/api/common/types/common-find-many-output.type.ts
@@ -2,11 +2,15 @@ import { type ObjectRecord } from 'twenty-shared/types';
import { type CommonPageInfo } from 'src/engine/api/common/types/common-page-info.type';
import { type CommonSelectedFieldsResult } from 'src/engine/api/common/types/common-selected-fields-result.type';
+import { type OrderByValuesByRecordId } from 'src/engine/api/utils/build-order-by-values-by-record-id.util';
export type CommonFindManyOutput = {
records: ObjectRecord[];
aggregatedValues: Record<string, number> | undefined;
totalCount: number | undefined;
pageInfo: CommonPageInfo;
+ // Cursor values read from the scan's raw rows, so edge cursors carry the
+ // exact SQL sort values whatever the selection presents
+ orderByValuesByRecordId: OrderByValuesByRecordId;
selectedFieldsResult: CommonSelectedFieldsResult;
};
diff --git a/packages/twenty-server/src/engine/api/common/utils/get-page-info.util.ts b/packages/twenty-server/src/engine/api/common/utils/get-page-info.util.ts
index a8fe4132cb4..1ed05c2e386 100644
--- a/packages/twenty-server/src/engine/api/common/utils/get-page-info.util.ts
+++ b/packages/twenty-server/src/engine/api/common/utils/get-page-info.util.ts
@@ -5,6 +5,7 @@ import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query
import { type CommonPageInfo } from 'src/engine/api/common/types/common-page-info.type';
import { type CursorPageFlags } from 'src/engine/api/types/cursor-page-flags.type';
import { encodeCursor } from 'src/engine/api/graphql/graphql-query-runner/utils/cursors.util';
+import { type OrderByValuesByRecordId } from 'src/engine/api/utils/build-order-by-values-by-record-id.util';
import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
@@ -14,32 +15,34 @@ export const getPageInfo = ({
orderBy,
pageInfo,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
+ orderByValuesByRecordId,
}: {
records: ObjectRecord[];
orderBy: ObjectRecordOrderBy;
pageInfo: CursorPageFlags;
flatObjectMetadata: FlatObjectMetadata;
+ flatObjectMetadataMaps?: FlatEntityMaps<FlatObjectMetadata>;
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+ orderByValuesByRecordId?: OrderByValuesByRecordId;
}): CommonPageInfo => {
- const startCursor =
- records.length > 0
- ? encodeCursor({
- objectRecord: records[0],
- order: orderBy,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- })
- : null;
- const endCursor =
- records.length > 0
- ? encodeCursor({
- objectRecord: records[records.length - 1],
- order: orderBy,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- })
- : null;
+ const encodeRecordCursor = (record: ObjectRecord) =>
+ encodeCursor({
+ objectRecord: record,
+ order: orderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ orderByValuesFromScan: orderByValuesByRecordId?.[record.id],
+ });
- return { startCursor, endCursor, ...pageInfo };
+ return {
+ startCursor: records.length > 0 ? encodeRecordCursor(records[0]) : null,
+ endCursor:
+ records.length > 0
+ ? encodeRecordCursor(records[records.length - 1])
+ : null,
+ ...pageInfo,
+ };
};
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
index f04080bb3b3..96c9158d9ea 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
@@ -198,7 +198,19 @@ export class GraphqlQueryOrderFieldParser {
return null;
}
- const nestedFieldName = Object.keys(orderByDirection)[0];
+ const nestedFieldNames = Object.keys(orderByDirection);
+
+ // Cursor continuation carries exactly one sub-field value per relation, so
+ // reject ambiguous input here instead of silently ordering by the first key
+ if (nestedFieldNames.length !== 1) {
+ throw new GraphqlQueryRunnerException(
+ `Relation field "${fieldMetadata.name}" supports ordering by exactly one field of the related object`,
+ GraphqlQueryRunnerExceptionCode.INVALID_QUERY_INPUT,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
+ }
+
+ const [nestedFieldName] = nestedFieldNames;
const nestedFieldOrderByValue = orderByDirection[nestedFieldName];
if (!isDefined(nestedFieldOrderByValue)) {
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/helpers/object-records-to-graphql-connection.helper.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/helpers/object-records-to-graphql-connection.helper.ts
index 059e7c5dc20..f8f61dcb3cf 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/helpers/object-records-to-graphql-connection.helper.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/helpers/object-records-to-graphql-connection.helper.ts
@@ -15,6 +15,7 @@ import {
GraphqlQueryRunnerExceptionCode,
} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
import { encodeCursor } from 'src/engine/api/graphql/graphql-query-runner/utils/cursors.util';
+import { type OrderByValuesByRecordId } from 'src/engine/api/utils/build-order-by-values-by-record-id.util';
import { getTargetObjectMetadataOrThrow } from 'src/engine/api/graphql/graphql-query-runner/utils/get-target-object-metadata.util';
import { type AggregationField } from 'src/engine/api/graphql/workspace-schema-builder/utils/get-available-aggregations-from-object-fields.util';
import { RelationType } from 'src/engine/metadata-modules/field-metadata/interfaces/relation-type.interface';
@@ -55,6 +56,7 @@ export class ObjectRecordsToGraphqlConnectionHelper {
hasNextPage,
hasPreviousPage,
depth = 0,
+ orderByValuesByRecordId,
}: {
objectRecords: T[];
parentObjectRecord?: T;
@@ -69,6 +71,7 @@ export class ObjectRecordsToGraphqlConnectionHelper {
hasNextPage: boolean;
hasPreviousPage: boolean;
depth?: number;
+ orderByValuesByRecordId?: OrderByValuesByRecordId;
}): IConnection<T> {
const objectMetadataId = this.objectIdByNameSingular[objectName];
const flatObjectMetadata = findFlatEntityByIdInFlatEntityMapsOrThrow({
@@ -91,7 +94,9 @@ export class ObjectRecordsToGraphqlConnectionHelper {
objectRecord,
order,
flatObjectMetadata,
+ flatObjectMetadataMaps: this.flatObjectMetadataMaps,
flatFieldMetadataMaps: this.flatFieldMetadataMaps,
+ orderByValuesFromScan: orderByValuesByRecordId?.[objectRecord.id],
}),
}));
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/types/record-query-builder.type.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/types/record-query-builder.type.ts
index 1375b4e0ca9..5ced7b397ae 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/types/record-query-builder.type.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/types/record-query-builder.type.ts
@@ -44,6 +44,10 @@ export type ReadRecordQueryBuilder = RecordQueryBuilder & {
limit(count?: number): unknown;
offset(count?: number): unknown;
getMany(): Promise<ObjectLiteral[]>;
+ getRawAndEntities(): Promise<{
+ entities: ObjectLiteral[];
+ raw: Record<string, unknown>[];
+ }>;
getRawOne<T extends Record<string, unknown> = ObjectLiteral>(): Promise<
T | undefined
>;
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
index a2a5b6ee319..1f1434bc214 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
@@ -49,17 +49,25 @@ const companyField = buildMockField(
FieldMetadataType.RELATION,
{ settings: { relationType: RelationType.MANY_TO_ONE } },
);
+const ownerField = buildMockField(
+ 'owner-id',
+ 'owner',
+ FieldMetadataType.MORPH_RELATION,
+ { settings: { relationType: RelationType.MANY_TO_ONE } },
+);
const flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata> = {
byUniversalIdentifier: {
'name-id': nameField,
'fullname-id': fullNameField,
'company-id': companyField,
+ 'owner-id': ownerField,
},
universalIdentifierById: {
'name-id': 'name-id',
'fullname-id': 'fullname-id',
'company-id': 'company-id',
+ 'owner-id': 'owner-id',
},
universalIdentifiersByApplicationId: {},
};
@@ -81,7 +89,7 @@ const flatObjectMetadata: FlatObjectMetadata = {
icon: 'Icon123',
createdAt: new Date(),
updatedAt: new Date(),
- fieldIds: ['name-id', 'fullname-id', 'company-id'],
+ fieldIds: ['name-id', 'fullname-id', 'company-id', 'owner-id'],
indexMetadataIds: [],
viewIds: [],
applicationId: null,
@@ -193,10 +201,10 @@ describe('encodeCursor', () => {
expect(decoded).toEqual({ name: null, id: 'abc' });
});
- it('should not embed related records for relation orderBy entries', () => {
+ it('should carry only the ordered sub-field of a loaded relation', () => {
const record = {
id: 'abc',
- company: { id: 'company-1', name: 'Acme' },
+ company: { id: 'company-1', name: 'Acme', employees: 10 },
};
const orderBy = [
{ company: { name: OrderByDirection.AscNullsLast } },
@@ -204,9 +212,77 @@ describe('encodeCursor', () => {
const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+ expect(decoded).toEqual({ company: { name: 'Acme' }, id: 'abc' });
+ });
+
+ it('should carry null for a relation orderBy entry when there is no related record', () => {
+ const record = { id: 'abc', company: null };
+ const orderBy = [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ ] as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
+ expect(decoded).toEqual({ company: { name: null }, id: 'abc' });
+ });
+
+ it('should leave the relation orderBy entry out when the relation is not loaded', () => {
+ const record = { id: 'abc' };
+ const orderBy = [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ ] as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
expect(decoded).toEqual({ id: 'abc' });
});
+ it('should prefer relation order values from the ordering join over the loaded record', () => {
+ const record = { id: 'abc' };
+ const orderBy = [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ ] as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(
+ encodeCursor({
+ objectRecord: record as never,
+ order: orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ orderByValuesFromScan: { company: { name: 'Acme' } },
+ }),
+ );
+
+ expect(decoded).toEqual({ company: { name: 'Acme' }, id: 'abc' });
+ });
+
+ it('should nest composite target values of a relation orderBy', () => {
+ const record = { id: 'abc' };
+ const orderBy = [
+ {
+ company: { contactName: { firstName: OrderByDirection.AscNullsLast } },
+ },
+ { company: { contactName: { lastName: OrderByDirection.AscNullsLast } } },
+ ] as unknown as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(
+ encodeCursor({
+ objectRecord: record as never,
+ order: orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ orderByValuesFromScan: {
+ company: { contactName: { firstName: 'Ada', lastName: null } },
+ },
+ }),
+ );
+
+ expect(decoded).toEqual({
+ company: { contactName: { firstName: 'Ada', lastName: null } },
+ id: 'abc',
+ });
+ });
+
it('should encode join column values when ordering by the foreign key', () => {
const record = { id: 'abc', companyId: 'company-1' };
const orderBy = [{ companyId: OrderByDirection.AscNullsLast }];
@@ -216,6 +292,20 @@ describe('encodeCursor', () => {
expect(decoded).toEqual({ companyId: 'company-1', id: 'abc' });
});
+ it('should carry morph relation sub-field values like relation ones', () => {
+ const record = {
+ id: 'abc',
+ owner: { id: 'owner-1', name: 'Morph target' },
+ };
+ const orderBy = [
+ { owner: { name: OrderByDirection.AscNullsLast } },
+ ] as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
+ expect(decoded).toEqual({ owner: { name: 'Morph target' }, id: 'abc' });
+ });
+
it('should handle undefined orderBy', () => {
const record = { id: 'abc', name: 'John' };
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts
index f6f0fc8a363..72591e519d9 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts
@@ -29,6 +29,12 @@ export const buildOrderByColumnsToSelect = ({
flatObjectMetadata,
flatFieldMetadataMaps,
}).filter(checkIfLeafCanCarryCursorValue)) {
+ // Relation orderBy values live on a joined alias, not on a root column:
+ // cursors read them from the ordering join's raw rows instead
+ if (leaf.kind === 'relation') {
+ continue;
+ }
+
columnsToSelect[
leaf.kind === 'composite'
? computeCompositeColumnName(leaf.path[0], leaf.compositeProperty)
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/compute-where-condition-parts.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/compute-where-condition-parts.ts
index 61770a29695..57e08aaff05 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/compute-where-condition-parts.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/compute-where-condition-parts.ts
@@ -130,6 +130,27 @@ export const computeWhereConditionParts = ({
? { [`${key}${secondParamSuffix}`]: nullEquivalentFieldValue }
: {},
};
+ // Exact variants used by keyset pagination conditions: cursor continuation
+ // must mirror the SQL scan order, where only actual SQL NULLs sort into the
+ // NULL block, so the empty-value widening of 'is' and 'eq' would skip or
+ // duplicate rows around the block boundaries
+ case 'isStrictly':
+ return {
+ sql: `${fieldReference} IS ${value === 'NULL' ? 'NULL' : 'NOT NULL'}`,
+ params: {},
+ };
+ case 'eqStrict':
+ if (isDateTimeField) {
+ return {
+ sql: `(${fieldReference} >= :${key}${paramSuffix} AND ${fieldReference} < :${key}${paramSuffix}::timestamptz + interval '1 millisecond')`,
+ params: { [`${key}${paramSuffix}`]: value },
+ };
+ }
+
+ return {
+ sql: `${fieldReference} = :${key}${paramSuffix}`,
+ params: { [`${key}${paramSuffix}`]: value },
+ };
case 'like':
return {
sql: `${fieldReference}::text LIKE :${key}${paramSuffix}${hasNullEquivalentFieldValue ? ` OR ${fieldReference} IS NULL` : ''}`,
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
index a85500d1cdf..abd246afe6f 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
@@ -38,12 +38,20 @@ export const encodeCursor = <T extends ObjectRecord = ObjectRecord>({
objectRecord,
order,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
+ orderByValuesFromScan,
}: {
objectRecord: T;
order: ObjectRecordOrderBy | undefined;
flatObjectMetadata: FlatObjectMetadata;
+ flatObjectMetadataMaps?: FlatEntityMaps<FlatObjectMetadata>;
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+ // Sort values read from the scan's raw rows by the find-many runner: they
+ // carry the exact SQL values (NULLs included) the continuation must mirror.
+ // Falling back to the formatted record covers callers without them (e.g.
+ // nested connections), whose cursors do not continue a root scan.
+ orderByValuesFromScan?: Record<string, unknown>;
}): string => {
// oxlint-disable-next-line typescript/no-explicit-any
const orderByValues: Record<string, any> = {};
@@ -51,17 +59,29 @@ export const encodeCursor = <T extends ObjectRecord = ObjectRecord>({
for (const leaf of resolveOrderByLeaves({
orderBy: order,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
}).filter(checkIfLeafCanCarryCursorValue)) {
- // Read the ordered value along the leaf's path (a null or missing
- // container makes the value undefined, which JSON serialization drops)
+ // Read the ordered value along the leaf's path: a null container yields
+ // null (the row belongs to the NULL block of the ordering), a missing one
+ // yields undefined, which JSON serialization drops
const [rootKey, ...nestedKeys] = leaf.path;
- let leafValue: unknown = objectRecord[rootKey];
+ const valueSource = orderByValuesFromScan ?? objectRecord;
+ let leafValue: unknown = valueSource[rootKey];
for (const key of nestedKeys) {
+ if (leafValue === null) {
+ break;
+ }
leafValue = isPlainObject(leafValue) ? leafValue[key] : undefined;
}
+ // An unloaded relation cannot contribute a value at all: leave the key out
+ // instead of writing an empty object
+ if (leaf.kind === 'relation' && leafValue === undefined) {
+ continue;
+ }
+
// Write it back under the same path
let container = orderByValues;
diff --git a/packages/twenty-server/src/engine/api/graphql/workspace-resolver-builder/factories/find-many-resolver.factory.ts b/packages/twenty-server/src/engine/api/graphql/workspace-resolver-builder/factories/find-many-resolver.factory.ts
index 1d578a1e2a8..b867e670eb9 100644
--- a/packages/twenty-server/src/engine/api/graphql/workspace-resolver-builder/factories/find-many-resolver.factory.ts
+++ b/packages/twenty-server/src/engine/api/graphql/workspace-resolver-builder/factories/find-many-resolver.factory.ts
@@ -43,6 +43,7 @@ export class FindManyResolverFactory implements WorkspaceResolverBuilderFactoryI
aggregatedValues,
totalCount,
pageInfo,
+ orderByValuesByRecordId,
selectedFieldsResult,
},
args: processedArgs,
@@ -68,6 +69,7 @@ export class FindManyResolverFactory implements WorkspaceResolverBuilderFactoryI
order: processedArgs.orderBy,
hasNextPage: pageInfo.hasNextPage,
hasPreviousPage: pageInfo.hasPreviousPage,
+ orderByValuesByRecordId,
});
} catch (error) {
workspaceQueryRunnerGraphqlApiExceptionHandler(error);
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts b/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
index 1fbae5aa757..a293d53da7c 100644
--- a/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
+++ b/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
@@ -1,4 +1,13 @@
-import { FieldMetadataType, OrderByDirection } from 'twenty-shared/types';
+import {
+ FieldMetadataType,
+ OrderByDirection,
+ RelationType,
+} from 'twenty-shared/types';
+
+import {
+ type ObjectRecordCursor,
+ type ObjectRecordOrderBy,
+} from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
import { GraphqlQueryRunnerException } from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
import { computeCursorArgFilter } from 'src/engine/api/utils/compute-cursor-arg-filter.utils';
@@ -71,6 +80,37 @@ describe('computeCursorArgFilter', () => {
isNullable: true,
});
+ const companyField = {
+ ...createMockField({
+ id: 'company-id',
+ type: FieldMetadataType.RELATION,
+ name: 'company',
+ label: 'Company',
+ }),
+ settings: { relationType: RelationType.MANY_TO_ONE },
+ relationTargetObjectMetadataId: 'company-object-id',
+ } as FlatFieldMetadata;
+
+ const companyNameField = {
+ ...createMockField({
+ id: 'company-name-id',
+ type: FieldMetadataType.TEXT,
+ name: 'name',
+ label: 'Name',
+ }),
+ objectMetadataId: 'company-object-id',
+ } as FlatFieldMetadata;
+
+ const companyContactNameField = {
+ ...createMockField({
+ id: 'company-contactname-id',
+ type: FieldMetadataType.FULL_NAME,
+ name: 'contactName',
+ label: 'Contact Name',
+ }),
+ objectMetadataId: 'company-object-id',
+ } as FlatFieldMetadata;
+
const buildFlatFieldMetadataMaps = (
fields: FlatFieldMetadata[],
): FlatEntityMaps<FlatFieldMetadata> => ({
@@ -99,6 +139,9 @@ describe('computeCursorArgFilter', () => {
fullNameField,
idField,
closeDateField,
+ companyField,
+ companyNameField,
+ companyContactNameField,
]);
const flatObjectMetadata: FlatObjectMetadata = {
@@ -118,18 +161,47 @@ describe('computeCursorArgFilter', () => {
createdAt: new Date(),
updatedAt: new Date(),
universalIdentifier: objectMetadataId,
- fieldIds: ['name-id', 'age-id', 'fullname-id', 'id-id', 'closedate-id'],
+ fieldIds: [
+ 'name-id',
+ 'age-id',
+ 'fullname-id',
+ 'id-id',
+ 'closedate-id',
+ 'company-id',
+ ],
indexMetadataIds: [],
viewIds: [],
applicationId: null,
} as unknown as FlatObjectMetadata;
+ const companyObjectMetadata = {
+ id: 'company-object-id',
+ universalIdentifier: 'company-object-id',
+ workspaceId,
+ nameSingular: 'company',
+ namePlural: 'companies',
+ fieldIds: ['company-name-id', 'company-contactname-id'],
+ } as unknown as FlatObjectMetadata;
+
+ const flatObjectMetadataMaps: FlatEntityMaps<FlatObjectMetadata> = {
+ byUniversalIdentifier: {
+ 'object-id': flatObjectMetadata,
+ 'company-object-id': companyObjectMetadata,
+ },
+ universalIdentifierById: {
+ 'object-id': 'object-id',
+ 'company-object-id': 'company-object-id',
+ },
+ universalIdentifiersByApplicationId: {},
+ };
+
describe('basic cursor filtering', () => {
it('should return empty array when cursor is empty', () => {
const result = computeCursorArgFilter({
cursor: {},
orderBy: [],
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
@@ -145,11 +217,16 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
- expect(result).toEqual([{ name: { gt: 'John' } }]);
+ // TEXT columns hold SQL NULL for rows written empty or without the
+ // field, so the trailing NULL block is part of the continuation
+ expect(result).toEqual([
+ { or: [{ name: { gt: 'John' } }, { name: { isStrictly: 'NULL' } }] },
+ ]);
});
it('should compute backward pagination filter for single field', () => {
@@ -160,6 +237,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: false,
});
@@ -180,16 +258,17 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
- { name: { gt: 'John' } },
+ { or: [{ name: { gt: 'John' } }, { name: { isStrictly: 'NULL' } }] },
{
and: [
- { name: { eq: 'John' } },
- { or: [{ age: { lt: 30 } }, { age: { is: 'NULL' } }] },
+ { name: { eqStrict: 'John' } },
+ { or: [{ age: { lt: 30 } }, { age: { isStrictly: 'NULL' } }] },
],
},
]);
@@ -214,27 +293,30 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
{
- fullName: {
- firstName: { gt: 'John' },
- },
+ or: [
+ { fullName: { firstName: { gt: 'John' } } },
+ { fullName: { firstName: { isStrictly: 'NULL' } } },
+ ],
},
{
and: [
{
fullName: {
- firstName: { eq: 'John' },
+ firstName: { eqStrict: 'John' },
},
},
{
- fullName: {
- lastName: { gt: 'Doe' },
- },
+ or: [
+ { fullName: { lastName: { gt: 'Doe' } } },
+ { fullName: { lastName: { isStrictly: 'NULL' } } },
+ ],
},
],
},
@@ -257,15 +339,17 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
{
- fullName: {
- firstName: { gt: 'John' },
- },
+ or: [
+ { fullName: { firstName: { gt: 'John' } } },
+ { fullName: { firstName: { isStrictly: 'NULL' } } },
+ ],
},
]);
});
@@ -288,27 +372,30 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
{
- fullName: {
- firstName: { gt: 'John' },
- },
+ or: [
+ { fullName: { firstName: { gt: 'John' } } },
+ { fullName: { firstName: { isStrictly: 'NULL' } } },
+ ],
},
{
and: [
{
fullName: {
- firstName: { eq: 'John' },
+ firstName: { eqStrict: 'John' },
},
},
{
- fullName: {
- lastName: { gt: 'Doe' },
- },
+ or: [
+ { fullName: { lastName: { gt: 'Doe' } } },
+ { fullName: { lastName: { isStrictly: 'NULL' } } },
+ ],
},
],
},
@@ -332,6 +419,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: false,
});
@@ -346,7 +434,7 @@ describe('computeCursorArgFilter', () => {
and: [
{
fullName: {
- firstName: { eq: 'John' },
+ firstName: { eqStrict: 'John' },
},
},
{
@@ -370,6 +458,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
}),
@@ -385,6 +474,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
}),
@@ -401,6 +491,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
@@ -409,7 +500,7 @@ describe('computeCursorArgFilter', () => {
{
or: [
{ closeDate: { gt: '2026-01-01T00:00:00Z' } },
- { closeDate: { is: 'NULL' } },
+ { closeDate: { isStrictly: 'NULL' } },
],
},
]);
@@ -423,6 +514,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
@@ -441,13 +533,17 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
{
- and: [{ closeDate: { is: 'NULL' } }, { id: { gt: 'uuid-1' } }],
+ and: [
+ { closeDate: { isStrictly: 'NULL' } },
+ { id: { gt: 'uuid-1' } },
+ ],
},
]);
});
@@ -463,14 +559,18 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
expect(result).toEqual([
- { closeDate: { is: 'NOT_NULL' } },
+ { closeDate: { isStrictly: 'NOT_NULL' } },
{
- and: [{ closeDate: { is: 'NULL' } }, { id: { gt: 'uuid-1' } }],
+ and: [
+ { closeDate: { isStrictly: 'NULL' } },
+ { id: { gt: 'uuid-1' } },
+ ],
},
]);
});
@@ -483,6 +583,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: false,
});
@@ -491,25 +592,26 @@ describe('computeCursorArgFilter', () => {
{
or: [
{ closeDate: { lt: '2026-01-01T00:00:00Z' } },
- { closeDate: { is: 'NULL' } },
+ { closeDate: { isStrictly: 'NULL' } },
],
},
]);
});
- it('should not add a NULL block for fields with a null-equivalent default', () => {
- const cursor = { name: 'John' };
- const orderBy = [{ name: OrderByDirection.AscNullsLast }];
+ it('should not add a NULL block for non-nullable fields', () => {
+ const cursor = { id: 'uuid-1' };
+ const orderBy = [{ id: OrderByDirection.AscNullsLast }];
const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
});
- expect(result).toEqual([{ name: { gt: 'John' } }]);
+ expect(result).toEqual([{ id: { gt: 'uuid-1' } }]);
});
});
@@ -526,6 +628,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
}),
@@ -544,6 +647,7 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
}),
@@ -564,10 +668,167 @@ describe('computeCursorArgFilter', () => {
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination: true,
}),
).not.toThrow();
});
});
+
+ describe('relation orderBy cursor continuation', () => {
+ const relationOrderBy = [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ it('should continue on the joined column with the missing-relation block last', () => {
+ const cursor = { company: { name: 'Acme' }, id: 'uuid-1' };
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy: relationOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([
+ {
+ or: [
+ { company: { name: { gt: 'Acme' } } },
+ { company: { name: { isStrictly: 'NULL' } } },
+ ],
+ },
+ {
+ and: [
+ { company: { name: { eqStrict: 'Acme' } } },
+ { id: { gt: 'uuid-1' } },
+ ],
+ },
+ ]);
+ });
+
+ it('should ride the tie-breaking keys inside the missing-relation block', () => {
+ const cursor = { company: { name: null }, id: 'uuid-1' };
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy: relationOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([
+ {
+ and: [
+ { company: { name: { isStrictly: 'NULL' } } },
+ { id: { gt: 'uuid-1' } },
+ ],
+ },
+ ]);
+ });
+
+ it('should reject a cursor without the relation orderBy value', () => {
+ const cursor = { id: 'uuid-1' };
+
+ expect(() =>
+ computeCursorArgFilter({
+ cursor,
+ orderBy: relationOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ }),
+ ).toThrow('Cursor is missing the value for orderBy field "company.name"');
+ });
+ });
+
+ describe('relation orderBy on a composite target field', () => {
+ // The web app sorts person-labeled relation columns exactly like this: one
+ // entry per ordered FULL_NAME property of the target's label identifier
+ const relationCompositeOrderBy = [
+ {
+ company: { contactName: { firstName: OrderByDirection.AscNullsLast } },
+ },
+ { company: { contactName: { lastName: OrderByDirection.AscNullsLast } } },
+ { id: OrderByDirection.AscNullsFirst },
+ ] as unknown as ObjectRecordOrderBy;
+
+ it('should continue across both composite properties of the joined record', () => {
+ const cursor = {
+ company: { contactName: { firstName: 'Ada', lastName: 'Lovelace' } },
+ id: 'uuid-1',
+ } as unknown as ObjectRecordCursor;
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy: relationCompositeOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ // The joined column is NULL both for rows without a related record and
+ // for related records holding an empty value: they all sort into the
+ // NULL block, which the exact nested check matches
+ expect(result).toEqual([
+ {
+ or: [
+ { company: { contactName: { firstName: { gt: 'Ada' } } } },
+ { company: { contactName: { firstName: { isStrictly: 'NULL' } } } },
+ ],
+ },
+ {
+ and: [
+ { company: { contactName: { firstName: { eqStrict: 'Ada' } } } },
+ {
+ or: [
+ { company: { contactName: { lastName: { gt: 'Lovelace' } } } },
+ {
+ company: {
+ contactName: { lastName: { isStrictly: 'NULL' } },
+ },
+ },
+ ],
+ },
+ ],
+ },
+ {
+ and: [
+ { company: { contactName: { firstName: { eqStrict: 'Ada' } } } },
+ {
+ company: { contactName: { lastName: { eqStrict: 'Lovelace' } } },
+ },
+ { id: { gt: 'uuid-1' } },
+ ],
+ },
+ ]);
+ });
+
+ it('should reject a cursor missing one composite property of the relation', () => {
+ const cursor = {
+ company: { contactName: { firstName: 'Ada' } },
+ id: 'uuid-1',
+ } as unknown as ObjectRecordCursor;
+
+ expect(() =>
+ computeCursorArgFilter({
+ cursor,
+ orderBy: relationCompositeOrderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ }),
+ ).toThrow(
+ 'Cursor is missing the value for orderBy field "company.contactName.lastName"',
+ );
+ });
+ });
});
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts b/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts
index 8b87265d907..58cdccf4c74 100644
--- a/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts
+++ b/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts
@@ -70,13 +70,28 @@ describe('resolveOrderByLeaves', () => {
} as any,
});
- const fields = [
+ const companyNameField = createMockField({
+ id: 'company-name-id',
+ type: FieldMetadataType.TEXT,
+ name: 'name',
+ objectMetadataId: 'company-object-id',
+ });
+
+ const companyContactNameField = createMockField({
+ id: 'company-contactname-id',
+ type: FieldMetadataType.FULL_NAME,
+ name: 'contactName',
+ objectMetadataId: 'company-object-id',
+ });
+
+ const rootFields = [
idField,
closeDateField,
fullNameField,
linksField,
companyField,
];
+ const fields = [...rootFields, companyNameField, companyContactNameField];
const flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata> = {
byUniversalIdentifier: Object.fromEntries(
@@ -92,9 +107,29 @@ describe('resolveOrderByLeaves', () => {
id: objectMetadataId,
workspaceId,
nameSingular: 'opportunity',
- fieldIds: fields.map((field) => field.id),
+ fieldIds: rootFields.map((field) => field.id),
} as unknown as FlatObjectMetadata;
+ const companyObjectMetadata = {
+ id: 'company-object-id',
+ universalIdentifier: 'company-object-id',
+ workspaceId,
+ nameSingular: 'company',
+ fieldIds: ['company-name-id', 'company-contactname-id'],
+ } as unknown as FlatObjectMetadata;
+
+ const flatObjectMetadataMaps: FlatEntityMaps<FlatObjectMetadata> = {
+ byUniversalIdentifier: {
+ [objectMetadataId]: flatObjectMetadata,
+ 'company-object-id': companyObjectMetadata,
+ },
+ universalIdentifierById: {
+ [objectMetadataId]: objectMetadataId,
+ 'company-object-id': 'company-object-id',
+ },
+ universalIdentifiersByApplicationId: {},
+ };
+
const resolve = (
// oxlint-disable-next-line typescript/no-explicit-any
orderBy: any,
@@ -107,6 +142,19 @@ describe('resolveOrderByLeaves', () => {
strictValidation,
});
+ const resolveWithObjectMaps = (
+ // oxlint-disable-next-line typescript/no-explicit-any
+ orderBy: any,
+ strictValidation = false,
+ ) =>
+ resolveOrderByLeaves({
+ orderBy,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ strictValidation,
+ });
+
it('should flatten scalar, composite and relation entries into leaves with their own direction', () => {
const leaves = resolve([
{ closeDate: OrderByDirection.DescNullsLast },
@@ -235,7 +283,7 @@ describe('resolveOrderByLeaves', () => {
).toThrow('requires nested field ordering');
});
- it('should exclude relation and RAW_JSON leaves from cursor use', () => {
+ it('should exclude RAW_JSON leaves from cursor use', () => {
const leaves = resolve([
{ company: { name: OrderByDirection.AscNullsLast } },
{ domainName: { primaryLinkUrl: OrderByDirection.AscNullsLast } },
@@ -247,7 +295,59 @@ describe('resolveOrderByLeaves', () => {
leaves
.filter(checkIfLeafCanCarryCursorValue)
.map(({ path }) => path.join('.')),
- ).toEqual(['domainName.primaryLinkUrl', 'id']);
+ ).toEqual(['company.name', 'domainName.primaryLinkUrl', 'id']);
+ });
+
+ describe('relation leaf resolution against the target object', () => {
+ it('should resolve the target field and composite property when object maps are provided', () => {
+ const [scalarTargetLeaf, compositeTargetLeaf] = resolveWithObjectMaps([
+ { company: { name: OrderByDirection.AscNullsLast } },
+ {
+ company: {
+ contactName: { firstName: OrderByDirection.AscNullsLast },
+ },
+ },
+ ]);
+
+ expect(scalarTargetLeaf).toMatchObject({
+ kind: 'relation',
+ path: ['company', 'name'],
+ targetFieldMetadata: { id: 'company-name-id' },
+ });
+ expect(compositeTargetLeaf).toMatchObject({
+ kind: 'relation',
+ path: ['company', 'contactName', 'firstName'],
+ targetFieldMetadata: { id: 'company-contactname-id' },
+ targetCompositeProperty: { name: 'firstName' },
+ });
+ });
+
+ it('should reject unknown or malformed target orderings in strict mode', () => {
+ expect(() =>
+ resolveWithObjectMaps(
+ [{ company: { unknownField: OrderByDirection.AscNullsLast } }],
+ true,
+ ),
+ ).toThrow('not found in target object "company"');
+ expect(() =>
+ resolveWithObjectMaps(
+ [{ company: { name: { nested: OrderByDirection.AscNullsLast } } }],
+ true,
+ ),
+ ).toThrow('does not support nested ordering');
+ expect(() =>
+ resolveWithObjectMaps(
+ [
+ {
+ company: {
+ contactName: { unknownSub: OrderByDirection.AscNullsLast },
+ },
+ },
+ ],
+ true,
+ ),
+ ).toThrow('requires one of its sub fields to be ordered');
+ });
});
describe('getCursorValueForLeaf', () => {
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts
index c55ad23f3c1..2aba34e88d2 100644
--- a/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts
+++ b/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts
@@ -1,26 +1,7 @@
-import {
- type FieldMetadataType,
- type OrderByDirection,
-} from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
+import { type OrderByDirection } from 'twenty-shared/types';
-import { findPostgresDefaultNullEquivalentValue } from 'src/engine/api/common/common-args-processors/data-arg-processor/utils/find-postgres-default-null-equivalent-value.util';
import { getEffectiveScanOrder } from 'src/engine/api/utils/get-effective-scan-order.utils';
-// Columns of these types are created NOT NULL with a Postgres default (e.g. ''
-// for TEXT), so they never hold SQL NULL and need no NULL-continuation branch
-export const checkIfColumnHasNullEquivalentDefault = (
- fieldType: FieldMetadataType,
- compositeSubFieldKey?: string,
-): boolean =>
- isDefined(
- findPostgresDefaultNullEquivalentValue(
- 'NULL',
- fieldType,
- compositeSubFieldKey,
- ),
- );
-
type BuildCursorKeysetConditionParams = {
cursorValue: unknown;
orderByDirection: OrderByDirection;
@@ -54,13 +35,15 @@ export function buildCursorKeysetCondition({
isEqualityCondition,
canFieldHoldNullValue,
buildLeafCondition,
+ // The strict operators compare exactly: the empty-value widening of 'is'
+ // and 'eq' does not mirror the SQL scan order the cursor continues
buildNullCheckCondition = (isNull) =>
- buildLeafCondition({ is: isNull ? 'NULL' : 'NOT_NULL' }),
+ buildLeafCondition({ isStrictly: isNull ? 'NULL' : 'NOT_NULL' }),
}: BuildCursorKeysetConditionParams): Record<string, unknown> | null {
if (isEqualityCondition) {
return cursorValue === null
? buildNullCheckCondition(true)
- : buildLeafCondition({ eq: cursorValue });
+ : buildLeafCondition({ eqStrict: cursorValue });
}
const { isAscending, areNullsScannedLast } = getEffectiveScanOrder(
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts
index 18eee33265b..e8111da0612 100644
--- a/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts
+++ b/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts
@@ -1,28 +1,13 @@
-import {
- buildCursorKeysetCondition,
- checkIfColumnHasNullEquivalentDefault,
-} from 'src/engine/api/utils/build-cursor-keyset-condition.utils';
+import { buildCursorKeysetCondition } from 'src/engine/api/utils/build-cursor-keyset-condition.utils';
import { type OrderByLeaf } from 'src/engine/api/utils/resolve-order-by-leaves.utils';
-// Composite sub-columns are NOT NULL whenever their type defines a Postgres
-// null-equivalent default; scalar columns additionally honor field nullability.
-const checkIfLeafCanHoldNullValue = (leaf: OrderByLeaf): boolean => {
- switch (leaf.kind) {
- case 'composite':
- return !checkIfColumnHasNullEquivalentDefault(
- leaf.fieldMetadata.type,
- leaf.compositeProperty.name,
- );
- case 'scalar':
- return (
- leaf.fieldMetadata.isNullable !== false &&
- !checkIfColumnHasNullEquivalentDefault(leaf.fieldMetadata.type)
- );
- // A LEFT JOIN can always produce NULLs, whatever the target column's type
- case 'relation':
- return true;
- }
-};
+// SQL NULL can sit in any nullable column whatever its type: write-side
+// normalization stores empty TEXT-like values as NULL, and rows written
+// without the field hold NULL too, so they all sort into the NULL block.
+// Composite sub-columns and joined columns carry no own nullability metadata
+// and are treated as nullable; a needless IS NULL branch matches nothing.
+const checkIfLeafCanHoldNullValue = (leaf: OrderByLeaf): boolean =>
+ leaf.kind === 'scalar' ? leaf.fieldMetadata.isNullable !== false : true;
type BuildCursorLeafWhereConditionParams = {
leaf: OrderByLeaf;
@@ -31,8 +16,9 @@ type BuildCursorLeafWhereConditionParams = {
isEqualityCondition: boolean;
};
-// The leaf's path is also its filter nesting: { name: { firstName: { gt: v } } }
-// resolves against the same column the ordering uses.
+// The leaf's path is also its filter nesting: { company: { name: { gt: v } } }
+// resolves against the same column the ordering uses (relation paths through
+// the LEFT JOIN of the ordering, composite paths through the flat sub-column).
export function buildCursorLeafWhereCondition(
params: BuildCursorLeafWhereConditionParams & { isEqualityCondition: true },
): Record<string, unknown>;
diff --git a/packages/twenty-server/src/engine/api/utils/build-order-by-values-by-record-id.util.ts b/packages/twenty-server/src/engine/api/utils/build-order-by-values-by-record-id.util.ts
new file mode 100644
index 00000000000..bc519335a2b
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/build-order-by-values-by-record-id.util.ts
@@ -0,0 +1,100 @@
+import { type ObjectRecord } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
+
+import {
+ checkIfLeafCanCarryCursorValue,
+ type OrderByLeaf,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
+import { computeCompositeColumnName } from 'src/engine/metadata-modules/field-metadata/utils/compute-column-name.util';
+
+export type OrderByValuesByRecordId = Record<string, Record<string, unknown>>;
+
+const computeRawColumnAlias = (
+ leaf: OrderByLeaf,
+ objectNameSingular: string,
+): string => {
+ switch (leaf.kind) {
+ // The relation ordering always selects its joined columns under the
+ // deterministic "<joinAlias>_<column>" raw alias, whatever the client
+ // selected (see addRelationOrderColumnsToBuilder)
+ case 'relation':
+ return `${leaf.path[0]}_${
+ isDefined(leaf.targetCompositeProperty)
+ ? computeCompositeColumnName(
+ leaf.path[1],
+ leaf.targetCompositeProperty,
+ )
+ : leaf.path[1]
+ }`;
+ case 'composite':
+ return `${objectNameSingular}_${computeCompositeColumnName(leaf.path[0], leaf.compositeProperty)}`;
+ case 'scalar':
+ return `${objectNameSingular}_${leaf.path[0]}`;
+ }
+};
+
+// Cursors are encoded from the raw rows of the scan rather than from the
+// formatted records: result formatting presents SQL NULLs of TEXT-like columns
+// as empty values, but only actual SQL NULLs sort into the NULL block the
+// cursor must continue from. This also carries relation orderBy values without
+// requiring the ordered relation in the selection (or any REST depth).
+export const buildOrderByValuesByRecordId = ({
+ orderByLeaves,
+ records,
+ rawRows,
+ objectNameSingular,
+}: {
+ orderByLeaves: OrderByLeaf[];
+ records: ObjectRecord[];
+ rawRows: Record<string, unknown>[];
+ objectNameSingular: string;
+}): OrderByValuesByRecordId => {
+ const cursorLeaves = orderByLeaves.filter(checkIfLeafCanCarryCursorValue);
+
+ if (cursorLeaves.length === 0 || records.length === 0) {
+ return {};
+ }
+
+ // The runner rejects row-multiplying joins, so raw rows and entities match
+ // one to one; the root id raw alias keys the pairing when available
+ const rootIdRawAlias = `${objectNameSingular}_id`;
+ const rawRowsByRecordId = new Map<string, Record<string, unknown>>();
+
+ rawRows.forEach((rawRow, index) => {
+ const recordId = (rawRow[rootIdRawAlias] ?? records[index]?.id) as
+ | string
+ | undefined;
+
+ if (isDefined(recordId)) {
+ rawRowsByRecordId.set(recordId, rawRow);
+ }
+ });
+
+ const orderByValuesByRecordId: OrderByValuesByRecordId = {};
+
+ for (const record of records) {
+ const rawRow = rawRowsByRecordId.get(record.id);
+
+ if (!isDefined(rawRow)) {
+ continue;
+ }
+
+ const orderByValues: Record<string, unknown> = {};
+
+ for (const leaf of cursorLeaves) {
+ const rawValue = rawRow[computeRawColumnAlias(leaf, objectNameSingular)];
+
+ let container = orderByValues;
+
+ for (const key of leaf.path.slice(0, -1)) {
+ container[key] = isDefined(container[key]) ? container[key] : {};
+ container = container[key] as Record<string, unknown>;
+ }
+ container[leaf.path[leaf.path.length - 1]] = rawValue;
+ }
+
+ orderByValuesByRecordId[record.id] = orderByValues;
+ }
+
+ return orderByValuesByRecordId;
+};
diff --git a/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts b/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
index 9e5527f427e..7e40c895d97 100644
--- a/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
+++ b/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
@@ -25,6 +25,7 @@ type ComputeCursorArgFilterParams = {
cursor: ObjectRecordCursor;
orderBy: ObjectRecordOrderBy;
flatObjectMetadata: FlatObjectMetadata;
+ flatObjectMetadataMaps: FlatEntityMaps<FlatObjectMetadata>;
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
isForwardPagination: boolean;
};
@@ -39,12 +40,14 @@ export const computeCursorArgFilter = ({
cursor,
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
isForwardPagination,
}: ComputeCursorArgFilterParams): ObjectRecordFilter[] => {
const leaves = resolveOrderByLeaves({
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
strictValidation: true,
}).filter(checkIfLeafCanCarryCursorValue);
diff --git a/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts b/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts
index c6d70634c13..9cb6cd2ebd2 100644
--- a/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts
+++ b/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts
@@ -17,6 +17,7 @@ import { isOrderByDirection } from 'src/engine/api/graphql/graphql-query-runner/
import { resolveFilterKeyFieldMetadata } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/resolve-filter-key-field-metadata.util';
import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';
import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
import { isMorphOrRelationFlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/is-morph-or-relation-flat-field-metadata.util';
@@ -24,8 +25,9 @@ import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object
export type OrderByLeaf = {
// Path of the ordered value from the record root, e.g. ['closeDate'],
- // ['name', 'firstName'] or ['company', 'name']. It is at once the cursor
- // value path and the filter nesting of the keyset conditions.
+ // ['name', 'firstName'], ['company', 'name'] or ['company', 'name',
+ // 'firstName']. It is at once the cursor value path and the filter nesting
+ // of the keyset conditions.
path: string[];
direction: OrderByDirection;
fieldMetadata: FlatFieldMetadata;
@@ -33,16 +35,20 @@ export type OrderByLeaf = {
| // Scalar columns, including join columns addressed directly (e.g. companyId)
{ kind: 'scalar' }
| { kind: 'composite'; compositeProperty: CompositeProperty }
- | { kind: 'relation' }
+ | {
+ kind: 'relation';
+ // Resolved against the target object when flatObjectMetadataMaps is
+ // provided; the keyset condition builder relies on it for NULL semantics
+ targetFieldMetadata?: FlatFieldMetadata;
+ targetCompositeProperty?: CompositeProperty;
+ }
);
-// RAW_JSON sub-fields can be ordered by in SQL but take no part in cursors;
-// relation values live on a joined alias and are carried by cursors only once
-// the relation cursor continuation supports them.
+// RAW_JSON sub-fields can be ordered by in SQL but take no part in cursors
export const checkIfLeafCanCarryCursorValue = (leaf: OrderByLeaf): boolean => {
switch (leaf.kind) {
case 'relation':
- return false;
+ return leaf.targetCompositeProperty?.type !== FieldMetadataType.RAW_JSON;
case 'composite':
return leaf.compositeProperty.type !== FieldMetadataType.RAW_JSON;
case 'scalar':
@@ -78,6 +84,106 @@ const flattenNestedOrderByValue = (
: [];
});
+// Resolves one flattened relation orderBy path (e.g. ['company', 'name'] or
+// ['pointOfContact', 'name', 'firstName']) against the relation's target
+// object. Without the object metadata maps the leaf stays unresolved, which is
+// enough for consumers that ignore relation leaves (e.g. column selection).
+const resolveRelationLeaf = ({
+ fieldMetadata,
+ path,
+ direction,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ strictValidation,
+}: {
+ fieldMetadata: FlatFieldMetadata;
+ path: string[];
+ direction: OrderByDirection;
+ flatObjectMetadataMaps?: FlatEntityMaps<FlatObjectMetadata>;
+ flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+ strictValidation: boolean;
+}): OrderByLeaf | null => {
+ const targetObjectMetadata =
+ isDefined(flatObjectMetadataMaps) &&
+ isDefined(fieldMetadata.relationTargetObjectMetadataId)
+ ? findFlatEntityByIdInFlatEntityMaps({
+ flatEntityId: fieldMetadata.relationTargetObjectMetadataId,
+ flatEntityMaps: flatObjectMetadataMaps,
+ })
+ : undefined;
+
+ if (!isDefined(targetObjectMetadata)) {
+ return { kind: 'relation', path, direction, fieldMetadata };
+ }
+
+ const [, targetFieldName, targetPropertyName, ...extraPath] = path;
+ const targetFieldMetadataId = buildFieldMapsFromFlatObjectMetadata(
+ flatFieldMetadataMaps,
+ targetObjectMetadata,
+ ).fieldIdByName[targetFieldName];
+ const targetFieldMetadata = isDefined(targetFieldMetadataId)
+ ? findFlatEntityByIdInFlatEntityMaps({
+ flatEntityId: targetFieldMetadataId,
+ flatEntityMaps: flatFieldMetadataMaps,
+ })
+ : undefined;
+
+ if (!isDefined(targetFieldMetadata)) {
+ if (strictValidation) {
+ throw new GraphqlQueryRunnerException(
+ `Nested field "${targetFieldName}" not found in target object "${targetObjectMetadata.nameSingular}"`,
+ GraphqlQueryRunnerExceptionCode.FIELD_NOT_FOUND,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
+ }
+
+ return null;
+ }
+
+ if (isCompositeFieldMetadataType(targetFieldMetadata.type)) {
+ const targetCompositeProperty = compositeTypeDefinitions
+ .get(targetFieldMetadata.type)
+ ?.properties.find((property) => property.name === targetPropertyName);
+
+ if (!isDefined(targetCompositeProperty) || extraPath.length > 0) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Composite field "${path[0]}.${targetFieldName}" requires one of its sub fields to be ordered`,
+ );
+ }
+
+ return null;
+ }
+
+ return {
+ kind: 'relation',
+ path,
+ direction,
+ fieldMetadata,
+ targetFieldMetadata,
+ targetCompositeProperty,
+ };
+ }
+
+ if (isDefined(targetPropertyName)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Field "${path[0]}.${targetFieldName}" does not support nested ordering`,
+ );
+ }
+
+ return null;
+ }
+
+ return {
+ kind: 'relation',
+ path,
+ direction,
+ fieldMetadata,
+ targetFieldMetadata,
+ };
+};
+
// Single source of truth for walking an orderBy: every entry is flattened into
// ordered leaves that carry their own direction, so the SQL ordering, column
// selection, cursor encoding, cursor validation and keyset conditions all
@@ -90,11 +196,15 @@ const flattenNestedOrderByValue = (
export const resolveOrderByLeaves = ({
orderBy,
flatObjectMetadata,
+ flatObjectMetadataMaps,
flatFieldMetadataMaps,
strictValidation = false,
}: {
orderBy: ObjectRecordOrderBy | undefined;
flatObjectMetadata: FlatObjectMetadata;
+ // Needed to resolve relation leaves against their target object; without it
+ // they stay unresolved, which lenient callers tolerate
+ flatObjectMetadataMaps?: FlatEntityMaps<FlatObjectMetadata>;
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
strictValidation?: boolean;
}): OrderByLeaf[] => {
@@ -158,12 +268,18 @@ export const resolveOrderByLeaves = ({
for (const { path, direction } of flattenNestedOrderByValue(
orderByValue,
)) {
- pushLeaf({
- kind: 'relation',
+ const relationLeaf = resolveRelationLeaf({
+ fieldMetadata,
path: [fieldName, ...path],
direction,
- fieldMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ strictValidation,
});
+
+ if (isDefined(relationLeaf)) {
+ pushLeaf(relationLeaf);
+ }
}
continue;
}
diff --git a/packages/twenty-server/src/engine/twenty-orm-v2/query-builder/workspace-select-query-builder-v2.ts b/packages/twenty-server/src/engine/twenty-orm-v2/query-builder/workspace-select-query-builder-v2.ts
index 3d69fde6e50..5c2aceaea16 100644
--- a/packages/twenty-server/src/engine/twenty-orm-v2/query-builder/workspace-select-query-builder-v2.ts
+++ b/packages/twenty-server/src/engine/twenty-orm-v2/query-builder/workspace-select-query-builder-v2.ts
@@ -557,14 +557,18 @@ export class WorkspaceSelectQueryBuilderV2 implements WhereExpressionLike {
return [compiled.text, compiled.values];
}
+ private materializeEntities<T extends Record<string, unknown>>(
+ rows: Record<string, unknown>[],
+ ): T[] {
+ const columnNameByResultAlias = this.buildColumnNameByResultAlias();
+
+ return rows.map((row) => mapRowToEntity<T>(row, columnNameByResultAlias));
+ }
+
async getMany<T extends Record<string, unknown>>(options?: {
noFormatting?: boolean;
}): Promise<T[]> {
- const rows = await this.executeSelect();
- const columnNameByResultAlias = this.buildColumnNameByResultAlias();
- const entities = rows.map((row) =>
- mapRowToEntity<T>(row, columnNameByResultAlias),
- );
+ const entities = this.materializeEntities<T>(await this.executeSelect());
if (options?.noFormatting) {
return entities;
@@ -573,6 +577,18 @@ export class WorkspaceSelectQueryBuilderV2 implements WhereExpressionLike {
return this.context.formatResult<T[]>(entities);
}
+ async getRawAndEntities<T extends Record<string, unknown>>(): Promise<{
+ entities: T[];
+ raw: Record<string, unknown>[];
+ }> {
+ const rows = await this.executeSelect();
+
+ return {
+ raw: rows,
+ entities: this.context.formatResult<T[]>(this.materializeEntities(rows)),
+ };
+ }
+
async getOne<T extends Record<string, unknown>>(options?: {
noFormatting?: boolean;
}): Promise<T | null> {
@@ -592,10 +608,7 @@ export class WorkspaceSelectQueryBuilderV2 implements WhereExpressionLike {
return null;
}
- const entity = mapRowToEntity<T>(
- rows[0],
- this.buildColumnNameByResultAlias(),
- );
+ const [entity] = this.materializeEntities<T>([rows[0]]);
if (options?.noFormatting) {
return entity;
diff --git a/packages/twenty-server/src/engine/twenty-orm/repository/workspace-select-query-builder.ts b/packages/twenty-server/src/engine/twenty-orm/repository/workspace-select-query-builder.ts
index 4c9e9677e5a..f79f905cde8 100644
--- a/packages/twenty-server/src/engine/twenty-orm/repository/workspace-select-query-builder.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/repository/workspace-select-query-builder.ts
@@ -135,6 +135,37 @@ export class WorkspaceSelectQueryBuilder<
}
}
+ // oxlint-disable-next-line typescript/no-explicit-any
+ override async getRawAndEntities<RawRow = any>(): Promise<{
+ entities: T[];
+ raw: RawRow[];
+ }> {
+ try {
+ this.validatePermissions();
+
+ const { entities, raw } = await super.getRawAndEntities<RawRow>();
+
+ const mainAliasTarget = this.getMainAliasTarget();
+
+ const objectMetadata = getObjectMetadataFromEntityTarget(
+ mainAliasTarget,
+ this.internalContext,
+ );
+
+ return {
+ raw,
+ entities: formatResult<T[]>(
+ entities,
+ objectMetadata,
+ this.internalContext.flatObjectMetadataMaps,
+ this.internalContext.flatFieldMetadataMaps,
+ ),
+ };
+ } catch (error) {
+ throw await computeTwentyORMException(error);
+ }
+ }
+
override async getMany(options?: { noFormatting?: boolean }): Promise<T[]> {
try {
this.validatePermissions();
diff --git a/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts b/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts
index ff7d04fd818..88b596cb338 100644
--- a/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts
+++ b/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts
@@ -520,3 +520,73 @@ describe('Cursor pagination with duplicate sort values', () => {
);
});
});
+
+// Empty TEXT values are stored as SQL NULL (write-side normalization) and
+// presented as '' by the API: the scan's NULL block holds every empty row, and
+// cursors read the raw SQL values so the continuation follows the scan exactly
+describe('Cursor pagination ordered by a TEXT field with empty values', () => {
+ const namedCompanyIds = {
+ ALPHA: '20202020-eeee-4000-8000-000000000001',
+ BETA: '20202020-eeee-4000-8000-000000000002',
+ };
+ const emptyNameCompanyIds = [
+ '20202020-eeee-4000-8000-000000000003',
+ '20202020-eeee-4000-8000-000000000004',
+ '20202020-eeee-4000-8000-000000000005',
+ '20202020-eeee-4000-8000-000000000006',
+ ];
+ const allCompanyIds = [
+ ...Object.values(namedCompanyIds),
+ ...emptyNameCompanyIds,
+ ];
+
+ beforeAll(async () => {
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'company',
+ objectMetadataPluralName: 'companies',
+ gqlFields: 'id',
+ data: [
+ { id: namedCompanyIds.ALPHA, name: 'Alpha Corp' },
+ { id: namedCompanyIds.BETA, name: 'Beta Inc' },
+ // One explicitly empty, the others without the field: both store NULL
+ { id: emptyNameCompanyIds[0], name: '' },
+ ...emptyNameCompanyIds.slice(1).map((id) => ({ id })),
+ ],
+ upsert: true,
+ }),
+ ).expect(200);
+ });
+
+ it('should paginate the empty block exhaustively with AscNullsLast', async () => {
+ const { ids } = await paginateForward({
+ objectMetadataSingularName: 'company',
+ objectMetadataPluralName: 'companies',
+ filter: { id: { in: allCompanyIds } },
+ orderBy: { name: 'AscNullsLast' },
+ first: 2,
+ });
+
+ expect(ids).toEqual([
+ namedCompanyIds.ALPHA,
+ namedCompanyIds.BETA,
+ ...emptyNameCompanyIds,
+ ]);
+ });
+
+ it('should paginate the empty block exhaustively with DescNullsLast', async () => {
+ const { ids } = await paginateForward({
+ objectMetadataSingularName: 'company',
+ objectMetadataPluralName: 'companies',
+ filter: { id: { in: allCompanyIds } },
+ orderBy: { name: 'DescNullsLast' },
+ first: 2,
+ });
+
+ expect(ids).toEqual([
+ namedCompanyIds.BETA,
+ namedCompanyIds.ALPHA,
+ ...emptyNameCompanyIds,
+ ]);
+ });
+});
diff --git a/packages/twenty-server/test/integration/graphql/suites/order-by-relation-field.integration-spec.ts b/packages/twenty-server/test/integration/graphql/suites/order-by-relation-field.integration-spec.ts
index ccc6d6e068c..d2f4ecf266f 100644
--- a/packages/twenty-server/test/integration/graphql/suites/order-by-relation-field.integration-spec.ts
+++ b/packages/twenty-server/test/integration/graphql/suites/order-by-relation-field.integration-spec.ts
@@ -337,22 +337,95 @@ describe('Order by relation field (e2e)', () => {
expect(overlap.length).toBe(0);
});
- it.skip('should return clear error when using cursor pagination with relation orderBy', async () => {
- const firstQueryData = {
+ it('should paginate exhaustively with cursors when the ordered relation field is selected', async () => {
+ const collectedIds: string[] = [];
+ const collectedCompanyNames: (string | null)[] = [];
+ let after: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const response = await makeGraphqlAPIRequest({
+ query: gql`
+ query People(
+ $orderBy: [PersonOrderByInput]
+ $filter: PersonFilterInput
+ $after: String
+ ) {
+ people(
+ orderBy: $orderBy
+ filter: $filter
+ first: 3
+ after: $after
+ ) {
+ edges {
+ node {
+ id
+ company {
+ name
+ }
+ }
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+ }
+ `,
+ variables: {
+ orderBy: [{ company: { name: 'AscNullsLast' } }],
+ filter: { id: { in: TEST_PERSON_IDS } },
+ after,
+ },
+ });
+
+ expect(response.body.errors).toBeUndefined();
+
+ const connection = response.body.data.people;
+
+ for (const edge of connection.edges) {
+ collectedIds.push(edge.node.id);
+ collectedCompanyNames.push(edge.node.company?.name ?? null);
+ }
+
+ if (!connection.pageInfo.hasNextPage) {
+ break;
+ }
+
+ after = connection.pageInfo.endCursor;
+ }
+
+ expect(collectedIds).toHaveLength(TEST_PERSON_IDS.length);
+ expect(new Set(collectedIds).size).toBe(TEST_PERSON_IDS.length);
+
+ // Company names must be globally non-decreasing across pages, nulls last
+ const companyNames = collectedCompanyNames.filter(
+ (name): name is string => name !== null,
+ );
+
+ expect(companyNames).toEqual([...companyNames].sort());
+ expect(collectedCompanyNames.slice(companyNames.length)).toEqual(
+ Array(TEST_PERSON_IDS.length - companyNames.length).fill(null),
+ );
+ });
+
+ it('should walk backward across the missing-relation boundary with before cursors', async () => {
+ const forwardResponse = await makeGraphqlAPIRequest({
query: gql`
query People(
$orderBy: [PersonOrderByInput]
$filter: PersonFilterInput
+ $first: Int
) {
- people(orderBy: $orderBy, filter: $filter, first: 3) {
+ people(orderBy: $orderBy, filter: $filter, first: $first) {
edges {
node {
id
+ company {
+ name
+ }
}
- cursor
}
pageInfo {
- hasNextPage
endCursor
}
}
@@ -361,50 +434,191 @@ describe('Order by relation field (e2e)', () => {
variables: {
orderBy: [{ company: { name: 'AscNullsLast' } }],
filter: { id: { in: TEST_PERSON_IDS } },
+ first: TEST_PERSON_IDS.length,
},
- };
+ });
- const firstResponse = await makeGraphqlAPIRequest(firstQueryData);
+ expect(forwardResponse.body.errors).toBeUndefined();
- expect(firstResponse.body.data).toBeDefined();
- expect(firstResponse.body.errors).toBeUndefined();
+ const forwardConnection = forwardResponse.body.data.people;
+ const forwardIds = forwardConnection.edges.map(
+ (edge: { node: { id: string } }) => edge.node.id,
+ );
- const pageInfo = firstResponse.body.data.people.pageInfo;
+ expect(forwardIds).toHaveLength(TEST_PERSON_IDS.length);
- // Assert we have enough data for pagination test
- expect(pageInfo.hasNextPage).toBe(true);
- expect(pageInfo.endCursor).toBeDefined();
+ const backwardIds: string[] = [];
+ let before: string | undefined = forwardConnection.pageInfo.endCursor;
- const secondQueryData = {
- query: gql`
- query People(
- $orderBy: [PersonOrderByInput]
- $filter: PersonFilterInput
- $after: String
- ) {
- people(orderBy: $orderBy, filter: $filter, first: 3, after: $after) {
- edges {
- node {
- id
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const response = await makeGraphqlAPIRequest({
+ query: gql`
+ query People(
+ $orderBy: [PersonOrderByInput]
+ $filter: PersonFilterInput
+ $before: String
+ ) {
+ people(
+ orderBy: $orderBy
+ filter: $filter
+ last: 3
+ before: $before
+ ) {
+ edges {
+ node {
+ id
+ company {
+ name
+ }
+ }
+ }
+ pageInfo {
+ hasPreviousPage
+ startCursor
}
}
}
- }
- `,
- variables: {
- orderBy: [{ company: { name: 'AscNullsLast' } }],
- filter: { id: { in: TEST_PERSON_IDS } },
- after: pageInfo.endCursor,
- },
- };
+ `,
+ variables: {
+ orderBy: [{ company: { name: 'AscNullsLast' } }],
+ filter: { id: { in: TEST_PERSON_IDS } },
+ before,
+ },
+ });
- const secondResponse = await makeGraphqlAPIRequest(secondQueryData);
+ expect(response.body.errors).toBeUndefined();
- expect(secondResponse.body.errors).toBeDefined();
+ const connection = response.body.data.people;
- expect(secondResponse.body.errors[0].message).toContain(
- 'Cursor-based pagination is not supported with relation field ordering',
- );
+ backwardIds.unshift(
+ ...connection.edges.map(
+ (edge: { node: { id: string } }) => edge.node.id,
+ ),
+ );
+
+ if (!connection.pageInfo.hasPreviousPage) {
+ break;
+ }
+
+ before = connection.pageInfo.startCursor;
+ }
+
+ // Everything before the last record, in the same order as the forward scan
+ expect(backwardIds).toEqual(forwardIds.slice(0, -1));
+ });
+
+ // Cursors read the relation orderBy values from the ordering join itself,
+ // so pagination must not depend on the selection set (issue #24333)
+ it('should paginate exhaustively without the ordered relation field selected', async () => {
+ const collectedIds: string[] = [];
+ let after: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const response = await makeGraphqlAPIRequest({
+ query: gql`
+ query People(
+ $orderBy: [PersonOrderByInput]
+ $filter: PersonFilterInput
+ $after: String
+ ) {
+ people(
+ orderBy: $orderBy
+ filter: $filter
+ first: 3
+ after: $after
+ ) {
+ edges {
+ node {
+ id
+ }
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+ }
+ `,
+ variables: {
+ orderBy: [{ company: { name: 'AscNullsLast' } }],
+ filter: { id: { in: TEST_PERSON_IDS } },
+ after,
+ },
+ });
+
+ expect(response.body.errors).toBeUndefined();
+
+ const connection = response.body.data.people;
+
+ collectedIds.push(
+ ...connection.edges.map((edge: { node: { id: string } }) => edge.node.id),
+ );
+
+ if (!connection.pageInfo.hasNextPage) {
+ break;
+ }
+
+ after = connection.pageInfo.endCursor;
+ }
+
+ // Companies sort Alpha < Beta < Gamma with id tie-breaks, then the
+ // missing-relation block in id order: exactly the seeded id order
+ expect(collectedIds).toEqual(TEST_PERSON_IDS);
+ });
+
+ it('should paginate from an edge cursor without the ordered relation field selected', async () => {
+ const collectedIds: string[] = [];
+ let after: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 20; iteration++) {
+ const response = await makeGraphqlAPIRequest({
+ query: gql`
+ query People(
+ $orderBy: [PersonOrderByInput]
+ $filter: PersonFilterInput
+ $after: String
+ ) {
+ people(
+ orderBy: $orderBy
+ filter: $filter
+ first: 2
+ after: $after
+ ) {
+ edges {
+ node {
+ id
+ }
+ cursor
+ }
+ pageInfo {
+ hasNextPage
+ }
+ }
+ }
+ `,
+ variables: {
+ orderBy: [{ company: { name: 'AscNullsLast' } }],
+ filter: { id: { in: TEST_PERSON_IDS } },
+ after,
+ },
+ });
+
+ expect(response.body.errors).toBeUndefined();
+
+ const connection = response.body.data.people;
+
+ collectedIds.push(
+ ...connection.edges.map((edge: { node: { id: string } }) => edge.node.id),
+ );
+
+ if (!connection.pageInfo.hasNextPage) {
+ break;
+ }
+
+ after = connection.edges[connection.edges.length - 1].cursor;
+ }
+
+ expect(collectedIds).toEqual(TEST_PERSON_IDS);
});
it('should allow sorting by relation FK (backward compatibility)', async () => {
@@ -604,3 +818,203 @@ describe('Order by relation field (e2e)', () => {
expect(resultIds).not.toContain(TEST_PERSON_IDS[0]);
});
});
+
+const COMPOSITE_TEST_PERSON_IDS = {
+ ADA_LOVELACE: '20202020-cccc-4000-8000-000000000001',
+ ADA_ZUSE: '20202020-cccc-4000-8000-000000000002',
+ GRACE_HOPPER: '20202020-cccc-4000-8000-000000000003',
+ LINUS_TORVALDS: '20202020-cccc-4000-8000-000000000004',
+};
+
+const COMPOSITE_TEST_OPPORTUNITY_IDS = [
+ '20202020-dddd-4000-8000-000000000001',
+ '20202020-dddd-4000-8000-000000000002',
+ '20202020-dddd-4000-8000-000000000003',
+ '20202020-dddd-4000-8000-000000000004',
+ '20202020-dddd-4000-8000-000000000005',
+ '20202020-dddd-4000-8000-000000000006',
+];
+
+// The web app sorts a relation column by the target's label identifier; for a
+// person target that is the FULL_NAME composite, sent as one orderBy entry per
+// property: [{ pointOfContact: { name: { firstName } } }, { ...lastName... }]
+describe('Order by a composite field through a relation (e2e)', () => {
+ const orderBy = [
+ { pointOfContact: { name: { firstName: 'AscNullsLast' } } },
+ { pointOfContact: { name: { lastName: 'AscNullsLast' } } },
+ ];
+
+ // Opportunities ordered by their contact's (firstName, lastName), the two
+ // Adas separated by lastName, then the two without a contact in id order
+ const expectedOpportunityIds = COMPOSITE_TEST_OPPORTUNITY_IDS;
+
+ beforeAll(async () => {
+ const createPeople = createManyOperationFactory({
+ objectMetadataSingularName: 'person',
+ objectMetadataPluralName: 'people',
+ gqlFields: 'id',
+ data: [
+ {
+ id: COMPOSITE_TEST_PERSON_IDS.ADA_LOVELACE,
+ name: { firstName: 'Ada', lastName: 'Lovelace' },
+ },
+ {
+ id: COMPOSITE_TEST_PERSON_IDS.ADA_ZUSE,
+ name: { firstName: 'Ada', lastName: 'Zuse' },
+ },
+ {
+ id: COMPOSITE_TEST_PERSON_IDS.GRACE_HOPPER,
+ name: { firstName: 'Grace', lastName: 'Hopper' },
+ },
+ {
+ id: COMPOSITE_TEST_PERSON_IDS.LINUS_TORVALDS,
+ name: { firstName: 'Linus', lastName: 'Torvalds' },
+ },
+ ],
+ upsert: true,
+ });
+
+ await makeGraphqlAPIRequest(createPeople);
+
+ const createOpportunities = createManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ data: [
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[0],
+ name: 'Deal Ada Lovelace',
+ pointOfContactId: COMPOSITE_TEST_PERSON_IDS.ADA_LOVELACE,
+ },
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[1],
+ name: 'Deal Ada Zuse',
+ pointOfContactId: COMPOSITE_TEST_PERSON_IDS.ADA_ZUSE,
+ },
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[2],
+ name: 'Deal Grace',
+ pointOfContactId: COMPOSITE_TEST_PERSON_IDS.GRACE_HOPPER,
+ },
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[3],
+ name: 'Deal Linus',
+ pointOfContactId: COMPOSITE_TEST_PERSON_IDS.LINUS_TORVALDS,
+ },
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[4],
+ name: 'Deal without contact 1',
+ pointOfContactId: null,
+ },
+ {
+ id: COMPOSITE_TEST_OPPORTUNITY_IDS[5],
+ name: 'Deal without contact 2',
+ pointOfContactId: null,
+ },
+ ],
+ upsert: true,
+ });
+
+ await makeGraphqlAPIRequest(createOpportunities);
+ });
+
+ const fetchPage = async (variables: Record<string, unknown>) => {
+ const response = await makeGraphqlAPIRequest({
+ query: gql`
+ query Opportunities(
+ $orderBy: [OpportunityOrderByInput]
+ $filter: OpportunityFilterInput
+ $first: Int
+ $last: Int
+ $after: String
+ $before: String
+ ) {
+ opportunities(
+ orderBy: $orderBy
+ filter: $filter
+ first: $first
+ last: $last
+ after: $after
+ before: $before
+ ) {
+ edges {
+ node {
+ id
+ }
+ }
+ pageInfo {
+ hasNextPage
+ hasPreviousPage
+ startCursor
+ endCursor
+ }
+ }
+ }
+ `,
+ variables: {
+ orderBy,
+ filter: { id: { in: COMPOSITE_TEST_OPPORTUNITY_IDS } },
+ ...variables,
+ },
+ });
+
+ expect(response.body.errors).toBeUndefined();
+
+ return response.body.data.opportunities;
+ };
+
+ it('should paginate exhaustively in the label order with only id selected', async () => {
+ const collectedIds: string[] = [];
+ let after: string | undefined = undefined;
+ let pages = 0;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const connection = await fetchPage({ first: 2, after });
+
+ collectedIds.push(
+ ...connection.edges.map(
+ (edge: { node: { id: string } }) => edge.node.id,
+ ),
+ );
+ pages++;
+
+ if (!connection.pageInfo.hasNextPage) {
+ break;
+ }
+
+ after = connection.pageInfo.endCursor;
+ }
+
+ expect(collectedIds).toEqual(expectedOpportunityIds);
+ expect(pages).toBe(3);
+ });
+
+ it('should walk backward across the missing-contact boundary', async () => {
+ const forwardConnection = await fetchPage({
+ first: COMPOSITE_TEST_OPPORTUNITY_IDS.length,
+ });
+ const endCursor = forwardConnection.pageInfo.endCursor;
+
+ const collectedIds: string[] = [];
+ let before: string | undefined = endCursor;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const connection = await fetchPage({ last: 2, before });
+
+ collectedIds.unshift(
+ ...connection.edges.map(
+ (edge: { node: { id: string } }) => edge.node.id,
+ ),
+ );
+
+ if (!connection.pageInfo.hasPreviousPage) {
+ break;
+ }
+
+ before = connection.pageInfo.startCursor;
+ }
+
+ // Everything before the last record, in forward order
+ expect(collectedIds).toEqual(expectedOpportunityIds.slice(0, -1));
+ });
+});
diff --git a/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts b/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
index 5da4fe716c7..1687144b6ea 100644
--- a/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
+++ b/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
@@ -377,6 +377,70 @@ describe('Core REST API Find Many endpoint', () => {
}).expect(400);
});
+ describe('cursor pagination ordered by a relation field', () => {
+ it('should continue past the first page when depth loads the ordered relation', async () => {
+ const ids: string[] = [];
+ let startingAfter: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const path: string =
+ '/people?order_by=company.name[AscNullsLast]&limit=2&depth=1' +
+ (startingAfter ? `&starting_after=${startingAfter}` : '');
+ const response = await makeRestAPIRequest({
+ method: 'get',
+ path,
+ }).expect(200);
+
+ ids.push(
+ ...response.body.data.people.map(
+ (person: { id: string }) => person.id,
+ ),
+ );
+
+ if (!response.body.pageInfo.hasNextPage) {
+ break;
+ }
+
+ startingAfter = response.body.pageInfo.endCursor;
+ }
+
+ expect(ids).toHaveLength(testPersonIds.length);
+ expect(new Set(ids).size).toBe(testPersonIds.length);
+ });
+
+ // Cursors read relation orderBy values from the ordering join itself, so
+ // continuation must not require any depth (issue #24333)
+ it('should continue past the first page at depth 0', async () => {
+ const ids: string[] = [];
+ let startingAfter: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const path: string =
+ '/people?order_by=company.name[AscNullsLast]&limit=2&depth=0' +
+ (startingAfter ? `&starting_after=${startingAfter}` : '');
+ const response = await makeRestAPIRequest({
+ method: 'get',
+ path,
+ }).expect(200);
+
+ ids.push(
+ ...response.body.data.people.map(
+ (person: { id: string }) => person.id,
+ ),
+ );
+
+ if (!response.body.pageInfo.hasNextPage) {
+ break;
+ }
+
+ startingAfter = response.body.pageInfo.endCursor;
+ }
+
+ expect(ids).toHaveLength(testPersonIds.length);
+ expect(new Set(ids).size).toBe(testPersonIds.length);
+ });
+ });
+
describe('cursor pagination ordered by a nullable field', () => {
const datedOpportunityCloseDates = [
'2026-03-01T00:00:00.000Z',