Skip to main content
Version: v3.x

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:

TypeDescription
ScalarThis specifies how a user able to compare a scalar field.
ObjectThis 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.

KeyValueRequiredDescription
kindBooleanExpressionTypetrue
versionv1true
definitionBooleanExpressionTypeV1trueDefinition 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.

KeyValueRequiredDescription
nameCustomTypeNametrueThe 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.
operandBooleanExpressionOperandtrueThe type that this boolean expression applies to.
logicalOperatorsBooleanExpressionLogicalOperatorstrueWhether to enable _and / _or / _not
isNullBooleanExpressionIsNulltrueWhether to enable _is_null
graphqlBooleanExpressionTypeGraphQlConfiguration / nullfalseConfiguration for how this object type should appear in the GraphQL schema.

BooleanExpressionTypeGraphQlConfiguration

GraphQL configuration of an OpenDD boolean expression type.

KeyValueRequiredDescription
typeNameGraphQlTypeNametrueThe 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

KeyValueRequiredDescription
enablebooleantrue

BooleanExpressionLogicalOperators

Configuration for logical operators in boolean expressions

KeyValueRequiredDescription
enablebooleantrue

BooleanExpressionOperand

Configuration for object or scalar boolean expression

Must have exactly one of the following fields:

KeyValueRequiredDescription
objectBooleanExpressionObjectOperandfalseDefinition of an object type representing a boolean expression on an OpenDD object type.
scalarBooleanExpressionScalarOperandfalseDefinition 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.

KeyValueRequiredDescription
typeTypeNametrueThe OpenDD type name of the scalar type that this boolean expression applies to.
comparisonOperators[ComparisonOperator]trueThe list of comparison operators that can used on this scalar type
dataConnectorOperatorMapping[DataConnectorOperatorMapping]trueThe 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

KeyValueRequiredDescription
dataConnectorNameDataConnectorNametrueName of the data connector this mapping applies to
dataConnectorScalarTypeDataConnectorScalarTypetrueName of the scalar type according to the data connector's schema
operatorMappingoperator_mappingtrueMapping 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.

KeyValueRequiredDescription
<customKey>DataConnectorOperatorNamefalseThe 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

KeyValueRequiredDescription
nameOperatorNametrueName you want to give the operator in OpenDD / GraphQL
argumentTypeTypeReferencetrueAn 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:

ValueDescription
InbuiltTypeAn 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.

KeyValueRequiredDescription
typeCustomTypeNametrueThe name of the object type that this boolean expression applies to.
comparableFields[BooleanExpressionComparableField]trueThe list of fields of the object type that can be used for comparison when evaluating this boolean expression.
comparableRelationships[BooleanExpressionComparableRelationship]trueThe 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

KeyValueRequiredDescription
relationshipNameRelationshipNametrueThe name of the relationship to use for comparison
booleanExpressionTypeCustomTypeName / nullfalseThe 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

KeyValueRequiredDescription
fieldNameFieldNametrue
booleanExpressionTypeCustomTypeNametrue

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.

KeyValueRequiredDescription
kindObjectBooleanExpressionTypetrue
versionv1true
definitionObjectBooleanExpressionTypeV1trueDefinition 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.

KeyValueRequiredDescription
nameCustomTypeNametrueThe 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.
objectTypeCustomTypeNametrueThe name of the object type that this boolean expression applies to.
dataConnectorNameDataConnectorNametrueThe data connector this boolean expression type is based on.
dataConnectorObjectTypeDataConnectorObjectTypetrueThe object type in the data connector's schema this boolean expression type is based on.
comparableFields[ComparableField]trueThe list of fields of the object type that can be used for comparison when evaluating this boolean expression.
graphqlObjectBooleanExpressionTypeGraphQlConfiguration / nullfalseConfiguration for how this object type should appear in the GraphQL schema.

ObjectBooleanExpressionTypeGraphQlConfiguration

GraphQL configuration of an Open DD boolean expression type.

KeyValueRequiredDescription
typeNameGraphQlTypeNametrueThe 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.

KeyValueRequiredDescription
fieldNameFieldNametrue
operatorsEnableAllOrSpecifictrueEnable all or specific values.

EnableAllOrSpecific

Enable all or specific values.

Must have exactly one of the following fields:

KeyValueRequiredDescription
enableAllbooleanfalse
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

Loading...