mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-10-26 10:20:54 +03:00
Docs: Clarify custom function return types
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10237 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: ba4af7df3650675db107275d564c6dc1cec15969
This commit is contained in:
parent
f73a8d98e5
commit
4e83f7cd18
@ -18,13 +18,14 @@ import TabItem from '@theme/TabItem';
|
||||
## What are computed fields?
|
||||
|
||||
Computed fields are virtual fields that are dynamically computed and can be queried along with a table's columns.
|
||||
Computed fields are computed upon request. They are computed by executing user-defined SQL functions using other columns
|
||||
of the table and other custom inputs if needed.
|
||||
|
||||
:::info Note
|
||||
Computed fields are computed upon request. They are computed by executing user-defined SQL functions which take columns
|
||||
of the table, and other custom values if needed, as inputs to compute the field.
|
||||
|
||||
Computed fields are only exposed over the GraphQL API and the BigQuery database schema is not modified on addition of a
|
||||
computed field.
|
||||
:::info Computed fields do not modify the database schema
|
||||
|
||||
Computed fields are only exposed over the GraphQL API and the database schema is not modified on addition of a computed
|
||||
field. i.e. a computed field cannot be fetched as a table column directly from the database.
|
||||
|
||||
:::
|
||||
|
||||
|
@ -17,8 +17,8 @@ import TabItem from '@theme/TabItem';
|
||||
|
||||
## What are views?
|
||||
|
||||
[Views][] can be used to expose the results of a custom query as a virtual table. Views are not persisted physically
|
||||
i.e. the query defining a view is executed whenever data is requested from the view.
|
||||
BigQuery [Views][] can be used to expose the results of a custom query as a virtual table. Views are not persisted
|
||||
physically i.e. the query defining a view is executed whenever data is requested from the view.
|
||||
|
||||
Hasura GraphQL Engine lets you expose views over the GraphQL API to allow querying them using both `queries` and
|
||||
`subscriptions` just like regular tables.
|
||||
|
@ -37,7 +37,7 @@ and execute them via the Hasura GraphQL Engine.
|
||||
SQL Server stored procedures are built-in or user-defined Transact-SQL statements that can be used to encapsulate some
|
||||
custom business logic or extend the built-in SQL functions and operators.
|
||||
|
||||
stored procedures support is a Cloud and Enterprise feature of Hasura.
|
||||
_Stored procedures support is a Cloud and Enterprise feature of Hasura._
|
||||
|
||||
:::info Supported features
|
||||
|
||||
|
@ -20,14 +20,16 @@ import TabItem from '@theme/TabItem';
|
||||
## What are computed fields?
|
||||
|
||||
Computed fields are virtual values or objects that are dynamically computed and can be queried along with a table/view's
|
||||
columns. Computed fields are computed upon request. They are computed by executing
|
||||
[custom SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html) (a.k.a. stored procedures) using
|
||||
other columns of the table/view and other custom inputs if needed.
|
||||
columns.
|
||||
|
||||
:::info Note
|
||||
Computed fields are computed upon request. They are computed by executing
|
||||
[user-defined SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html) (a.k.a. stored procedures)
|
||||
which take the columns of the table/view, and other custom values if needed, as inputs to compute the field.
|
||||
|
||||
:::info Computed fields do not modify the database schema
|
||||
|
||||
Computed fields are only exposed over the GraphQL API and the database schema is not modified on addition of a computed
|
||||
field.
|
||||
field. i.e. a computed field cannot be fetched as a table column directly from the database.
|
||||
|
||||
:::
|
||||
|
||||
@ -38,14 +40,17 @@ from_ [Postgres docs](https://www.postgresql.org/docs/current/sql-createfunction
|
||||
|
||||
- **Function behavior**: ONLY `STABLE` or `IMMUTABLE`
|
||||
- **Argument modes**: ONLY `IN`
|
||||
- **Table Argument**: One input argument with a table row type
|
||||
- **Table Argument**: ONE input argument as the table row type
|
||||
- **Return type**: Either `SETOF <table-name>` or `BASE` type
|
||||
|
||||
:::info Note
|
||||
Functions used as computed fields can also accept other arguments other than the mandatory table row argument. Values
|
||||
for these extra arguments can be passed as arguments to the computed field in the GraphQL API.
|
||||
|
||||
- Functions used as computed fields can also accept other arguments other than the mandatory table row argument. Values
|
||||
for these extra arguments can be passed as arguments to the computed field in the GraphQL API.
|
||||
- Functions used as computed fields do not need to be tracked by the Hasura GraphQL Engine.
|
||||
:::info No need for tracking
|
||||
|
||||
Functions used as computed fields do not need to be [tracked](./custom-functions.mdx#pg-track-custom-sql-functions) by
|
||||
the Hasura GraphQL Engine. As the requirements for tracking functions differ from those to add them as computed fields,
|
||||
not all functions that can be used as computed fields can be tracked and vice versa.
|
||||
|
||||
:::
|
||||
|
||||
|
@ -16,33 +16,42 @@ import Thumbnail from '@site/src/components/Thumbnail';
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Postgres: Extend Schema with SQL Functions
|
||||
# Postgres: Extend Schema with Custom SQL Functions
|
||||
|
||||
## What are custom SQL functions?
|
||||
## What are Custom functions?
|
||||
|
||||
Custom SQL functions are [user-defined SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html)
|
||||
that can be used to either encapsulate some custom business logic or extend the built-in SQL functions and operators.
|
||||
SQL functions are also referred to as **stored procedures**.
|
||||
Postgres [user-defined SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html) can be used to
|
||||
either encapsulate some custom business logic or extend the built-in SQL functions and operators. SQL functions are also
|
||||
referred to as **stored procedures**.
|
||||
|
||||
Hasura GraphQL Engine lets you expose certain types of custom functions as top level fields in the GraphQL API to allow
|
||||
querying them with either `queries` or `subscriptions`, or for `VOLATILE` functions as `mutations`.
|
||||
Hasura GraphQL Engine lets you expose certain types of user-defined functions as top level fields in the GraphQL API to
|
||||
allow querying them with either `queries` or `subscriptions`, or for `VOLATILE` functions as `mutations`. These are
|
||||
called Custom functions.
|
||||
|
||||
:::info Note
|
||||
:::info Functions as computed fields
|
||||
|
||||
Custom SQL functions can also be queried as [computed fields](/schema/postgres/computed-fields.mdx) of tables.
|
||||
User-defined SQL functions can also be added as [computed fields](/schema/postgres/computed-fields.mdx) of tables.
|
||||
|
||||
:::
|
||||
|
||||
### Supported SQL functions {#pg-supported-sql-functions}
|
||||
|
||||
Currently, only functions which satisfy the following constraints can be exposed as top level fields in the GraphQL API
|
||||
(_terminology from_ [Postgres docs](https://www.postgresql.org/docs/current/sql-createfunction.html)):
|
||||
Currently, only functions which satisfy the following constraints can be [tracked](#pg-track-custom-sql-functions) as
|
||||
Custom functions to be exposed as top level fields in the GraphQL API (_terminology from_
|
||||
[Postgres docs](https://www.postgresql.org/docs/current/sql-createfunction.html)):
|
||||
|
||||
- **Function behavior**: `STABLE` or `IMMUTABLE` functions may _only_ be exposed as queries. `VOLATILE` functions may
|
||||
be exposed as mutations or queries.
|
||||
- **Return type**: MUST be `SETOF <table-name>` OR `<table-name>` where `<table-name>` is already tracked
|
||||
- **Function behavior**: `STABLE` or `IMMUTABLE` functions may _only_ be exposed as queries. `VOLATILE` functions may be
|
||||
exposed as mutations or queries.
|
||||
- **Return type**: **MUST** be `SETOF <table-name>` OR `<table-name>` where `<table-name>` is already tracked
|
||||
- **Argument modes**: ONLY `IN`
|
||||
|
||||
:::tip Return type workaround
|
||||
|
||||
If the required `SETOF` table doesn't already exist or your function needs to return a custom type i.e. row set, you can
|
||||
[create and track](/schema/postgres/tables.mdx) an empty table with the required schema to support the function.
|
||||
|
||||
:::
|
||||
|
||||
## Creating SQL functions {#pg-create-sql-functions}
|
||||
|
||||
SQL functions can be created using SQL statements which can be executed as follows:
|
||||
@ -94,7 +103,7 @@ X-Hasura-Role: admin
|
||||
## Track SQL functions {#pg-track-custom-sql-functions}
|
||||
|
||||
Functions can be present in the underlying Postgres database without being exposed over the GraphQL API. In order to
|
||||
expose a function over the GraphQL API, it needs to be **tracked**.
|
||||
expose a function as a top level field in the GraphQL API, it needs to be **tracked** as custom functions.
|
||||
|
||||
<Tabs groupId="user-preference" className="api-tabs">
|
||||
<TabItem value="console" label="Console">
|
||||
@ -148,13 +157,6 @@ X-Hasura-Role: admin
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info Note
|
||||
|
||||
If the `SETOF` table doesn't already exist or your function needs to return a custom type i.e. row set, create and track
|
||||
an empty table with the required schema to support the function before executing the above steps.
|
||||
|
||||
:::
|
||||
|
||||
## Use cases
|
||||
|
||||
Custom functions are ideal solutions for retrieving some derived data based on some custom business logic that requires
|
||||
@ -563,8 +565,8 @@ A custom function `f` is only accessible to a role `r` if there is a function pe
|
||||
defined on the function `f` for the role `r`. Additionally, role `r` must have SELECT permissions on the returning table
|
||||
of the function `f`.
|
||||
|
||||
[Access control permissions](/auth/authorization/permissions/index.mdx) configured for the `SETOF` table of a
|
||||
function are also applicable to the function itself.
|
||||
[Access control permissions](/auth/authorization/permissions/index.mdx) configured for the `SETOF` table of a function
|
||||
are also applicable to the function itself.
|
||||
|
||||
**For example**, in our text-search example above, if the role `user` has access only to certain columns of the table
|
||||
`article`, a validation error will be thrown if the `search_articles` query is run selecting a column to which the
|
||||
|
@ -17,9 +17,9 @@ import TabItem from '@theme/TabItem';
|
||||
|
||||
## What are views?
|
||||
|
||||
[Views](https://www.postgresql.org/docs/current/sql-createview.html) can be used to expose the results of a custom query
|
||||
as a virtual table. Views are not persisted physically i.e. the query defining a view is executed whenever data is
|
||||
requested from the view.
|
||||
Postgres [Views](https://www.postgresql.org/docs/current/sql-createview.html) can be used to expose the results of a
|
||||
custom query as a virtual table. Views are not persisted physically i.e. the query defining a view is executed whenever
|
||||
data is requested from the view.
|
||||
|
||||
Hasura GraphQL Engine lets you expose views over the GraphQL API to allow querying them using both `queries` and
|
||||
`subscriptions` just like regular tables.
|
||||
|
@ -26,11 +26,11 @@ Snowflake UDFs are supported from v2.26.0.
|
||||
|
||||
## What are user-defined functions?
|
||||
|
||||
[User-defined functions](https://docs.snowflake.com/en/sql-reference/udf-overview) (UDFs) are custom functions that can
|
||||
be used to either encapsulate some custom business logic or extend the built-in SQL functions and operators.
|
||||
Snowflake [User-defined functions](https://docs.snowflake.com/en/sql-reference/udf-overview) (UDFs) are custom functions
|
||||
that can be used to either encapsulate some custom business logic or extend the built-in SQL functions and operators.
|
||||
|
||||
Hasura GraphQL Engine lets you expose certain types of custom functions as top-level fields in the GraphQL API to allow
|
||||
querying them.
|
||||
Hasura GraphQL Engine lets you expose certain types of UDFs as top-level fields in the GraphQL API to allow querying
|
||||
them.
|
||||
|
||||
### Supported functions {#snowflake-supported-sql-functions}
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user