Skip to main content
Version: v3.x

Aggregate Expressions

Introduction

Aggregate expression types allow you to summarize and calculate collective properties of your data. These expressions enable you to define how to aggregate over different data types, facilitating efficient data manipulation and retrieval.

Aggregate expressions can be used to configure how data is summarized in your models, or as the types of arguments to commands or models.

How AggregateExpressions work

Lifecycle

Examples below

Below this description of the lifecycle are examples for each step and how to define AggregateExpressions in your metadata files.

You'll need to ensure you've generated ScalarTypes and DataConnectorScalarRepresentations for the data types you want to aggregate over. We recommend saving these in your connector's type definition file.

Once you have these, you can create AggregateExpression objects for the types you want to aggregate over. We recommend these be saved in a model's metadata file.

Finally, you'll need to update your graphql-config.hml in the globals subgraph to include an aggregate field in the definition.

Once these are included, you'll need to create a new build using the CLI.

Examples

In the following example, we'll show the snippets necessary to implement the example explained above: an AggregateExpression for the Reviews model of our sample application.

metadata/my_connector-types.hml
# Existing definitions above
---
kind: ScalarType
version: v1
definition:
name: Numeric
graphql:
typeName: Numeric

---
kind: DataConnectorScalarRepresentation
version: v1
definition:
dataConnectorName: my_connector
dataConnectorScalarType: numeric
representation: Numeric
graphql:
comparisonExpressionTypeName: NumericComparisonExp
metadata/Reviews.hml
# Existing objects above
---
kind: AggregateExpression
version: v1
definition:
name: Int4_aggregate_exp
operand:
scalar:
aggregatedType: Int4
aggregationFunctions:
- name: avg
returnType: Numeric
dataConnectorAggregationFunctionMapping:
- dataConnectorName: my_connector
dataConnectorScalarType: int4
functionMapping:
avg:
name: avg
graphql:
selectTypeName: Int4_aggregate_fields

---
kind: AggregateExpression
version: v1
definition:
name: Reviews_aggregate_exp
operand:
object:
aggregatedType: Reviews
aggregatableFields:
- fieldName: rating
aggregateExpression: Int4_aggregate_exp
graphql:
selectTypeName: Reviews_aggregate_fields
description: Aggregate over Reviews
globals/graphql-config.hml
kind: GraphqlConfig
version: v1
definition:
query:
rootOperationTypeName: Query
argumentsInput:
fieldName: args
limitInput:
fieldName: limit
offsetInput:
fieldName: offset
filterInput:
fieldName: where
operatorNames:
and: _and
or: _or
not: _not
isNull: _is_null
orderByInput:
fieldName: order_by
enumDirectionValues:
asc: Asc
desc: Desc
enumTypeNames:
- directions:
- Asc
- Desc
typeName: OrderBy
aggregate:
filterInputFieldName: filter_input
countFieldName: _count
countDistinctFieldName: _count_distinct
mutation:
rootOperationTypeName: Mutation

Metadata structure

AggregateExpression

Definition of an aggregate expression on an OpenDD type.

KeyValueRequiredDescription
kindAggregateExpressiontrue
versionv1true
definitionAggregateExpressionV1trueDefinition of how to aggregate over a particular operand type

Example:

kind: AggregateExpression
version: v1
definition:
name: Invoice_aggregate_exp
operand:
object:
aggregatedType: Invoice
aggregatableFields:
- fieldName: Total
aggregateExpression: Float_aggregate_exp
graphql:
selectTypeName: Invoice_aggregate_fields
description: Aggregate over Invoices

AggregateExpressionV1

Definition of how to aggregate over a particular operand type

KeyValueRequiredDescription
nameAggregateExpressionNametrueThe name of the aggregate expression.
operandAggregateOperandtrueThe type this aggregation expression aggregates over, and its associated configuration
countAggregateCountDefinition / nullfalseConfiguration for the count aggregate function used over the operand
countDistinctAggregateCountDefinition / nullfalseConfiguration for the count distinct aggregate function used over the operand
graphqlAggregateExpressionGraphQlDefinition / nullfalseConfiguration for how this command should appear in the GraphQL schema.
descriptionstring / nullfalseThe description of the aggregate expression. Gets added to the description of the command's root field in the GraphQL schema.

AggregateExpressionGraphQlDefinition

The definition of how an aggregate expression should appear in the GraphQL API.

KeyValueRequiredDescription
selectTypeNameGraphQlTypeNametrueThe type name to use for the aggregate selection type
deprecatedDeprecated / nullfalseWhether this command root field is deprecated. If set, this will be added to the graphql schema as a deprecated field.

Example:

selectTypeName: Invoice_aggregate_fields

Deprecated

OpenDd configuration to indicate whether an object type field, relationship, model root field or command root field is deprecated.

KeyValueRequiredDescription
reasonstring / nullfalseThe reason for deprecation.

GraphQlTypeName

The name of a GraphQL type.

Value: string

AggregateCountDefinition

Definition of a count aggregation function

KeyValueRequiredDescription
enablebooleantrueWhether or not the aggregate function is available for use or not
descriptionstring / nullfalseA description of the aggregation function. Gets added to the description of the field in the GraphQL schema.

AggregateOperand

Definition of an aggregate expression's operand

Must have exactly one of the following fields:

KeyValueRequiredDescription
objectObjectAggregateOperandfalseDefinition of an aggregate over an object-typed operand
scalarScalarAggregateOperandfalseDefinition of an aggregate over a scalar-typed operand

ScalarAggregateOperand

Definition of an aggregate over a scalar-typed operand

KeyValueRequiredDescription
aggregatedTypeTypeNametrueThe name of the scalar type the aggregate expression is aggregating
aggregationFunctions[AggregationFunctionDefinition]trueThe aggregation functions that operate over the scalar type
dataConnectorAggregationFunctionMapping[DataConnectorAggregationFunctionMapping]trueMapping of aggregation functions to corresponding aggregation functions in various data connectors

DataConnectorAggregationFunctionMapping

Definition of how to map an aggregate expression's aggregation functions to data connector aggregation functions.

KeyValueRequiredDescription
dataConnectorNameDataConnectorNametrueThe data connector being mapped to
dataConnectorScalarTypeDataConnectorScalarTypetrueThe matching scalar type in the data connector for the operand scalar type
functionMappingAggregationFunctionMappingstrueMapping from Open DD aggregation function to data connector aggregation function

AggregationFunctionMappings

Mapping of aggregation functions to their matching aggregation functions in the data connector.

KeyValueRequiredDescription
<customKey>AggregateFunctionMappingfalseDefinition of how to map the aggregation function to a function in the data connector

AggregateFunctionMapping

Definition of how to map the aggregation function to a function in the data connector

KeyValueRequiredDescription
nameDataConnectorAggregationFunctionNametrueThe name of the aggregation function in the data connector

DataConnectorAggregationFunctionName

The name of an aggregation function 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

AggregationFunctionDefinition

Definition of an aggregation function

KeyValueRequiredDescription
nameAggregationFunctionNametrueThe name of the aggregation function
descriptionstring / nullfalseA description of the aggregation function. Gets added to the description of the field in the GraphQL schema.
returnTypeTypeReferencetrue

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

AggregationFunctionName

The name of an aggregation function.

Value: string

TypeName

The name of the scalar type the aggregate expression is aggregating

One of the following values:

ValueDescription
InbuiltTypeAn inbuilt primitive OpenDD type.
CustomTypeName

InbuiltType

An inbuilt primitive OpenDD type.

Value: ID / Int / Float / Boolean / String

ObjectAggregateOperand

Definition of an aggregate over an object-typed operand

KeyValueRequiredDescription
aggregatedTypeCustomTypeNametrueThe name of the object type the aggregate expression is aggregating
aggregatableFields[AggregatableFieldDefinition]trueThe fields on the object that are aggregatable

AggregatableFieldDefinition

Definition of an aggregatable field on an object type

KeyValueRequiredDescription
fieldNameFieldNametrueThe name of the field on the operand aggregated type that is aggregatable
descriptionstring / nullfalseA description of the aggregatable field. Gets added to the description of the field in the GraphQL schema.
aggregateExpressionAggregateExpressionNametrueThe aggregate expression used to aggregate 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

AggregateExpressionName

The name of an aggregate expression.

Value: string

Loading...