kylefang/graphql-engine
1
0
Fork 0
mirror of https://github.com/zhigang1992/graphql-engine.git synced 2026-05-25 18:32:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs update (#1535)

Browse Source
This commit is contained in:
Rikin Kachhia
2019-02-06 12:09:36 +05:30
committed by Shahidh K Muhammed
parent a25099427f
commit e8e0168da7
36 changed files with 627 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/_static/hasura-custom.css vendored
View File

@@ -131,6 +131,8 @@ ul {
-webkit-box-shadow: -1px 2px 20px 2px rgba(217,217,217,1);
-moz-box-shadow: -1px 2px 20px 2px rgba(217,217,217,1);
box-shadow: -1px 2px 20px 2px rgba(217,217,217,1);
margin-top: 20px;
margin-bottom: 30px;
}
#docs-content img.no-shadow {

2
docs/_theme/djangodocs/layout.html vendored
View File

@@ -134,7 +134,7 @@
<div>
<a target="_blank" href="https://github.com/hasura/graphql-engine/blob/master/docs/{{ pagename }}.rst">check this page on github</a>
| <a target="_blank" href="https://github.com/hasura/graphql-engine/blob/master/CONTRIBUTING.md">contributing guidelines</a>
| <a target="_blank" href="https://github.com/hasura/graphql-engine/issues/new">report an issue</a>
| <a target="_blank" href="https://github.com/hasura/graphql-engine/issues">report an issue</a>
</div>
<br/>
<div>

14
docs/graphql/manual/api-reference/index.rst
View File

@@ -18,13 +18,13 @@ Request types
The following types of requests can be made using the GraphQL API:
- :doc:`Query/Subscription <query>`
- :doc:`Query / Subscription <query>`
- :doc:`Mutation <mutation>`
Schema/Metadata API
-------------------
Schema / Metadata API
---------------------
Hasura exposes a Schema/Metadata API for managing metadata for permissions/relationships or for directly
Hasura exposes a Schema / Metadata API for managing metadata for permissions/relationships or for directly
executing SQL on the underlying Postgres.
This is primarily intended to be used as an ``admin`` API to manage Hasura schema and metadata.
@@ -36,7 +36,7 @@ Request types
The following lists all the types of requests that can be made using the Schema/Metadata API:
- :ref:`Schema/Metadata API query types <query_syntax>`
- :ref:`Schema / Metadata API query types <Query>`
Supported PostgreSQL types
--------------------------
@@ -48,7 +48,7 @@ You can refer to the following to know about all PostgreSQL types supported by t
:maxdepth: 1
:hidden:
Query/Subscription <query>
Query / Subscription <query>
Mutation <mutation>
Schema/Metadata APIs <schema-metadata-api/index>
Schema / Metadata APIs <schema-metadata-api/index>
Supported PostgreSQL types <postgresql-types>

96
docs/graphql/manual/api-reference/mutation.rst
View File

@@ -1,13 +1,13 @@
.. title:: API Reference - Mutation
API Reference - Mutation
========================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:depth: 2
:local:
.. _insert_upsert_syntax:
Insert/Upsert syntax
--------------------
@@ -91,6 +91,7 @@ Insert/Upsert syntax
}
}
.. _update_syntax:
Update syntax
-------------
@@ -170,6 +171,8 @@ Update syntax
}
}
.. _delete_syntax:
Delete syntax
-------------
@@ -229,10 +232,37 @@ Delete syntax
Syntax definitions
------------------
.. _MutationResponse:
Mutation Response
^^^^^^^^^^^^^^^^^
.. code-block:: none
{
affected_rows
returning {
response-field1
response-field2
..
}
}
E.g.:
.. code-block:: graphql
{
affected_rows
returning {
id
author_id
}
}
.. _InputObject:
Input Object
^^^^^^^^^^^^
**objects** argument
^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -271,37 +301,10 @@ E.g.:
}
]
.. _MutationResponse:
Mutation Response
^^^^^^^^^^^^^^^^^
.. code-block:: none
{
affected_rows
returning {
response-field1
response-field2
..
}
}
E.g.:
.. code-block:: graphql
{
affected_rows
returning {
id
author_id
}
}
.. _ConflictClause:
Conflict Clause
^^^^^^^^^^^^^^^
**on_conflict** argument
^^^^^^^^^^^^^^^^^^^^^^^^
Conflict clause is used to convert an *insert* query to an *upsert* query. *Upsert* respects the table's *update*
permissions before editing an existing row in case of a conflict. Hence the conflict clause is permitted only if a
table has *update* permissions defined.
@@ -324,7 +327,7 @@ E.g.:
.. _whereArgExp:
``where`` argument
**where** argument
^^^^^^^^^^^^^^^^^^
.. parsed-literal::
@@ -377,7 +380,8 @@ ColumnExp
Operator
########
Generic operators (all column types except json, jsonb) :
**Generic operators (all column types except json, jsonb):**
- ``_eq``
- ``_ne``
@@ -388,7 +392,7 @@ Generic operators (all column types except json, jsonb) :
- ``_gte``
- ``_lte``
Operators for comparing columns (all column types except json, jsonb):
**Operators for comparing columns (all column types except json, jsonb)**:
- ``_ceq``
- ``_cneq``
@@ -397,7 +401,7 @@ Operators for comparing columns (all column types except json, jsonb):
- ``_cgte``
- ``_cnlte``
Text related operators :
**Text related operators:**
- ``_like``
- ``_nlike``
@@ -406,13 +410,13 @@ Text related operators :
- ``_similar``
- ``_nsimilar``
Checking for ``null`` values :
**Checking for NULL values:**
- ``_is_null`` (takes true/false as values)
.. _setArgExp:
``_set`` argument
**_set** argument
^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -425,7 +429,7 @@ Checking for ``null`` values :
.. _incArgExp:
``_inc`` argument
**_inc** argument
^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -438,7 +442,7 @@ Checking for ``null`` values :
.. _appendArgExp:
``_append`` argument
**_append** argument
^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -460,7 +464,7 @@ E.g.
.. _prependArgExp:
``_prepend`` argument
**_prepend** argument
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -482,7 +486,7 @@ E.g.
.. _deleteKeyArgExp:
``_delete_key`` argument
**_delete_key** argument
^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -495,7 +499,7 @@ E.g.
.. _deleteElemArgExp:
``_delete_elem`` argument
**_delete_elem** argument
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
@@ -508,7 +512,7 @@ E.g.
.. _deleteAtPathArgExp:
``_delete_at_path`` argument
**_delete_at_path** argument
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: none

97
docs/graphql/manual/api-reference/query.rst
View File

@@ -1,7 +1,5 @@
.. title:: API Reference - Query/Subscription
API Reference - Query/Subscription
==================================
API Reference - Query / Subscription
====================================
.. contents:: Table of contents
:backlinks: none
@@ -71,7 +69,11 @@ Syntax definitions
Object
^^^^^^
.. _simple_object:
.. parsed-literal::
SimpleObject_ | AggregateObject_
.. _SimpleObject:
Simple Object
*************
@@ -108,7 +110,7 @@ E.g.
}
}
.. _aggregate_object:
.. _AggregateObject:
Aggregate Object
****************
@@ -218,7 +220,7 @@ E.g.
title
}
article_aggregate{ # aggregate nested object
article_aggregate { # aggregate nested object
aggregate {
count
}
@@ -328,6 +330,19 @@ Operator
- ``_gte``
- ``_lte``
**Text related operators:**
- ``_like``
- ``_nlike``
- ``_ilike``
- ``_nilike``
- ``_similar``
- ``_nsimilar``
**Checking for NULL values:**
- ``_is_null`` (takes true/false as values)
**JSONB operators:**
.. list-table::
@@ -348,19 +363,6 @@ Operator
(For more details on what these operators do, refer to `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
**Text related operators :**
- ``_like``
- ``_nlike``
- ``_ilike``
- ``_nilike``
- ``_similar``
- ``_nsimilar``
**Checking for NULL values:**
- ``_is_null`` (takes true/false as values)
**PostGIS related operators on GEOMETRY columns:**
.. list-table::
@@ -389,10 +391,10 @@ Operator
.. note::
1. All operators take a ``json`` representation of ``geometry/geography`` values.
2. Input value for ``_st_d_within`` operator is an object:-
- All operators take a JSON representation of ``geometry/geography`` values as input value.
- Input value for ``_st_d_within`` operator is an object:
.. parsed-literal::
.. parsed-literal::
{
field-name : {_st_d_within: {distance: Float, from: Value} }
@@ -428,7 +430,7 @@ or
TableOrderBy
************
""""""""""""
For columns:
@@ -463,32 +465,8 @@ Order by type for "article" table:
likes_aggregate: likes_aggregate_order_by
}
AggregateOrderBy
****************
Count aggregate
.. parsed-literal::
{count: OrderByEnum_}
Operation aggregate
.. parsed-literal::
{op_name: TableAggOpOrderBy_}
Available operations are ``sum``, ``avg``, ``max``, ``min``, ``stddev``, ``stddev_samp``,
``stddev_pop``, ``variance``, ``var_samp`` and ``var_pop``
TableAggOpOrderBy
*****************
.. parsed-literal::
{column: OrderByEnum_}
OrderByEnum
***********
###########
.. code-block:: graphql
@@ -508,6 +486,27 @@ OrderByEnum
desc_nulls_last
}
AggregateOrderBy
################
Count aggregate
.. parsed-literal::
{count: OrderByEnum_}
Operation aggregate
.. parsed-literal::
{op_name: TableAggOpOrderBy_}
Available operations are ``sum``, ``avg``, ``max``, ``min``, ``stddev``, ``stddev_samp``,
``stddev_pop``, ``variance``, ``var_samp`` and ``var_pop``
TableAggOpOrderBy
&&&&&&&&&&&&&&&&&
.. parsed-literal::
{column: OrderByEnum_}
.. _PaginationExp:

17
docs/graphql/manual/api-reference/schema-metadata-api/custom-functions.rst
View File

@@ -6,20 +6,23 @@ Schema/Metadata API Reference: Custom Functions
:depth: 1
:local:
Add or remove a custom SQL function to Hasura GraphQL Engine's metadata using following API.
Track/untrack a custom SQL function in Hasura GraphQL engine.
.. Note::
Only custom functions added to metadata are available for ``querying/subscribing`` data over **GraphQL** API.
Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API.
.. _track_function:
track_function
--------------
``track_function`` is used to add a custom SQL function.
``track_function`` is used to add a custom SQL function to the GraphQL schema.
Refer :ref:`this <supported_sql_functions>` for constraints on supported functions.
Currently, only functions which satisfy the following constraints can be exposed over the GraphQL API
(*terminology from* `Postgres docs <https://www.postgresql.org/docs/current/sql-createfunction.html>`__):
- **Function behaviour**: ONLY ``STABLE`` or ``IMMUTABLE``
- **Return type**: MUST be ``SETOF <table-name>``
- **Argument modes**: ONLY ``IN``
Add a SQL function ``search_articles``:
@@ -42,7 +45,7 @@ Add a SQL function ``search_articles``:
untrack_function
----------------
``untrack_function`` is used to remove a SQL function from metadata.
``untrack_function`` is used to remove a SQL function from the GraphQL schema.
Remove a SQL function ``search_articles``:

20
docs/graphql/manual/api-reference/schema-metadata-api/event-triggers.rst
View File

@@ -136,8 +136,8 @@ Args syntax
.. _TriggerName:
``TriggerName``
&&&&&&&&&&&&&&&
TriggerName
&&&&&&&&&&&
.. parsed-literal::
@@ -145,8 +145,8 @@ Args syntax
.. _OperationSpec:
``OperationSpec``
&&&&&&&&&&&&&&&&&
OperationSpec
&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -166,8 +166,8 @@ Args syntax
.. _HeaderFromValue:
``HeaderFromValue``
&&&&&&&&&&&&&&&&&&&
HeaderFromValue
&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -187,8 +187,8 @@ Args syntax
.. _HeaderFromEnv:
``HeaderFromEnv``
&&&&&&&&&&&&&&&&&
HeaderFromEnv
&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -208,8 +208,8 @@ Args syntax
.. _EventTriggerColumns:
``EventTriggerColumns``
&&&&&&&&&&&&&&&&&&&&&&&
EventTriggerColumns
&&&&&&&&&&&&&&&&&&&
.. parsed-literal::
:class: haskell-pre

29
docs/graphql/manual/api-reference/schema-metadata-api/index.rst
View File

@@ -1,12 +1,12 @@
Schema/Metadata API Reference
=============================
Schema / Metadata API Reference
===============================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
The Schema/Metadata API provides the following features:
The Schema / Metadata API provides the following features:
1. Execute SQL on the underlying Postgres database, supports schema modifying actions.
2. Modify Hasura metadata (permissions rules and relationships).
@@ -30,12 +30,17 @@ Request structure
"args": <args-object>
}
Body syntax: :ref:`Query <query_syntax>`
Request body
^^^^^^^^^^^^
.. _query_syntax:
.. parsed-literal::
``Query``
^^^^^^^^^
Query_
.. _Query:
Query
*****
.. list-table::
:header-rows: 1
@@ -60,7 +65,11 @@ The various types of queries are listed in the following table:
* - ``type``
- ``args``
- ``Synopsis``
- Synopsis
* - **bulk**
- :ref:`Query <Query>` array
- Execute multiple operations in a single query
* - :ref:`run_sql`
- :ref:`run_sql_args <run_sql_syntax>`
@@ -134,10 +143,6 @@ The various types of queries are listed in the following table:
- :ref:`set_permission_comment_args <set_permission_comment_syntax>`
- Set comment on an existing permission
* - ``"bulk"``
- :ref:`Query <query_syntax>` array
- Execute multiple operations in a single query
* - :ref:`create_event_trigger`
- :ref:`create_event_trigger_args <create_event_trigger_syntax>`
- Create or replace event trigger

16
docs/graphql/manual/api-reference/schema-metadata-api/permission.rst
View File

@@ -121,8 +121,8 @@ Args syntax
.. _InsertPermission:
``InsertPermission``
&&&&&&&&&&&&&&&&&&&&
InsertPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -235,8 +235,8 @@ Args syntax
.. _SelectPermission:
``SelectPermission``
&&&&&&&&&&&&&&&&&&&&
SelectPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -357,8 +357,8 @@ Args syntax
.. _UpdatePermission:
``UpdatePermission``
&&&&&&&&&&&&&&&&&&&&
UpdatePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -468,8 +468,8 @@ Args syntax
.. _DeletePermission:
``DeletePermission``
&&&&&&&&&&&&&&&&&&&&
DeletePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1

25
docs/graphql/manual/api-reference/schema-metadata-api/relationship.rst
View File

@@ -6,8 +6,7 @@ Schema/Metadata API Reference: Relationships
:depth: 1
:local:
Relationships are used to capture the connectedness of data amongst tables.
In general, when retrieving data from tables, it is very helpful if we can also
When retrieving data from tables, it is very helpful if we can also
fetch the related data alongside the columns. This is where relationships come
in. They can be considered as pseudo columns for a table to access the related
data.
@@ -17,7 +16,7 @@ For a simple ``article/author`` schema, the following relationships exist:
- ``author`` of an ``article``
- ``articles`` of an ``author``
As you may have noticed, there are two kinds of relationships:
There are two kinds of relationships:
- one-to-one or ``object relationships`` (e.g. ``author``).
- one-to-many or ``array relationships`` (e.g. ``articles``).
@@ -134,8 +133,8 @@ Args syntax
.. _ObjRelUsing:
``ObjRelUsing``
&&&&&&&&&&&&&&&
ObjRelUsing
&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -159,8 +158,8 @@ Args syntax
and ``manual_mapping``.
``ObjRelUsingManualMapping``
&&&&&&&&&&&&&&&&&&&&&&&&&&&&
ObjRelUsingManualMapping
&&&&&&&&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -291,8 +290,8 @@ Args syntax
.. _ArrRelUsing:
``ArrRelUsing``
&&&&&&&&&&&&&&&
ArrRelUsing
&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -310,8 +309,8 @@ Args syntax
- ArrRelUsingManualMapping_
- Manual mapping of table and columns
``ArrRelUsingFKeyOn``
&&&&&&&&&&&&&&&&&&&&&
ArrRelUsingFKeyOn
&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
@@ -329,8 +328,8 @@ Args syntax
- :ref:`PGColumn`
- Name of the column with foreign key constraint
``ArrRelUsingManualMapping``
&&&&&&&&&&&&&&&&&&&&&&&&&&&&
ArrRelUsingManualMapping
&&&&&&&&&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1

10
docs/graphql/manual/api-reference/schema-metadata-api/run-sql.rst
View File

@@ -11,6 +11,11 @@ Schema/Metadata API Reference: Run SQL
run_sql
-------
``run_sql`` can be used to run arbitrary SQL statements.
Multiple SQL statements can be separated by a ``;``, however, only the result of the last SQL statement will be
returned.
.. admonition:: Admin-only
This is an admin-only query, i.e. the query can only be executed by a
@@ -29,9 +34,6 @@ Use cases
1. To execute DDL operations that are not supported by the console (e.g. managing indexes).
2. Run custom DML queries from backend microservices instead of installing libraries to speak to Postgres.
``run_sql`` can be used to run arbitrary SQL statements. Multiple SQL statements can be separated by a
"``;``", however, only the result of the last sql statement will be returned.
An example:
.. code-block:: http
@@ -165,7 +167,7 @@ The response is a JSON Object with the following structure.
.. note::
The first row in the ``result`` (when present) will be the names of the columns.
More examples
Some examples
^^^^^^^^^^^^^
A query returning results.

12
docs/graphql/manual/api-reference/schema-metadata-api/table-view.rst
View File

@@ -1,23 +1,21 @@
Schema/Metadata API Reference: Tables/Views
============================================
===========================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Add or remove a table/view to Hasura GraphQL Engine's metadata using following API.
Track/untrack a table/view in Hasura GraphQL engine
.. Note::
Only tables/views added to metadata are available for ``querying/mutating/subscribing`` data over **GraphQL** API.
Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.
.. _track_table:
track_table
-----------
``track_table`` is used to add a table/view.
``track_table`` is used to add a table/view to the GraphQL schema.
Add a table/view ``author``:
@@ -57,7 +55,7 @@ Args syntax
untrack_table
-------------
``untrack_table`` is used to remove a table/view.
``untrack_table`` is used to remove a table/view from the GraphQL schema.
Remove a table/view ``author``:

56
docs/graphql/manual/auth/basics.rst
View File

@@ -21,19 +21,7 @@ Head to your console and :ref:`create a table <create-tables>` called ``author``
name TEXT
)
Insert some sample data into the table:
+-------------+----------+
| **id** | **name** |
+-------------+----------+
| 1 | john |
+-------------+----------+
| 2 | shruti |
+-------------+----------+
| 3 | celine |
+-------------+----------+
| 4 | raj |
+-------------+----------+
Now, insert some sample data into the table using the ``Insert Row`` tab of the ``author`` table.
Try out a query
---------------
@@ -58,28 +46,26 @@ accepted with **admin** permissions.
Add a simple access control rule for a logged in user
-----------------------------------------------------
Let's say that for our app, logged in users are only allowed to fetch their own data.
Let's say that we want to restrict users to fetch only their own data.
Head to the ``Permissions`` tab of the ``author`` table.
Let's add a **select** permission for the **user** role on the ``author`` table:
Now add a ``select`` access control rule for the ``user`` role on the ``author`` table:
.. image:: ../../../img/graphql/manual/auth/author-select-perms.png
This reads as:
This rule reads as:
.. list-table::
:header-rows: 1
:widths: 15 20 25 40
:widths: 25 20 45
* - Table
- Definition
* - Definition
- Condition
- Representation
* - author
- user's own row
- ``id`` in the row is equal to ``user-id`` from the request session
* - allow user to access only their own row
- ``id`` in the row is equal to ``user-id`` from the request session variable
-
.. code-block:: json
@@ -96,19 +82,31 @@ Now, let's make the same query as above but also include two dynamic authorizati
You can notice above how the same query now only includes the right slice of data.
.. admonition:: Permission rules can also use nested object's fields
.. admonition:: Defining access control rules
For example, for an ``article`` table with nested ``author`` table, we can define the select permission as:
Access control, or permission rules can be as complex as you need them to be, even using a nested object's
fields if required. You can use the same operators that you use to filter query results to define
permission rules. See :doc:`filtering query results <../queries/query-filters>` for more details.
For example, for an ``article`` table with a nested ``author`` table, we can define the select permission as:
.. code-block:: json
{
"author" : {
"id": {
"_eq": "X-Hasura-User-Id"
}
"_and":
[
{
"published_on": { "_gt": "31-12-2018" }
},
{
"author": {
"id": { "_eq": "X-Hasura-User-Id" }
}
}
]
}
}
This rule reads as: allow selecting an article if it was published after "31-12-2018" and its author is the current user.
.. _restrict_columns:

4
docs/graphql/manual/deployment/docker/securing-graphql-endpoint.rst
View File

@@ -25,5 +25,5 @@ Run the docker command with an access-key env var
.. note::
If you're looking at adding authentication and access control to your GraphQL API then head
to :doc:`Authentication / access control <../../auth/index>`.
If you're looking at adding access control rules for your data to your GraphQL API then head
to :doc:`Authentication / access control <../auth/index>`.

4
docs/graphql/manual/deployment/heroku/securing-graphql-endpoint.rst
View File

@@ -35,5 +35,5 @@ In case you're using the CLI to open the Hasura console, use the ``access-key``
.. note::
If you're looking at adding authentication and access control to your GraphQL API then head
to :doc:`Authentication / access control <../../auth/index>`.
If you're looking at adding access control rules for your data to your GraphQL API then head
to :doc:`Authentication / access control <../auth/index>`.

8
docs/graphql/manual/deployment/heroku/updating.rst
View File

@@ -23,19 +23,23 @@ Step 1: Clone the Hasura GraphQL engine Heroku app
The Hasura app with Heroku buildpack/configuration is available at:
https://github.com/hasura/graphql-engine-heroku
Clone the above repository.
If you already have this, then pull the latest changes which will have the updated GraphQL engine docker image.
Step 2: Attach your Heroku app
------------------------------
Let's say your Heroku app is called ``hasura-heroku`` and is running on ``https://hasura-heroku.herokuapp.com``.
Use the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_ to configure the git repo you cloned in Step 1
to be able to push to this app.
.. code-block:: bash
# Replace hasura-heroku with your Heroku app's name
$ heroku git:remote -a hasura-heroku
# Replace <hasura-heroku> with your Heroku app's name
$ heroku git:remote -a <hasura-heroku>
$ heroku stack:set container -a <hasura-heroku>
Step 3: Git push to deploy the latest Hasura GraphQL engine
-----------------------------------------------------------

4
docs/graphql/manual/deployment/kubernetes/securing-graphql-endpoint.rst
View File

@@ -48,5 +48,5 @@ In case you're using the CLI to open the Hasura console, use the ``access-key``
.. note::
If you're looking at adding authentication and access control to your GraphQL API then head
to :doc:`Authentication / access control <../../auth/index>`.
If you're looking at adding access control rules for your data to your GraphQL API then head
to :doc:`Authentication / access control <../auth/index>`.

9
docs/graphql/manual/deployment/postgres-permissions.rst
View File

@@ -51,11 +51,16 @@ Here's a sample SQL block that you can run on your database to create the right
-- tables/schemas - you want give to hasura. If you want expose the public
-- schema for GraphQL query then give permissions on public schema to the
-- hasura user.
-- Be careful to use these in your production db. Consult the postgres manual or
-- your DBA and give appropriate permissions.
-- grant all privileges on all tables in the public schema. This can be customised:
-- For example, if you only want to use GraphQL regular queries and not mutations,
-- then you can: GRANT SELECT ON ALL TABLES...
-- then you can set: GRANT SELECT ON ALL TABLES...
GRANT ALL ON ALL TABLES IN SCHEMA public TO hasurauser;
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO hasurauser;
-- Similarly repeat this for other schemas, if you have.
-- Similarly add this for other schemas, if you have any.
-- GRANT USAGE ON SCHEMA <schema-name> TO hasurauser;
-- GRANT ALL ON ALL TABLES IN SCHEMA <schema-name> TO hasurauser;
-- GRANT ALL ON ALL SEQUENCES IN SCHEMA <schema-name> TO hasurauser;

2
docs/graphql/manual/deployment/securing-graphql-endpoint.rst
View File

@@ -18,6 +18,6 @@ access to your GraphQL endpoint and the Hasura console:
.. note::
If you're looking at adding authentication and access control to your GraphQL API then head
If you're looking at adding access control rules for your data to your GraphQL API then head
to :doc:`Authentication / access control <../auth/index>`.

16
docs/graphql/manual/getting-started/first-event-trigger.rst
View File

@@ -15,17 +15,15 @@ Create a table
Head to the Hasura console, navigate to ``Data -> Create table`` and create a sample table called ``profile`` with
the following columns:
+----------+----------+
| **profile** |
+----------+----------+
| id | integer |
+----------+----------+
| name | text |
+----------+----------+
.. code-block:: sql
profile (
id INT PRIMARY KEY,
name TEXT
)
.. image:: ../../../img/graphql/manual/getting-started/create-profile-table.png
Setup an event trigger
----------------------
In the Hasura console, navigate to ``Events -> Create trigger`` and:
@@ -44,7 +42,7 @@ This sets up our webhook ``https://httpbin.org/post`` to receive database change
Watch the trigger in action
---------------------------
1. Insert some sample data into the ``profile`` table.
1. Insert some sample data into the ``profile`` table using the ``Insert Row`` tab.
2. Now navigate to the ``Events`` tab and click on the ``echo`` trigger in the left sidebar.
3. Expand the details of an event to see the response from the webhook.

27
docs/graphql/manual/getting-started/first-graphql-query.rst
View File

@@ -16,29 +16,16 @@ Create a table
Head to the Hasura console, navigate to ``Data -> Create table`` and create a sample table called ``profile`` with
the following columns:
+----------+----------+
| **profile** |
+----------+----------+
| id | integer |
+----------+----------+
| name | text |
+----------+----------+
.. code-block:: sql
profile (
id INT PRIMARY KEY,
name TEXT
)
.. image:: ../../../img/graphql/manual/getting-started/create-profile-table.png
Insert some sample data into the table:
+-----------+------------+
| **id** | **name** |
+-----------+------------+
| 1 | john |
+-----------+------------+
| 2 | shruti |
+-----------+------------+
| 3 | celine |
+-----------+------------+
| 4 | raj |
+-----------+------------+
Now, insert some sample data into the table using the ``Insert Row`` tab of the ``profile`` table.
Try out a query
---------------

4
docs/graphql/manual/mutations/delete.rst
View File

@@ -9,7 +9,7 @@ Delete mutation
Auto-generated delete mutation schema
-------------------------------------
Here’s the schema for the delete mutation field for a table ``article``:
**For example**, the auto-generated schema for the delete mutation field for a table ``article`` looks like this:
.. code-block:: graphql
@@ -31,6 +31,8 @@ As you can see from the schema:
for filtering options. Objects can be deleted based on filters on their own fields or those in their nested objects.
- You can return the number of affected rows and the affected objects (with nested objects) in the response.
See the :ref:`delete mutation API reference <delete_syntax>` for the full specifications
.. note::
If a table is not in the ``public`` Postgres schema, the delete mutation field will be of the format

67
docs/graphql/manual/mutations/insert.rst
View File

@@ -9,7 +9,7 @@ Insert mutation
Auto-generated insert mutation schema
-------------------------------------
Here’s the schema for the insert mutation field for a table ``article``:
**For example**, the auto-generated schema for the insert mutation field for a table ``article`` looks like this:
.. code-block:: graphql
@@ -32,6 +32,8 @@ As you can see from the schema:
- You can pass an ``on_conflict`` argument to convert the mutation to an :doc:`upsert mutation <upsert>`
- You can return the number of affected rows and the affected objects (with nested objects) in the response.
See the :ref:`insert mutation API reference <insert_upsert_syntax>` for the full specifications
.. note::
If a table is not in the ``public`` Postgres schema, the insert mutation field will be of the format
@@ -76,7 +78,9 @@ Insert a single object
}
}
OR
Insert a single object (using variables)
----------------------------------------
**Example:** Insert a new ``article`` object and return the inserted article object in the response
.. graphiql::
:view_only:
@@ -266,6 +270,63 @@ in the response
}
}
Insert an object with a JSONB column
------------------------------------
**Example:** Insert a new ``author`` object with a JSONB ``address`` column
.. graphiql::
:view_only:
:query:
mutation insert_author($address: jsonb) {
insert_author (
objects: [
{
id: 1,
name: "Ash",
address: $address
}
]
) {
affected_rows
returning {
id
name
address
}
}
}
:response:
{
"data": {
"insert_author": {
"affected_rows": 1,
"returning": [
{
"id": 1,
"name": "Ash",
"address": {
"city": "Bengaluru",
"phone": "9090909090",
"state": "Karnataka",
"pincode": 560095,
"street_address": "161, 19th Main Road, Koramangala 6th Block"
}
}
]
}
}
}
:variables:
{
"address": {
"street_address": "161, 19th Main Road, Koramangala 6th Block",
"city": "Bengaluru",
"phone": "9090909090",
"state": "Karnataka",
"pincode": 560095
}
}
Set a field to its default value during insert
----------------------------------------------
@@ -308,7 +369,7 @@ To set a field to its ``default`` value, just omit it from the input object, irr
}
}
Set a field to null during insert
Set a field to NULL during insert
---------------------------------
If a field is ``nullable`` in the database, to set its value to ``null``, either pass its value as ``null`` or

102
docs/graphql/manual/mutations/update.rst
View File

@@ -9,7 +9,7 @@ Update mutation
Auto-generated update mutation schema
-------------------------------------
Here’s the schema for the update mutation field for a table ``article``:
**For example**, the auto-generated schema for the update mutation field for a table ``article`` looks like this:
.. code-block:: graphql
@@ -33,6 +33,8 @@ As you can see from the schema:
for filtering options. Objects can be updated based on filters on their own fields or those in their nested objects.
- You can return the number of affected rows and the affected objects (with nested objects) in the response.
See the :ref:`update mutation API reference <update_syntax>` for the full specifications
.. note::
- At least any one of ``_set``, ``_inc`` operators or the jsonb operators ``_append``, ``_prepend``, ``_delete_key``,
@@ -83,6 +85,100 @@ Update based on an object's fields
}
}
Update based on an object's fields (using variables)
----------------------------------------------------
**Example:** Update the ``title``, ``content`` and ``rating`` of the article with a given ``id``:
.. graphiql::
:view_only:
:query:
mutation update_article($id: Int, $changes: article_set_input) {
update_article(
where: {id: {_eq: $id}},
_set: $changes
) {
affected_rows
returning {
id
title
content
rating
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": [
{
"id": 3,
"title": "lorem ipsum",
"content": "dolor sit amet",
"rating": 2
}
]
}
}
}
:variables:
{
"id": 3,
"changes": {
"title": "lorem ipsum",
"content": "dolor sit amet",
"rating": 2
}
}
OR
.. graphiql::
:view_only:
:query:
mutation update_article($id: Int, $title: String, $content: String, $rating: Int) {
update_article(
where: {id: {_eq: $id}},
_set: {
title: $title,
content: $content,
rating: $rating
}
) {
affected_rows
returning {
id
title
content
rating
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": [
{
"id": 3,
"title": "lorem ipsum",
"content": "dolor sit amet",
"rating": 2
}
]
}
}
}
:variables:
{
"id": 3,
"title": "lorem ipsum",
"content": "dolor sit amet",
"rating": 2
}
Update based on a nested object's fields
----------------------------------------
**Example:** Update the ``rating`` of all articles authored by "Sidney":
@@ -175,7 +271,7 @@ You can append any ``jsonb`` column with another json value by using the ``_appe
Since the input is a json value, it should be provided through a variable.
**Example:** Append the json ``{"key1": "value1}`` to ``jsonb`` column ``extra_info`` of ``article`` table:
**Example:** Append the json ``{"key1": "value1"}`` to ``jsonb`` column ``extra_info`` of ``article`` table:
.. graphiql::
:view_only:
@@ -218,7 +314,7 @@ You can prepend any ``jsonb`` column with another json value by using the ``_pre
Since the input is a json value, it should be provided through a variable.
**Example:** Prepend the json ``{"key0": "value0}`` to ``jsonb`` column ``extra_info`` of ``article`` table:
**Example:** Prepend the json ``{"key0": "value0"}`` to ``jsonb`` column ``extra_info`` of ``article`` table:
.. graphiql::
:view_only:

18
docs/graphql/manual/mutations/upsert.rst
View File

@@ -108,15 +108,15 @@ Upsert in nested mutations
--------------------------
You can specify ``on_conflict`` clause while inserting nested objects
.. graphiql::
:view_only:
:query:
mutation upsert_author_article {
insert_author(
objects: [
{ name: "John",
{
id: 10,
name: "John",
articles: {
data: [
{
@@ -146,9 +146,15 @@ You can specify ``on_conflict`` clause while inserting nested objects
}
.. note::
.. admonition:: Edge-cases
Inserting nested objects fails when:
Nested upserts will fail when:
- Any of upsert in object relationships does not affect any rows (``update_columns: []``)
- Array relationships are queued for insert and parent insert does not affect any rows (``update_columns: []``)
- In case of an array relationship, parent upsert does not affect any rows (i.e. ``update_columns: []`` for parent
and a conflict occurs)
- In case of an object relationship, nested object upsert does not affect any row (i.e. ``update_columns: []`` for
nested object and a conflict occurs)
To allow upserting in these cases, set ``update_columns: [<conflict-column>]``. By doing this, in case of a
conflict, the conflicted column will be updated with the new value (which is the same value it had before and hence
will effectively leave it unchanged) and will allow the upsert to go through.

2
docs/graphql/manual/queries/aggregation-queries.rst
View File

@@ -11,7 +11,7 @@ Available aggregation functions are ``count``, ``sum``, ``avg``, ``max`` and ``m
.. note::
The name of the :ref:`aggregate field <aggregate_object>` is of the form ``field-name + _aggregate``
The name of the :ref:`aggregate field <AggregateObject>` is of the form ``<field-name> + _aggregate``
Fetch aggregated data of an object
----------------------------------

17
docs/graphql/manual/queries/distinct-queries.rst
View File

@@ -6,8 +6,10 @@ Distinct query results
:depth: 1
:local:
You can fetch rows with only distinct values of a column using the ``distinct_on`` argument. The first ``order_by``
columns must match the ``distinct_on`` column. See :doc:`sort queries <sorting>` for more info on ``order_by``.
You can fetch rows with only distinct values of a column using the ``distinct_on`` argument.
This requires the data to be first sorted by the column i.e. the ``distinct_on`` column should also be the first
``order_by`` column. See :doc:`sort queries <sorting>` for more info on using ``order_by``.
.. code-block:: graphql
@@ -24,6 +26,8 @@ columns must match the ``distinct_on`` column. See :doc:`sort queries <sorting>`
salary
}
You can see the complete specification of the ``distinct_on`` argument in the :ref:`API reference <DistinctOnExp>`.
Fetch results with distinct values of a particular field
--------------------------------------------------------
@@ -33,10 +37,13 @@ Fetch results with distinct values of a particular field
:view_only:
:query:
query {
employee(
employee (
distinct_on: [department]
order_by: [{department: asc}, {salary: desc}]
){
order_by: [
{department: asc},
{salary: desc}
]
) {
id
name
department

7
docs/graphql/manual/queries/index.rst
View File

@@ -16,10 +16,10 @@ All tables of the database tracked by the GraphQL engine can be queried over the
If you have a tracked table in your database, its query field is added as a nested
field under the ``query_root`` root level type.
Auto-generated query schema
---------------------------
Auto-generated query field schema
---------------------------------
**For example**, the auto-generated query schema for an ``author`` table may look like this:
**For example**, the auto-generated schema for the query field for a table ``author`` looks like this:
.. code-block:: graphql
@@ -31,6 +31,7 @@ Auto-generated query schema
order_by: [author_order_by!]
): [author]
See the :doc:`Query API reference <../api-reference/query>` for the full specifications
.. note::

9
docs/graphql/manual/queries/multiple-arguments.rst
View File

@@ -6,10 +6,13 @@ Using multiple arguments in a query
:depth: 1
:local:
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.
Multiple arguments can be used together in the same query.
For example, fetch a list of authors and only 2 of their published articles that are sorted by their date of publication:
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:
.. graphiql::
:view_only:

4
docs/graphql/manual/queries/multiple-queries.rst
View File

@@ -6,10 +6,10 @@ Multiple queries in a request
:depth: 1
:local:
If multiple queries are part of the same request, they are executed **parallelly**, the individual responses are
If multiple queries are part of the same request, **they are executed parallelly**, the individual responses are
collated and returned. You can fetch objects of different unrelated types in the same query.
For example, fetch a list of ``authors`` and a list of ``articles``:
**For example**, fetch a list of ``authors`` and a list of ``articles``:
.. graphiql::
:view_only:

2
docs/graphql/manual/queries/nested-object-queries.rst
View File

@@ -207,4 +207,4 @@ Fetch an author whose id is ``1`` and a nested list of articles with aggregated
.. note::
The name of the :ref:`aggregate field <aggregate_object>` is of the form ``field-name + _aggregate``
The name of the :ref:`aggregate field <AggregateObject>` is of the form ``<field-name> + _aggregate``

12
docs/graphql/manual/queries/pagination.rst
View File

@@ -6,11 +6,15 @@ Paginate query results
:depth: 1
:local:
The operators :ref:`limit <PaginationExp>` and :ref:`offset <PaginationExp>` 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.
The operators ``limit`` and ``offset`` are used for pagination.
The following are examples of pagination in different scenarios:
``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
:ref:`API reference <PaginationExp>`.
The following are examples of different pagination scenarios:
Limit results
-------------

152
docs/graphql/manual/queries/query-filters.rst
View File

@@ -6,7 +6,7 @@ Filter query results / search queries
:depth: 1
:local:
You can use the :ref:`where <WhereExp>` argument in your queries to filter results based on some field’s values (even
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.
@@ -43,13 +43,16 @@ For example, to fetch a list of authors who have articles with a rating greater
}
}
Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators <Operator>` that can be used in the ``where``
Here ``_eq`` and ``_gt`` are examples of comparison operators that can be used in the ``where``
argument to filter on equality.
Let’s take a look at different operators that can be used to filter results and other advanced use cases:
You can see the complete specification of the ``where`` argument in the :ref:`API reference <WhereExp>`.
Let’s take a look at different comparision operators that can be used to filter results and other advanced use cases:
Equality operators (_eq, _neq)
------------------------------
Equality operators (_eq and _neq)
---------------------------------
The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible with any Postgres type other than
``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``,
``Date``/``Time``/``Timestamp``, etc.).
@@ -186,6 +189,7 @@ Fetch a list of articles that were published on a certain date (``published_on``
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 Postgres type other than ``json`` or ``jsonB``
(like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.).
@@ -310,6 +314,7 @@ Fetch a list of articles that were published on or after date "01/01/2018":
List based search operators (_in, _nin)
---------------------------------------
The ``_in`` (in a list) and ``_nin`` (not in list) operators are used to comparing field values to a list of values.
They are compatible with any Postgres type other than ``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``,
``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.).
@@ -399,11 +404,13 @@ Fetch a list of those authors whose names are NOT part of a list:
}
}
Text search / filter or pattern matching operators
--------------------------------------------------
The ``_like``, ``_nlike``, ``_ilike``, ``_nilike``, ``_similar``, ``_nsimilar`` operators behave exactly like
their `SQL counterparts <https://www.postgresql.org/docs/10/static/functions-matching.html>`__ and are used for
pattern matching on string/Text fields.
Text search or pattern matching operators (_like, _similar, etc.)
-----------------------------------------------------------------
The ``_like``, ``_nlike``, ``_ilike``, ``_nilike``, ``_similar``, ``_nsimilar`` operators are used for
pattern matching on string/text fields.
These operators behave exactly like their `SQL counterparts <https://www.postgresql.org/docs/current/static/functions-matching.html>`__
Example: _like
^^^^^^^^^^^^^^
@@ -438,10 +445,14 @@ Fetch a list of articles whose titles contain the word “amet”:
}
]
.. note::
``_like`` is case-sensitive. Use ``_ilike`` for case-insensitive search.
Example: _similar
^^^^^^^^^^^^^^^^^
Fetch a list of authors whose names begin with A or C (``similar`` is case-sensitive):
Fetch a list of authors whose names begin with A or C:
.. graphiql::
:view_only:
@@ -478,14 +489,108 @@ Fetch a list of authors whose names begin with A or C (``similar`` is case-sensi
}
}
PostGIS topology operators
--------------------------
.. note::
``_similar`` is case-sensitive
JSONB operators (_contains, _has_key, etc.)
-------------------------------------------
The ``_contains``, ``_contained_in``, ``_has_key``, ``_has_key_any`` and ``_has_key_all`` operators are used to filter
based on ``JSONB`` columns.
For more details on what these operators do, refer to `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.
Example: _contains
^^^^^^^^^^^^^^^^^^
Fetch all authors living within a particular pincode (present in ``address`` JSONB column):
.. graphiql::
:view_only:
:query:
query get_authors_in_pincode ($jsonFilter: jsonb){
author(
where: {
address: {_contains: $jsonFilter }
}
) {
id
name
address
}
}
:response:
{
"data": {
"author": [
{
"id": 1,
"name": "Ash",
"address": {
"street_address": "161, 19th Main Road, Koramangala 6th Block",
"city": "Bengaluru",
"state": "Karnataka",
"pincode": 560095,
"phone": "9090909090",
}
}
]
}
}
:variables:
{
"jsonFilter": {
"pincode": 560095
}
}
Example: _has_key
^^^^^^^^^^^^^^^^^
Fetch authors if the ``phone`` key is present in their JSONB ``address`` column:
.. graphiql::
:view_only:
:query:
query get_authors_if_phone {
author(
where: {
address: {_has_key: "phone" }
}
) {
id
name
address
}
}
:response:
{
"data": {
"author": [
{
"id": 1,
"name": "Ash",
"address": {
"street_address": "161, 19th Main Road, Koramangala 6th Block",
"city": "Bengaluru",
"state": "Karnataka",
"pincode": 560095,
"phone": "9090909090"
}
}
]
}
}
PostGIS topology operators (_st_contains, _st_crosses, etc.)
------------------------------------------------------------
The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st_overlaps``, ``_st_touches``,
``_st_within`` and ``_st_d_within`` operators are used to filter based on ``geometry`` like columns.
The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st_overlaps``,
``_st_touches``, ``_st_within`` and ``_st_d_within`` operators are used to filter ``geometry`` like columns.
For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.
Use ``json`` (`GeoJSON <https://tools.ietf.org/html/rfc7946>`__) representation of ``geometry`` values in
Use JSON (`GeoJSON <https://tools.ietf.org/html/rfc7946>`__) representation of ``geometry`` values in
``variables`` as shown in the following examples:
@@ -587,8 +692,9 @@ Fetch a list of geometry values which are 3 units from given ``point`` value:
}
}
Filter or check for null values
-------------------------------
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
@@ -635,8 +741,8 @@ Fetch a list of articles that have a value in the ``published_on`` field:
}
}
Filter based on failure of some criteria
----------------------------------------
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
@@ -696,8 +802,9 @@ Fetch all authors who don't have any published articles:
}
}
Using multiple filters in the same query
----------------------------------------
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.
@@ -814,6 +921,7 @@ Fetch a list of articles rated more than 4 or published after "01/01/2018":
Filter nested objects
---------------------
The ``where`` argument can be used in nested objects as well to filter the nested objects
Example:

95
docs/graphql/manual/queries/sorting.rst
View File

@@ -6,68 +6,23 @@ Sort query results
:depth: 1
:local:
Results from your query can be sorted by using the :ref:`order_by <OrderByExp>` argument. The argument can be used to sort nested
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 ``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. ``null`` values can be fetched first on ascending ordering by specifying
``asc_nulls_first`` and last on descending ordering by specifying ``desc_nulls_last`` enum value e.g. ``{name: desc_nulls_last}``.
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. ``null`` values can be fetched first on
ascending ordering by specifying ``asc_nulls_first`` and last on descending ordering by specifying
``desc_nulls_last`` enum value e.g. ``{name: desc_nulls_last}``.
The ``order_by`` argument takes an array of objects to allow sorting by multiple columns.
.. code-block:: graphql
You can also use nested objects' fields to sort the results. Only columns from **object relationships** and
are aggregates from **array relationships** can be used for sorting.
article (
order_by: [article_order_by!]
): [article]!
#order by type for "article" table
input article_order_by {
id: order_by
title: order_by
content: order_by
author_id: order_by
#order by using "author" object relationship columns
author: author_order_by
#order by using "likes" array relationship aggregates
likes_aggregate: likes_aggregate_order_by
}
#the likes_aggregate_order_by type
input likes_aggregate_order_by {
count: order_by
op_name: likes_op_name_order_by
}
#Available "op_name"s are 'max', 'min', 'sum', 'avg', 'stddev', 'stddev_samp', 'stddev_pop', 'variance', 'var_samp' and 'var_pop'
#the likes_<op-name>_order_by type
input likes_sum_order_by {
like_id: order_by
}
#the order_by enum type
enum order_by {
#in the ascending order, nulls last
asc
#in the ascending order, nulls last
asc_nulls_last
#in the ascending order, nulls first
asc_nulls_first
#in the descending order, nulls first
desc
#in the descending order, nulls first
desc_nulls_first
#in the descending order, nulls last
desc_nulls_last
}
.. Note::
Only columns from **object** relationships are allowed for sorting.
Only aggregates from **array** relationships are allowed for sorting.
You can see the complete specification of the ``order_by`` argument in the :ref:`API reference <OrderByExp>`.
The following are example queries for different sorting use cases:
@@ -80,7 +35,7 @@ Fetch list of authors sorted by their names in an ascending order:
:view_only:
:query:
query {
author(
author (
order_by: {name: asc}
) {
id
@@ -127,7 +82,7 @@ Fetch a list of authors sorted by their names with a list of their articles that
:view_only:
:query:
query {
author(order_by: {name: asc}) {
author (order_by: {name: asc}) {
id
name
articles(order_by: {rating: desc}) {
@@ -198,16 +153,17 @@ Fetch a list of authors sorted by their names with a list of their articles that
}
}
Sorting objects based on nested object's fields
-----------------------------------------------
Fetch a list of articles that is sorted by their author's id (descending).
Only columns in object relationships are allowed:
Sorting based on nested object's fields
---------------------------------------
Only columns in object relationships can be used for sorting.
Fetch a list of articles that are sorted by their author ids in descending:
.. graphiql::
:view_only:
:query:
query {
article(
article (
order_by: {author: {id: desc}}
) {
id
@@ -254,15 +210,19 @@ Only columns in object relationships are allowed:
}
}
Sorting by array relationship aggregates
----------------------------------------
Fetch a list of authors sorted by their article count.
Sorting based on nested objects' aggregates
-------------------------------------------
Only aggregates in array relationships can be used for sorting.
Fetch a list of authors sorted by their article count in descending.
.. graphiql::
:view_only:
:query:
query {
author(order_by: {articles_aggregate: {count: desc}}) {
author (
order_by: {articles_aggregate: {count: desc}}
) {
id
name
articles_aggregate {
@@ -317,8 +277,11 @@ nulls first):
:view_only:
:query:
query {
article(
order_by: [{rating: desc}, {published_on: asc_nulls_first}]
article (
order_by: [
{rating: desc},
{published_on: asc_nulls_first}
]
) {
id
rating

9
docs/graphql/manual/schema/basics.rst
View File

@@ -44,7 +44,7 @@ For example, here is the schema for the ``article`` table in this interface:
.. image:: ../../../img/graphql/manual/schema/create-table-graphql.png
The following *object type* and *query/mutation* fields are generated for the ``article`` table we just created:
The following object type and query/mutation fields are generated for the ``article`` table we just created:
.. code-block:: graphql
@@ -83,12 +83,15 @@ The following *object type* and *query/mutation* fields are generated for the ``
where: article_bool_exp!
): article_mutation_response
See the :doc:`API reference <../api-reference/index>` for more details.
See the :doc:`query <../api-reference/query>` and :doc:`mutation <../api-reference/mutation>`
API references for the full specifications
You can insert some sample data into the tables using the ``Insert Row`` tab of the created tables.
Try basic GraphQL queries
-------------------------
At this point, you should be able to try out basic GraphQL queries/mutations on the newly created tables using the
console ``GraphiQL`` tab (*you may want to add some test data in the tables first*).
console ``GraphiQL`` tab (*you may want to add some sample data into the tables first*).
Here are a couple of examples:

21
docs/graphql/manual/schema/default-values/column-presets.rst
View File

@@ -9,16 +9,16 @@ Setting default values for fields using role based column presets
Let's say you want certain fields to have their values set automatically when not explicitly passed using session
variables or fixed values when a new row is created with a particular :doc:`user role <../../auth/roles-variables>`
Hasura GraphQL engine's column presets let you define role-based default values for any field/column. These values can either
be an Authorization header's value or a static value.
Hasura GraphQL engine's column presets let you define role-based default values for any field/column. These values
can either be a session variable value or a static value.
.. admonition:: Column preset restricts mutation access for configured role
If a column has a preset defined for a given role, access to the column for mutations will be restricted for users
with said role.
with that role.
**Example:** Say we have a field ``user_id`` in a table ``article`` which is to be set to the id of the user, from
the value of the user's Authorization header whenever a new row is added to the ``article`` table.
the value of the user's session variable whenever a new row is added to the ``article`` table.
Step 1: Configure a column preset
---------------------------------
@@ -34,7 +34,12 @@ setting the preset using a static value or from a session variable.
.. image:: ../../../../img/graphql/manual/schema/column-presets-value-options.png
For our chosen example, we'll use the ``from session variable`` option and configure the ``user_id`` column to be
automatically populated based on the value of the Authorization header ``X-Hasura-User-Id``.
automatically populated based on the value of ``X-Hasura-User-Id`` session variable.
.. note::
To set a column preset for a nested object's column, simply set the corresponding column preset in the remote
table.
Step 2: Run an insert mutation
------------------------------
@@ -43,16 +48,16 @@ Head to the GraphiQL interface in the console and try making an insert mutation
following headers (*to run through this example, don't forget to also grant the* ``user`` *role sufficient permissions
to select from the* ``article`` *table*):
- ``X-Hasura-role`` --> ``user`` (*to test the behaviour for the configured role*)
- ``X-Hasura-Role`` --> ``user`` (*to test the behaviour for the configured role*)
- ``X-Hasura-User-Id`` --> ``1`` (*this is the value we should expect in the* ``user_id`` *field*)
As mentioned earlier, you'll notice when you add the ``X-Hasura-role`` header that the field, ``user_id``, is no longer
As mentioned earlier, you'll notice when you add the ``X-Hasura-Role`` header that the field, ``user_id``, is no longer
available as the mutation type's field:
.. image:: ../../../../img/graphql/manual/schema/column-preset-schema-change-for-role.png
Now, if we run the following insert mutation, we'll see that the ``user_id`` field is indeed being set with the value
passed in the ``X-Hasura-User-Id`` header:
passed in the ``X-Hasura-User-Id`` variable:
.. image:: ../../../../img/graphql/manual/schema/column-preset-mutation-result.png