graphql-engine/server/src-lib/Hasura/Experimental/IR/Expression.hs

{-# LANGUAGE DeriveAnyClass #-}

module Hasura.Experimental.IR.Expression
  ( Expression (..),
    Operator (..),
  )
where

--------------------------------------------------------------------------------

import Data.Aeson (FromJSON, ToJSON)
import Hasura.Experimental.IR.Column qualified as Column (Name)
import Hasura.Experimental.IR.Scalar.Value qualified as Scalar (Value)
import Hasura.Incremental (Cacheable)
import Hasura.Prelude

--------------------------------------------------------------------------------

-- | A concrete (i.e. not polymorphic) representation for expressions that make
-- up datasource-agnostic queries.
--
-- This type should be seen as an intermediate phase of the processing pipeline
-- which provides a high-level interface that the GraphQL Engine can use to
-- inspect, manipulate, optimize, etc. before sending off to an agent that will
-- be responsible for performing query generation/execution.
--
-- This type should ascribe clear semantics to its sub-expressions; when this
-- is not possible, it should clearly defer to the semantics of some reference
-- datasource with clearer documentation.
--
-- e.g. https://www.postgresql.org/docs/13/sql-expressions.html
data Expression
  = -- | A constant 'Scalar.Value'.
    Literal Scalar.Value
  | -- | A construct for making multiple comparisons between groups of
    -- 'Scalar.Value's.
    --
    -- The right-hand side is a collection of unique 'Scalar.Value's; the
    -- result is "true" if the result of the left-hand 'Expression' is equal to
    -- any of these 'Scalar.Value's.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-comparisons.html#FUNCTIONS-COMPARISONS-IN-SCALAR
    --
    -- NOTE(jkachmar): It's unclear that there's any benefit from using a
    -- 'HashSet' for the RHS collection of 'Scalar.Value's.
    --
    -- Consider switching this to a 'Set' after the typeclass methods which use
    -- this type have been implemented and we have an opportunity to see how
    -- its used in practice.
    In Expression (HashSet Scalar.Value)
  | -- | A logical @AND@ operator.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-logical.html
    And [Expression]
  | -- | A logical @OR@ operator.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-logical.html
    Or [Expression]
  | -- | A logical @NOT@ operator.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-logical.html
    Not Expression
  | -- | A comparison predicate which returns "true" if an expression evaluates
    -- to 'Scalar.Null'.
    IsNull Expression
  | -- | A comparison predicate which returns "true" if an expression does not
    -- evaluate to 'Scalar.Null'.
    IsNotNull Expression
  | -- | The textual name associated with some "column" of data within a
    -- datasource.
    --
    -- XXX(jkachmar): It's unclear whether "column" is the right descriptor for
    -- this construct; what we want here seems closer to an "identifier".
    --
    -- cf. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
    Column Column.Name
  | -- | An equality operation which returns "true" if two expressions evaluate
    -- to equivalent forms.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-comparison.html
    --
    -- XXX(jkachmar): Consider making this a part of 'Operator'.
    --
    -- XXX(jkachmar): Equality of expressions is tricky business!
    --
    -- We should define the semantics of expression equality in a way that is
    -- clear and carefully considered.
    Equal Expression Expression
  | -- | An inequality operation which returns "true" if two expressions do not
    -- evaluate to equivalent forms.
    --
    -- cf. https://www.postgresql.org/docs/13/functions-comparison.html
    --
    -- XXX(jkachmar): Consider making this a part of 'Operator', or eliminating
    -- 'NotEqual' as an explicit case of 'Expression' and only ever construct
    -- it as @Not (Equal x y)@.
    --
    -- XXX(jkachmar): Inequality of expressions is tricky business!
    --
    -- We should define the semantics of expression inequality in a way that is
    -- clear and carefully considered.
    NotEqual Expression Expression
  | -- | Apply a comparison 'Operator' to two expressions; the result of this
    -- application will return "true" or "false" depending on the 'Operator'
    -- that's being applied.
    --
    -- XXX(jkachmar): Consider renaming 'Operator' to @ComparisonOperator@ and
    -- this sub-expression to @ApplyComparisonOperator@ for clarity.
    ApplyOperator Operator Expression Expression
  deriving stock (Data, Eq, Generic, Ord, Show)
  deriving anyclass (Cacheable, FromJSON, Hashable, NFData, ToJSON)

--------------------------------------------------------------------------------

-- | Operators which are typically applied to two 'Expression's (via the
-- 'ApplyOperator' sub-'Expression') to perform a boolean comparison.
--
-- cf. https://www.postgresql.org/docs/13/functions-comparison.html
--
-- XXX(jkachmar): Comparison operations are tricky business!
--
-- We should define the semantics of these comparisons in a way that is clear
-- and carefully considered.
data Operator
  = LessThan
  | LessThanOrEqual
  | GreaterThan
  | GreaterThanOrEqual
  deriving stock (Data, Eq, Generic, Ord, Show)
  deriving anyclass (Cacheable, FromJSON, Hashable, NFData, ToJSON)