Boolean Expressions
Introduction
Hasura provides powerful tools to control filtering and selecting data. Boolean expression types let you control which filters are available for a model or command. They can be used to configure filters on models, such as in the filtering section, or as the types of arguments to commands or models.
How Boolean expressions work
Lifecycle
There are two types of boolean expressions:
| Type | Description |
|---|---|
| Scalar | This specifies how a user able to compare a scalar field. |
| Object | This specifies how fields of a type can be filtered. |
Regardless of the type, boolean expressions are used to define how a user is able to filter data and are defined in your metadata.
Examples
Scalar
This specifies how a user is able to compare a scalar field. For instance, you might want to say that a user can only
check if a String type is equals to another, or whether it is null or not. You can do that with the following
metadata:
kind: BooleanExpressionType
version: v1
definition:
name: String_comparison_exp_with_eq_and_is_null
operand:
scalar:
type: String
comparisonOperators:
- name: equals
argumentType: String!
dataConnectorOperatorMapping:
- dataConnectorName: postgres
dataConnectorScalarType: varchar
operatorMapping:
equals: _eq
logicalOperators:
enable: true
isNull:
enable: true
graphql:
typeName: String_comparison_exp_with_eq_and_is_null
Note the dataConnectorOperatorMapping. This allows us to define what these operators mean in zero or more data
connectors. Here, we want our equals operator to use Postgres's _eq operator.
This would allow us to write filters like:
{ "first_name": { "_is_null": true } }
{ "last_name": { "equals": "Bruce" } }
Object
An object BooleanExpressionType is used to define how fields of a type can be filtered. Note that nothing here talks
about specific data connectors - instead you can specify which BooleanExpressionType is used to filter each field or
relationship, and then defer the mappings of individual scalar types to those BooleanExpressionTypes.
kind: BooleanExpressionType
version: v2
definition:
name: Album_bool_exp
operand:
object:
type: Album
comparableFields:
- fieldName: AlbumId
booleanExpressionType: Int_comparison_exp
- fieldName: ArtistId
booleanExpressionType: Int_comparison_exp_with_is_null
- fieldName: Address
booleanExpressionType: Address_bool_exp
comparableRelationships:
- relationshipName: artist
booleanExpressionType: Artist_bool_exp
logicalOperators:
enable: true
isNull:
enable: true
graphql:
typeName: Album_bool_exp
Note here that we can specify different comparison operators for AlbumId and ArtistId by using different
BooleanExpressionTypes for them. We are also able to define filtering on nested objects such as Address.
The above would let us write filters on Album types like:
{ "album": { "AlbumId": { "equals": 100 } } }
{ "album": { "Address": { "postcode": { "like": "N1" } } } }
{ "album": { "artist": { "name": { "equals": "Madonna" } } } }
Metadata structure
BooleanExpressionType
Definition of a type representing a boolean expression on an OpenDD type.
| Key | Value | Required | Description |
|---|---|---|---|
kind | BooleanExpressionType | true | |
version | v1 | true | |
definition | BooleanExpressionTypeV1 | true | Definition of a type representing a boolean expression on an OpenDD object type. |
Example:
kind: BooleanExpressionType
version: v1
definition:
name: Album_bool_exp
operand:
object:
type: Album
comparableFields:
- fieldName: AlbumId
booleanExpressionType: pg_Int_Comparison_exp
- fieldName: ArtistId
booleanExpressionType: pg_Int_Comparison_exp_with_is_null
- fieldName: Address
booleanExpressionType: Address_bool_exp
comparableRelationships:
- relationshipName: artist
booleanExpressionType: Artist_bool_exp
logicalOperators:
enable: true
isNull:
enable: true
graphql:
typeName: App_Album_bool_exp
BooleanExpressionTypeV1
Definition of a type representing a boolean expression on an OpenDD object type.
| Key | Value | Required | Description |
|---|---|---|---|
name | CustomTypeName | true | The name to give this boolean expression type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph. |
operand | BooleanExpressionOperand | true | The type that this boolean expression applies to. |
logicalOperators | BooleanExpressionLogicalOperators | true | Whether to enable _and / _or / _not |
isNull | BooleanExpressionIsNull | true | Whether to enable _is_null |
graphql | BooleanExpressionTypeGraphQlConfiguration / null | false | Configuration for how this object type should appear in the GraphQL schema. |
BooleanExpressionTypeGraphQlConfiguration
GraphQL configuration of an OpenDD boolean expression type.
| Key | Value | Required | Description |
|---|---|---|---|
typeName | GraphQlTypeName | true | The name to use for the GraphQL type representation of this boolean expression type. |
GraphQlTypeName
The name of a GraphQL type.
Value: string
BooleanExpressionIsNull
Configuration for is_null in boolean expressions
| Key | Value | Required | Description |
|---|---|---|---|
enable | boolean | true |
BooleanExpressionLogicalOperators
Configuration for logical operators in boolean expressions
| Key | Value | Required | Description |
|---|---|---|---|
enable | boolean | true |
BooleanExpressionOperand
Configuration for object or scalar boolean expression
Must have exactly one of the following fields:
| Key | Value | Required | Description |
|---|---|---|---|
object | BooleanExpressionObjectOperand | false | Definition of an object type representing a boolean expression on an OpenDD object type. |
scalar | BooleanExpressionScalarOperand | false | Definition of a scalar type representing a boolean expression on an OpenDD scalar type. |
BooleanExpressionScalarOperand
Definition of a scalar type representing a boolean expression on an OpenDD scalar type.
| Key | Value | Required | Description |
|---|---|---|---|
type | TypeName | true | The OpenDD type name of the scalar type that this boolean expression applies to. |
comparisonOperators | [ComparisonOperator] | true | The list of comparison operators that can used on this scalar type |
dataConnectorOperatorMapping | [DataConnectorOperatorMapping] | true | The list of mappings between OpenDD operator names and the names used in the data connector schema |
DataConnectorOperatorMapping
Mapping between OpenDD operator names and the names used in the data connector schema
| Key | Value | Required | Description |
|---|---|---|---|
dataConnectorName | DataConnectorName | true | Name of the data connector this mapping applies to |
dataConnectorScalarType | DataConnectorScalarType | true | Name of the scalar type according to the data connector's schema |
operatorMapping | operator_mapping | true | Mapping between OpenDD operator names and the data connector's operator names Defaults to the same operator name (e.g. "_eq: _eq") if no explicit mapping is present. |
operator_mapping
Mapping between OpenDD operator names and the data connector's operator names Defaults to the same operator name (e.g. "_eq: _eq") if no explicit mapping is present.
| Key | Value | Required | Description |
|---|---|---|---|
<customKey> | DataConnectorOperatorName | false | The name of an operator in a data connector. |
DataConnectorOperatorName
The name of an operator in a data connector.
Value: string
DataConnectorScalarType
The name of a scalar type in a data connector.
Value: string
DataConnectorName
The name of a data connector.
Value: string
ComparisonOperator
Definition of a comparison operator for a scalar type
| Key | Value | Required | Description |
|---|---|---|---|
name | OperatorName | true | Name you want to give the operator in OpenDD / GraphQL |
argumentType | TypeReference | true | An OpenDD type |
TypeReference
A reference to an Open DD type including nullable values and arrays. Suffix '!' to indicate a non-nullable reference, and wrap in '[]' to indicate an array. Eg: '[String!]!' is a non-nullable array of non-nullable strings.
Value: string
OperatorName
The name of an operator
Value: string
TypeName
The OpenDD type name of the scalar type that this boolean expression applies to.
One of the following values:
| Value | Description |
|---|---|
| InbuiltType | An inbuilt primitive OpenDD type. |
| CustomTypeName |
InbuiltType
An inbuilt primitive OpenDD type.
Value: ID / Int / Float / Boolean / String
BooleanExpressionObjectOperand
Definition of an object type representing a boolean expression on an OpenDD object type.
| Key | Value | Required | Description |
|---|---|---|---|
type | CustomTypeName | true | The name of the object type that this boolean expression applies to. |
comparableFields | [BooleanExpressionComparableField] | true | The list of fields of the object type that can be used for comparison when evaluating this boolean expression. |
comparableRelationships | [BooleanExpressionComparableRelationship] | true | The list of relationships of the object type that can be used for comparison when evaluating this boolean expression. |
BooleanExpressionComparableRelationship
Definition of a relationship that can be used for a comparison
| Key | Value | Required | Description |
|---|---|---|---|
relationshipName | RelationshipName | true | The name of the relationship to use for comparison |
booleanExpressionType | CustomTypeName / null | false | The boolean expression type to use for comparison. This is optional for relationships to models, and defaults to the filterExpressionType of the model |
RelationshipName
The name of the GraphQL relationship field.
Value: string
BooleanExpressionComparableField
Comparison configuration definition for a field that can be used for a comparison
| Key | Value | Required | Description |
|---|---|---|---|
fieldName | FieldName | true | The name of the field that can be compared. |
booleanExpressionType | CustomTypeName | true | The boolean expression type that can be used for comparison against the type of the field. |
FieldName
The name of a field in a user-defined object type.
Value: string
CustomTypeName
The name of a user-defined type.
Value: string
ObjectBooleanExpressionType
Definition of a type representing a boolean expression on an Open DD object type.
| Key | Value | Required | Description |
|---|---|---|---|
kind | ObjectBooleanExpressionType | true | |
version | v1 | true | |
definition | ObjectBooleanExpressionTypeV1 | true | Definition of a type representing a boolean expression on an Open DD object type. Deprecated in favour of BooleanExpressionType. |
Example:
kind: ObjectBooleanExpressionType
version: v1
definition:
name: AuthorBoolExp
objectType: Author
dataConnectorName: my_db
dataConnectorObjectType: author
comparableFields:
- fieldName: article_id
operators:
enableAll: true
- fieldName: title
operators:
enableAll: true
- fieldName: author_id
operators:
enableAll: true
graphql:
typeName: Author_bool_exp
ObjectBooleanExpressionTypeV1
Definition of a type representing a boolean expression on an Open DD object type. Deprecated in favour of BooleanExpressionType.
| Key | Value | Required | Description |
|---|---|---|---|
name | CustomTypeName | true | The name to give this object boolean expression type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph. |
objectType | CustomTypeName | true | The name of the object type that this boolean expression applies to. |
dataConnectorName | DataConnectorName | true | The data connector this boolean expression type is based on. |
dataConnectorObjectType | DataConnectorObjectType | true | The object type in the data connector's schema this boolean expression type is based on. |
comparableFields | [ComparableField] | true | The list of fields of the object type that can be used for comparison when evaluating this boolean expression. |
graphql | ObjectBooleanExpressionTypeGraphQlConfiguration / null | false | Configuration for how this object type should appear in the GraphQL schema. |
ObjectBooleanExpressionTypeGraphQlConfiguration
GraphQL configuration of an Open DD boolean expression type.
| Key | Value | Required | Description |
|---|---|---|---|
typeName | GraphQlTypeName | true | The name to use for the GraphQL type representation of this boolean expression type. |
GraphQlTypeName
The name of a GraphQL type.
Value: string
ComparableField
A field of an object type that can be used for comparison when evaluating a boolean expression.
| Key | Value | Required | Description |
|---|---|---|---|
fieldName | FieldName | true | |
operators | EnableAllOrSpecific | true | Enable all or specific values. |
EnableAllOrSpecific
Enable all or specific values.
Must have exactly one of the following fields:
| Key | Value | Required | Description |
|---|---|---|---|
enableAll | boolean | false | |
enableSpecific | [OperatorName] | false |
OperatorName
The name of an operator
Value: string
FieldName
The name of a field in a user-defined object type.
Value: string
DataConnectorObjectType
The name of an object type in a data connector.
Value: string
DataConnectorName
The name of a data connector.
Value: string
CustomTypeName
The name of a user-defined type.
Value: string
