chore(docs): [skip-ci] docs for queries, pagination, sorting (#4)

* docs(docs): pagination, queries, sorting

* docs(docs): update announcing-hydra-v3.md

GitBook: [hydra-v3] 6 pages modified

GitBook: [hydra-v3] 4 pages modified

SUMMARY.md

@@ -3,6 +3,9 @@
 * [Hydra](README.md)
 * [Overview](docs/README.md)
   * [Query Node Manifest](docs/manifest-spec.md)
+  * [Query Node Queries](docs/queries.md)
+  * [Pagination](docs/paginate-query-results.md)
+  * [Sorting](docs/sort-query-results.md)
   * [Mappings](docs/mappings/README.md)
     * [DatabaseManager](docs/mappings/databasemanager.md)
     * [SubstrateEvent](docs/mappings/substrateevent.md)
@@ -15,7 +18,6 @@
     * [Full-text queries](docs/schema-spec/full-text-queries.md)
     * [Entity Relationships](docs/schema-spec/entity-relationship.md)
   * [Install Hydra](docs/install-hydra.md)
-  * [Query Node schema](docs/query-node-schema.md)
   * [Tutorial](docs/quick-start.md)
   * [GraphQL Entity Relationships](docs/entity-relationship.md)
   * [Architecture](docs/architecture.md)

announcing-hydra-v3.md

@@ -3,20 +3,19 @@
 Hydra v3 is already in the works. Here are the main features planned:
 
 * Support for filtering by relations
-* Define block ranges for any mapping, i.e. specify that your mapping X should be run only from block 5 to block 7
-* Import all model files from a single library.  Instead of the cumbersome 
+* Support for adding relations to variant types
+* Ordering by multiple fields
+* Multiple filters in the same query \(`AND` and `OR`\)
+* Filters for mapping handlers: specify heights and runtime spec version range
+* Import all model files from a single library. Instead of the cumbersome
 
 ```typescript
-import { MyEntity1 }  from '../generated/graphql-server/my-entity2/my-entity2.model' 
-import { MyEntity2 }  from '../generated/graphql-server/my-entity2/my-entity2.model' 
-
+import { MyEntity1 } from '../generated/graphql-server/my-entity2/my-entity2.model'
+import { MyEntity2 } from '../generated/graphql-server/my-entity2/my-entity2.model'
 ```
 
 write
 
 ```typescript
 import { MyEntity1, MyEntity2 } from '../generated/graphql-server/model'
 ```
-
-
-

docs/paginate-query-results.md

@@ -0,0 +1,180 @@
+---
+description: Paginate query results
+---
+
+## The `limit` & `offset` arguments
+
+The operators limit and offset are used for pagination.
+
+`limit` specifies the number of entities to retain from the result set and `offset` determines which slice to retain from the results.
+
+Default value for `limit` is `50` and `offset` is `0`.
+
+**Limit results**
+
+Example: Fetch the first 5 channels:
+
+```graphql
+query {
+  channels(limit: 5) {
+    id
+    handle
+  }
+}
+```
+
+**Limit results from an offset**
+
+Example: Fetch 5 channels from the list of all channels, starting with the 6th one:
+
+```graphql
+query {
+  channels(limit: 5, offset: 5) {
+    id
+    handle
+  }
+}
+```
+
+## Cursor based pagination
+
+Cursors are used to traverse across entities of an entity set. They work by returning a pointer to a specific entity which can then be used to fetch the next batch of entities.
+
+For cursor based pagination for every entity in the input schema a query is generated with the `<entityName>Connection` pattern.
+
+Example: Fetch a list of videos where `isExplicit` is true and get their count. Then limit the number of videos to return.
+
+```graphql
+query {
+  videosConnection(where: { isExplicit_eq: true }) {
+    totalCount
+    edges {
+      node {
+        id
+        title
+      }
+    }
+  }
+}
+```
+
+**`first` `last` operators**
+
+The `first` operator is used to fetch specified number of entities from the beginning and `last` is vice versa.
+
+Example: Fetch first 5 videos and last 5 videos:
+
+```graphql
+query Query1 {
+  videosConnection(first: 5) {
+    edges {
+      node {
+        id
+        title
+      }
+    }
+  }
+}
+
+query Query1 {
+  videosConnection(last: 5) {
+    edges {
+      node {
+        id
+        title
+      }
+    }
+  }
+}
+```
+
+**PageInfo object**
+
+`PageInfo` returns the cursor, page information and object has following fields:
+
+```json
+pageInfo {
+  startCursor
+  endCursor
+  hasNextPage
+  hasPreviousPage
+}
+```
+
+**`before` and `after` operators**
+
+Example: Fetch a first 10 channels order by `createdAt` and then fetch the next 10 channels:
+
+```graphql
+query FirstBatchQ {
+  channelsConnection(first: 10, orderBy: createdAt_ASC) {
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+    edges {
+      node {
+        id
+        handle
+        createdAt
+      }
+    }
+  }
+}
+
+query SecondBatchQ {
+  channelsConnection(after: <endCursor>, orderBy: createdAt_ASC) {
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+    edges {
+      node {
+        id
+        handle
+        createdAt
+      }
+    }
+  }
+}
+```
+
+Example: Fetch a last 10 channels order by `createdAt` and then fetch the previous 10 channels:
+
+```graphql
+query FirstBatchQ {
+  channelsConnection(last: 10, orderBy: createdAt_ASC) {
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+    edges {
+      node {
+        id
+        handle
+        createdAt
+      }
+    }
+  }
+}
+
+query SecondBatchQ {
+  channelsConnection(before: <endCursor>, orderBy: createdAt_ASC) {
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+    edges {
+      node {
+        id
+        handle
+        createdAt
+      }
+    }
+  }
+}
+```
+
+**Important Note on orderBy**
+
+The field entities are ordered by should be fetch `node { <fieldNameThatOrderedBy> }` otherwise the returned result wouldn't be ordered correctly.