From f12b15c44064dec75900af0561cd2ca5a674ddff Mon Sep 17 00:00:00 2001
From: Kyrch <kyrchk5@gmail.com>
Date: Thu, 24 Jul 2025 21:11:33 -0300
Subject: [PATCH] docs(graphql): pagination arguments (#111)

(cherry picked from commit bf69d27a989a51aa6ec63b8ac749c59ba43fe5a9)
---
 docs/guide/graphql/filtering/index.md  | 69 +++++++++++---------------
 docs/guide/graphql/pagination/index.md | 57 +++++++++++++++++----
 2 files changed, 75 insertions(+), 51 deletions(-)

diff --git a/docs/guide/graphql/filtering/index.md b/docs/guide/graphql/filtering/index.md
index 9c1cbba..63e33f6 100644
--- a/docs/guide/graphql/filtering/index.md
+++ b/docs/guide/graphql/filtering/index.md
@@ -6,16 +6,19 @@ title: Filtering
 
 ---
 
-Most queries provide filtering arguments using the AND operator. Filtering arguments are built using `{fields}_{filter}`.
+Most queries provide filtering arguments using the AND operator. Filtering arguments are built using the `{fields}_{filter}` pattern.
 
 ## All Filters
 
-* Eq: `name` (without the filter argument)
-* Like: `name_like`
-* In: `id_in`
-* Not in: `id_not_in`
-* Greater: `id_greater`
-* Lesser: `id_lesser`
+| Name    | Fields                                         | Example    | Description                           |
+| :-----: | :--------------------------------------------: | :--------: | ------------------------------------- |
+| Eq      | String, Int, Float, Boolean, enums, DateTimeTz | name       | Add an `equal` conditional to the query |
+| Like    | String                                         | name_like  | Add a `like` conditional to the query   |
+| In      | Int, Float, enums                              | id_in      | Add an `in` conditional to the query    |
+| Not in  | Int, Float, enums                              | id_not_in  | Add a `not in` conditional to the query |
+| Greater | Int, Float, DateTimeTz                         | id_greater | Add a `gt` conditional to the query     |
+| Lesser  | Int, Float, DateTimeTz                         | id_lesser  | Add a `lt` conditional to the query     |
+
 
 Query example:
 ```graphql
@@ -28,45 +31,29 @@ query {
 }
 ```
 
-## Available Filters for the fields
+## Trashed Filter
 
-### String Fields
+The queries that return a type that implements soft-deletes have a `trashed` filter.
 
-* Eq
-* Like
+The argument is: `trashed: Trashed`, which allows to filter if trashed elements should be fetched.
 
-### Int Fields
+`Trashed` is an enum with the following values:
 
-* Eq
-* In
-* Not in
-* Greater
-* Lesser
-
-### Float Fields
-
-* Eq
-* In
-* Not in
-* Lesser
-* Greater
-
-### Boolean Fields
-
-* Eq
-
-### Enum Fields
-
-* Eq
-* In
-* Not in
-
-### DateTimeTz Fields
-
-* Eq
-* Greater
-* Lesser
+| Value        | Description                                  |
+| :----------: | :------------------------------------------- |
+| ONLY         | Only return trashed results.                 |
+| WITH         | Return both trashed and non-trashed results. |
+| WITHOUT      | Only return non-trashed results.             |
 
+```graphql
+query {
+    animes(trashed: ONLY) {
+        data {
+            name
+        }
+    }
+}
+```
 
 ## Nested Filtering
 
diff --git a/docs/guide/graphql/pagination/index.md b/docs/guide/graphql/pagination/index.md
index 02e20a1..2214b9a 100644
--- a/docs/guide/graphql/pagination/index.md
+++ b/docs/guide/graphql/pagination/index.md
@@ -8,23 +8,60 @@ title: Pagination
 
 The AnimeThemes API query that uses pagination shall contain a `paginatorInfo` object for pagination strategies and a `data` collection with the resources.
 
+
+## Arguments
+
+There are two arguments available for every query that uses pagination.
+
+| Name      | Type     | Default  | Max      | Description                               |
+| :-------: | :------: | :------: | :------: | ----------------------------------------- |
+| first     | Int!     | 15       | 100      | Limits number of fetched items            |
+| page      | Int      | 1        | lastPage | The offset from which items are returned  |
+
+## Query
+
+The following query
+```graphql
+query {
+    animes(first: 15, page: 1) {
+        paginatorInfo {
+            count
+            currentPage
+            firstItem
+            hasMorePages
+            lastItem
+            lastPage
+            perPage
+            total
+        }
+        data {
+            name
+        }
+    }
+}
+```
+will return a JSON like:
 ```json
-// The animes query contains a paginatorInfo object
 {
     "data": {
         "animes": {
             "paginatorInfo": {
-                "count": count,
-                "currentPage": currentPage,
-                "firstItem": firstItem,
-                "hasMorePages": hasMorePages,
-                "lastItem": lastItem,
-                "lastPage": lastPage,
-                "perPage": perPage,
-                "total": total
+                "count": 2,
+                "currentPage": 1,
+                "firstItem": 1,
+                "hasMorePages": true,
+                "lastItem": 2,
+                "lastPage": 2317,
+                "perPage": 2,
+                "total": 4633
             },
             "data": [
-                ...
+                {
+                    "name": ".hack//Liminality"
+                },
+                {
+                    "name": ".hack//roots"
+                }
             ]
         }
     }