Commands

Introduction

Commands are backed by functions or procedures declared in a DataConnectorLink allowing you to execute business logic directly from your GraphQL API. You can use them to validate, process or enrich data, call another API, or even log a user in.

Commands are the metadata representation of these functions or procedures. As an example, if we have a TypeScript function connected using the Node.js Lambda connector:

/**
 * @readonly Exposes the function as an NDC function (the function should only query data without making modifications)
 */
export function hello(name?: string) {
  return `hello ${name ?? "world"}`;
}

It would be represented in our metadata as the following command:

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

Automatically track commands

When using ddn dev, the CLI will automatically track functions in your functions.ts file as commands after generating their types. However, you can also use define these commands manually in your metadata.

Check out the custom business logic section for guidance on how to add functions and procedures using the Node.js Lambda connector.

Functions vs. Procedures

Functions are used for read operations. They will not modify the data in the database. They can only be used to retrieve data. As relationships are a querying construct, only functions can be used in relationships.

Procedures are used for write operations. They can modify the data in the database. They can be used to create, update, or delete data.

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.

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.

Example:

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

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>	string	false

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	string	false	The name of a function backing the command.
procedure	string	false	The name of a procedure backing the command.

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
type	TypeReference	true
description	string / null	false

ArgumentName

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