MongoDB

What this endpoint does

A MongoDB endpoint selects a collection of documents in a MongoDB database. It lets pipelines and supported reads retrieve those documents, including nested and optional fields. Query behavior depends on the installed connector contract.

Like all data endpoints, it belongs to a workspace and can be referenced by projects in that workspace, subject to permissions. Saving it configures access; it does not start ingestion.

Directions and supported operations

Use separate source and destination endpoints and select the matching installed capability. Read credentials alone do not authorize writes. This plugin does not expose an ontology fact-store capability.

The writer implements append and replace. Replace removes collection contents before inserting; it is not a multi-document transaction. Upsert, update and delete are not implemented. Append does not enforce a configured business key, and existing _id values can cause duplicate-key errors.

Published-contract limitation: the current catalog advertises upsert and overwrite, but these do not match the implemented writer modes. Use append for this example. Do not promise keyed upsert or select overwrite as an alias for replace.

Plugin used

This plugin provides separate read and write capabilities. Select read for Ingress or write for Egress; the example below installs read first and then explains how to install write. Installation steps for this example are included below. The MongoDB installation guide provides optional further detail. Connection details and credentials stay on the installation; the endpoint selects a particular target through that installed capability.

What you need

• A Semogram account with workspace access and permission to manage endpoints
• An existing matching installation, or the connection details to create one using the steps below
• The connection can reach MongoDB and its database user can read the collection you select. Know the database and collection names and have a few sample documents with different shapes

Read example setup

This example assumes an existing database named crm contains a collection named customers. We choose customers as the Semogram endpoint name and sales as its namespace. The database/collection names come from MongoDB; the endpoint name and namespace are labels you choose. _id is the example document key.

Install and configure the plugin

1. Open Plugins in this workspace and select Explore.
2. Find Mongodb, inspect its publisher/version and select its read capability.
3. Name the installation and fill its connection settings using your actual external-system details.
4. Save and run the supported connection check. Fix any reported error before creating the endpoint.

Example installation configuration:

Install the plugin described on this page in this workspace. Discover its catalog entry, select the matching capability and propose the installation using the connection settings shown here. Ask me to enter credentials in protected installation fields. Show the selected plugin/version, capability and non-secret settings before saving.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "plugin_installation_create",
    "arguments": {
      "capabilityClass": "<MATCHING_CAPABILITY_CLASS>",
      "discoveryId": "<DISCOVERY_ID_FROM_CATALOG>",
      "name": "<INSTALLATION_NAME>",
      "config": {
        "uri": "mongodb+srv://USER:PASSWORD@YOUR_CLUSTER/",
        "database": "crm"
      },
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_INSTALLATION>"
    }
  }
}

Replace every YOUR_… value. Enter credentials only in protected installation configuration. The configuration above is separate from the endpoint target below; selecting a target does not create or authenticate the connection.

Prepare example data

In a test MongoDB deployment, run this in mongosh with an authorized user:

use crm
db.customers.insertMany([
  { _id: "customer_1", name: "Example Customer", region: "north" },
  { _id: "customer_2", name: "Another Customer", region: "south" }
])

Use an empty test collection or different fixture IDs to avoid conflicts. Give the configured database user read access to this collection.

Use the assistant

Open Data Endpoints → New data endpoint in the workspace. Describe your actual target and choose a name for the endpoint. For the example above, you could ask:

Create a source endpoint named customers in namespace sales.
Use our installed MongoDB read capability with contract source_stream
and set these target fields:
Database: crm
Collection: customers
Review the proposed connection and target before saving.

Replace example values with your own. Give the assistant the installed connection reference; keep credentials in protected installation settings.

Configure manually

Choose Edit manually, select the matching installed capability and configure:

Create the endpoint described on this page using these settings:
name: <ENDPOINT_NAME_FROM_THIS_EXAMPLE>
namespace: <ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>
role: source
contractKind: source_stream
target / database: crm
target / collection: customers
pluginCapabilityInstallationId: <INSTALLED_CAPABILITY_UUID>
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
  "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
  "role": "source",
  "contractKind": "source_stream",
  "target": {
    "database": "crm",
    "collection": "customers"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
      "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
      "role": "source",
      "contractKind": "source_stream",
      "target": {
        "database": "crm",
        "collection": "customers"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

Set the primary-key hint to _id after checking uniqueness and nulls. Add a useful description, owner and expected freshness. Save in the workspace. Inspect the installed version’s contract before adding optional settings.

Verify the endpoint

1. Open the saved endpoint and run its supported connection check and schema inspection.
2. Read a small sample through the supported preview. If the connector has no preview, select a project, open Pipeline Studio and create a pipeline with a source node referencing this endpoint.
3. Configure a bounded test input using the connector's supported settings, validate the pipeline, save a version and run it.
4. Inspect returned records or the completed run's output. Compare expected keys and values with the example fixture before scheduling anything.

Compare _id, nested values and optional fields with several original documents. A single document does not describe every shape in the collection.

Check connectivity, target validity and actual data separately. Saving does not import records or schedule execution.

Write example: copy two customers into a test collection

Use the crm.customers source and two documents created above. This example creates a separate destination named verified_customers in Semogram namespace sales, targeting MongoDB collection crm.verified_customers.

1. In workspace Plugins → Explore, select MongoDB → write. Install it using the URI/database configuration shown above, with a database user allowed to create/insert into the test output collection. Read and write installations may have different credentials.
2. In mongosh, prepare an empty dedicated collection:

use crm
db.createCollection("verified_customers")

3. Open Data Endpoints → New data endpoint → Edit manually. Set name verified_customers, namespace sales, Egress (role destination), the installed write capability and contract write. Save this target:

Create the endpoint described on this page using these settings:
name: <ENDPOINT_NAME_FROM_THIS_EXAMPLE>
namespace: <ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>
role: destination
contractKind: write
target / database: crm
target / collection: verified_customers
target / writeMode: append
pluginCapabilityInstallationId: <INSTALLED_CAPABILITY_UUID>
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
  "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
  "role": "destination",
  "contractKind": "write",
  "target": {
    "database": "crm",
    "collection": "verified_customers",
    "writeMode": "append"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
      "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
      "role": "destination",
      "contractKind": "write",
      "target": {
        "database": "crm",
        "collection": "verified_customers",
        "writeMode": "append"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

4. In a workspace project, open Pipeline Studio. Connect an ingress node referencing customers to an egress node referencing verified_customers. Restrict this test to the two fixture documents. Review the output target and write permissions/policy, validate, save a version and run once.
5. Inspect the run, then check MongoDB directly:

use crm
db.verified_customers.find().sort({ _id: 1 })
db.verified_customers.countDocuments({})

Expect two documents with _id values customer_1 and customer_2, names and regions matching the source. Confirm crm.customers still has its original documents. Check nested/type conversions with your real schema before broader use.

Append retries can encounter duplicate _id values or insert duplicate business records with new IDs. A failed run may leave partial output. Inspect the receiving collection before retrying; reset only the dedicated fixture collection when repeating this test. Do not use a primary-key hint as a substitute for a MongoDB uniqueness constraint or expect this writer to upsert.

You can ask the assistant to create the same destination using the exact target above. Review its capability and append mode before saving.

Manage the endpoint

Filters and projections must follow the installed query contract. Normalize nested fields in a pipeline when consumers need tabular records.

Keep credentials on the installation. Review consumers before replacing capabilities, changing targets or deleting endpoints.

FAQ

Why does verification fail?

Check URI authentication, network access and database/collection permissions

Can another project use it?

Yes, within the same workspace and subject to permissions. The endpoint remains workspace-scoped.

What comes after verification?

Use sources in a bounded pipeline, destinations in a supported write flow, and stores in ontology bindings. Inspect real output before scheduling recurring work.