Configuration

Subject to change

During this active development phase, the configuration structure is subject to change.

Connnection Environment Variable

To set up the MongoDB connector, you need to configure the MONGODB_DATABASE_URI environment variable. If you are using Hasura DDN, this variable is automatically managed for you. You can also map it to a different environment variable as described in the documentation.

Introduction

This document is the reference documentation for the MongoDB data connector configuration. Configuration is currently broken down into 3 folders and a root configuration file.

1. configuration.json
2. schema
3. native_queries
4. native_mutations

Root Configuration File

The root configuration file serves as a central point for configuring various aspects of the system. Below is an example configuration file along with explanations of its components:

Example

{
  "introspectionOptions": {
    "sampleSize": 100,
    "noValidatorSchema": false,
    "allSchemaNullable": true
  }
}

introspectionOptions

The introspectionOptions section allows customization of options related to introspection, which is the process of examining or analyzing the system's structure and capabilities.

• sampleSize: Specifies the size of the sample used for introspection. In the provided example, the sample size is set to 100. Adjust this value as needed based on the requirements and characteristics of your system.
  • Default: 100
• noValidatorSchema: Determines whether to include a validator schema during introspection. When set to false, a validator schema will be included. In the example, it's set to false, indicating that a validator schema will be included if one exists.
  • Default: false
• allSchemaNullable: Indicates whether all schema elements are nullable. When set to true, all schema elements are considered nullable. This setting can impact how the system handles data validation and type checking. In the example, it's set to true, implying that all schema elements are nullable.
  • Default: true

The .configuration_metadata file is a blank file with no content. It's used by the system as a marker to check if the configuration.json file has been modified. Essentially, its presence alone serves as an indicator that the configuration file has been updated since the last check. This simple mechanism helps the system keep track of changes to the configuration without storing any actual timestamps or data.

Schema

The schema directory contains JSON files of all collections that were introspected in your database.

Example

{
  "name": "users",
  "collections": {
    "users": {
      "type": "users"
    }
  },
  "objectTypes": {
    "users": {
      "fields": {
        "_id": {
          "type": {
            "scalar": "objectId"
          }
        },
        "email": {
          "type": {
            "scalar": "string"
          }
        },
        "name": {
          "type": {
            "scalar": "string"
          }
        },
        "password": {
          "type": {
            "scalar": "string"
          }
        }
      }
    }
  }
}

Name

The name property specifies the name which gets exposed to Hasura metadata/tooling:

{
  "name": "users"
}

Collections

The collections property contains definitions of the collection name in your database and the object type it returns:

{
  "collections": {
    "users": {
      "type": "users"
    }
  }
}

Object types

The objectTypes property defines the returned object types. Object types contain fields that specify either scalar or other structural object types.

{
  "objectTypes": {
    "users": {
      "fields": {
        "_id": {
          "type": {
            "scalar": "objectId"
          }
        },
        "email": {
          "type": {
            "scalar": "string"
          }
        },
        "name": {
          "type": {
            "scalar": "string"
          }
        },
        "password": {
          "type": {
            "scalar": "string"
          }
        }
      }
    }
  }
}

Type Examples

{ "type": { "scalar": "string" } }

{ "type": "extended_json" }

{ "type": { "arrayOf": { "scalar": "string" } } }

{ "type": { "object": "TypeName" } }

{ "type": { "nullable": { "scalar": "string" } } }

Scalar Types

• double: Represents a floating point number.
• string: Represents a sequence of characters.
• bool: Represents a boolean value, true or false.
• int: Represents an integer.
• long: Represents a longer form of integer.
• decimal: Represents a large decimal number.
• date: Represents a date, stored as a string in ISO format.
• timestamp: Represents a Unix timestamp.
• objectId: Represents an object identifier.

Structural Types

• object: Represents a BSON document or an embedded document. Users can define their own nested object types, specifying the structure of these objects as required by their applications.
• arrayOf: Represents an array of elements, with each element being a type specified after arrayOf. For instance, {"arrayOf" : "string"} means an array of strings.

Native queries

Native queries are named MongoDB aggregation pipelines that you specify in the data connector configuration. They are similar to a database view, but more expressive as they admit parameters similar to a function and do not require any DDL permissions on the database. See the configuration reference on Native Queries.

More information in the Native Queries documention.

Native mutations

Native mutations are named MongoDB runCommand operations that you specify in the data connector configuration. These are commonly used for mutations, but we do support the full runCommand API. See the configuration reference on Native Mutations.

More information in the Native Mutations documentation.

Configuration workflows

The data connector provides a plugin to the hasura CLI to assist you in authoring configuration.

We provide the mongodb-cli-plugin, which is a small executable, of which the builds can be accessed here.

Current status

The intended way to use this plugin is through the main ddn CLI.

But at the time of this writing, this part of the developer experience is undergoing active development, so the exact command invocations are likely to change.

Updating with introspection

Whenever the schema of your database changes you will need to update your data connector configuration accordingly to reflect those changes.

Running mongodb-cli-plugin update in a directory will do the following:

Connect to the database with the specified connection-uri, create a schema directory, if one does not exist, and then either create or update a file for each collection that is introspected in your database.

Currently, the mongodb-cli-plugin tries to use any validation schemas if they exist, and falls back to sampling documents in your collection. The current sample size is 10. This will be configurable in future releases.

Manually editing

There are occasions when the automatic introspection falls short of your needs. For instance, it may not detect a particular entity type, or it may pick names according to conventions you disagree with.

note

This only applies to the files under the schema directory

If you find yourself in this situation you are still able to bring your configuration into an acceptable state by editing it manually. In this case you'd be well advised to keep your configuration files under version control, as re-running the update command will overwrite your manually-crafted changes.

Native Queries and Native Mutations will always need manual authorship currently. We plan on improving this authorship flow in the future.