Getting started with the MongoDB database

Use this page to help you get started with MongoDB in Semarchy xDI.

Connect to your data

Metadata creation

The first step is to create the MongoDB Metadata. Launch the Metadata creation wizard, and select MongoDB. Then, define the properties of the root node.

getting started mongodb metadata overview

Property Description

Name

A label or alias for the metadata.

Module

The active Designer module to use for this metadata. Usually doesn’t need to be changed.

Connection Method

One of the following two options:

  • URL: choose this option manually create a single URL that contains all necessary connection properties to connect to MongoDB.

  • UserPassword: choose this option to define connection properties in individual fields.

MongoDB home

Path to the MongoDB server installation directory. Used by Templates that import data through the mongoimport utility.

If you chose the URL connection method, you need to set one more property as follows:

Property Description

MongoDB URL

The MongoDB server URL, with the following syntax:

mongodb://[<user>:<password>@]<host>:<port>

Some examples:

mongodb://localhost:27017
mongodb://myUser:myPassword@localhost:27017

If you chose the UserPassword connection method, Designer exposes multiple properties to set:

Property Description

Use SRV

When checked, xDI connects to a DNS-constructed seed list based on SRV records. For more information, see the MongoDB documentation.

Use SSL

When checked, connects to MongoDB over SSL.

MongoDB Hostname

MongoDB server hostname to connect to.

MongoDB Port

MongoDB server port to connect on.

Authentication Type

Authentication mechanism that MongoDB uses to authenticate the connection.

MongoDB User

Username to connect with.

MongoDB Password

Password to connect with.

MongoDB Authentication Database

MongoDB database the specified user was created in.

Metadata reverse

Each node of the MongoDB Metadata offers the possibility to reverse its structure.

Simply right click on the desired node and choose: Actions > Reverse [All]

  • On the server node: All databases and collections are reversed

  • On a database node: All the collections of the database are reversed

  • On a collection: The collection is reversed

Define a database node

To add a database node manually, you can right clic on the server node and choose New > Database.

The following properties are available on this node.

Property Description

Name

A label/alias for the database.

Database Physical Name

Physical Name of the database. It will be used during data and reverse operations.
You can reverse all the collections of the database with a right click > Actions > Reverse.

Define a collection node

To add a collection node manually, right-click the server node and choose New > Collection.

Property Description

Name

A label/alias for the collection

Collection Physical Name

Physical Name of the collection.
You can then reverse the structure of the collection with a right click > Actions > Reverse.

Define and reverse find queries

Common query

A Find Query is a placeholder that will contain a MongoDB query.

It is used to retrieved data from a predefined query.

To define a Find Query:

  1. Right-click the server node

  2. Choose New then Find Query.

  3. Specify the query properties

  4. Right-click the find query node and choose Actions > reverse. This runs the query and parses the response to get the metadata structure. This is optional. The results can also be designed manually.

Example:

getting started mongodb find query common

The following properties are available:

Property Description

Name

Label for the find query.

Collection physical name

Name of the collection on which to perform the Find Query.

Find Query

MongoDB query to run, with the JSON format. Refer to the MongoDB documentation for further information on how to design it.

Parametrized query

The values of find queries can be parametrized with the use of parameters, which allow to dynamically change the query values at run.

To parametrize a query:

  1. Right-click the find query.

  2. Choose New, then Value.

  3. Fill-in its properties.

  4. Use it in the query to replace a manually set value.

Example:

getting started mongodb find query parametrized

The following properties are available:

Property Description

Name

Label for the parametrized value, to be used in the query.

Reverse Value

Default value to be used when reverse-engineering the query.

Type

JSON Type (string, boolean, number)

Size

Size used for the target staging column when using this value as source in a mapping.

Scale

Number of decimals for the target staging column when using this value as source in a mapping.

Example:

getting started mongodb find query parameter

The parametrized values only work to replace values, not keys.

Query extra fields

Multiple query extra fields are supported:

  • skip: Numerical value defining an amount of results to skip when reading the results of a query. This field can be mapped as input in a mapping and is useful for implementing paginated results.

  • limit: Numerical value defining the maximum number of results to return. This field can be mapped as input in a mapping and is useful for implementing paginated results.

  • count: Returns the number of results that match the query. The optional Apply Skip Limit property can be enabled if the count should consider the effects of the skip and limit fields in the calculation. Otherwise, the operation returns the count for the whole query.

To define an extra field:

  1. Right-click the find query node.

  2. Choose New, then select the extra field to create.

  3. Save the metadata.

getting started mongodb find query extra fields

The extra fields can then be used in mappings.

Create your first mappings

Send data into MongoDB

MongoDB collections can be loaded from any database.

To do this:

  1. Create a Mapping

  2. Drag and drop your source database table

  3. Drag and drop your target MongoDB collection

  4. Map the fields between the source and the target

  5. Define the 'MongoDB Operation' of the MongoDB Template to the expected value

getting started mongodb write example

Read data from MongoDB

You can extract data from MongoDB and load it into a target table.

To do this:

  1. Create a Mapping

  2. Drag and drop:

    1. A source table that will be used to call MongoDB

    2. The MongoDB collection or Query to read

    3. A target table to load data into

  3. Map the root node of the MongoDB collection from the source

  4. Map the fields between MongoDB and the target table as usual

  5. Define the 'MongoDB Operation' of the MongoDB Template to the 'get' value

getting started mongodb read example

Refer to the Template and parameters descriptions for further details
The source table calling MongoDB is used for the repetition key. MongoDB will be called once for each source row.

Sample project

The MongoDB component is distributed with sample projects that contain various examples and files. Use these projects to better understand how the component works, and to get a head start on implementing it in your projects.

Refer to Install components in Semarchy xDI Designer to learn about importing sample projects.