Graphql Pagination

이제 커서를 이용하는 커넥션(connection)을 받아 페이지처리를 할 수 있게 되었다고 하자. 커넥션의 마지막은 어디일까? 아마 마지막까지 쿼리를 계속 날려서 빈값이 리턴될 때까지 가봐야 알 것이다.

만약에 '이곳이 마지막 페이지'라는 것을 알려준다면 우리는 마지막 요청을 할 필요가 없게된다. 마찬가지로, 커넥션 자체에 대한 추가 정보를 알고 싶다면 어떻게 해야 할까? 예를 들어, 'R2-D2에는 총 친구가 몇 명 있을까?' 같은 질문을 말이다.

이걸 해결하기 위해 frieds 필드는 connection object 를 리턴할 수 있다. 이 커넥션 개체는 edge 에 대한 필드 뿐만 아니라 다른 정보도 가질 수 있다. (토탈카운트나 다음 페이지 존재여부)

하여 마지막 쿼리는 다음과 같다.

{
  hero {
    name
    friends(first:2) {
      totalCount
      edges {
	node {
	  name
	}
	cursor
      }
      pageInfo {
	endCursor
	hasNextPage
      }
    }
  }
}

PageInfo 를 보자 이곳에는 endCursor, startCursor 둘다 올 수 있다.

Connection Type 은 edges 와 PageInfo 라는 필드를 가져야 한다. 이것들은 connection에 연관된 추가 필드를 가질 수 있다. (스키마 디자이너가 적합하다고 생각하는)

만약 ExceptionConnection 이 타입시스템에 존재한다면, 이녀석은 connection일 것이다, 왜냐하면 "Connection"이라는 이름으로 끝나기 때문이다. 만약 이 커넥션의 edge type이 ExampleEdge 라는 이름을 가진다고하자.

서버가 이 구현을 Spec에 따라 잘 구현했다면 하여 아래 Introspection 쿼리를 허용하고, 제공된 응답을 반환한다.

{
  __type(name: "ExampleConnection") {
    fields {
      name
      type {
	name
	kind
	ofType {
	  name
	  kind
	}
      }
    }
  }
}

리턴은 다음처럼

{
  "data": {
    "__type": {
      "fields": [
	// May contain other items
	{
	  "name": "pageInfo",
	  "type": {
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "PageInfo",
	      "kind": "OBJECT"
	    }
	  }
	},
	{
	  "name": "edges",
	  "type": {
	    "name": null,
	    "kind": "LIST",
	    "ofType": {
	      "name": "ExampleEdge",
	      "kind": "OBJECT"
	    }
	  }
	}
      ]
    }
  }
}

Edge Type은 node , cursor 라는 필드가 있어야 한다. 또한 edge 와 관련있는 추가적인 필드가 있을 수 있다.

ExampleEdge 가 Example object를 리턴하는 우리 스칼라타입의 edge type 이라고 하자. 서버가 다음 구현을 Spec에 맞춰 잘 만들었다면 다음의 introspection 쿼리를 허용 및 제공되는 응답을 리턴한다.

{
  __type(name: "ExampleEdge") {
    fields {
      name
      type {
	name
	kind
	ofType {
	  name
	  kind
	}
      }
    }
  }
}

리턴은

{
  "data": {
    "__type": {
      "fields": [
	// May contain other items
	{
	  "name": "node",
	  "type": {
	    "name": "Example",
	    "kind": "OBJECT",
	    "ofType": null
	  }
	},
	{
	  "name": "cursor",
	  "type": {
	    // This shows the cursor type as String!, other types are possible
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "String",
	      "kind": "SCALAR"
	    }
	  }
	}
      ]
    }
  }
}

정방향 페이지네이션을 사용하려면, 두 인자가 필수다.

• first 는 음수가 아닌 숫자여야 한다.
• after 는 cursor type 을 취해야 한다.

서버는 두 인자를 사용하여 connection에 의해 after cursor 뒤의 edge 를 리턴하고, first edge에 맞는 갯수를 리턴함.

역방향 페이지네이션을 사용하려면, 두 인자가 필수다.

• last 는 음수가 아닌 숫자여야 한다.
• before 는 cursor type 을 취해야 한다.

중요한 점, edges 의 순서는 first|after 를 쓰건 last|before 를 쓰건 동일해야한다. 역방향 조회를 한다고 해서, 순서가 역방향이 저절로 되면 안된다.

좀 더 설명하면,

• before: cursor 가 쓰인다면 커서의 가장 가까운 edge 는 리턴하는 edges 의 last 이다.
• after: cursor 가 쓰인다면 커서의 가장 가까운 edge 는 리턴하는 edges 의 first 이다.

PageInfo 는 hasPreviousPage 와 hasNextPage 필드를 반드시 가진다. 둘 다 non-null bolean 이다. 또한 startCursor , endCursor 필드를 가져야한다. 둘다 non-null opague string 을 리턴한다.

hasPreviousPage 는 클라이언트 인자에 의해 정의된 집합(조건에 부합하는 edges)의 이전( previous )에 edges 가 더 있는지 알려준다. 클라이언트에서 last|before 요청쿼리로 조회할 때, 이전 값이 존재하면 true 아니면 false 를 리턴한다. 또한 first|after 의 경우는 after 이전 값이 존재하면서 이것을 효율적으로 수행할 수 있을 때 true 아니면 false 를 리턴한다.

좀 더 공식적으로는

HasPreviousPage(addEdges, before, after, first, last) :

1. last 가 설정되어 있으면
   1. edges 를 ApplyCursorsToEdges(allEdges, before, after) 의 결과라고 하자.
   2. 만약 edges 가 last 보다 많은 요소를 가진다면 true , 아니면 false
2. after 가 설정되어 있으면
   1. 서버가 효율적으로 after 이전에 요소가 존재하는지 결정 할 수 있다면 true 를 반환한다.
3. false 를 리턴한다.

hasNextPage 는 클라이언트 인자에 의해 정의된 집합(조건에 부합하는 edges) 이후에 더 많은 edge가 있는지 여부를 리턴. first/after 를 쓸 때, 서버에서 추가 edges 가 존재하면 true 아니면 false 를 리턴한다. last/before 를 쓸 때, 서버에서 before 기준으로 추가 edges 가 존재하고, 효율적으로 수행할 수 있으면 true 아니면 false 를 리턴한다.

좀 더 공식적으로는

HasNextPage(allEdges, before, after, first, last) :

1. first 가 설정되어 있으면
   1. edges 를 ApplyCursorsToEdges(allEdges, before, after) 의 결과라고 하자.
   2. 만약 edges 가 first 보다 많은 요소를 가진다면 true , 아니면 false
2. before 가 설정되어 있으면
   1. 서버가 효율적으로 before 이전에 요소가 존재하는지 결정 할 수 있다면 true 를 반환한다.
3. false 를 리턴한다.

만약 first , last 가 동시에 있으면 위 법칙에 따라 리턴할 것이다. 하지만 페이지처리방식이 명확해 보이지 않을 것이다. 그러므로 동시에 쓰는 것은 권장하지 않는다.

startCursor 와 endCursor 는 edges 의 first , last 노드를 각각 말한다.

위 스펙을 잘 구현했다면 아래 처럼 수행될 것

{
  __type(name: "PageInfo") {
    fields {
      name
      type {
	name
	kind
	ofType {
	  name
	  kind
	}
      }
    }
  }
}

다음처럼 리턴

{
  "data": {
    "__type": {
      "fields": [
	// May contain other fields.
	{
	  "name": "hasNextPage",
	  "type": {
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "Boolean",
	      "kind": "SCALAR"
	    }
	  }
	},
	{
	  "name": "hasPreviousPage",
	  "type": {
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "Boolean",
	      "kind": "SCALAR"
	    }
	  }
	},
	{
	  "name": "startCursor",
	  "type": {
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "String",
	      "kind": "SCALAR"
	    }
	  }
	},
	{
	  "name": "endCursor",
	  "type": {
	    "name": null,
	    "kind": "NON_NULL",
	    "ofType": {
	      "name": "String",
	      "kind": "SCALAR"
	    }
	  }
	}
      ]
    }
  }
}