Default values

This page describes how to use default values in the Neo4j GraphQL Library.

@default

When generating the input type for the create` mutation, the value specified in this directive is used as the default value for this field.

Definition

"""Int | Float | String | Boolean | ID | DateTime | Enum"""
scalar Scalar

"""Instructs @neo4j/graphql to set the specified value as the default value in the CreateInput type for the object type in which this directive is used."""
directive @default(
    """The default value to use. Must be a scalar type and must match the type of the field with which this directive decorates."""
    value: Scalar!,
) on FIELD_DEFINITION

Usage

@default may be used with enums. When setting the default value for an enum field, it must be one of the enumerated enum values:

enum Location {
    HERE
    THERE
    EVERYWHERE
}

type SomeType {
    firstLocation: Location! @default(value: HERE) # valid usage
    secondLocation: Location! @default(value: ELSEWHERE) # invalid usage, will throw an error
}

@coalesce

When translating from GraphQL to Cypher, any instances of fields to which this directive is applied will be wrapped in a coalesce() function in the WHERE clause (see https://neo4j.com/developer/kb/understanding-non-existent-properties-and-null-values/#_use_coalesce_to_use_a_default_for_a_null_value).

This directive helps querying against non-existent properties in a database. However, it is encouraged to populate these properties with meaningful values if this is becoming the norm. The `@coalesce`directive is a primitive implementation of the function which only takes a static default value as opposed to using another property in a node or a Cypher expression.

Definition

"""Int | Float | String | Boolean | ID | DateTime | Enum"""
scalar ScalarOrEnum

"""Instructs @neo4j/graphql to wrap the property in a coalesce() function during queries, using the single value specified."""
directive @coalesce(
    """The value to use in the coalesce() function. Must be a scalar type and must match the type of the field with which this directive decorates."""
    value: Scalar!,
) on FIELD_DEFINITION

Usage

@coalesce may be used with enums. When setting the default value for an enum field, it must be one of the enumerated enum values:

enum Status {
    ACTIVE
    INACTIVE
}
type Movie {
    status: Status @coalesce(value: ACTIVE)
}

@limit

Available on nodes, this directive injects values into a query such as the limit.

Definition

"""The `@limit` is to be used on nodes, where applied will inject values into a query such as the `limit`."""
directive @limit(
    default: Int
    max: Int
) on OBJECT

Usage

The directive has two arguments:

  • default - if no limit argument is passed to the query, the default limit is used. The query may still pass a higher or lower limit.

  • max - defines the maximum limit to be passed to the query. If a higher value is passed, it is used instead. If no default value is set, max is used for queries without limit.

{
  Movie @limit(amount: 5) {
    title
    year
  }
}