Connector Types
Although MongoDB is schema-less it does use a set of types for storing data. Specifically MongoDB stores data in BSON format. BSON is similar to JSON except that it is a binary instead of a text format, and BSON includes a number of types that are not distinguished in JSON. For example BSON includes several numeric types while JSON only has one type for numbers.
Choices of types determine what operations are available for filtering and sorting data. Types also determine how data from your database will be represented in JSON since all data coming into and out of your database through the GraphQL API is converted from BSON to JSON or vice versa.
This page describes the types that MongoDB supports, and provides information about type-related configuration in the MongoDB connector.
Scalar types
The MongoDB connector supports all of the scalar types defined by BSON (except dbPointer), plus a first-class UUID
type (technically in BSON UUIDs are stored using the binData scalar type), and a special type called extendedJSON
which represents all possible BSON values. These are the types available:
| Type | Details |
|---|---|
extendedJSON | the connector's "any" type - this type can hold any possible value |
int | 32-bit integer |
long | 64-bit integer |
double | 64-bit float |
decimal | 128-bit float |
string | UTF-8 encoded string |
date | date with time |
timestamp | used internally by MongoDB - use date instead |
binData | binary data with a "subtype" that indicates how the data is interpreted |
uuid | UUIDs such as those generated by the mongosh new UUID() constructor (added in connector v1.7) |
objectId | the default document identifier used by MongoDB |
bool | |
null | |
regex | regular expression |
javascript | JavaScript code |
javascriptWithScope | JavaScript code with bindings for closure variables |
minKey | defined to be less than any other value for comparisons, regardless of type |
maxKey | defined to be greater than any other value for comparisons, regardless of type |
undefined | deprecated by MongoDB |
dbPointer | deprecated by MongoDB, not supported by connector |
symbol | deprecated by MongoDB |
The table above gives names for types as they are used in connector configuration which is taken from names in BSON
documentation. On the other hand, GraphQL uses uppercase type names. In your GraphQL schema and in metadata
configuration in .hml files you will see these type names with the first letter uppercased.
Complex types
The complex types that the connector recognizes are:
| Type Constructor | Details |
|---|---|
| array | homogenous array |
| object | record type with a fixed set of string keys, and a distinct type for each key |
| nullable | values of a nullable type might be null |
For details on how to write complex types see Type Expressions.
Representations in JSON
GraphQL operates using JSON; to interact with BSON data in your database, the connector must convert inputs (such as filter arguments or mutation inputs) from JSON to BSON, and must convert result data from BSON to JSON. These conversions are determined by the types configured in your connector's schema.
The extendedJSON type represents all possible BSON values. Fields of this type are converted to JSON differently from
fields with more specific types. See Extended JSON.
In general, conversions between JSON and BSON are symmetric: input values will look the same as response data. Here are JSON conversion details for each scalar type:
| Type | Example JSON | Details |
|---|---|---|
extendedJSON | { "$numberInt": "3" } | see Extended JSON |
int | 3 | JSON number |
long | "3" | converted to a string to avoid accidental loss of precision |
double | 3.14 | JSON number |
decimal | "3.14" | converted to a string to avoid accidental loss of precision |
string | "Hello, world!" | JSON string |
date | "2016-03-04T00:00:00.000000000Z" | string in ISO-8601 format |
timestamp | { "t":1565545664, "i":1 } | use date instead |
binData | { "base64": "EEEBEIEIERA=", subType: "00" } | base64-encoded data and interpretation hint - see BSON docs |
uuid | "40a693d0-c00a-425d-af5c-535e37fdfe9c" | string in UUID format |
objectId | "66135e86eed2c00176f6fbe6" | string with hex encoding - the same format that ObjectId stringifies to in mongosh |
bool | true | |
null | null | |
regex | { "pattern": "^H", "options": "i" } | JSON object with separate fields for pattern and options - inputs may be given as a plain string for a pattern without options |
javascript | "function(x) { return x + 1 }" | JSON string |
javascriptWithScope | { "$code": "function(x) { return x + y }", "$scope": { "y": "1" } } | JSON object with code as string, and mappings for captured variables |
minKey | {} | empty object |
maxKey | {} | empty object |
undefined | null | JSON doesn't have an undefined so BSON undefined converts to null instead |
symbol | "foo" | JSON string |
dbPointer | not supported by connector |
