MongoDB Database Connector (DRAFT v10.1.5)

MongoDB document databases.

Overview

MongoDB is the first document database that FrameworX integrates across all four data connection surfaces. One MongoDB instance can serve any combination of these surfaces from the same solution.

A MongoDB UnsTagProvider row and a Historian StorageLocation row can both point at the same MongoDB instance.

Supported MongoDB versions

• Floor: MongoDB 6.0 (Time Series Collections require 6.0+).
• Recommended target: MongoDB 7.0 (current LTS).
• Tested against 6.0, 7.0, 8.0.

Prerequisites

MongoDB .NET drivers ship unconditionally with FrameworX in FS/ThirdPartyBin/. No separate install and no optional pack. Approximate footprint is 4 MB per framework (net48 and net10).

Dataset Provider

Use MongoDB with the Datasets module to read and write document data from a FrameworX solution. The provider exposes four query shapes through the standard Dataset Query object and binds full document collections through Dataset Table for CRUD work.

Steps to connect:

1. Install a MongoDB server and create a database.
2. Create a Database Connection with the MongoDB provider.
3. Configure the connection string and test the connection.
4. Create Dataset Queries for Find, Aggregate, Count, or SQL subset.
5. Create Dataset Tables to bind collections for insert, update, and delete.
6. Call the queries and tables from scripts, displays, or reports.

Installation

Install a MongoDB server (6.0 or newer, 7.0 LTS recommended), create a database and user, then move to the FrameworX configuration below.

Install the MongoDB server

Follow the official MongoDB installation guide for your platform at mongodb.com/docs/manual/installation. Summary by target:

• Windows: download the MongoDB Community Server MSI and run the installer. The default install registers mongod as a Windows service on port 27017.
• Linux: install the distro package per the vendor instructions (for example, apt install mongodb-org on Debian or Ubuntu with the MongoDB repository configured). Start the service with systemctl start mongod.
• macOS: brew tap mongodb/brew && brew install mongodb-community, then brew services start mongodb-community.
• Docker: docker run -d --name fx-mongo -p 27017:27017 mongo:7.

Install the mongosh command-line shell alongside the server. Most platform installers include it by default.

Verify the server is reachable

Run the command below to confirm the server responds:

mongosh "mongodb://localhost:27017" --quiet --eval "db.adminCommand('ping').ok"

A successful ping returns 1.

Create the database and user

Run these commands in mongosh to create a target database, a starter collection, and a user for FrameworX to authenticate as:

use plant_data

db.readings.insertOne({ plant: "Plant01", value: 0, ts: new Date() })

db.createUser({
  user: "fxuser",
  pwd: "<choose-a-strong-password>",
  roles: [ { role: "readWrite", db: "plant_data" } ]
})

The user is stored against the plant_data database above. Use plant_data as the Auth Source value in the FrameworX connection string in the next section, or use admin when the user lives in the admin database.

Platform compatibility

The MongoDB connector targets netstandard2.0 and runs unchanged on both .NET Framework 4.8 (Designer and Windows Runtime) and .NET 10 (cross-platform Runtime on Windows, Linux, and containers). The vendored MongoDB driver ships in both flavors with the FrameworX installation. The mongod server is OS-native and has no .NET dependency.

Configuration

Follow the steps below to connect FrameworX to a MongoDB server.

1. Access Datasets / DBs.
2. Click the plus icon to create a new Database Connection.
3. In the Name field, enter a name for the connection, for example MongoDB1.
4. Choose MongoDB Data Provider as the Provider.
5. Click OK.
   
6. In the data grid, click the Connection String column of the newly created row.
7. Configure the connection. The Designer dialog shows structured fields for Server, Port, User, Password, Database, Auth Source, and TLS. For replica sets and Atlas clusters, use the Advanced Connection URI field with a mongodb:// or mongodb+srv:// URI, which overrides the structured fields.
   
8. Click Test to verify the connection with the MongoDB server.

Connection string options

Query shapes

MongoDB queries accept four input shapes. The provider routes the Command Text of a Dataset Query to the correct driver operation based on the input shape:

SQL subset dialect (new in 10.1.5)

New in Phase B of the 10.1.5 MongoDB connector, users can write standard SELECT statements in the Dataset Query SqlStatement. The connector translates the statement to a MongoDB filter, sort, and projection automatically and executes it through the same driver that handles JSON directives and aggregation pipelines.

Supported grammar (v1)

The translator accepts this subset of standard SQL:

• Clauses: SELECT cols | *, FROM collection, WHERE expr, ORDER BY col [ASC|DESC] (, col [ASC|DESC]...), LIMIT n.
• Comparison operators: =, <>, !=, <, <=, >, >=.
• Boolean operators: AND, OR, NOT.
• Predicates: IS [NOT] NULL, [NOT] BETWEEN ... AND ..., [NOT] IN (...), [NOT] LIKE.
• Identifier forms: bare (plant), double-quoted ("plant"), bracketed ([plant]), back-ticked (`plant`).
• Dotted BSON paths: identifiers like site.line.station resolve to nested BSON fields.
• Numeric literals: integer and decimal, including negative values such as -42 or -3.14.
• Case sensitivity: identifiers are case-sensitive by design. BSON field names are case-sensitive in MongoDB and the translator preserves that behavior.

Semantic notes

• x IS NULL and x = NULL both match documents where the field is missing or has a null value. This follows the MongoDB idiom for missing-or-null match.
• LIKE translates to an anchored regular expression. The wildcard % becomes .* and _ becomes .. Case-folding collation is not applied.
• No collation. Comparisons follow BSON default collation.
• No parameter plumbing at the translator layer. The Dataset host pre-interpolates @Tag.Name references before the statement reaches the SQL-to-MongoDB bridge, so tag values appear as literals in the parsed statement.

Three query shapes side by side

All three shapes below coexist at the same Provider = MongoDB.Driver. Pick the shape that fits the call site.

JSON directive.

{ "collection": "readings", "filter": { "plant": "Plant01" }, "sort": { "ts": -1 }, "limit": 10 }

Aggregation pipeline.

[
  { "$match": { "plant": "Plant01" } },
  { "$sort": { "ts": -1 } },
  { "$limit": 10 }
]

SQL subset.

SELECT plant, value, ts
FROM readings
WHERE plant = 'Plant01'
ORDER BY ts DESC
LIMIT 10

Out of scope in v1

The translator raises MongoSqlTranslationException for any construct outside the supported grammar. Out-of-scope constructs include:

• GROUP BY and aggregate functions (COUNT, SUM, AVG, MIN, MAX).
• JOIN in any form.
• Subqueries.
• DISTINCT.
• OFFSET.
• Arithmetic expressions inside SELECT or WHERE.
• INSERT, UPDATE, DELETE statements (use Dataset Tables, or write an aggregation pipeline).

These constructs are parked for later releases. No ETA is promised. Use an aggregation pipeline or a Dataset Table when the SQL subset does not cover the need.

Write semantics

• The Save call on a Dataset Table dispatches to MongoDB UpdateOne with $set on tracked columns. Fields outside the tracked column list are preserved on update.
• Batched changes use BulkWrite with the same tracking rules.
• Authentication supports SCRAM-SHA-256, TLS, replica sets, and mongodb+srv:// URIs.

Worked example

For an end-to-end Dataset configuration that reads, aggregates, and writes documents in a MongoDB collection (one Dataset DB, three Queries, one Dataset Table, three Script Tasks), see the dedicated example page: Datasets MongoDB Example.

The example uses the seed data described in the Installation section above (database plant_data, collection readings).

Device Protocol

When to use

Use the Device Protocol surface when you want each MongoDB document field addressed as an individual Tag with a Node-level connection. This is the classic SCADA Channel / Node / Point model.

Use UNS TagProvider instead (next section) when you want dynamic browse and tree-style registration.

Configure

Channel. Devices / Channels / New. Protocol = MongoDB. Interface is automatically Custom (no CommAPI).

Node. One Node per MongoDB server plus database. PrimaryStation is a delimited string with the shape:

ConnectionUri;Database;AuthSource;TlsEnabled

Example value:

mongodb://localhost:27017;plant_a;admin;false

Point. Address is a single-dot collection.field string. Example: sensors.temperature.

Read semantics

On each scan cycle, the driver runs one find per configured address, sorts by _id descending, limits to 1, and projects the requested field. The value is returned as a string on every successful read. Quality is 192 (Good) on hit, 0 (Bad) when the collection is empty or the field is absent.

Values round-trip as strings in the Device path. Numeric or boolean tags show their value as text. Use the UNS TagProvider surface (next section) when your integration needs the value native type preserved.

Write semantics - UPDATE, not append

WriteTagValue finds the most recent document in the collection and runs $set on that document _id. If the collection is empty, a fresh document is inserted with the field plus a ts UTC timestamp.

This is config-style or settings-style write behavior. Every write mutates the latest document. It does NOT append a new time-series sample. Use a Historian StorageLocation (later section) for append-style time-series writes.

Address limits

Only single-dot addresses are accepted in 10.1.5. collection.field works. collection.field.subfield is rejected. Nested BSON path support is planned for a later release.

Configuration Example

This example maps a single MongoDB document field to a Tag using the Channel / Node / Point model. Prerequisites: a running mongod with the plant_data database and the sensors collection from the Installation section above, plus a UNS Tag named SensorTemp of type Double.

1. In Devices / Channels, create a Channel:
   • Name: MongoDB1.
   • Protocol: MongoDB. The Interface is set to Custom automatically.
2. In Devices / Nodes, create a Node under that Channel:
   • Name: Plant_A.
   • Channel: MongoDB1.
   • PrimaryStation:

     mongodb://localhost:27017;plant_data;admin;false

3. In Devices / Points, create a Point bound to the tag SensorTemp:
   • TagName: SensorTemp.
   • Node: Plant_A.
   • Address: sensors.temperature.
   • AccessType: ReadWrite.
4. Run the solution. SensorTemp reads the latest temperature value from the most recent document in the sensors collection on each scan cycle.
5. From a Script Task, write the tag back: @Tag.SensorTemp = 75.0;. The driver runs $set on the latest sensors document. The collection's most recent document is mutated in place. This is config-style write behavior, not append. Use the Historian StorageLocation surface (later section) for append-style time-series writes.

UNS TagProvider

When to use

Use the UNS TagProvider surface when you want to browse a MongoDB instance from the Designer UNS tree, discover field names dynamically, and register fields as UNS tags.

Configure

UNS / TagProviders / New. Protocol = MongoDB. Station uses the same delimited format as the Device Protocol:

ConnectionUri;Database;AuthSource;TlsEnabled

Browse semantics

The browse view has two levels:

• Level 0 (tree root for this TagProvider). Lists all collections in the configured database.
• Level 1 (inside a collection). Samples the most recent document with sort({_id:-1}).limit(1) and lists that document top-level field names. The _id field is hidden from the browse view.

The browse is schema-less. If different documents in a collection carry different fields, the browse reflects only the sample document. Register the fields you need and define them explicitly on the UNS Tag when the schema varies.

Designer refresh does not mutate state. Browse is side-effect-free and safe to call on every tree expansion.

Register a tag

Select a field under a collection and use Add to UNS. The registered address is collection.field. The attribute type is string in 10.1.5 (all scalars). Typed registration is planned for a later release.

Read and write semantics

Identical to the Device Protocol section:

• Read pulls the latest document field value and tags quality 192 on hit, 0 on miss.
• Write runs $set on the latest document _id, or inserts a minimal document when the collection is empty.

Address limits

Single-dot collection.field only. The registration call rejects multi-dot addresses with the message Multi-segment paths not supported in 10.1.5, use 'collection.field' with a single dot.

Configuration Example

This example browses a MongoDB instance from the Designer UNS tree and registers a document field as a UNS tag. Prerequisites: a running mongod with the plant_data database and the sensors collection from the Installation section above.

1. In UNS / TagProviders, create a TagProvider:
   • Name: MongoTags.
   • Protocol: MongoDB.
   • ServiceType: TagDiscovery.
   • PrimaryStation:

     mongodb://localhost:27017;plant_data;admin;false

2. Open the UNS tree in Designer and expand MongoTags. The tree shows the collections in plant_data at level 0 (for example readings and sensors).
3. Expand sensors. The browse samples the most recent document and lists its top-level field names (for example temperature, plant, ts). The _id field is hidden.
4. Right-click the temperature field and choose Add to UNS. A tag MongoTags/sensors/temperature appears in the UNS Tags list with attribute type string.
5. Run the solution. @Tag.MongoTags/sensors/temperature reads the latest temperature value from the collection on each scan cycle.
6. Writing the tag from a Script Task runs $set on the latest sensors document, with the same UPDATE semantics as the Device Protocol surface.

Historian StorageLocation

When to use

Use this surface when you want FrameworX Historian to write tag samples into MongoDB as an append-style time series. This is the append behavior most users expect from a historian.

Prerequisites

A MongoDB UNS TagProvider row must already exist (previous section). The Historian StorageLocation references it by name.

Configure

Historian / Storage Locations / New. The Protocol combo includes MongoDB when the TagProvider row has IsHistorian="true" (the default for 10.1.5). The DataRepository field selects which MongoDB UnsTagProvider to use.

Storage model - Time Series Collections

Each FrameworX tag-collection maps to a MongoDB Time Series Collection (MongoDB 6.0+). The canonical document schema is:

{
  "t": "<UTC DateTime>",
  "m": { "tag": "<address>" },
  "v": "<value>",
  "q": "<quality ushort>"
}

The collection is created on first write if absent. Granularity is hard-coded to seconds in 10.1.5. This value is immutable on the MongoDB side after collection creation. Station-configurable granularity is planned for a later release.

Write semantics - BATCHED APPEND

WriteHistorianDataEx groups the incoming batch by collection name and calls InsertMany with IsOrdered=false. Every sample becomes a new document. Partial-batch failures are surfaced on a per-document basis. A bad document does not fail the whole batch.

Read semantics - raw samples only in 10.1.5

GetSamples does a range query ($gte and $lte on the t field) with ascending sort. The interval and getSamplesMode parameters are ignored in 10.1.5. Raw samples only.

Aggregation (Average, Min, Max, Sum with non-zero interval) is planned for a later release using MongoDB $bucket and $bucketAuto stages.

Known edge case - same collection as both TagProvider and StorageLocation

If a user configures the same collection as BOTH a UNS TagProvider browse target AND a Historian StorageLocation target, the Historian write path succeeds silently into a plain (non-Time-Series) collection but reads behave incorrectly. A runtime guard is planned for a later release. Until it lands, use distinct collection names for the two roles.

Configuration Example

This example appends historian samples for a UNS tag to a MongoDB Time Series Collection. Prerequisites: a UNS TagProvider MongoTags exists from the previous section and points at the same MongoDB instance, plus a UNS Tag SensorTemp of type Double being updated by a Device, Script, or external source.

1. In Historian / Storage Locations, create a StorageLocation:
   • Name: MongoStore.
   • DataRepository: TagProvider.MongoTags.
2. In Historian / Tags, bind SensorTemp to MongoStore with a sample interval (for example one second) and a deadband appropriate for the signal.
3. Run the solution. On the first sample, the connector creates a Time Series Collection in plant_data with the canonical schema documented in the Storage model section above (granularity hard-coded to seconds in 10.1.5). Subsequent samples are appended via InsertMany with IsOrdered=false.
4. Read history with @Tag.SensorTemp.GetSamples(...) from a Script or Trend control. The connector runs a range query on the t field with ascending sort and returns raw samples. Aggregation (Average, Min, Max, Sum with non-zero interval) is planned for a later release.

Known limitations and deferrals

The table below collects per-surface limits that apply to the 10.1.5 release.

In this section...