hasura / hasura/graphql-engine
Unable to Set Schema Comment for Custom Function Arguments Type
- Dominant language
- TypeScript
- Stars
- 32.1k
- Forks
- 3k
- PR merge metrics
- PR metrics pending
Description
## Description
Currently, there is no apparent means of applying a schema comment to the args type for a custom function within Hasura. We can comment on the function itself, but not the args type. Here's a quick example of a migration that creates a function (let's say it's tracked in Hasura), and the resultant schema information:
Let's say we have a single table:
```sql
articles(
id INTEGER PRIMARY KEY,
contents TEXT
);
```
A function:
```sql
CREATE FUNCTION foo(bar integer)
RETURNS SETOF articles AS $$
SELECT * FROM articles WHERE id > bar
$$ LANGUAGE sql STABLE;
COMMENT ON FUNCTION foo IS 'Returns all articles with id > bar';
```
Now if we want to generate documentation for our schema using something like `graphdoc`, we get the following output (or something similar):
For the function `foo` at query root:
```
# Returns all articles with id > bar
#
#
# execute function "foo" which returns "articles"
#
# Arguments
# args: input parameters for function "foo"
# distinct_on: distinct select on columns
# limit: limit the number of rows returned
# offset: skip the first n rows. Use only with order_by
# order_by: sort the rows by one or more columns
# where: filter the rows returned
foo(
args: foo_args!,
distinct_on: [articles_select_column!],
limit: Int,
offset: Int,
order_by: [articles_order_by!],
where: articles_bool_exp
): [articles!]!
```
And for the type `foo_args`:
```
input foo_args {
bar: Int
}
```
Whereas functions are represented as Postgres objects that can have a comment applied to them, types such as `foo_args` have no such representation (at least not that I am aware of), and thus we cannot apply a comment to them directly using a `COMMENT ON` statement. This suggests that the means for applying a comment to a type such as `foo_args` would need to be exposed via the Hasura API.
Currently, it does not seem as though the Hasura API provides any method for adding a comment to an input type. The API provides methods for [setting comments on relationships](https://hasura.io/docs/latest/graphql/core/api-reference/schema-metadata-api/relationship.html#set-relationship-comment) as well as for [setting comments on permissions](https://hasura.io/docs/latest/graphql/core/api-reference/schema-metadata-api/permission.html#id20), but at the time of this writing there does not appear to be a means for adding a comment to specific types.
Adding this capability would definitely improve the UX for API consumers; it seems odd to me that the argument type of a function would have to be documented at the function itself rather than at the args type, especially if we were to define an overloaded function.
Contributor guide
Research direction
Start with the schema metadata API described in the issue and trace how a tracked PostgreSQL function produces its generated GraphQL input type, such as foo_args. Determine how a comment could be associated with that type, then verify that the API can set it and that the generated schema or graphdoc output shows the comment.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, postgres
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100