Commands

Introduction

In Hasura DDN, a command represents an action that can be executed within your data domain. Commands act as the verbs or operations that modify or interact with the data managed by your models. They can be triggered via GraphQL queries or mutations.

Commands have a fixed definition and are backed by functions (exposed as queries) or procedures (exposed as mutations) allowing you to add top-level methods to your API, or, add a custom field to an existing model.

Commands also allow you to execute custom business logic directly from your GraphQL API and are useful in validating, processing or enriching data, calling another API, or, for example, logging a user in.

How commands work

Lifecycle

Commands can be added to your metadata using the CLI. The CLI will use a connector's DataConnectorLink object to determine which functions or procedures are available to be added as commands.

You should update your commands whenever you make changes to your data sources and, in turn, your DataConnectorLink objects. This ensures that your API remains in sync with your data.

As an example, if you're usings the TypesScript connector for business logic and add a new function, you'll need to update your DataConnectorLink to ensure that the new function is present in the connector's configuration. Then, add the new command to your metadata.

To make a new command available in your supergraph, you'll need to create a new build using the CLI.

Examples

The following is an example of a command for a function:

---
kind: Command
version: v1
definition:
  name: Hello
  outputType: String!
  arguments:
    - name: name
      type: String
  source:
    dataConnectorName: my_data_connector
    dataConnectorCommand:
      function: hello
  graphql:
    rootFieldName: hello
    rootFieldKind: Query

Field	Description	Reference
kind	Specifies the type of object being defined, which is a command in this context.	Command
version	Indicates the version of the command's structure.	CommandV1
definition.name	The name of the command, representing the action to be executed. You can configure this to whatever you wish.	CommandName
definition.outputType	Defines the return type of the command, specifying what kind of data is returned after execution.	TypeReference
definition.arguments	Lists the arguments the command can take, allowing customization of the command's execution based on input parameters.	ArgumentDefinition
definition.source.dataConnectorName	The name of the data connector that backs this command, linking it to the data source or function.	DataConnectorName
definition.source.dataConnectorCommand	Specifies the function or procedure in the data connector's configuration file(s) that implements the command's logic.	DataConnectorCommand
definition.graphql.rootFieldName	The name of the root field in the GraphQL API for invoking this command.	GraphQlFieldName
definition.graphql.rootFieldKind	Determines whether the command should be part of the Query or Mutation root in the GraphQL API.	GraphQlRootFieldKind

The HML example above results in this query:

query {
  hello(name: "Hasura")
}

---

Metadata structure

Command

The definition of a command. A command is a user-defined operation which can take arguments and returns an output. The semantics of a command are opaque to the Open DD specification.

Key	Value	Required	Description
kind	Command	true
version	v1	true
definition	CommandV1	true	Definition of an OpenDD Command, which is a custom operation that can take arguments and returns an output. The semantics of a command are opaque to OpenDD.

Example:

kind: Command
version: v1
definition:
  name: get_latest_article
  outputType: commandArticle
  arguments: []
  source:
    dataConnectorName: data_connector
    dataConnectorCommand:
      function: latest_article
    argumentMapping: {}
  graphql:
    rootFieldName: getLatestArticle
    rootFieldKind: Query
  description: Get the latest article

CommandV1

Definition of an OpenDD Command, which is a custom operation that can take arguments and returns an output. The semantics of a command are opaque to OpenDD.

Key	Value	Required	Description
name	CommandName	true	The name of the command.
outputType	TypeReference	true	The return type of the command.
arguments	[ArgumentDefinition]	false	The list of arguments accepted by this command. Defaults to no arguments.
source	CommandSource / null	false	The source configuration for this command.
graphql	CommandGraphQlDefinition / null	false	Configuration for how this command should appear in the GraphQL schema.
description	string / null	false	The description of the command. Gets added to the description of the command's root field in the GraphQL schema.

CommandGraphQlDefinition

The definition of how a command should appear in the GraphQL API.

Key	Value	Required	Description
rootFieldName	GraphQlFieldName	true	The name of the graphql root field to use for this command.
rootFieldKind	GraphQlRootFieldKind	true	Whether to put this command in the Query or Mutation root of the GraphQL API.
deprecated	Deprecated / null	false	Whether this command root field is deprecated. If set, this will be added to the graphql schema as a deprecated field.

Example:

rootFieldName: getLatestArticle
rootFieldKind: Query

Deprecated

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

Key	Value	Required	Description
reason	string / null	false	The reason for deprecation.

GraphQlRootFieldKind

Whether to put this command in the Query or Mutation root of the GraphQL API.

Value: Query / Mutation

GraphQlFieldName

The name of a GraphQL object field.

Value: string

CommandSource

Description of how a command maps to a particular data connector

Key	Value	Required	Description
dataConnectorName	DataConnectorName	true	The name of the data connector backing this command.
dataConnectorCommand	DataConnectorCommand	true	The function/procedure in the data connector that backs this command.
argumentMapping	ArgumentMapping	false	Mapping from command argument names to data connector function or procedure argument names.

Example:

dataConnectorName: data_connector
dataConnectorCommand:
  function: latest_article
argumentMapping: {}

ArgumentMapping

Mapping of a comand or model argument name to the corresponding argument name used in the data connector. The key of this object is the argument name used in the command or model and the value is the argument name used in the data connector.

Key	Value	Required	Description
<customKey>	DataConnectorArgumentName	false

DataConnectorArgumentName

The name of an argument as defined by a data connector.

Value: string

DataConnectorCommand

The function/procedure in the data connector that backs this command.

Must have exactly one of the following fields:

Key	Value	Required	Description
function	FunctionName	false	The name of a function backing the command.
procedure	ProcedureName	false	The name of a procedure backing the command.

ProcedureName

The name of a procedure backing the command.

Value: string

FunctionName

The name of a function backing the command.

Value: string

DataConnectorName

The name of a data connector.

Value: string

ArgumentDefinition

The definition of an argument for a field, command, or model.

Key	Value	Required	Description
name	ArgumentName	true	The name of an argument.
type	TypeReference	true
description	string / null	false

ArgumentName

The name of an argument.

Value: string

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

CommandName

The name of a command.

Value: string