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

docs/docs/schema/bigquery/computed-fields.mdx

@@ -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.
 
 :::
 

docs/docs/schema/bigquery/views.mdx

@@ -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.

docs/docs/schema/ms-sql-server/stored-procedures.mdx

@@ -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
 

docs/docs/schema/postgres/computed-fields.mdx

@@ -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.
 
 :::
 

docs/docs/schema/postgres/custom-functions.mdx

@@ -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

docs/docs/schema/postgres/views.mdx

@@ -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.

docs/docs/schema/snowflake/custom-functions.mdx

@@ -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}