From 20cd405f754dfda0cb02469f00644d0205185ee8 Mon Sep 17 00:00:00 2001 From: Kyrch Date: Tue, 27 Jan 2026 14:09:51 -0300 Subject: [PATCH] docs: advanced filtering & pivot sorting (#125) --- .../examples/filter-by-external-site/index.md | 10 +- docs/graphql/examples/search/index.md | 2 +- docs/graphql/guide/filtering/index.md | 95 ++++++++++++++++--- docs/graphql/guide/sorting/index.md | 23 +++++ 4 files changed, 112 insertions(+), 18 deletions(-) diff --git a/docs/graphql/examples/filter-by-external-site/index.md b/docs/graphql/examples/filter-by-external-site/index.md index 2f04da8..9987905 100644 --- a/docs/graphql/examples/filter-by-external-site/index.md +++ b/docs/graphql/examples/filter-by-external-site/index.md @@ -29,11 +29,11 @@ None ## Parameters -| Name | Type | Description | -| :---: | :-----------: | :---------------------------------------------------------------- | -| site | ResourceSite! | The site enum used to filter | -| id | Int | The id of the anime in the external site | -| link | String | The URL of the external resource. Required if no `id` provided. | +| Name | Type | Description | +| :---: | :-----------: | :------------------------------------------------------------------------ | +| site | ResourceSite! | The site enum used to filter. | +| id | Int | The id of the anime in the external site. Required if no `link` provided. | +| link | String | The URL of the external resource. Required if no `id` provided. | ## Response diff --git a/docs/graphql/examples/search/index.md b/docs/graphql/examples/search/index.md index 217641c..974a02b 100644 --- a/docs/graphql/examples/search/index.md +++ b/docs/graphql/examples/search/index.md @@ -50,7 +50,7 @@ None | Name | Type | Description | | :----------: | :------: | :----------------------------- | | page | Int | Index of the current page | -| perPage | Int | Number of items per page | +| first | Int! | Number of items per page | | search | String! | The term used for the search | ## Response diff --git a/docs/graphql/guide/filtering/index.md b/docs/graphql/guide/filtering/index.md index dd23b8a..3265108 100644 --- a/docs/graphql/guide/filtering/index.md +++ b/docs/graphql/guide/filtering/index.md @@ -6,18 +6,18 @@ title: Filtering --- -Most queries provide filtering arguments using the AND operator. Filtering arguments are built using the `{fields}_{filter}` pattern. +Most queries provide filtering arguments using the AND operator. Filtering arguments are built using the `{field}_{filter}` pattern. -## All Filters +## Filter Arguments -| Name | Fields | Example | Description | -| :-----: | :--------------------------------------------: | :--------: | ------------------------------------- | -| Eq | String, Int, Float, Boolean, enums, DateTimeTz | name | Add an `equal` conditim to the query | -| Like | String | name_like | Add a `like` condition to the query | -| In | Int, Float, enums | id_in | Add an `in` condition to the query | -| Not in | Int, Float, enums | id_not_in | Add a `not in` condition to the query | +| Name | Fields | Example | Description | +| :-----: | :--------------------------------------------: | :--------: | ----------------------------------------------- | +| Eq | String, Int, Float, Boolean, enums, DateTimeTz | name | Add an `equal` conditim to the query | +| Like | String | name_like | Add a `like` condition to the query | +| In | Int, Float, enums | id_in | Add an `in` condition to the query | +| Not in | Int, Float, enums | id_not_in | Add a `not in` condition to the query | | Greater | Int, Float, DateTimeTz | id_greater | Add a `greater than` condition to the query | -| Lesser | Int, Float, DateTimeTz | id_lesser | Add a `less than` condition to the query | +| Lesser | Int, Float, DateTimeTz | id_lesser | Add a `less than` condition to the query | Query example: @@ -35,9 +35,9 @@ query { Queries that return a type implementing soft deletes have a `trashed` filter. -The argument is `trashed: Trashed`, which allows filtering to determine if trashed elements should be fetched. +The argument is `trashed: TrashedFilter`, which allows filtering to determine if trashed elements should be fetched. -`Trashed` is an enum with the following values: +`TrashedFilter` is an enum with the following values: | Value | Description | | :----------: | :------------------------------------------- | @@ -69,4 +69,75 @@ query { } } } -``` \ No newline at end of file +``` + +## Advanced Filtering + +The where argument allows you to apply flexible and composable filters to pagination queries. +It supports single conditions, logical operators, and nested filters. + +```graphql +query { + animePagination( + where: { + field: SEASON, + operator: NE, + value: FALL + } + ) { + data { + name + season + } + } +} +``` + +### Logical Operators + +Logical operators (AND, OR) can be nested to build complex filter trees, allowing advanced query expressions with precise control over result sets. + +Query example: +```graphql +query { + # Returns all anime where the season is either WINTER or FALL. + animePagination( + where: { + OR: [ + { + field: SEASON, + operator: EQ, + value: WINTER, + }, + { + field: SEASON, + operator: EQ, + value: FALL, + } + ] + } + ) { + data { + name + season + } + } +} +``` + +::: info +Aggregate filters (such as count/exists) do not work when combined with logical operators. +::: + +### Comparison Operators + +| Value | Description | +| :-----: | :----------------------------------------------------------------------------- | +| EQ | Matches values that are exactly equal to the given value. | +| NE | Matches values that are not equal to the given value. | +| LT | Matches values less than the given value. | +| GT | Matches values greater than the given value. | +| LTE | Matches values less than or equal to the given value. | +| GTE | Matches values greater than or equal to the given value. | +| LIKE | Matches values that partially match the given pattern (using wildcard search). | +| NOTLIKE | Matches values that do not match the given pattern. | \ No newline at end of file diff --git a/docs/graphql/guide/sorting/index.md b/docs/graphql/guide/sorting/index.md index 8e8954a..59b3a07 100644 --- a/docs/graphql/guide/sorting/index.md +++ b/docs/graphql/guide/sorting/index.md @@ -64,6 +64,29 @@ query { } ``` +## Pivot Sorting + +It is possible to sort results using pivot fields. +All pivot fields are exposed with the `PIVOT_` prefix and can be used in the sort argument. + +```graphql +query { + animePagination { + data { + name + images(sort: PIVOT_DEPTH) { + edges { + node { + link + } + depth + } + } + } + } +} +``` + ## Multiple Sorting By providing a list of enum cases, the sort will be applied in the order of the values provided by the client.