Getting Started with HCL OneDB's MongoDB Solution

This topic covers the basics of getting started with using MongoDB API with HCL OneDB™.

How does HCL OneDB support the MongoDB API?

The HCL OneDB wire listener implements the MongoDB wire protocol. This allows MongoDB applications to connect to the HCL OneDB wire listener and its associated HCL OneDB database server. These applications communicate with HCL OneDB as if it was a MongoDB server, with the wire listener acting as a translation layer between theMongoDB wire protocol and the SQL understood by the HCL OneDB database server.

What are the components of the HCL OneDB MongoDB solution?

There are three main components: the OneDB server, the wire listener, and a MongoDB client. The wire listener is a mid-tier gateway server that enables communication between the MongoDB client and the OneDB server.

How are JSON collections different from relational tables?

A JSON collection holds BSON (binary JSON) data. BSON documents have a flexible schema and can be used with unstructed data, meaning the structure and contents of BSON documents can differ from one document to another. This differs from relational tables where all rows must following the same predefined structure.

HCL OneDB fully supports JSON collections, which can be created through the wire listener. Additionally, the wire listener also makes it possible to run MongoDB queries against your traditional relational tables, using the same MongoDB API that you would use with JSON collections.

How do MongoDB commands map to SQL features?

MongoDB collection methods Informix SQL statements
find SELECT
save/insert INSERT
remove DELETE
update UPDATE
ensureIndex CREATE INDEX
sort ORDER BY
limit LIMIT/FIRST

Commonly customizable wire listener properties

The properties that control the wire listener and the connection between the client and database server are set in the wire listener configuration. The url parameter is required, but all other parameters are optional. Here are the commonly customized parameters.

url

This required parameter specifies the host name, database server, user ID, and password that are used in connections to the HCL OneDB database server.

authentication.enable

This optional parameter indicates whether to enable user authentication. The default value is false.

listener.port

This optional parameter specifies the port number to listen on for incoming connections from MongoDB clients. The default value is 27017.

security.sql.passthrough

This optional parameter indicates whether to enable support for issuing SQL statements through the MongoDB API. The default value is false.

sharding.enable

This optional parameter indicates whether to enable the use of commands and queries on sharded data. The default value is false.

Starting the wire listener from the command line

You can start the wire listener by using a system command. For example:

java -jar $INFORMIXDIR/bin/jsonListener.jar 
   -config $INFORMIXDIR/etc/jsonListener.properties 
   -logFile jsonListener.log -loglevel info -start

MongoDB Create, read, update, and delete (CRUD) operations on collections and tables

These standard MongoDB CRUD operations are supported by HCL OneDB:

  • insert
  • find
  • update
  • remove

This table shows an example of MongoDB operations and comparable SQL statements against relational tables. In the example, the retirement age of a customer is queried:

MongoDB operation Informix SQL statement
db.customer.insert( { name: “John", age: 65 } ) INSERT INTO customer (name, age) VALUES (“John”,65)
db.customer.find() SELECT * FROM customer
db.customer.find( {age: { $gt:65 } } ) SELECT * FROM customer WHERE age > 65
db.customer.drop() DROP TABLE customer
db.customer.ensureIndex( { name : 1, age : -1 } ) CREATE INDEX idx_1 on customer(name, age DESC)
db.customer.remove( {age: { $gt:65 } } ) DELETE FROM customer where age > 65
db.customer.update( { age: { $gt: 64 } }, { $set: { status: “Retire" } }, { multi: true } ) UPDATE customer SET status = “Retire" WHERE age > 64

Implicit operations for JSON collections and databases

If you insert into a non-existent JSON collection, a collection is implicitly created.

If you create a JSON collection in a non-existent database, a database is implicitly created.

Creating and listing indexes

You can use the MongoDB ensureIndex syntax to create an index that works for all data types. For example:

db.collection.ensureIndex( { zipcode: 1 } )
db.collection.ensureIndex( { state: 1, zipcode: -1} )

You can use the HCL OneDB ensureIndex syntax to create an index for a specific data type. For example:

db.collection.ensureIndex( { zipcode : [1, “$int”] } )
db.collection.ensureIndex( { state: [1, “$string”], zipcode: [-1, “$int”] } )

You can list indexes by running the MongoDB getIndexes command.

Accessing multiple databases per connection

In standard OneDB JDBC connections, you must specify the database name on the connection string and you must create one connection per database. In MongoDB, all messages include a fully qualified namespace that includes the database name and the collection. MongoDB connections are not associated with a particular database and each individual message or command specifies the intended database. A single MongoDB connection can switch between databases.

Moving data to and from collections and tables

You can run the MongoDB mongodump and mongoexport utilities to export data from MongoDB to OneDB.

You can run the MongoDB mongorestore and mongoimport utilities to import data from MongoDB to OneDB.

Viewing usage statistics

You can run the MongoDB serverStatus command to get the wire listener status information, including:

  • Uptime
  • Number of active and available connections
  • Number of open cursors
  • Total number of requests
  • Counters for the number operations (queries, inserts, updates, deletes, commands, etc)