Added support for setting an offset value as part of query options. (aws#102)

andreachild · web-flow · commit feb34d4a2ad9 · 2025-06-02T13:29:53.000-07:00
Added support for setting an offset value as part of query options which can be used in combination with the existing limit for pagination purposes. The offset is translated to open cypher's SKIP by the resolver. If offset and limit are specified for nested edge queries, the values are translated to open cypher's list slice lower and upper bounds.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -38,6 +38,8 @@ This release contains new support for Apollo Server integration.
 
 * Support output of zip package of Apollo Server artifacts (([#70](https://github.com/aws/amazon-neptune-for-graphql/pull/70)), ([#72](https://github.com/aws/amazon-neptune-for-graphql/pull/72)), ([#73](https://github.com/aws/amazon-neptune-for-graphql/pull/73)), ([#75](https://github.com/aws/amazon-neptune-for-graphql/pull/75)), ([#76](https://github.com/aws/amazon-neptune-for-graphql/pull/76)))
 * Allow filtering using string comparison operators `eq`, `contains`, `startsWith`, `endsWith` (([#100](https://github.com/aws/amazon-neptune-for-graphql/pull/100))
+* Added pagination support through the addition of an `offset` argument in query options which can be used in combination with the existing `limit` (([#102](https://github.com/aws/amazon-neptune-for-graphql/pull/102))
+
 
 ### Improvements
 
diff --git a/src/graphdb.js b/src/graphdb.js
@@ -290,6 +290,7 @@ function graphDBInferenceSchema (graphbSchema, addMutations) {
     // input options
     r += `input Options {\n`;
     r += `\tlimit:Int\n`;
+    r += `\toffset:Int\n`;
     r += '}\n\n';
     
     r += 'input StringScalarFilters {\n' +
diff --git a/src/schemaModelValidator.js b/src/schemaModelValidator.js
@@ -383,7 +383,10 @@ function inferGraphDatabaseDirectives(schemaModel) {
         }
     });
 
-    typesToAdd.push(`input Options {\n  limit: Int\n}\n`);
+    typesToAdd.push('input Options {\n' +
+        '\tlimit: Int\n' +
+        '\toffset: Int\n' +
+        '}\n');
     typesToAdd.push('input StringScalarFilters {\n' +
         '\teq: String\n' +
         '\tcontains: String\n' +
diff --git a/src/test/airports-mutations.graphql b/src/test/airports-mutations.graphql
@@ -179,6 +179,7 @@ input RouteInput {
 
 input Options {
   limit:Int
+  offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/airports.customized.graphql b/src/test/airports.customized.graphql
@@ -102,6 +102,7 @@ dist: Int
 
 input Options {
 limit:Int
+offset:Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/airports.graphql b/src/test/airports.graphql
@@ -101,6 +101,7 @@ input RouteInput {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/dining.graphql b/src/test/dining.graphql
@@ -120,6 +120,7 @@ type Friends @alias(property: "friends") {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/epl.graphql b/src/test/epl.graphql
@@ -74,6 +74,7 @@ type Stadium_edge @alias(property: "STADIUM_EDGE") {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/fraud.graphql b/src/test/fraud.graphql
@@ -133,6 +133,7 @@ type Merchant_edge @alias(property: "MERCHANT_EDGE") {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/knowledge.graphql b/src/test/knowledge.graphql
@@ -148,6 +148,7 @@ type Written_by @alias(property: "written_by") {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/node-edge-same-label.graphql b/src/test/node-edge-same-label.graphql
@@ -31,6 +31,7 @@ input _authorInput {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/security.graphql b/src/test/security.graphql
@@ -489,6 +489,7 @@ type Transient_resource_link @alias(property: "transient_resource_link") {
 
 input Options {
     limit: Int
+    offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/special-chars-mutations.graphql b/src/test/special-chars-mutations.graphql
@@ -122,6 +122,7 @@ type Resource_link @alias(property:"resource_link") {
 
 input Options {
   limit:Int
+  offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/special-chars.graphql b/src/test/special-chars.graphql
@@ -66,6 +66,7 @@ type Resource_link @alias(property: "resource_link") {
 
 input Options {
         limit: Int
+        offset: Int
 }
 
 input StringScalarFilters {
diff --git a/src/test/templates/JSResolverOCHTTPS.test.js b/src/test/templates/JSResolverOCHTTPS.test.js
@@ -824,4 +824,103 @@ test('should resolve custom mutation with @graphQuery directive and $input param
         language: 'opencypher',
         refactorOutput: null
     });
+});
+
+test('should resolve query with limit and offset', () => {
+    const result = resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { limit: 10, offset: 3 } },
+        selectionSetGraphQL: '{ code }'
+    });
+    expect(result).toEqual({
+        query: 'MATCH (getNodeAirports_Airport:`airport`) WITH getNodeAirports_Airport SKIP 3 LIMIT 10\n' +
+            'RETURN collect({code: getNodeAirports_Airport.`code`})[..10]',
+        parameters: {},
+        language: 'opencypher',
+        refactorOutput: null
+    });
+});
+
+test('should resolve query with nested edge limit and offset', () => {
+    const result = resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { limit: 10, offset: 2 } },
+        selectionSetGraphQL: '{ code, airportRoutesIn(options: {offset: 5, limit: 3}) {code} }'
+    });
+    expect(result).toEqual({
+        query: 'MATCH (getNodeAirports_Airport:`airport`) WITH getNodeAirports_Airport SKIP 2 LIMIT 10\n' +
+            'OPTIONAL MATCH (getNodeAirports_Airport)<-[getNodeAirports_Airport_airportRoutesIn_route:route]-(getNodeAirports_Airport_airportRoutesIn:`airport`)\n' +
+            'WITH getNodeAirports_Airport, CASE WHEN getNodeAirports_Airport_airportRoutesIn IS NULL THEN [] ' +
+            'ELSE COLLECT({code: getNodeAirports_Airport_airportRoutesIn.`code`})[5..8] ' +
+            'END AS getNodeAirports_Airport_airportRoutesIn_collect\n' +
+            'RETURN collect({' +
+            'code: getNodeAirports_Airport.`code`, ' +
+            'airportRoutesIn: getNodeAirports_Airport_airportRoutesIn_collect' +
+            '})[..10]',
+        parameters: {},
+        language: 'opencypher',
+        refactorOutput: null
+    });
+});
+
+test('should resolve query with nested edge limit and offset from variables', () => {
+    const result = resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { limit: 2, offset: 4 } },
+        selectionSetGraphQL: '{code, airportRoutesOut(options: $nestedOptions) {code}}',
+        variables: { nestedOptions: { limit: 3, offset: 6 } }
+    });
+    expect(result).toEqual({
+        query: 'MATCH (getNodeAirports_Airport:`airport`) WITH getNodeAirports_Airport SKIP 4 LIMIT 2\n' +
+            'OPTIONAL MATCH (getNodeAirports_Airport)-[getNodeAirports_Airport_airportRoutesOut_route:route]->(getNodeAirports_Airport_airportRoutesOut:`airport`)\n' +
+            'WITH getNodeAirports_Airport, CASE WHEN getNodeAirports_Airport_airportRoutesOut IS NULL THEN [] ' +
+            'ELSE COLLECT({code: getNodeAirports_Airport_airportRoutesOut.`code`})[6..9] ' +
+            'END AS getNodeAirports_Airport_airportRoutesOut_collect\n' +
+            'RETURN collect({' +
+            'code: getNodeAirports_Airport.`code`, ' +
+            'airportRoutesOut: getNodeAirports_Airport_airportRoutesOut_collect' +
+            '})[..2]',
+        parameters: {},
+        language: 'opencypher',
+        refactorOutput: null
+    });
+});
+
+test('should resolve query zero limit and offset', () => {
+    // zero limit and offset would be odd, but is allowed
+    const result = resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { limit: 0, offset: 0 } },
+        selectionSetGraphQL: '{ code, airportRoutesIn(options: {offset: 0, limit: 0}) {code} }'
+    });
+    expect(result).toEqual({
+        query: 'MATCH (getNodeAirports_Airport:`airport`) WITH getNodeAirports_Airport SKIP 0 LIMIT 0\n' +
+            'OPTIONAL MATCH (getNodeAirports_Airport)<-[getNodeAirports_Airport_airportRoutesIn_route:route]-(getNodeAirports_Airport_airportRoutesIn:`airport`)\n' +
+            'WITH getNodeAirports_Airport, CASE WHEN getNodeAirports_Airport_airportRoutesIn IS NULL THEN [] ' +
+            'ELSE COLLECT({code: getNodeAirports_Airport_airportRoutesIn.`code`})[0..0] ' +
+            'END AS getNodeAirports_Airport_airportRoutesIn_collect\n' +
+            'RETURN collect({' +
+            'code: getNodeAirports_Airport.`code`, ' +
+            'airportRoutesIn: getNodeAirports_Airport_airportRoutesIn_collect' +
+            '})[..0]',
+        parameters: {},
+        language: 'opencypher',
+        refactorOutput: null
+    });
+});
+
+test('should throw error for query with negative limit', () => {
+    expect(() => resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { limit: -1} },
+        selectionSetGraphQL: '{ code }'
+    }).toThrow('The limit value must be a positive integer'));
+});
+
+test('should throw error for query with negative offset', () => {
+    expect(() => resolveGraphDBQueryFromAppSyncEvent({
+        field: 'getNodeAirports',
+        arguments: { options: { offset: -1} },
+        selectionSetGraphQL: '{ code }'
+    }).toThrow('The offset value must be a positive integer'));
 });
diff --git a/src/test/user-group-validated.graphql b/src/test/user-group-validated.graphql
@@ -87,6 +87,7 @@ type GroupEdge {
 
 input Options {
   limit: Int
+  offset: Int
 }
 
 input StringScalarFilters {
diff --git a/templates/JSResolverOCHTTPS.js b/templates/JSResolverOCHTTPS.js
@@ -10,7 +10,7 @@ express or implied. See the License for the specific language governing
 permissions and limitations under the License.
 */
 
-import { astFromValue, buildASTSchema, GraphQLID, GraphQLInputObjectType, typeFromAST } from 'graphql';
+import { astFromValue, buildASTSchema, GraphQLError, GraphQLID, GraphQLInputObjectType, typeFromAST } from 'graphql';
 import { gql } from 'graphql-tag'; // GraphQL library to parse the GraphQL query
 
 const useCallSubquery = false;
@@ -448,22 +448,32 @@ function getSchemaFieldInfo(typeName, fieldName, pathName) {
 }
 
 
-function getOptionsInSchemaInfo(fields, schemaInfo) {
-    fields.forEach( field => {
-        if (field.name.value == 'limit') {
-            schemaInfo.argOptionsLimit = field.value.value;
-        }
-        /* TODO        
-        if (field.name.value == 'offset') {            
-            schemaInfo.argOptionsOffset = field.value.value;
-        }
-        if (field.name.value == 'orderBy') {            
-            schemaInfo.argOptionsOrderBy = field.value.value;
-        }
-        */
-    });
+function setOptionsInSchemaInfo(fields, schemaInfo) {
+    fields.filter(field => field.name.value === 'limit' || field.name.value === 'offset')
+        .forEach(field => {
+            const value = extractPositiveIntegerFieldValue(field);
+            if (field.name.value === 'limit') {
+                schemaInfo.argOptionsLimit = value;
+            } else if (field.name.value === 'offset') {
+                schemaInfo.argOptionsOffset = value;
+            }
+            /* TODO 
+            if (field.name.value == 'orderBy') {            
+                schemaInfo.argOptionsOrderBy = field.value.value;
+            }
+            */
+        });
 }
 
+function extractPositiveIntegerFieldValue(field) {
+    if (field.value.kind === 'IntValue') {
+        const value = Number(field.value.value);
+        if (value >= 0) {
+            return value;
+        }
+    }
+    throw new GraphQLError(`The ${field.name.value} value must be a positive integer`);
+}
 
 function createQueryFunctionMatchStatement(obj, matchStatements, querySchemaInfo) {
     if (querySchemaInfo.graphQuery != null) {
@@ -480,7 +490,9 @@ function createQueryFunctionMatchStatement(obj, matchStatements, querySchemaInfo
         const argsAndWhereClauses = extractQueryArgsAndWhereClauses(selection.arguments, querySchemaInfo);
         const queryArgs = argsAndWhereClauses?.queryArguments.length > 0 ? `{${argsAndWhereClauses.queryArguments.join(',')}}` : '';
         const whereClause = argsAndWhereClauses?.whereClauses.length > 0 ? ` WHERE ${argsAndWhereClauses.whereClauses.join(' AND ')}` : '';
-        const withClause = querySchemaInfo.argOptionsLimit ? ` WITH ${querySchemaInfo.pathName} LIMIT ${querySchemaInfo.argOptionsLimit}` : '';
+        const skipClause = typeof querySchemaInfo.argOptionsOffset === 'number' ? ` SKIP ${querySchemaInfo.argOptionsOffset}` : '';
+        const limitClause = typeof querySchemaInfo.argOptionsLimit === 'number' ? ` LIMIT ${querySchemaInfo.argOptionsLimit}` : '';
+        const withClause = limitClause || skipClause ? ` WITH ${querySchemaInfo.pathName}${skipClause}${limitClause}` : '';
         matchStatements.push(`MATCH (${querySchemaInfo.pathName}:\`${querySchemaInfo.returnTypeAlias}\`${queryArgs})${whereClause}${withClause}`);
     }
 
@@ -524,7 +536,7 @@ function extractQueryArgsAndWhereClauses(selectionArguments, querySchemaInfo) {
             }
         } else if (selectionArgument.name?.value === 'options' && selectionArgument.value?.kind === 'ObjectValue') {
             // TODO change to set limit value on the returned object instead of mutating the querySchemaInfo
-            getOptionsInSchemaInfo(selectionArgument.value.fields, querySchemaInfo);
+            setOptionsInSchemaInfo(selectionArgument.value.fields, querySchemaInfo);
         } else if (selectionArgument.name?.value && selectionArgument.value?.value) {
             queryArguments.push(`${selectionArgument.name.value}:'${selectionArgument.value.value}'`);
         }
@@ -650,7 +662,7 @@ function createTypeFieldStatementAndRecurse(selection, fieldSchemaInfo, lastName
     if (selection.arguments !== undefined) {
         selection.arguments.forEach(arg => {
             if (arg.value.kind === 'ObjectValue' && arg.name.value === 'options')
-                getOptionsInSchemaInfo(arg.value.fields, fieldSchemaInfo);
+                setOptionsInSchemaInfo(arg.value.fields, fieldSchemaInfo);
         });
     }
     
@@ -678,11 +690,14 @@ function createTypeFieldStatementAndRecurse(selection, fieldSchemaInfo, lastName
     withStatements[thisWithId].content += '}';
 
     if (schemaTypeInfo.isArray) {
-        if (fieldSchemaInfo.argOptionsLimit != null) {
-            withStatements[thisWithId].content += `)[..${fieldSchemaInfo.argOptionsLimit}] END AS ${schemaTypeInfo.pathName}_collect`;
-        } else {
-            withStatements[thisWithId].content += ') END AS ' + schemaTypeInfo.pathName + '_collect';
+        const lowerBound = typeof fieldSchemaInfo.argOptionsOffset === 'number' ? fieldSchemaInfo.argOptionsOffset : null;
+        let upperBound = typeof fieldSchemaInfo.argOptionsLimit === 'number' ? fieldSchemaInfo.argOptionsLimit : null;
+        if (lowerBound != null && upperBound != null) {
+            upperBound = lowerBound + upperBound;
         }
+        const slice = (lowerBound != null || upperBound != null) ? `[${lowerBound ?? ''}..${upperBound ?? ''}]` : '';
+        withStatements[thisWithId].content += `)${slice} END AS ${schemaTypeInfo.pathName}_collect`;
+ 
         let i = withStatements.findIndex(({carryOver}) => carryOver.startsWith(lastNamePath));
 
         if (withStatements[i].content.slice(-2) != ', ' && withStatements[i].content.slice(-1) != '{')

Original file line number	Diff line number	Diff line change
`@@ -179,6 +179,7 @@ input RouteInput {`
`179`	`179`
`180`	`180`	`input Options {`
`181`	`181`	`limit:Int`
	`182`	`+ offset: Int`
`182`	`183`	`}`
`183`	`184`
`184`	`185`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -102,6 +102,7 @@ dist: Int`
`102`	`102`
`103`	`103`	`input Options {`
`104`	`104`	`limit:Int`
	`105`	`+offset:Int`
`105`	`106`	`}`
`106`	`107`
`107`	`108`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -101,6 +101,7 @@ input RouteInput {`
`101`	`101`
`102`	`102`	`input Options {`
`103`	`103`	`limit: Int`
	`104`	`+ offset: Int`
`104`	`105`	`}`
`105`	`106`
`106`	`107`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -120,6 +120,7 @@ type Friends @alias(property: "friends") {`
`120`	`120`
`121`	`121`	`input Options {`
`122`	`122`	`limit: Int`
	`123`	`+ offset: Int`
`123`	`124`	`}`
`124`	`125`
`125`	`126`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -74,6 +74,7 @@ type Stadium_edge @alias(property: "STADIUM_EDGE") {`
`74`	`74`
`75`	`75`	`input Options {`
`76`	`76`	`limit: Int`
	`77`	`+ offset: Int`
`77`	`78`	`}`
`78`	`79`
`79`	`80`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -133,6 +133,7 @@ type Merchant_edge @alias(property: "MERCHANT_EDGE") {`
`133`	`133`
`134`	`134`	`input Options {`
`135`	`135`	`limit: Int`
	`136`	`+ offset: Int`
`136`	`137`	`}`
`137`	`138`
`138`	`139`	`input StringScalarFilters {`
Original file line number	Diff line number	Diff line change
`@@ -148,6 +148,7 @@ type Written_by @alias(property: "written_by") {`
`148`	`148`
`149`	`149`	`input Options {`
`150`	`150`	`limit: Int`
	`151`	`+ offset: Int`
`151`	`152`	`}`
`152`	`153`
`153`	`154`	`input StringScalarFilters {`