hasura / hasura/graphql-engine
Docs for Boolean expressions are incomplete
- Dominant language
- TypeScript
- Stars
- 32.1k
- Forks
- 3k
- PR merge metrics
- PR metrics pending
Description
The API docs specify that a Boolean expression (e.g. for `where` clauses) is one of five options.
https://github.com/hasura/graphql-engine/blob/52873dba95df9aac8dfee174597c7967291e4828/docs/docs/api-reference/graphql-api/query.mdx#L366-L384
In particular, `ColumnExp` simply represents a comparison operator.
https://github.com/hasura/graphql-engine/blob/52873dba95df9aac8dfee174597c7967291e4828/docs/docs/api-reference/graphql-api/query.mdx#L578-L620
At first sight, this is matched by the internal Haskell representation: a `GBoolExp` is one of five options.
https://github.com/hasura/graphql-engine/blob/52873dba95df9aac8dfee174597c7967291e4828/server/src-lib/Hasura/RQL/IR/BoolExp.hs#L81-L90
However, in most cases, the `a` type parameter used by `BoolFld` is filled in by `AnnBoolExpFld`:
https://github.com/hasura/graphql-engine/blob/52873dba95df9aac8dfee174597c7967291e4828/server/src-lib/Hasura/RQL/IR/BoolExp.hs#L504-L517
This allows for not just a binary operator on a column (`AVColumn`), but also for deeper Boolean expressions in the case of relationships and computed fields.
Concretely, this means that something like
```graphql
query {
articles(where: {author: {hometown: {_eq:"Amsterdam"}}}) {
title
}
}
```
is not considered a valid query by the documentation.
Was this part of the documentation possibly written before support for DB table relationships was added? In any case, it didn't get improved after computed fields were added.
Contributor guide
Research direction
Start with the Boolean expression and ColumnExp sections in docs/docs/api-reference/graphql-api/query.mdx, then compare them with GBoolExp and AnnBoolExpFld in server/src-lib/Hasura/RQL/IR/BoolExp.hs. Update the API documentation to account for nested relationship and computed-field expressions, including the provided articles query example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, haskell
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100