Configuration
During this active development phase, the configuration structure is subject to change.
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.
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
- Default:
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
- Default:
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
- Default:
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 afterarrayOf
. 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.
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.
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.