Commands Modify Data

Introduction

Commands enable you to perform actions that modify data — such a perform updates or inserts — in your data source. Commands also allow you to execute custom business logic directly via your API.

Lifecycle

New to Hasura DDN?

If you haven't already, have a run through our Quickstart guide to set up your Hasura DDN instance. In the sections below, we'll guide you through how to interact with your metadata and shape your API to your liking!

Creating a command

To modify data, you first need to create a command that maps to a specific operation within your data source.

PostgreSQL

Since ndc-postgres v1.2.0, mutations are generated automatically. If you are on an earlier version, since v0.8.0, you can still get autogenerated mutations by adding "mutationsVersion": "v2" to your configuration.json. You can read more about this configuration option and others on the PostgreSQL connector configuration docs.

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, update your commands:

ddn command add <connector_name> "*"

MongoDB

The MongoDB data connector defines custom commands via native mutations.

Within your connector's directory, you can add a new JSON configuration file to define a native mutation.

Create a new directory to store your native mutations:

mkdir -p <my_subgraph>/connector/<connector_name>/native_mutations/

Create a new file in your connector's directory:

// native_mutations/insert_user.json
{
  "name": "insertUser",
  "description": "Inserts a user record into the database",

  "arguments": {
    "name": { "type": { "scalar": "string" } }
  },

  "resultType": {
    "object": "InsertUser"
  },
  "objectTypes": {
    "InsertUser": {
      "fields": {
        "ok": { "type": { "scalar": "double" } },
        "n": { "type": { "scalar": "int" } }
      }
    }
  },

  "command": {
    "insert": "users",
    "documents": [{ "name": "{{ name }}" }]
  }
}

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, update your commands:

ddn command add <connector_name> "*"

ClickHouse

Commands are currently not supported on ClickHouse.

Lambda connectors

Lambda connectors allow you to execute custom business logic directly via your API. You can learn more about Lambda connectors in the docs.

Updating a command

Your underlying data source may change over time. You can update your command to reflect these changes.

PostgreSQL

Since ndc-postgres v1.2.0, mutations are generated automatically. If you are on an earlier version, since v0.8.0, you can still get autogenerated mutations by adding "mutationsVersion": "v2" to your configuration.json. You can read more about this configuration option and others on the PostgreSQL connector configuration docs.

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, update your commands:

ddn command update <connector_name> "*"

MongoDB

For example if you have a native mutation that inserts a user you can modify it to include a second field on new documents.

Edit the existing native mutation in your connector's directory:

// native_mutations/insert_user.json
{
  "name": "insertUser",
  "description": "Inserts a user record into the database",

  "arguments": {
    "name": { "type": { "scalar": "string" } },
    "role": { "type": { "nullable": { "scalar": "string" } } } // add an argument
  },

  "resultType": {
    "object": "InsertUser"
  },
  "objectTypes": {
    "InsertUser": {
      "fields": {
        "ok": { "type": { "scalar": "double" } },
        "n": { "type": { "scalar": "int" } }
      }
    }
  },

  "command": {
    "insert": "users",
    "documents": [
      {
        "name": "{{ name }}",
        "role": "{{ role }}" // include a field with the value of the new argument
      }
    ]
  }
}

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, update your commands:

ddn command update <connector_name> "*"

ClickHouse

Commands are currently not supported on ClickHouse.

Deleting a command

If you no longer need a command, you can delete it:

ddn command remove <command_name>

Reference

You can learn more about commands in the metadata reference docs.