hasura / hasura/graphql-engine

docs: fix confusion about functions return types

Open
#4,629 14 comments 10 reactions 1 assignee Claimed by @0x777 View on GitHub
a/api/graphql a/data/postgres c/docs
Dominant language
TypeScript
Stars
32.1k
Forks
3k
PR merge metrics
PR metrics pending

Description

by @abooij

`Return type: MUST be SETOF `
https://hasura.io/docs/1.0/graphql/manual/schema/custom-functions.html#supported-sql-functions

`Computed fields whose associated SQL function returns a base type like Integer, Boolean, Geography etc. are scalar computed fields.`
https://hasura.io/docs/1.0/graphql/manual/schema/computed-fields.html#computed-field-types

There is a seeming inconsistency in the docs here: are supported SQL functions allowed to have non-setof return types? The former says it's not, the latter says it is. The answer is that SQL functions can be used in three different places:

- As a "custom function", which adds it as an alternative to the standard query, and the return type must be `setof `:

```
query q {
author(..) {
first_name
last_name
full_name
}
search_articles(args: {..}) {}
}
```

- As a "table computed field", which adds it as a field as part of the object, and the return type must be setof , where the result is an object:

```
query {
author {
id
first_name
last_name
filtered_articles(args: {search: "Hasura"}){
id
title
content
}
}
}
```

- As a "scalar computed field", which adds it as a field as part of the object, and the return type must be a scalar, and the result is simply an additional field in the object:

```
query {
author {
id
first_name
last_name
full_name
}
}
```

I think it may be valuable to make a few cross-references in the documentation emphasising the distinctions between these three. Especially since SQL functions are both supported on their own, and as part of the computed fields feature.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.