Configuration for GraphQL API

Introduction

The GraphqlConfig object allows you to configure the GraphQL schema generated by Hasura. This object helps you configure the common GraphQL schema applicable to all subgraphs within a project.

The GraphqlConfig object belongs to the supergraph and can be defined once across your supergraph in any subgraph of your choice.

How GraphqlConfig works

Lifecycle

By default, all projects are created with a default GraphqlConfig object in the globals subgraph.

Specifically, it allows you to configure:

1. The root type names for query, mutation and subscription operations.
2. The name for model selection input field names (where, limit, offset, args, order_by)
3. The enum values for order_by directions and the order_by enum type name.

An GraphqlConfig object is required to be defined in the supergraph metadata. If not defined, any attempted builds will not be successful.

Examples

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
  mutation:
    rootOperationTypeName: Mutation
  apolloFederation:
    enableRootFields: false

Field	Description	Reference
kind	The type of configuration you're defining, in this case, it's for GraphQL API settings.	GraphqlConfig
version	The version of this configuration object.	GraphqlConfigV1
definition.query.rootOperationTypeName	The name used for the root query type in your GraphQL schema, usually Query.	QueryGraphqlConfig
definition.query.argumentsInput.fieldName	The field name used for passing arguments in queries, usually args.	ArgumentsInputGraphqlConfig
definition.query.limitInput.fieldName	The field name used to limit the number of results, typically limit.	LimitInputGraphqlConfig
definition.query.offsetInput.fieldName	The field name used to set the starting point for results, typically offset.	OffsetInputGraphqlConfig
definition.query.filterInput.fieldName	The field name used for filtering results, usually where.	FilterInputGraphqlConfig
definition.query.filterInput.operatorNames[]	The names of the built-in filter operators.	FilterInputOperatorNames
definition.query.orderByInput.fieldName	The field name used for sorting results, usually order_by.	OrderByInputGraphqlConfig
definition.query.orderByInput.enumDirectionValues[]	The names of the direction parameters, like asc and desc.	OrderByDirectionValues
definition.query.orderByInput.enumTypeNames	The name of the enum type used for sorting, like OrderBy.	OrderByEnumTypeName
definition.mutation.rootOperationTypeName	The name used for the root mutation type in your GraphQL schema, usually Mutation.	MutationGraphqlConfig
definition.apolloFederation.enableRootFields	A setting to enable or disable fields needed for Apollo Federation (_entities, _services).	GraphqlApolloFederationConfig

---

Metadata structure

GraphqlConfig

GraphqlConfig object tells us two things:

1. How the Graphql schema should look like for the features (where, order_by etc) Hasura provides 2. What features should be enabled/disabled across the subgraphs

Key	Value	Required	Description
kind	GraphqlConfig	true
version	v1	true
definition	GraphqlConfigV1	true	GraphqlConfig object tells us two things: 1. How the Graphql schema should look like for the features (where, order_by etc) Hasura provides 2. What features should be enabled/disabled across the subgraphs

GraphqlConfigV1

GraphqlConfig object tells us two things:

1. How the Graphql schema should look like for the features (where, order_by etc) Hasura provides 2. What features should be enabled/disabled across the subgraphs

Key	Value	Required	Description
query	QueryGraphqlConfig	true	Configuration for the GraphQL schema of Hasura features for queries. None means disable the feature.
mutation	MutationGraphqlConfig	true	Configuration for the GraphQL schema of Hasura features for mutations.
subscription	SubscriptionGraphqlConfig / null	false
apolloFederation	GraphqlApolloFederationConfig / null	false

GraphqlApolloFederationConfig

Configuration for the GraphQL schema of Hasura features for Apollo Federation.

Key	Value	Required	Description
enableRootFields	boolean	true	Adds the _entities and _services root fields required for Apollo Federation.

SubscriptionGraphqlConfig

Configuration for the GraphQL schema of Hasura features for subscriptions.

Key	Value	Required	Description
rootOperationTypeName	GraphQlTypeName	true	The name of the root operation type name for subscriptions. Usually subscription.

MutationGraphqlConfig

Configuration for the GraphQL schema of Hasura features for mutations.

Key	Value	Required	Description
rootOperationTypeName	GraphQlTypeName	true	The name of the root operation type name for mutations. Usually mutation.

QueryGraphqlConfig

Configuration for the GraphQL schema of Hasura features for queries. None means disable the feature.

Key	Value	Required	Description
rootOperationTypeName	GraphQlTypeName	true	The name of the root operation type name for queries. Usually query.
argumentsInput	ArgumentsInputGraphqlConfig / null	false	Configuration for the arguments input.
limitInput	LimitInputGraphqlConfig / null	false	Configuration for the limit operation.
offsetInput	OffsetInputGraphqlConfig / null	false	Configuration for the offset operation.
filterInput	FilterInputGraphqlConfig / null	false	Configuration for the filter operation.
orderByInput	OrderByInputGraphqlConfig / null	false	Configuration for the sort operation.
aggregate	AggregateGraphqlConfig / null	false	Configuration for aggregates

AggregateGraphqlConfig

Configuration for the GraphQL schema for aggregates.

Key	Value	Required	Description
filterInputFieldName	GraphQlFieldName	true	The name of the filter input parameter of aggregate fields and field name in predicates
countFieldName	GraphQlFieldName	true	The name of the _count field used for the count aggregate function
countDistinctFieldName	GraphQlFieldName	true	The name of the _count_distinct field used for the count distinct aggregate function

OrderByInputGraphqlConfig

Configuration for the sort operation.

Key	Value	Required	Description
fieldName	GraphQlFieldName	true	The name of the filter operation field. Usually order_by.
enumDirectionValues	OrderByDirectionValues	true	The names of the direction parameters.
enumTypeNames	[OrderByEnumTypeName]	true

OrderByEnumTypeName

Type name for a sort directions enum, with the given set of possible directions.

Key	Value	Required	Description
directions	[OrderByDirection]	true
typeName	GraphQlTypeName	true

OrderByDirection

Sort direction.

One of the following values:

Value	Description
Asc	Ascending.
Desc	Descending.

OrderByDirectionValues

The names of the direction parameters.

Key	Value	Required	Description
asc	GraphQlFieldName	true	The name of the ascending parameter. Usually Asc.
desc	GraphQlFieldName	true	The name of the descending parameter. Usually Desc.

FilterInputGraphqlConfig

Configuration for the filter operation.

Key	Value	Required	Description
fieldName	GraphQlFieldName	true	The name of the filter operation field. Usually where.
operatorNames	FilterInputOperatorNames	true	The names of built-in filter operators.

FilterInputOperatorNames

The names of built-in filter operators.

Key	Value	Required	Description
and	GraphQlFieldName	true	The name of the and operator. Usually _and.
or	GraphQlFieldName	true	The name of the or operator. Usually _or.
not	GraphQlFieldName	true	The name of the not operator. Usually _not.
isNull	GraphQlFieldName	true	The name of the is null operator. Usually _is_null.

OffsetInputGraphqlConfig

Configuration for the offset operation.

Key	Value	Required	Description
fieldName	GraphQlFieldName	true	The name of the offset operation field. Usually offset.

LimitInputGraphqlConfig

Configuration for the limit operation.

Key	Value	Required	Description
fieldName	GraphQlFieldName	true	The name of the limit operation field. Usually limit.

ArgumentsInputGraphqlConfig

Configuration for the arguments input.

Key	Value	Required	Description
fieldName	GraphQlFieldName	true	The name of arguments passing field. Usually args.

GraphQlFieldName

The name of a GraphQL object field.

Value: string

GraphQlTypeName

The name of a GraphQL type.

Value: string