Initial documentation for MongoDB (#390)

Co-authored-by: Sean Park-Ross <[email protected]>
Co-authored-by: Jesse Hallett <[email protected]>

docs/connectors/mongodb/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "MongoDB",
+  "position": 7
+}

docs/connectors/mongodb/config.mdx

@@ -0,0 +1,289 @@
+---
+sidebar_position: 2
+sidebar_label: Configuration
+description:
+  "Reference documentation for the setup process for the Hasura MongoDB connector, including connection URI details,
+  native queries, and native mutations."
+keywords:
+  - hasura mongodb setup
+  - connector configuration
+  - graphql api integration
+  - database connection uri
+  - native queries
+  - native mutations
+  - graphql mutations
+  - data modeling
+  - api customization
+  - hasura configuration guide
+  - database schema management
+seoFrontMatterUpdated: true
+---
+
+# Configuration
+
+:::warning Subject to change
+
+During this active development phase, the configuration structure is subject to change.
+
+:::
+
+## 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`](#root-configuration-file)
+2. [`schema`](#schema)
+3. [`native_queries`](#native-queries)
+4. [`native_mutations`](#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**
+
+```json
+{
+  "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**
+
+```json
+{
+  "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:
+
+```json
+{
+  "name": "users"
+}
+```
+
+#### Collections
+
+The `collections` property contains definitions of the collection name in your database and the object type it returns:
+
+```json
+{
+  "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.
+
+```json
+{
+  "objectTypes": {
+    "users": {
+      "fields": {
+        "_id": {
+          "type": {
+            "scalar": "objectId"
+          }
+        },
+        "email": {
+          "type": {
+            "scalar": "string"
+          }
+        },
+        "name": {
+          "type": {
+            "scalar": "string"
+          }
+        },
+        "password": {
+          "type": {
+            "scalar": "string"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Type Examples
+
+```json
+{ "type": { "scalar": "string" } }
+```
+
+```json
+{ "type": "extended_json" }
+```
+
+```json
+{ "type": { "arrayOf": { "scalar": "string" } } }
+```
+
+```json
+{ "type": { "object": "TypeName" } }
+```
+
+```json
+{ "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][MongoDB: pipeline] 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](#updating-with-introspection).
+
+More information in the [Native Queries](/connectors/mongodb/native-queries) documention.
+
+### Native mutations {#native-mutations}
+
+Native mutations are named MongoDB [runCommand][MongoDB: runCommand] operations that you specify in the data connector
+configuration. These are commonly used for mutations, but we do support the full [runCommand][MongoDB: runCommand] API.
+See the configuration reference on [Native Mutations](#updating-with-introspection).
+
+More information in the [Native Mutations](/connectors/mongodb/native-mutations/index.mdx) 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](https://github.com/hasura/ndc-mongodb/releases/).
+
+:::warning 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 {#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](/connectors/mongodb/native-queries) and
+[Native Mutations](/connectors/mongodb/native-mutations/index.mdx) will always need manual authorship currently. We
+plan on improving this authorship flow in the future.
+
+[MongoDB: pipeline]: https://www.mongodb.com/docs/manual/core/aggregation-pipeline
+[MongoDB: runCommand]: https://www.mongodb.com/docs/manual/reference/method/db.runCommand