Commands
Introduction
A "Command" in Hasura DDN represents an action that can be performed to returning some type of result (eg:
LogUserIn
). Very loosely, you can think of commands as the verbs or, "actions" of your data domain.
Commands have a fixed definition and are backed by functions or procedures, allowing you to add top level methods to your API, or, add a custom field to an existing model.
Commands allow you to execute 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.
Once a command is declared it will then often be referenced by Relationship
objects in order to compose them with
each other or models, and also by Permissions
objects to control access to the command execution.
View an example of a function, the command and an API query it enables
A function in TypeScript with 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: my_data_connector
dataConnectorCommand:
function: hello
graphql:
rootFieldName: my_subgraph_hello
rootFieldKind: Query
And then queried in the API like so:
query {
my_subgraph_hello(name: "Hasura")
}
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. |
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
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 | 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