Native Data Connector for MongoDB

MongoDB Atlas Users

When testing Hasura public DDN with MongoDB Atlas, you need to allow all IPs by adding 0.0.0.0/0 under the Network Access section in your Atlas Dashboard.

Introduction

The MongoDB Native Data Connector for Hasura DDN expands our connectivity options, enabling integration with MongoDB noSQL databases. Here we'll provide an overview of the features offered by the MongoDB connector and guide you through the configuration process within a Hasura DDN project.

The MongoDB data connector makes any database resource listed in its configuration available. In order to populate the configuration, the connector supports introspecting the database via the Hasura CLI update command.

Getting started

To get started with MongoDB and Hasura DDN, check out this guide.

Prerequisites

If you've never used Hasura DDN, we recommend that you first go through the getting started. 😊

Queryable collections

The MongoDB data connector supports several types of queryable collections:

• Tables
• Views
• Native queries
• Native mutations

Tables and views are typically discovered automatically during the introspection process.

Native queries are enabled via MongoDB's aggregation pipelines, and are defined in the MongoDB data connector's configuration. They are similar to a view but more expressive as they allow parameters similar to functions and do not require any DDL permissions on the database. See the configuration reference on Native Queries.

Native mutations in MongoDB are enabled via a runCommand and are also defined in the MongoDB data connector's configuration. These are commonly used for simple data mutations, but we do support the full runCommand API too. See the configuration reference on Native Mutations.

Data types

The Hasura MongoDB data connector supports any data type that MongoDB knows how encode and decode as JSON - No data type is handled as a special case.

Data type naming

Many data types have aliases in MongoDB, which can be found in the MongoDB documentation on data types.

In order to use standard GraphQL data types rather than custom data types in the resulting GraphQL schema, the Hasura supergraph configuration enables expressing a mapping between data connector types and GraphQL types.

BSON support

MongoDB stores data in BSON, while the GraphQL API uses JSON. Hasura converts query responses to JSON according to the types defined in the Hasura schema configuration. For example,

• double and int (64-bit floating-point numbers, and 32-bit integers) are converted to JSON numbers
• long and decimal (64-bit integers, and 128-bit floating point numbers) are converted to JSON strings to avoid loss of precision
• dates are converted to strings in ISO 8601 format
• object IDs are converted to hex-encoded strings

If there is a value in a query response that does not match the type defined in the Hasura schema configuration then the query will fail with an error.

In some cases it is not possible to configure a specific type for a collection field. For example if a field contains different types of data in different documents since Hasura does not implement union types. In those cases the configured type of a field may be extendedJSON. This is a fallback that captures any values that can be represented in BSON. To preserve type information values of this type are converted to JSON according to the canonical variation of the MongoDB Extended JSON v2 spec. For example,

• numbers are converted to objects with a type tag and a string value, like { "$numberDouble": "3.14" }
• dates are converted to the form, {"$date": {"$numberLong": "<milliseconds since Unix Epoch>" } }
• object IDs are converted to this form, { "$oid": "<hex-encoded string>" }

Queries may include input values in the form of arguments. These are converted from JSON to BSON according to the inverse of the above. For example,

• if the type of an argument is double then a valid input is 3.14.
• if the type of an argument is extendedJSON then either { "$numberDouble": "3.14" } or 3.14 is valid.

In general if an argument value does not match the expected type then the query will fail with an error. But there are a few cases where we apply implicit conversion where the BSON types have indistinguishable JSON representations. In particular, it is permissible to provide a GraphQL Int value where a double is expected, or to provide a GraphQL Float value where an int is expected.

Queries

The Hasura MongoDB data connector supports all query operations; see the query documentation for details.

Filtering

The MongoDB data connector supports the introspection and usage of all binary comparison functions and operators defined for any tracked scalar type, built-in and user-defined alike. Refer to filters documentation for more information.

Mutations

Mutations are still undergoing active development and are likely to change in the future. Currently, you can write your own mutations using Native Mutations.

Troubleshooting the MongoDB Connector

I'd like to tweak how the connector works or does database introspection

Visit the Configuration page for more information.

unprocessable content: error converting MongoDB response to JSON: expected a value of type Scalar(String), but got null

This happens when there is a discrepancy between types in the database data and the schema that was generated.

Usually this can happen when sampling determined that a field was non-nullable when in fact it is a nullable field. In this case you manually update the proper collections schema json file in the schema directory to be non-nullable.

I'm having issues getting my Native Query to run

More information can be found in the Native Queries Requirements section.

Connector build failed

If you see an error such as:

ERR Failed to create ConnectorBuild: ConnectorBuild with ID
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" failed : connector container failed to start.

It's likely that Hasura DDN can't access your MongoDB instance. You'll need to add 0.0.0.0/0 to your allow list. Alternatively, if you have the option, you can set up peering or a tunnel to an IP address you can allow list.