graphql-engine/docs/graphql/core/queries/nested-object-queries.rst

154 lines
3.5 KiB
ReStructuredText
Raw Normal View History

.. meta::
:description: Make nested object queries in Hasura
:keywords: hasura, docs, query, nested object query
.. _nested_object_queries:
Nested object queries
=====================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
2020-08-25 14:53:25 +03:00
Introduction
------------
You can use the object (one-to-one) or array (one-to-many) :ref:`relationships <table_relationships>` defined
in your schema to make a nested query i.e. fetch data for a type along with data from a nested or related type.
2019-04-19 13:48:18 +03:00
The **name of the nested object** is the same as the name of the object/array relationship configured in
the console.
You can also filter, sort, aggregate and paginate nested objects in case of array relationships. These are not exposed
for object relationships as they have only one nested object.
Fetch nested object using an object relationship
------------------------------------------------
2018-12-17 14:58:29 +03:00
The following is an example of a nested object query using the **object relationship** between an article and an
author.
2019-04-19 13:48:18 +03:00
**Example:** Fetch a list of articles and the name of each articles author:
.. graphiql::
:view_only:
:query:
query {
docs: pluralise query names, schema / table names ### Description This PR pluralises all sample query names in all sections of the docs, and these changes affect some schema, images, CLI commands and Apis too. _A warning was also fixed in the API reference section._ ### Changelog - [x] `CHANGELOG.md` is updated with user-facing content relevant to this PR. If no changelog is required, then add the `no-changelog-required` label. ### Affected components - [x] Docs ### Related Issues https://github.com/hasura/graphql-engine-internal/issues/75 ### Affected pages **Getting Started:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/getting-started/first-graphql-query.html **Schema:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/tables.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/create.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/rename.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/custom-functions.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/computed-fields.html **Queries:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/simple-object-queries.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/nested-object-queries.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/aggregation-queries.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/query-filters.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/sorting.html 6. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/distinct-queries.html 7. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/pagination.html 8. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-arguments.html 9. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-queries.html **Authentication/Authorization:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/auth/authorization/basics.html# **Data Modelling Guides** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-one.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-many.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/many-to-many.html GitOrigin-RevId: e02e279466909e0bbd48d908b1b6fa0a5d5e47cf
2021-02-17 14:12:53 +03:00
articles {
id
title
author {
name
}
}
}
:response:
{
"data": {
docs: pluralise query names, schema / table names ### Description This PR pluralises all sample query names in all sections of the docs, and these changes affect some schema, images, CLI commands and Apis too. _A warning was also fixed in the API reference section._ ### Changelog - [x] `CHANGELOG.md` is updated with user-facing content relevant to this PR. If no changelog is required, then add the `no-changelog-required` label. ### Affected components - [x] Docs ### Related Issues https://github.com/hasura/graphql-engine-internal/issues/75 ### Affected pages **Getting Started:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/getting-started/first-graphql-query.html **Schema:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/tables.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/create.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/rename.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/custom-functions.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/computed-fields.html **Queries:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/simple-object-queries.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/nested-object-queries.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/aggregation-queries.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/query-filters.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/sorting.html 6. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/distinct-queries.html 7. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/pagination.html 8. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-arguments.html 9. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-queries.html **Authentication/Authorization:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/auth/authorization/basics.html# **Data Modelling Guides** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-one.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-many.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/many-to-many.html GitOrigin-RevId: e02e279466909e0bbd48d908b1b6fa0a5d5e47cf
2021-02-17 14:12:53 +03:00
"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
------------------------------------------------
2018-12-17 14:58:29 +03:00
The following is an example of a nested object query using the **array relationship** between an author and
articles.
2019-04-19 13:48:18 +03:00
**Example:** Fetch a list of authors and a nested list of each authors articles:
.. graphiql::
:view_only:
:query:
query {
docs: pluralise query names, schema / table names ### Description This PR pluralises all sample query names in all sections of the docs, and these changes affect some schema, images, CLI commands and Apis too. _A warning was also fixed in the API reference section._ ### Changelog - [x] `CHANGELOG.md` is updated with user-facing content relevant to this PR. If no changelog is required, then add the `no-changelog-required` label. ### Affected components - [x] Docs ### Related Issues https://github.com/hasura/graphql-engine-internal/issues/75 ### Affected pages **Getting Started:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/getting-started/first-graphql-query.html **Schema:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/tables.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/create.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/rename.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/custom-functions.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/computed-fields.html **Queries:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/simple-object-queries.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/nested-object-queries.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/aggregation-queries.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/query-filters.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/sorting.html 6. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/distinct-queries.html 7. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/pagination.html 8. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-arguments.html 9. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-queries.html **Authentication/Authorization:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/auth/authorization/basics.html# **Data Modelling Guides** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-one.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-many.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/many-to-many.html GitOrigin-RevId: e02e279466909e0bbd48d908b1b6fa0a5d5e47cf
2021-02-17 14:12:53 +03:00
authors {
id
name
articles {
id
title
}
}
}
:response:
{
"data": {
docs: pluralise query names, schema / table names ### Description This PR pluralises all sample query names in all sections of the docs, and these changes affect some schema, images, CLI commands and Apis too. _A warning was also fixed in the API reference section._ ### Changelog - [x] `CHANGELOG.md` is updated with user-facing content relevant to this PR. If no changelog is required, then add the `no-changelog-required` label. ### Affected components - [x] Docs ### Related Issues https://github.com/hasura/graphql-engine-internal/issues/75 ### Affected pages **Getting Started:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/getting-started/first-graphql-query.html **Schema:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/tables.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/create.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/table-relationships/rename.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/custom-functions.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/schema/computed-fields.html **Queries:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/simple-object-queries.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/nested-object-queries.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/aggregation-queries.html 4. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/query-filters.html 5. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/sorting.html 6. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/distinct-queries.html 7. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/pagination.html 8. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-arguments.html 9. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/queries/multiple-queries.html **Authentication/Authorization:** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/auth/authorization/basics.html# **Data Modelling Guides** 1. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-one.html 2. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/one-to-many.html 3. https://deploy-preview-312--hasura-docs-mono.netlify.app/graphql/core/guides/data-modelling/many-to-many.html GitOrigin-RevId: e02e279466909e0bbd48d908b1b6fa0a5d5e47cf
2021-02-17 14:12:53 +03:00
"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"
}
]
}
]
}
}
.. note::
2019-04-19 13:48:18 +03:00
You can also :ref:`filter <nested_filter>`, :ref:`sort <nested_sort>`, :ref:`aggregate <nested_aggregate>`
2019-09-11 10:17:14 +03:00
and :ref:`paginate <nested_paginate>` nested objects in case of array relationships.