diff --git a/docs/usage/index.md b/docs/usage/index.md deleted file mode 100644 index 6143e07d8..000000000 --- a/docs/usage/index.md +++ /dev/null @@ -1,19 +0,0 @@ -# Hasura PostgreSQL Connector Usage Documentation - -Information on how to use the Hasura PostgreSQL Connector. - -- [Queries](./queries/index.md) - - [Simple Queries](./queries/simple-queries.md) - - [Nested Queries](./queries/nested-queries.md) - - [Multiple Arguments](./queries/multiple-arguments.md) - - [Multiple Queries](./queries/multiple-queries.md) - - [Pagination](./queries/pagination.md) - - [Sorting](./queries/sorting.md) - - [Variables, Aliases, Fragments & Directives](./queries/variables-aliases-fragments-directives.md) - - [Multi-Region Routing](./multi-region-routing.md) - - [Filters](./queries/filters/index.md) - - [Boolean Operators](./queries/filters/boolean-operators.md) - - [Comparison Operators](./queries/filters/comparison-operators.md) - - [Computed Fields](./queries/filters/computed-fields.md) - - [Nested Objects](./queries/filters/nested-objects.md) - - [Text Search Operators](./queries/filters/text-search-operators.md) diff --git a/docs/usage/queries/filters/_category_.json b/docs/usage/queries/filters/_category_.json deleted file mode 100644 index c55c005e1..000000000 --- a/docs/usage/queries/filters/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Filter query results", - "position": 20 -} diff --git a/docs/usage/queries/filters/boolean-operators.md b/docs/usage/queries/filters/boolean-operators.md deleted file mode 100644 index 6f0b2268f..000000000 --- a/docs/usage/queries/filters/boolean-operators.md +++ /dev/null @@ -1,207 +0,0 @@ -# PostgreSQL: Filter by Boolean Expressions - -## Filter based on failure of some criteria (_not) - -The `_not` operator can be used to fetch results for which some condition does not hold true. i.e. to invert the filter -set for a condition. - -**Example: _not** - -Fetch all authors who don't have any published articles: - -#### Request - -```graphql -{ - authors( - where: { - _not: { - articles: { is_published: {_eq: true} } - } - }) { - id - name - articles { - title - is_published - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 7, - "name": "Berti", - "articles": [ - { - "title": "ipsum primis in", - "is_published": false - } - ] - }, - { - "id": 9, - "name": "Ninnetta", - "articles": [] - }, - { - "id": 10, - "name": "Lyndsay", - "articles": [ - { - "title": "dui proin leo", - "is_published": false - } - ] - } - ] - } -} -``` - -## Using multiple filters in the same query (_and, _or) - -You can group multiple parameters in the same `where` argument using the `_and` or the `_or` operators to filter results -based on more than one criteria. - -> :information_source: You can use the `_or` and `_and` operators along with the `_not` operator to create arbitrarily -> complex boolean expressions involving multiple filtering criteria. - -**Example: _and** - -Fetch a list of articles published in a specific time-frame (for example: in year 2017): - -#### Request - -```graphql -query { - articles ( - where: { - _and: [ - { published_on: {_gte: "2017-01-01"}}, - { published_on: {_lte: "2017-12-31"}} - ] - } - ) - { - id - title - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet", - "published_on": "2017-08-09" - }, - { - "id": 3, - "title": "amet justo morbi", - "published_on": "2017-05-26" - }, - { - "id": 4, - "title": "vestibulum ac est", - "published_on": "2017-03-05" - }, - { - "id": 9, - "title": "sit amet", - "published_on": "2017-05-16" - } - ] - } -} -``` - -> :information_source: Certain `_and` expressions can be expressed in a simpler format using some syntactic sugar. - -**Example: _or** - -Fetch a list of articles rated more than 4 or published after "01/01/2018": - -#### Request - -```graphql -query { - articles ( - where: { - _or: [ - {rating: {_gte: 4}}, - {published_on: {_gte: "2018-01-01"}} - ] - } - ) - { - id - title - rating - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 2, - "title": "a nibh", - "rating": 3, - "published_on": "2018-06-10" - }, - { - "id": 3, - "title": "amet justo morbi", - "rating": 4, - "published_on": "2017-05-26" - }, - { - "id": 6, - "title": "sapien ut", - "rating": 1, - "published_on": "2018-01-08" - }, - { - "id": 7, - "title": "nisl duis ac", - "rating": 4, - "published_on": "2016-07-09" - } - ] - } -} -``` - -[//]: # ([//]: # ":::info Note") - -[//]: # ([//]: #) - -[//]: # ([//]:) - -[//]: # ( #) - -[//]: # ( "The `_or` operator expects an array of expressions as input. If an object is passed as input it will behave like the") - -[//]: # ([//]: # "`_and` operator as explained in the [API reference](/api-reference/graphql-api/query.mdx#orexp)") - -[//]: # ([//]: #) - -[//]: # ([//]: # ":::") diff --git a/docs/usage/queries/filters/comparison-operators.md b/docs/usage/queries/filters/comparison-operators.md deleted file mode 100644 index 63c27a909..000000000 --- a/docs/usage/queries/filters/comparison-operators.md +++ /dev/null @@ -1,631 +0,0 @@ -# PostgreSQL: Filter by Comparing Values - -## Introduction - -Comparison operators are used to compare values of the same type. For example, to compare two numbers, two strings, two -dates, etc. - -## Equality operators (_eq, _neq) - -The `_eq` (equal to) or the `_neq` (not equal to) operators are compatible with any PostgreSQL type other than `json` or -`jsonB` (like `Integer`, `Float`, `Double`, `Text`, `Boolean`, `Date`/`Time`/`Timestamp`, etc.). - -[//]: # ([//]: # "For more details on equality operators and PostgreSQL equivalents, refer to the") -[//]: # ([//]: # "[API reference](/api-reference/graphql-api/query.mdx#generic-operators).") - -The following are examples of using the equality operators on different types. - -**Example: Integer (works with Double, Float, Numeric, etc.)** - -Fetch data about an author whose `id` _(an integer field)_ is equal to 3: - -#### Request - -```graphql -query { - authors( - where: {id: {_eq: 3}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 3, - "name": "Sidney" - } - ] - } -} -``` - -**Example: String or Text** - -Fetch a list of authors with `name` _(a text field)_ as "Sidney": - -#### Request - -```graphql -query { - authors( - where: {name: {_eq: "Sidney"}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 3, - "name": "Sidney" - } - ] - } -} -``` - -**Example: Boolean** - -Fetch a list of articles that have not been published (`is_published` is a boolean field): - -#### Request - -```graphql -query { - articles( - where: {is_published: {_eq: false}} - ) { - id - title - is_published - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 5, - "title": "ut blandit", - "is_published": false - }, - { - "id": 8, - "title": "donec semper sapien", - "is_published": false - }, - { - "id": 10, - "title": "dui proin leo", - "is_published": false - }, - { - "id": 14, - "title": "congue etiam justo", - "is_published": false - } - ] - } -} -``` - -**Example: Date (works with Time, Timezone, etc.)** - -Fetch a list of articles that were published on a certain date (`published_on` is a Date field): - -#### Request - -```graphql -query { - articles( - where: {published_on: {_eq: "2017-05-26"}} - ) { - id - title - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 3, - "title": "amet justo morbi", - "published_on": "2017-05-26" - } - ] - } -} -``` - -**Example: Integer (works with Integer, Float, Double, etc.)** - -Fetch a list of users whose age is _not_ 30 (`age` is an Integer field): - -#### Request - -```graphql -query { - users(where: { age: { _neq: 30 } }) { - id - name - age - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "id": 1, - "name": "John", - "age": 20 - }, - { - "id": 2, - "name": "Jane", - "age": 25 - }, - { - "id": 4, - "name": "Bob", - "age": 40 - } - ] - } -``` - -### info Caveat for "null" values - -By design, the `_eq` or `_neq` operators will not return rows with `null` values. - -To also return rows with `null` values, the `_is_null` operator needs to be used along with these joined by the `_or` -operator. - -For example, to fetch a list of articles where the `is_published` column is either `false` or `null`: - -#### Request - -```graphql -query { - articles ( - where: { - _or: [ - {is_published: {_eq: false}}, - {is_published: {_is_null: true}} - ] - } - ) - { - id - title - is_published - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "Robben Island", - "is_published": false - }, - { - "id": 2, - "title": "The Life of Matthias", - "is_published": false - }, - { - "id": 3, - "title": "All about Hasura", - "is_published": null - } - ] - } -} -``` - -## Greater than or less than operators (_gt, _lt, _gte, _lte) - -The `_gt` (greater than), `_lt` (less than), `_gte` (greater than or equal to), `_lte` (less than or equal to) operators -are compatible with any PostgreSQL type other than `json` or `jsonB` (like `Integer`, `Float`, `Double`, `Text`, -`Boolean`, `Date`/`Time`/`Timestamp`, etc.). - -[//]: # ([//]: # "For more details on greater than or less than operators and PostgreSQL equivalents, refer to the") - -[//]: # ([//]: # "[API reference](/api-reference/graphql-api/query.mdx#generic-operators).") - -The following are examples of using these operators on different types: - -**Example: Integer (works with Double, Float, Numeric, etc.)** - -This query retrieves all users whose age is less than 30. The `_lt` operator is a comparison operator that means "less -than". It is used to filter records based on a specified value. - -#### Request - -```graphql -query { - users(where: { age: { _lt: 30 }}) { - id - name - age - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "id": 1, - "name": "John", - "age": 25 - }, - { - "id": 2, - "name": "Jane", - "age": 28 - } - ] - } -} -``` - -**Example: String or Text** - -Fetch a list of authors whose names begin with M or any letter that follows M _(essentially, a filter based on a -dictionary sort)_: - -#### Request - -```graphql -query { - authors( - where: {name: {_gt: "M"}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 3, - "name": "Sidney" - }, - { - "id": 9, - "name": "Ninnetta" - } - ] - } -} -``` - -**Example: Integer (works with Double, Float, etc.)** - -Fetch a list of all products with a price less than or equal to 10. - -#### Request - -```graphql -query { - products(where: { price: { _lte: 10 } }) { - name - price - } -} -``` - -#### Response - -```JSON -{ - "data": { - "products": [ - { - "name": "Bread", - "price": 2.5 - }, - { - "name": "Milk", - "price": 3.5 - }, - { - "name": "Eggs", - "price": 4.5 - } - ] - } -} -``` - -**Example: Integer (works with Double, Float, etc.)** - -Fetch a list of articles rated 4 or more (`rating` is an integer field): - -#### Request - -```graphql -query { - articles( - where: {rating: {_gte: 4}} - ) { - id - title - rating - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 3, - "title": "amet justo morbi", - "rating": 4 - }, - { - "id": 7, - "title": "nisl duis ac", - "rating": 4 - }, - { - "id": 17, - "title": "montes nascetur ridiculus", - "rating": 5 - } - ] - } -} -``` - -**Example: Date (works with Time, Timezone, etc.)** - -Fetch a list of articles that were published on or after date "01/01/2018": - -#### Request - -```graphql -query { - articles( - where: {published_on: {_gte: "2018-01-01"}} - ) { - id - title - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 2, - "title": "a nibh", - "published_on": "2018-06-10" - }, - { - "id": 6, - "title": "sapien ut", - "published_on": "2018-01-08" - }, - { - "id": 13, - "title": "vulputate elementum", - "published_on": "2018-03-10" - }, - { - "id": 15, - "title": "vel dapibus at", - "published_on": "2018-01-02" - } - ] - } -} -``` - -## List based search operators (_in, _nin) - -The `_in` (in a list) operator is used to compare field values to a list of values. They are -compatible with any PostgreSQL type other than `json` or `jsonB` (like `Integer`, `Float`, `Double`, `Text`, `Boolean`, -`Date`/`Time`/`Timestamp`, etc.). - -The following are examples of using these operators on different types: - -**Example: Integer (works with Double, Float, etc.)** - -Fetch a list of articles rated 1, 3 or 5: - -#### Request - -```graphql -query { - articles( - where: {rating: {_in: [1,3,5]}} - ) { - id - title - rating - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet", - "rating": 1 - }, - { - "id": 2, - "title": "a nibh", - "rating": 3 - }, - { - "id": 6, - "title": "sapien ut", - "rating": 1 - }, - { - "id": 17, - "title": "montes nascetur ridiculus", - "rating": 5 - } - ] - } -} -``` - -**Example: String or Text** - -Using an additional `_not` to fetch a list of those authors whose names are NOT part of a list: - -#### Request - -```graphql -query { - authors( - where: {name: {_not: {_in: ["Justin","Sidney","April"]}}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 2, - "name": "Beltran" - }, - { - "id": 4, - "name": "Anjela" - }, - { - "id": 5, - "name": "Amii" - }, - { - "id": 6, - "name": "Corny" - } - ] - } -} -``` - -## Filter or check for null values (_is_null) - -Checking for null values can be achieved using the `_is_null` operator. - -**Example: Filter null values in a field** - -Fetch a list of articles that have a value in the `published_on` field: - -#### Request - -```graphql -query { - articles( - where: {published_on: {_is_null: false}} - ) { - id - title - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet", - "published_on": "2017-08-09" - }, - { - "id": 2, - "title": "a nibh", - "published_on": "2018-06-10" - }, - { - "id": 3, - "title": "amet justo morbi", - "published_on": "2017-05-26" - }, - { - "id": 4, - "title": "vestibulum ac est", - "published_on": "2017-03-05" - } - ] - } -} -``` diff --git a/docs/usage/queries/filters/index.md b/docs/usage/queries/filters/index.md deleted file mode 100644 index d90e652d6..000000000 --- a/docs/usage/queries/filters/index.md +++ /dev/null @@ -1,70 +0,0 @@ -# PostgreSQL: Filter Query Results / Search Queries - -## Introduction - -Hasura provides a powerful yet simple syntax to filter query results on PostgreSQL. This is useful for building search -queries or filtering data based on some criteria. You can utilize arguments and operators to filter results based on -equality, comparison, pattern matching, etc. - -## The **where** argument - -You can use the `where` argument in your queries to filter results based on some field’s values (even nested objects' -fields). You can even use multiple filters in the same `where` clause using the `_and` or the `_or` operators. - -For example, to fetch data for an author whose name is "Sidney": - -```graphql {3} -query { - authors(where: { name: { _eq: "Sidney" } }) { - id - name - } -} -``` - -You can also use nested objects' fields to filter rows from a table and also filter the nested objects as well. - -For example, to fetch a list of authors who have articles with a rating greater than 4 along with those articles: - -```graphql {2,5} -query { - authors(where: { articles: { rating: { _gt: 4 } } }) { - id - name - articles(where: { rating: { _gt: 4 } }) { - id - title - rating - } - } -} -``` - -Here `_eq` and `_gt` are examples of comparison operators that can be used in the `where` argument to filter on -equality. - -## Other Filters: - -- [Boolean Operators](./boolean-operators.md) -- [Comparison Operators](./comparison-operators.md) -- [Nested Objects](./nested-objects.md) -- [Text Search Operators](./text-search-operators.md) - -[//]: # ([//]: # "You can see the complete specification of the `where` argument in the") - -[//]: # ([//]: # "[API reference](/api-reference/graphql-api/query.mdx#whereexp).") - -[//]: # (## Supported operators) - -[//]: # () -[//]: # (| Operator | Use case |) - -[//]: # (| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |) - -[//]: # (| [Simple Comparison Operators](/graphql-api/postgresql-queries/filters/comparison-operators.mdx) | Utilize comparison operators to selectively filter results by evaluating a field against a specific value. |) - -[//]: # (| [Boolean Operators](/graphql-api/postgresql-queries/filters/boolean-operators.mdx) | Employ boolean operators to refine result filters based on logical expressions. |) - -[//]: # (| [Text Search Operators](/graphql-api/postgresql-queries/filters/text-search-operators.mdx) | Apply text search operators to narrow down results according to the presence of text in a field. |) - -[//]: # (| [Nested Objects](/graphql-api/postgresql-queries/filters/nested-objects.mdx) | Navigate and filter results using nested object structures for advanced filtering. |) diff --git a/docs/usage/queries/filters/nested-objects.md b/docs/usage/queries/filters/nested-objects.md deleted file mode 100644 index 31e0b9c93..000000000 --- a/docs/usage/queries/filters/nested-objects.md +++ /dev/null @@ -1,211 +0,0 @@ -# PostgreSQL: Filter Based on Fields of Nested Objects - -## Introduction - -You can use the fields of nested objects as well to filter your query results. - -For example: - -```graphql {2} -query { - articles(where: { author: { name: { _eq: "Sidney" } } }) { - id - title - } -} -``` - -The behavior of the comparison operators depends on whether the nested objects are a single object related via an object -relationship or an array of objects related via an array relationship. - -- In case of an **object relationship**, a row will be returned if the single nested object satisfies the defined - condition. -- In case of an **array relationship**, a row will be returned if **any of the nested objects** satisfy the defined - condition. - -Let's look at a few use cases based on the above: - -## Fetch if the single nested object defined via an object relationship satisfies a condition - -**Example:** - -Fetch all articles whose author's name starts with "A": - -#### Request - -```graphql -{ - articles ( - where: { - author: { - name: { _similar: "A%"} - } - } - ) { - id - title - author { - name - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet", - "author": { - "name": "Anjela" - } - }, - { - "id": 3, - "title": "amet justo morbi", - "author": { - "name": "Anjela" - } - }, - { - "id": 4, - "title": "vestibulum ac est", - "author": { - "name": "Amii" - } - }, - { - "id": 12, - "title": "volutpat quam pede", - "author": { - "name": "Amii" - } - }, - { - "id": 13, - "title": "vulputate elementum", - "author": { - "name": "April" - } - } - ] - } -} -``` - -## Fetch if nested object(s) exist/do not exist - -You can filter results based on if they have nested objects by checking if any nested objects exist. This can be -achieved by using the expression `{}` which evaluates to `true` if any object exists. - -**Example where nested object(s) exist:** - -Fetch all authors which have at least one article written by them: - -#### Request - -```graphql -{ - authors ( - where: { - articles: {} - } - ) { - id - name - articles_aggregate { - aggregate { - count - } - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin", - "articles_aggregate": { - "aggregate": { - "count": 2 - } - } - }, - { - "id": 4, - "name": "Anjela", - "articles_aggregate": { - "aggregate": { - "count": 1 - } - } - } - ] - } -} -``` - -**Example where nested object(s) do not exist:** - -Fetch all authors which have not written any articles: - -#### Request - -```graphql -{ - authors ( - where: { - _not: { - articles: {} - } - } - ) { - id - name - articles_aggregate { - aggregate { - count - } - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 2, - "name": "Beltran", - "articles_aggregate": { - "aggregate": { - "count": 0 - } - } - }, - { - "id": 3, - "name": "Sidney", - "articles_aggregate": { - "aggregate": { - "count": 0 - } - } - } - ] - } -} -``` diff --git a/docs/usage/queries/filters/text-search-operators.md b/docs/usage/queries/filters/text-search-operators.md deleted file mode 100644 index 5789e8c56..000000000 --- a/docs/usage/queries/filters/text-search-operators.md +++ /dev/null @@ -1,313 +0,0 @@ -# PostgreSQL: Filter by Text - -## Introduction - -The `_like`, `_nlike`, `_ilike`, `_nilike`, `_similar`, `_nsimilar`, `_regex`, `_nregex`, `_iregex`, `_niregex` -operators are used for pattern matching on string/text fields. - -[//]: # ([//]: # "For more details on text search operators and PostgreSQL equivalents, refer to the") - -[//]: # ([//]: # "[API reference](/api-reference/graphql-api/query.mdx#text-operators).") - -## _like - -Fetch a list of articles whose titles contain the word “amet”: - -#### Request - -```graphql -query { - articles( - where: {title: {_like: "%amet%"}} - ) { - id - title - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet" - }, - { - "id": 3, - "title": "amet justo morbi" - }, - { - "id": 9, - "title": "sit amet" - } - ] - } -} -``` - -## _ilike - -This query will return all users whose name contains the string "john", regardless of case. - -#### Request - -```graphql -query { - users(where: { name: { _ilike: "%john%" } }) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "id": 1, - "name": "John Doe" - }, - { - "id": 2, - "name": "John Smith" - } - ] - } -``` - -## _nilike - -This query would return all users whose name does not contain the string "John". - -#### Request - -```graphql -query { - users(where: { name: { _nilike: "%John%" } }) { - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "name": "Jane Doe" - }, - { - "name": "Jane Smith" - } - ] - } -``` - -> :information_source: `_like` is case-sensitive. Use `_ilike` for case-insensitive search. - -## _similar - -Fetch a list of authors whose names begin with A or C: - -#### Request - -```graphql -query { - authors( - where: {name: {_similar: "(A|C)%"}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 4, - "name": "Anjela" - }, - { - "id": 5, - "name": "Amii" - }, - { - "id": 6, - "name": "Corny" - }, - { - "id": 8, - "name": "April" - } - ] - } -} -``` - -## _nsimilar - -Fetch a list of authors whose names do not begin with A or C: - -#### Request - -```graphql -query { - authors( - where: {name: {_nsimilar: "(A|C)%"}} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin" - }, - { - "id": 2, - "name": "Beltran" - }, - { - "id": 3, - "name": "Sidney" - }, - { - "id": 7, - "name": "Dorothy" - } - ] - } -``` - -> :information_source: `_similar` and `_nsimilar` are case-sensitive. - -## _regex - -Fetch a list of articles whose titles match the regex `[ae]met`: - -#### Request - -```graphql -query { - articles( - where: {title: {_regex: "[ae]met"}} - ) { - id - title - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet" - }, - { - "id": 3, - "title": "cremet justo morbi" - }, - { - "id": 9, - "title": "sit ametist" - } - ] - } -} -``` - -## _iregex - -This query will return all users whose name matches the regular expression `/^joh?n$/i`, which matches "John" and "Jon". - -#### Request - -```graphql -query { - users(where: { name: { _iregex: "/^joh?n$/i" } }) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "id": 1, - "name": "John Doe" - }, - { - "id": 2, - "name": "Jon Smith" - } - ] - } -``` - -## _nregex - -The _nregex operator in this GraphQL query is a negated regular expression filter that matches all users whose names do -not start with the letter "J". - -#### Request - -```graphql -query { - users(where: { name: { _nregex: "/^J/" } }) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "users": [ - { - "id": 3, - "name": "Tom Smith" - }, - { - "id": 4, - "name": "Alan Doe" - } - ] - } -``` - -> :information_source: `_regex` is case-sensitive. Use `_iregex` for case-insensitive search. diff --git a/docs/usage/queries/index.md b/docs/usage/queries/index.md deleted file mode 100644 index 714a7ef7e..000000000 --- a/docs/usage/queries/index.md +++ /dev/null @@ -1,28 +0,0 @@ -# PostgreSQL GraphQL Queries - -PostgreSQL is a powerful relational database system that has been around for over 30 years. It is the database of choice -for many developers and companies around the world. - -Hasura has a special relationship with this database and provides the official Hasura PostgreSQL data connector to -interact with it. - -Currently in Hasura we support only queries, with mutations and subscriptions coming soon. You can read more about how -to use queries with PostgreSQL and the official data connector in the following sections. - -Documentation for other data connectors can be found on the [Connector Hub](https://hasura.io/connector) and in the -repo of each specific connector itself. - -The pages below detail how to use queries for PostgreSQL with the default generated GraphQL API fields and values: - -- [Simple Queries](./simple-queries.md) -- [Nested Queries](./nested-queries.md) -- [Multiple Arguments](./multiple-arguments.md) -- [Multiple Queries](./multiple-queries.md) -- [Pagination](./pagination.md) -- [Sorting](./sorting.md) -- [Variables, Aliases, Fragments & Directives](./variables-aliases-fragments-directives.md) -- [Filters](./filters/index.md) - - [Boolean Operators](./filters/boolean-operators.md) - - [Comparison Operators](./filters/comparison-operators.md) - - [Nested Objects](./filters/nested-objects.md) - - [Text Search Operators](./filters/text-search-operators.md) diff --git a/docs/usage/queries/multiple-arguments.md b/docs/usage/queries/multiple-arguments.md deleted file mode 100644 index 8bf22c03f..000000000 --- a/docs/usage/queries/multiple-arguments.md +++ /dev/null @@ -1,112 +0,0 @@ -# Use Multiple Arguments in a Query - -Multiple arguments can be used together in the same query. - -For example, you can use the `where` argument to filter the results and then use the `order_by` argument to sort them. - -**For example**, fetch a list of authors and only 2 of their published articles that are sorted by their date of -publication: - -#### Request - -```graphql -query { - authors { - id - name - articles( - where: {is_published: {_eq: true}}, - order_by: {published_on: desc}, - limit: 2 - ) { - id - title - is_published - published_on - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin", - "articles": [ - { - "is_published": true, - "id": 16, - "title": "sem duis aliquam", - "published_on": "2018-02-14" - }, - { - "is_published": true, - "id": 15, - "title": "vel dapibus at", - "published_on": "2018-01-02" - } - ] - }, - { - "id": 2, - "name": "Beltran", - "articles": [ - { - "is_published": true, - "id": 2, - "title": "a nibh", - "published_on": "2018-06-10" - }, - { - "is_published": true, - "id": 9, - "title": "sit amet", - "published_on": "2017-05-16" - } - ] - }, - { - "id": 3, - "name": "Sidney", - "articles": [ - { - "is_published": true, - "id": 6, - "title": "sapien ut", - "published_on": "2018-01-08" - }, - { - "is_published": true, - "id": 11, - "title": "turpis eget", - "published_on": "2017-04-14" - } - ] - }, - { - "id": 4, - "name": "Anjela", - "articles": [ - { - "is_published": true, - "id": 1, - "title": "sit amet", - "published_on": "2017-08-09" - }, - { - "is_published": true, - "id": 3, - "title": "amet justo morbi", - "published_on": "2017-05-26" - } - ] - } - ] - } -} -``` diff --git a/docs/usage/queries/multiple-queries.md b/docs/usage/queries/multiple-queries.md deleted file mode 100644 index cc8da1aec..000000000 --- a/docs/usage/queries/multiple-queries.md +++ /dev/null @@ -1,134 +0,0 @@ -# Multiple Queries in a Request - -## Execution - -You can fetch objects of different unrelated types in the same query. - -## Run multiple top level queries in the same request - -**For example**, fetch a list of `authors` and a list of `articles`: - -#### Request - -```graphql -query { - authors(limit: 2) { - id - name - } - articles(limit: 2) { - id - title - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin" - }, - { - "id": 2, - "name": "Beltran" - } - ], - "articles": [ - { - "id": 1, - "title": "sit amet" - }, - { - "id": 2, - "title": "a nibh" - } - ] - } -} -``` - -## Fetch limited results along with data aggregated over all results _(e.g. total count)_ in the same query - -Sometimes, some aggregated information on all the data is required along with a subset of data. - -E.g. the total count of results can be returned along with a page of results. The count can then be used to calculate -the number of pages based on the limit that is set. - -**Example:** Fetch a list of articles where a certain condition is true and get their count. Then limit the number of -articles to return. - -#### Request - -```graphql -query articles ($where: articles_bool_exp!) { - articles_aggregate(where: $where) { - aggregate { - totalCount: count - } - } - articles (where: $where limit: 4) { - id - title - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles_aggregate": { - "aggregate": { - "totalCount": 8 - } - }, - "articles": [ - { - "id": 33, - "title": "How to make fajitas" - }, - { - "id": 31, - "title": "How to make fajitas" - }, - { - "id": 32, - "title": "How to make fajitas" - }, - { - "id": 2, - "title": "How to climb mount everest" - } - ] - } -} -``` - -[//]: # ([//]: # ":::info Caveat") - -[//]: # ([//]: #) - -[//]: # ([//]:) - -[//]: # ( #) - -[//]: # ( "If this needs to be done over [subscriptions](/subscriptions/postgres/index.mdx), two subscriptions will need to be run") - -[//]: # ([//]:) - -[//]: # ( #) - -[//]: # ( "as Hasura follows the [GraphQL spec](https://graphql.github.io/graphql-spec/June2018/#sec-Single-root-field) which") - -[//]: # ([//]: # "allows for only one root field in a subscription.") - -[//]: # ([//]: #) - -[//]: # ([//]: # ":::") - diff --git a/docs/usage/queries/nested-queries.md b/docs/usage/queries/nested-queries.md deleted file mode 100644 index ae59dd336..000000000 --- a/docs/usage/queries/nested-queries.md +++ /dev/null @@ -1,136 +0,0 @@ -# PostgreSQL Nested Object Queries - -## Introduction - -You can use the object (one-to-one) or array (one-to-many) relationships defined in your metadata to make a nested -queries, i.e. fetch data for one type along with data from a nested or related type. - -## Fetch nested object using an object relationship - -The following is an example of a nested object query using the **object relationship** between an article and an author. - -**Example:** Fetch a list of articles and the name of each article’s author: - -#### Request - -```graphql -query { - articles { - id - title - author { - name - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 1, - "title": "sit amet", - "author": { - "name": "Anjela" - } - }, - { - "id": 2, - "title": "a nibh", - "author": { - "name": "Beltran" - } - }, - { - "id": 3, - "title": "amet justo morbi", - "author": { - "name": "Anjela" - } - } - ] - } -} -``` - -## Fetch nested objects using an array relationship - -The following is an example of a nested object query using the **array relationship** between an author and articles. - -**Example:** Fetch a list of authors and a related, nested list of each author’s articles: - -#### Request - -```graphql -query { - authors { - id - name - articles { - id - title - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin", - "articles": [ - { - "id": 15, - "title": "vel dapibus at" - }, - { - "id": 16, - "title": "sem duis aliquam" - } - ] - }, - { - "id": 2, - "name": "Beltran", - "articles": [ - { - "id": 2, - "title": "a nibh" - }, - { - "id": 9, - "title": "sit amet" - } - ] - }, - { - "id": 3, - "name": "Sidney", - "articles": [ - { - "id": 6, - "title": "sapien ut" - }, - { - "id": 11, - "title": "turpis eget" - }, - { - "id": 14, - "title": "congue etiam justo" - } - ] - } - ] - } -} -``` diff --git a/docs/usage/queries/pagination.md b/docs/usage/queries/pagination.md deleted file mode 100644 index 7c81b0194..000000000 --- a/docs/usage/queries/pagination.md +++ /dev/null @@ -1,273 +0,0 @@ -# PostgreSQL: Paginate Query Results - -## The **limit** & **offset** arguments - -The operators `limit` and `offset` are used for pagination. - -`limit` specifies the number of rows to retain from the result set and `offset` determines which slice to retain from -the results. - -[//]: # ([//]: # "You can see the complete specification of the `limit` and `offset` arguments in the") - -[//]: # ([//]: # "[API reference](/api-reference/graphql-api/query.mdx#paginationexp).") - -The following are examples of different pagination scenarios: - -## Limit results - -**Example:** Fetch the first 5 authors from the list of all authors: - -#### Request - -```graphql -query { - authors( - limit: 5 - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin" - }, - { - "id": 2, - "name": "Beltran" - }, - { - "id": 3, - "name": "Sidney" - }, - { - "id": 4, - "name": "Anjela" - }, - { - "id": 5, - "name": "Amii" - } - ] - } -} -``` - -## Limit results from an offset - -**Example:** Fetch 5 authors from the list of all authors, starting with the 6th one: - -#### Request - -```graphql -query { - authors( - limit: 5, - offset:5 - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 6, - "name": "Corny" - }, - { - "id": 7, - "name": "Berti" - }, - { - "id": 8, - "name": "April" - }, - { - "id": 9, - "name": "Ninnetta" - }, - { - "id": 10, - "name": "Lyndsay" - } - ] - } -} -``` - -## Limit results in a nested object - -**Example:** Fetch a list of authors and a list of their first 2 articles: - -#### Request - -```graphql -query { - authors { - id - name - articles ( - limit: 2 - offset: 0 - ) { - id - title - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin", - "articles": [ - { - "id": 15, - "title": "vel dapibus at" - }, - { - "id": 16, - "title": "sem duis aliquam" - } - ] - }, - { - "id": 2, - "name": "Beltran", - "articles": [ - { - "id": 2, - "title": "a nibh" - }, - { - "id": 9, - "title": "sit amet" - } - ] - }, - { - "id": 3, - "name": "Sidney", - "articles": [ - { - "id": 6, - "title": "sapien ut" - }, - { - "id": 11, - "title": "turpis eget" - } - ] - }, - { - "id": 4, - "name": "Anjela", - "articles": [ - { - "id": 1, - "title": "sit amet" - }, - { - "id": 3, - "title": "amet justo morbi" - } - ] - } - ] - } -} -``` - -## Keyset cursor based pagination - -Cursors are used to traverse across rows of a dataset. They work by returning a pointer to a specific row which can then -be used to fetch the next batch of data. - -Keyset cursors are a column (or a set of columns) of the data that are used as the cursor. The column(s) used as the -cursor must be unique and sequential. This ensures that data is read after a specific row rather than relying on the -position of the row in the dataset as done by `offset`, and that duplicate records are not fetched again. - -**For example**, consider the following query to fetch a list of authors with a `where` clause used in place of -`offset`: - -#### Request - -```graphql -query { - authors( - limit: 5, - where: { id: {_gt: 5} } - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 6, - "name": "Corny" - }, - { - "id": 7, - "name": "Berti" - }, - { - "id": 8, - "name": "April" - }, - { - "id": 9, - "name": "Ninnetta" - }, - { - "id": 10, - "name": "Lyndsay" - } - ] - } -} -``` - -> :information_source: Because we ran the above example without an `order_by` clause, it is accidental that we -> received those results. Running a query without an `order_by` clause will return results in an arbitrary order. - -Here we are fetching authors where the value of `id` is greater than 5. This will always skip the previously fetched -results which would have been ids 1 to 5, ensuring no duplicate results. Column `id` is acting as the cursor here, -unique and sequential. - -The choice of cursor columns depends on the order of the expected results i.e. if the query has an `order_by` clause, -the column(s) used in the `order_by` need to be used as the cursor. - -Columns such as `id` (auto-incrementing integer/big integer) or `created_at` (timestamp) are commonly used as cursors -when an order is not explicit, as they should be unique and sequential. - -> :information_source: Keyset cursor based pagination using `where` is more performant than using `offset` because we -> can leverage database indexes on the columns that are being used as cursors. diff --git a/docs/usage/queries/simple-queries.md b/docs/usage/queries/simple-queries.md deleted file mode 100644 index f21461d30..000000000 --- a/docs/usage/queries/simple-queries.md +++ /dev/null @@ -1,217 +0,0 @@ -# PostgreSQL Simple Object Queries - -## Introduction - -You can fetch a single node or multiple nodes of the same type using a simple object query. - -## Fetch a list of objects - -**Example:** Fetch a list of authors: - -#### Request: -```graphql -query { - authors { - id - name - } -} -``` - -#### Response: -```JSON -{ - "data": { - "authors": [ - { - "id": 1, - "name": "Justin" - }, - { - "id": 2, - "name": "Beltran" - }, - { - "id": 3, - "name": "Sidney" - }, - { - "id": 4, - "name": "Anjela" - } - ] - } -} -``` - - - -## Fetch an object using its primary key - -**Example:** Fetch an author using their primary key: - -#### Request - -```graphql -query { - authors_by_pk(id: 1) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors_by_pk": { - "id": 1, - "name": "Justin" - } - } -} -``` - -## Fetch list of objects with pagination - -**Example:** Fetch 2 articles after removing the 1st article from the result set. - -#### Request - -```graphql -query { - ArticleMany(limit: 2, offset: 1) { - title - article_id - } -} -``` - -#### Response - -```JSON -{ - "data": { - "ArticleMany": [ - { - "article_id": 2, - "title": "Why Functional Programming Matters" - }, - { - "article_id": 3, - "title": "The Design And Implementation Of Programming Languages" - } - ] - } -} -``` - -> :warning: Without an `order_by` in `limit` queries, the results may be unpredictable. - -## Fetch list of objects with filtering - -**Example:** Fetch a list of articles whose title contains the word "The": - -#### Request - -```graphql -query { - ArticleMany(where: {title: {_like: "The"}}) { - title - article_id - } -} -``` - -#### Response - -```JSON -{ - "data": { - "ArticleMany": [ - { - "article_id": 1, - "title": "The Next 700 Programming Languages" - }, - { - "article_id": 3, - "title": "The Design And Implementation Of Programming Languages" - } - ] - } -} -``` - -## Fetch list of objects with sorting - -**Example:** Fetch a list of articles with `article_id` in descending order: - -#### Request - -```graphql -query { - ArticleMany(order_by: {article_id: Desc}) { - title - article_id - } -} -``` - -#### Response - -```JSON -{ - "data": { - "ArticleMany": [ - { - "article_id": 3, - "title": "The Design And Implementation Of Programming Languages" - }, - { - "article_id": 2, - "title": "Why Functional Programming Matters" - }, - { - "article_id": 1, - "title": "The Next 700 Programming Languages" - } - ] - } -} -``` - -## Fetch objects using model arguments - -> :information_source: Fetching objects using model arguments is only supported for native queries. - -**Example:** Fetch the articles for the given `author_id`: - -#### Request - -```graphql -query { - ArticlesByAuthorMany(args: {author_id: 2}) { - article_id - title - } -} -``` - -#### Response - -```JSON -{ - "data": [ - { - "article_id": 2, - "title": "Why Functional Programming Matters" - }, - { - "article_id": 3, - "title": "The Design And Implementation Of Programming Languages" - } - ] -} -``` diff --git a/docs/usage/queries/sorting.md b/docs/usage/queries/sorting.md deleted file mode 100644 index ef31b4a6c..000000000 --- a/docs/usage/queries/sorting.md +++ /dev/null @@ -1,443 +0,0 @@ -# PostgreSQL: Sort Query Results - -## The **order_by** argument - -Results from your query can be sorted by using the `order_by` argument. The argument can be used to sort nested objects -too. - -The sort order (ascending vs. descending) is set by specifying the `Asc` or `Desc` enum value for the column name in the -`order_by` input object, e.g. `{name: Desc}`. - -By default, for ascending ordering `null` values are returned at the end of the results and for descending ordering -`null` values are returned at the start of the results. - -The `order_by` argument takes an array of objects to allow sorting by multiple columns. - -You can also use nested objects' fields to sort the results. Only columns from object relationships** and **aggregates -from array relationships** can be used for sorting. - -The following are example queries for different sorting use cases: - -## Sorting objects - -**Example:** Fetch a list of authors sorted by their names in an ascending order: - -#### Request - -```graphql -query { - authors ( - order_by: {name: Asc} - ) { - id - name - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 5, - "name": "Amii" - }, - { - "id": 4, - "name": "Anjela" - }, - { - "id": 8, - "name": "April" - }, - { - "id": 2, - "name": "Beltran" - }, - { - "id": 7, - "name": "Berti" - }, - { - "id": 6, - "name": "Corny" - } - ] - } -} -``` - -## Sorting nested objects - -**Example:** Fetch a list of authors sorted by their names with a list of their articles that is sorted by their rating: - -#### Request - -```graphql -query { - authors (order_by: {name: Asc}) { - id - name - articles(order_by: {rating: Desc}) { - id - title - rating - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 5, - "name": "Amii", - "articles": [ - { - "rating": 5, - "id": 17, - "title": "montes nascetur ridiculus" - }, - { - "rating": 3, - "id": 12, - "title": "volutpat quam pede" - }, - { - "rating": 2, - "id": 4, - "title": "vestibulum ac est" - } - ] - }, - { - "id": 4, - "name": "Anjela", - "articles": [ - { - "rating": 4, - "id": 3, - "title": "amet justo morbi" - }, - { - "rating": 1, - "id": 1, - "title": "sit amet" - } - ] - }, - { - "id": 8, - "name": "April", - "articles": [ - { - "rating": 4, - "id": 13, - "title": "vulputate elementum" - }, - { - "rating": 2, - "id": 20, - "title": "eu nibh" - } - ] - } - ] - } -} -``` - -## Sorting based on nested object's fields - -Only **columns from object relationships** and **aggregates from array relationships** can be used for sorting. - -### For object relationships - -For object relationships only columns can be used for sorting. - -**Example:** Fetch a list of articles that are sorted by their author's ids in descending order: - -#### Request - -```graphql -query { - articles ( - order_by: {author: {id: Desc}} - ) { - id - rating - published_on - author { - id - name - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 3, - "title": "Article 3", - "content": "Sample article content 3", - "author": { - "id": 2, - "name": "Author 2" - } - }, - { - "id": 1, - "title": "Article 1", - "content": "Sample article content 1", - "author": { - "id": 1, - "name": "Author 1" - } - }, - { - "id": 2, - "title": "Article 2", - "content": "Sample article content 2", - "author": { - "id": 1, - "name": "Author 1" - } - } - ] - } -} -``` - -### For array relationships - -For array relationships only aggregates can be used for sorting. - -**Example:** Fetch a list of authors sorted in descending order of their article count: - -#### Request - -```graphql -query { - authors ( - order_by: { - articles_aggregate: {count: Desc} - } - ) { - id - name - articles_aggregate { - aggregate{ - count - } - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 5, - "name": "Amii", - "articles_aggregate":{ - "aggregate": { - "count": 3 - } - } - }, - { - "id": 4, - "name": "Anjela", - "articles_aggregate":{ - "aggregate": { - "count": 2 - } - } - }, - { - "id": 8, - "name": "April", - "articles_aggregate":{ - "aggregate": { - "count": 2 - } - } - } - ] - } -} -``` - -**Example:** Fetch a list of authors sorted in increasing order of their highest article rating: - -#### Request - -```graphql -query { - authors( - order_by: { - articles_aggregate: { - max: {rating: Asc} - } - } - ) { - id - name - articles_aggregate { - aggregate{ - max {rating} - } - } - } -} -``` - -#### Response - -```JSON -{ - "data": { - "authors": [ - { - "id": 7, - "name": "Berti", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": 2 - } - } - } - }, - { - "id": 2, - "name": "Beltran", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": 3 - } - } - } - }, - { - "id": 8, - "name": "April", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": 4 - } - } - } - }, - { - "id": 3, - "name": "Sidney", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": 4 - } - } - } - }, - { - "id": 5, - "name": "Amii", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": 5 - } - } - } - }, - { - "id": 9, - "name": "Ninnetta", - "articles_aggregate": { - "aggregate": { - "max": { - "rating": null - } - } - } - } - ] - } -} -``` - -## Sorting by multiple fields - -**Example:** Fetch a list of articles that is sorted by their rating (descending) and then on their published date -(ascending): - -#### Request - -```graphql -query { - articles ( - order_by: [ - {rating: Desc}, - {published_on: Asc} - ] - ) { - id - rating - published_on - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 17, - "rating": 5, - "published_on": null - }, - { - "id": 7, - "rating": 4, - "published_on": "2016-07-09" - }, - { - "id": 14, - "rating": 4, - "published_on": null - }, - { - "id": 3, - "rating": 4, - "published_on": "2017-05-26" - } - ] - } -} -``` - -> :warning: Key order in input object for order_by is not preserved. This means you should only have a single -> key per object, or you may see unexpected behavior. - diff --git a/docs/usage/queries/variables-aliases-fragments-directives.md b/docs/usage/queries/variables-aliases-fragments-directives.md deleted file mode 100644 index b47b72892..000000000 --- a/docs/usage/queries/variables-aliases-fragments-directives.md +++ /dev/null @@ -1,320 +0,0 @@ -# Use Variables / Aliases / Fragments / Directives in Queries - -## Using variables - -In order to make a query re-usable, it can be made dynamic by using variables. - -**Example:** Fetch an author by their `author_id`: - -#### Request - -```graphql -query getArticles($author_id: Int!) { - articles( - where: { author_id: { _eq: $author_id } } - ) { - id - title - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 15, - "title": "How to climb Mount Everest" - }, - { - "id": 6, - "title": "How to be successful on broadway" - } - ] - } -} -``` - -## Using aliases - -Aliases can be used to return objects with a different name than their field name. This is especially useful while -fetching the same type of objects with different arguments in the same query. - -**Example:** First, fetch all articles. Second, fetch the two top-rated articles. Third, fetch the worst-rated article: - -#### Request - -```graphql -query getArticles { - articles { - title - rating - } - topTwoArticles: articles( - order_by: {rating: desc}, - limit: 2 - ) { - title - rating - } - worstArticle: articles( - order_by: {rating: asc}, - limit: 1 - ) { - title - rating - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "title": "How to climb Mount Everest", - "rating": 4 - }, - { - "title": "How to be successful on broadway", - "rating": 20 - }, - { - "title": "How to make fajitas", - "rating": 6 - } - ], - "topTwoArticles": [ - { - "title": "How to be successful on broadway", - "rating": 20 - }, - { - "title": "How to make fajitas", - "rating": 6 - } - ], - "worstArticle": [ - { - "title": "How to climb Mount Everest", - "rating": 4 - } - ] - } -} -``` - -## Using fragments - -Sometimes, queries can get long and confusing. A fragment is a set of fields with any chosen name. This fragment can -then be used to represent the defined set. - -**Example:** Creating a fragment for a set of `article` fields (`id` and `title`) and using it in a query: - -#### Request - -```graphql -fragment articleFields on articles { - id - title -} -query getArticles { - articles { - ...articleFields - } - topTwoArticles: articles( - order_by: {rating: desc}, - limit: 2 - ) { - ...articleFields - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "id": 3, - "title": "How to make fajitas" - }, - { - "id": 15, - "title": "How to climb Mount Everest" - }, - { - "id": 6, - "title": "How to be successful on broadway" - } - ], - "topTwoArticles": [ - { - "id": 6, - "title": "How to be successful on broadway" - }, - { - "id": 3, - "title": "How to make fajitas" - } - ] - } -} -``` - -## Using directives - -Directives make it possible to include or skip a field based on a boolean expression passed as a query variable. - -### @include(if: Boolean) - -With `@include(if: Boolean)`, it is possible to include a field in the query result based on a Boolean expression. - -**Example:** The query result includes the field `publisher`, as `$with_publisher` is set to `true`: - -#### Request - -```graphql -query getArticles($with_publisher: Boolean!) { - articles { - title - publisher @include(if: $with_publisher) - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "title": "How to climb Mount Everest", - "publisher": "Mountain World" - }, - { - "title": "How to be successful on broadway", - "publisher": "Broadway World" - }, - { - "title": "How to make fajitas", - "publisher": "Fajita World" - } - ] - } -} -``` - -**Example:** The query result doesn't include the field `publisher`, as `$with_publisher` is set to `false`: - -#### Request - -```graphql -query getArticles($with_publisher: Boolean!) { - articles { - title - publisher @include(if: $with_publisher) - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "title": "How to climb Mount Everest" - }, - { - "title": "How to be successful on broadway" - }, - { - "title": "How to make fajitas" - } - ] - } -} -``` - -### @skip(if: Boolean) - -With `@skip(if: Boolean)`, it is possible to exclude (skip) a field in the query result based on a Boolean expression. - -**Example:** The query result doesn't include the field `publisher`, as `$with_publisher` is set to `true`: - -#### Request - -```graphql -query getArticles($with_publisher: Boolean!) { - articles { - title - publisher @skip(if: $with_publisher) - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "title": "How to climb Mount Everest" - }, - { - "title": "How to be successful on broadway" - }, - { - "title": "How to make fajitas" - } - ] - } -} -``` - -**Example:** The query result includes the field `publisher`, as `$with_publisher` is set to `false`: - -#### Request - -```graphql -query getArticles($with_publisher: Boolean!) { - articles { - title - publisher @skip(if: $with_publisher) - } -} -``` - -#### Response - -```JSON -{ - "data": { - "articles": [ - { - "title": "How to climb Mount Everest", - "publisher": "Mountain World" - }, - { - "title": "How to be successful on broadway", - "publisher": "Broadway World" - }, - { - "title": "How to make fajitas", - "publisher": "Fajita World" - } - ] - } -} -```