hasura / hasura/graphql-engine

Docs for Boolean expressions are incomplete

Open
#9,056 6 comments 0 reactions 0 assignees View on GitHub
c/docs c/server k/bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.