graphql-engine/v3/rfcs/open-dd-boolean-expression-types.md

# Boolean Expression Types in OpenDD

## Motivation

All mutations in NDC are implemented as standalone procedures, whose semantics are opaque to OpenDD. In order to provide the ability to filter rows on which a procedure would apply, NDC is [introducing](https://github.com/hasura/ndc-spec/pull/83) boolean expression types as procedure arguments. Consequently, we would also need to support boolean expressions as arguments in OpenDD.
Since OpenDD already uses boolean expressions (called filter expressions) for filtering models as a part of select many, we would want to unify the two definitions.

## Proposal

### kind: ObjectFilterExpressionType

The first proposal is to introduce a new OpenDD object type for filter expressions. This will allow us to exact;u define filter expressions and reuse them across models and command arguments.

```yaml
kind: ObjectFilterExpressionType
version: v1
definition:
  name: AuthorFilterExpression
  objectType: Author
  dataConnectorName: my_db
  dataConnectorObjectType: author
  filterableFields:
    - fieldName: id
      comparisonExpression:
        operators:
            enableAll: true
    - fieldName: name
      comparisonExpression:
        operators:
          enableSpecific: ["_eq", "_like"]
    graphql:
      typeName: Author_bool_exp
```

### Move type mappings to kind: ObjectType

Currently type mappings are specified as a part of model / command source, where we define how the object types used in a particular model map to object types used in the source data connector. It was designed this way so that `kind: ObjectType` was defined purely in terms of OpenDD and coupling to a connector was done only in `kind: Model` / `kind: Command`. However, now that mutations will be opaque commands, we expect an ObjectType used within a model to be commonly reused across multiple commands, making it verbose to redefine the type mappings for every command.

Hence, the second proposal is to move type mappings as a part of `kind: ObjectType` and removed from `kind: Model` / `kind: Command`. This is also more intuitive to understand for a reader of OpenDD.

```yaml
kind: ObjectType
version: v1
definition:
  name: Author
  fields:
    - name: id
      type: Int!
    - name: name
      type: String
  dataConnectorTypeMapping: # Optional key
    - dataConnectorName: my_db
      dataConnectorObjectType: author
      fieldMapping:
        id:
          column: author_id
        name:
          column: author_name
```

### Update kind: Model / kind: Command

Since filter expressions and type mappings are now being defined elsewhere, updates are needed to `kind: Model`.
- Remove the `typeMappings` key from the `source` field of the model definition.
- Remove the `filterExpressionType` key from the `graphql` field of the model definition.
- Remove the `filterable_fields` key from the model definition.
- Introduce a `filterExpressionType` key to the model definition, which is optional and points to an existing `ObjectFilterExpressionType` that is defined on the same object type as the model's object type.
  
```yaml
kind: Model
version: v1
definition:
  name: Authors
  objectType: Author
  filterExpressionType: AuthorFilterExpression
  orderableFields: ...
  graphql:
    orderByExpressionType: Author_order_by
    selectMany:
     queryRootField: authors
  source:
    dataConnectorName: author
```

Similarly, we would remove `typeMappings` key from the `source` field of the command definition.

## Alternatives Considered

A couple of alternatives were considered, but rejected.

### Implicit boolean expression types, fully qualified on reference
```yaml
kind: Command
version: v1
definition:
  arguments:
    - name: where
      type:
        booleanExpression:
          objectType: Author
          filterableFields: ...
          graphql:
            typeName: Author_bool_exp

```

There would be too much repition and it would be the inconsistent with the rest of OpenDD where you can only refer to explicitly defined types.

### Boolean expression types attached to kind: ObjectType

```yaml
kind: ObjectType
version: v1
definition:
    name: Author
    fields: ...
    filterExpressions:
      name: AuthorFilterExpression
      dataConnectorName: my_db
      dataConnectorObjectType: author
      filterableFields: ...
      graphql:
        typeName: Author_bool_exp
```

The problem with this is it is unclear whether the name `AuthorFilterExpression` shares the same namespace with other OpenDD types.
- If yes, it is inconsistent to define a named OpenDD type that is not its own kind.
- If no, then type references become more complicated:
```yaml
- name: id
  type:
    regular: Int!
- name: where
  type:
    booleanExpression: AuthorFilterExpression
```