Native Mutations

Introduction

Native Mutations allow you to run custom commands on your MongoDB database using the runCommand API that can be exposed via the Hasura GraphQL and modify the database state. As point-to-point mutations are not yet supported, this is one way to mutate data using your GraphQL API.

Setup

Native Mutations can be defined by

1. Adding a native_mutations directory if one doesn't already exist in your connector configuration directory
2. Adding a .json file following the syntax laid out in the following sections.

Example

Here's an example of simple "insert_artist" Native Mutation:

Configuration

{
  "name": "insertArtist",
  "description": "Example of a database insert using a native mutation",
  "resultType": {
    "object": "InsertArtist"
  },
  "arguments": {
    "artistId": {
      "type": {
        "scalar": "int"
      }
    },
    "name": {
      "type": {
        "scalar": "string"
      }
    }
  },
  "objectTypes": {
    "InsertArtist": {
      "fields": {
        "ok": {
          "type": {
            "scalar": "int"
          }
        },
        "n": {
          "type": {
            "scalar": "int"
          }
        }
      }
    }
  },
  "command": {
    "insert": "Artist",
    "documents": [
      {
        "ArtistId": "{{ artistId }}",
        "Name": "{{ name }}"
      }
    ]
  }
}

This will create a mutation called "insertUser" which takes two arguments called "artistId" of type int, and "name" of type string. The query will return an object with the keys "ok" and "n" and the values as ints.

Native Queries can take arguments using the placeholder syntax, "{{argument_name}}". Arguments must be specified along with their type.

Avoid code injection

When placeholders are substituted arguments are not sanitized. It is up to you as the author of a native query to construct the query to avoid potential code injection. See Security Best Practices.

To add the native query to your supergraph you need to update the metadata with a command like this one,

$ ddn connector-link update <connector-name> --add-all-resources

Valid Native Mutation Syntax

Check out our page on writing valid Hasura DDN Native Operations syntax.

Usage

With the example above, you can then use the query in your GraphQL API like this:

mutation MyMutation {
  insertArtist(artistId: 10000, name: "Pearl Jam") {
    ok
    n
  }
}