GraphQL Paging and Sorting

This page provides further details on paging and sorting supported by the Contract Eagle GraphQL implementation.


Paging

Paging of data is supported on Contracts, Counterparties, Contacts, Users and Contract User Defined Fields.

  • If a large amount of information is required by the use-case, use the paging feature to limit the number of records returned in a single query.

Sorting

Sorting is currently supported on fields within the top level node of the graph only.

Fair Use, Query Limiting and Paging

GraphQL queries provide a great deal of flexibility for the API developer, but it is also possible to create queries that consume a large amount of system resources.

Generally, only query fields needed to meet the immediate requirement, and particularly when querying contract information, avoid querying multiple graph levels (eg: counterparties, dates, user defined fields, documents) for a large number of records at once.

The below provides an example query that retrieves a list of contracts with associated details, retrieving up to 50 contracts at a time.

query getContracts(
  $contractInputFilter: ContractFilterInput
  $getFirst: Int
  $getAfter: String
) {
  contractDetails(
    inputFilter: $contractInputFilter
    first: $getFirst
    after: $getAfter
  ) {
    totalCount
    pageInfo {
      ...GraphQlPageInfo
    }
    nodes {
      contractId
      contractTitle
      summary
      contractTypeSummary {
        ...GraphQlContractTypeIdName
      }
      contractBusinessUnit {
        ...GraphQlBusinessUnit
      }
      contractStatus {
        ...GraphQlStatusTypeIdName
      }
      approvalStatus
      dateEnteredUtc
      lastModifiedDateUtc
      contractApprovalRule {
        ...GraphQlApprovalRuleIdName
      }
      contractCounterparties {
        ...GraphQlContractCounterparty
      }
    }
  }
}
fragment GraphQlContractTypeIdName on ContractTypeSummary {
  contractTypeId
  contractTypeDescription
}
fragment GraphQlBusinessUnit on BusinessUnit {
  businessUnitId
  businessUnitDescription
}
fragment GraphQlStatusTypeIdName on StatusType {
  statusTypeId
  statusTypeDescription
}
fragment GraphQlApprovalRuleIdName on ApprovalRule {
  approvalRuleId
  approvalRuleName
}
fragment GraphQlContractCounterparty on ContractCounterparty {
  counterpartyOrganization {
    ...GraphQlContractCounterpartyOrganization
  }
  contractContacts {
    ...GraphQlContractContactRole
  }
}
fragment GraphQlContractCounterpartyOrganization on Counterparty {
  counterpartyId
  counterpartyName
  referenceNumber
  tradingName
}
fragment GraphQlContractContactRole on ContractContactRole {
  contractRoleRoleType {
    ...GraphQlRoleTypeIdName
  }
  contractRoleContact {
    ...GraphQlContractContact
  }
}
fragment GraphQlRoleTypeIdName on RoleType {
  roleTypeId
  roleTypeTitle
}
fragment GraphQlContractContact on Contact {
  counterpartyId
  contactId
  contactDescription
  emailAddress
}
fragment GraphQlPageInfo on PageInfo {
  hasNextPage
  hasPreviousPage
  startCursor
  endCursor
}

With parameter variables

{
  "contractInputFilter": {
   "contractFilterSet" : 
    [
      { "statusTypes": [1, 1000] }
    ]},
  "getFirst": 50,
  "getAfter": null
}

This will return a result with header details similar to the following, showing the first 50 contracts matching the filter criteria.

This indicates that a total of 219 contracts match the criteria. Since this is the first page the "hasPreviousPage" is false, but the "hasNextPage" variable is true, indicating a further page can be retrieved using the "endCursor" value. 

{
  "data": {
    "contractDetails": {
      "totalCount": 219,
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "MA==",
        "endCursor": "OQ=="
      },
      "nodes": [
        {
          "contractId": 1012,
                                ...

To retrieve the next set of 50 contracts, the parameter variables would be specified as below - setting the "getAfter" value to the "endCursor" returned in the previous query results.:

{
  "contractInputFilter": {
   "contractFilterSet" : 
    [
      { "statusTypes": [1, 1000] }
    ]},
  "getFirst": 50,
  "getAfter": "OQ=="
}

Sorting

Sorting is enabled on all queries using standard GraphQL notation. E.g. To sort counterparties by their name in reverse order:

query getCounterparties(
  $orgTypeFilter: CounterpartyFilterInput
  $getFirst: Int) 
{
  counterparties(
    inputFilter: $orgTypeFilter 
    first: $getFirst
    order: [{counterpartyName : DESC }]) 
    {
    totalCount
    nodes {
      counterpartyId
      counterpartyName
      counterpartyContacts {
        contactId
        lastName
      }
    }
  }
}

With variables:

{
 "orgTypeFilter" : {
   "counterpartyName": "training"
 },
 "getFirst": 100
}