Introduction to SAP HANA Compatibility Layer for MongoDB Wire Protocol

Architecture%20overview%20of%20SAP%20HANA%20compatibility%20layer%20for%20MongoDB%20Wire%20Protocol.

Architecture overview of SAP HANA compatibility layer for MongoDB Wire Protocol.

Picture this: You have an application which uses MongoDB. You have realized that the SAP HANA JSON Document Store would have been a better fit for your application, or maybe your application already uses some other SAP products. Nevertheless, you are considering to make the switch. Well, this would require you to change all the source code which supported MongoDB to now support SAP HANA JSON Document Store. Depending on the size of the application, this could be a rather big task. So, this is where I might be able to help you out!

Introducing SAP HANA compatibility layer for MongoDB Wire Protocol (from here on just compatibility layer). What started as a student project has now become an open-source project at SAP. This project should be a great help to anyone looking to switch from MongoDB to the SAP HANA JSON Document Store. Why? Because compatibility layer is a drop-in replacement for MongoDB which uses SAP HANA JSON Document Store as the storage engine. It enables you to use any MongoDB driver or MongoDB Shell as if you were connected with MongoDB. For now, basic CRUD operations, collection methods and database methods are supported. Read a more elaborate description of what is supported.

The compatibility layer is written in Go and is a fork from FerretDB. FerretDB wants to become the de-facto open-source alternative to MongoDB. They so far offer the possibility to use either Postgres or Tigris as the database engine. Definitely a project worth checking out!

Let’s try it out!

I will introduce two ways for trying out compatibility layer. The first one is to connect with the MongoDB Shell mongosh. This is an ideal way to run some commands and get a feel for what compatibility layer is capable of. The second approach is to connect using a MongoDB driver.

Requirements

To connect using mongosh or any MongoDB driver, we first have to make sure that you have everything required for the setup:

Linux
Go 1.18.*
docker
docker-compose
GNU make
A running SAP HANA Cloud instance with SAP HANA JSON Document Store enabled
Go-hdb

For the installation of go-hdb please follow the two links below:

Install the SAP HANA Client
Connect Using the SAP HANA Go Interface
- Please make sure that you follow the steps till “Create a Go application that queries an SAP HANA database”, because 3. will have to be performed to finish the setup of go-hdb.
Note that the open-source version found here SAP/go-hdb is not compatible with compatibility layer.

Setup compatibility layer

The first step is to clone the repository and cd into it.
Then in the project folder sap-hana-compatibility-layer-for-mongodb-wire-protocol run the following:
```
$ make init
```
This step could take a while as it will install all the needed dependencies.
When step two is done installing all dependencies we can now start up compatibility layer by running the following:
```
$ make run HANAConnectString=<please-insert-connect-string-here>
... (multiple lines)
2022-11-29T19:01:59.555+0100 INFO listener clientconn/listener.go:73  Listening on :27017 ...
```
Multiple lines will appear. Please wait till the last shown line appears. When it appears, compatibility layer is now running.

I hope you made it until here and now have compatibility layer up and running. You should have something similar to the following image. It is now time to choose how to connect.

Connect using mongosh

Open up a new terminal window and run:
```
$ docker-compose up
```
Give step one a couple of seconds and then open a third terminal. We can now connect to compatibility layer using mongosh:

$ make mongosh DB=<please-insert-database-name-here>

If you already have a schema in your SAP HANA Cloud instance which you want to use, then set DB equal to that name. If not, then remove DB and only run “make mongosh”. This will create a schema called DB_NAME. Some shells might require you to put the database name in quotation marks.

Example commands for mongosh

Here are some examples of what you can do. I will leave it to you to try out everything else.

Commands%20used%20can%20be%20found%20here.

Copy/paste commands used.

Connect using a MongoDB driver

I will use the Python driver PyMongo, but any other MongoDB driver should work as well. The only thing you have to do is create the connection string as described in the Python file below and insert it where required for the chosen driver. If you use the Python driver you need to make sure that you have PyMongo installed. An easy way to do this is to use the package installer for Python pip.

from pymongo.mongo_client import MongoClient

# Enter a connection string.
# IP-ADDRESS: Either 127.17.0.1 if running on the same machine as SAP HANA compatibility layer for MongoDB Wire Protocol
#             or the ip-address where SAP HANA compatibility layer for MongoDB Wire Protocol is running.
# DB_NAME: Choose a name for a database (schema in SAP HANA Cloud). Either existing one or new one. 
#          You can also leave DB_NAME and a database with name DB_NAME will be created.  
connection_string = "mongodb://IP-ADDRESS:27017/DB_NAME?heartbeatFrequencyMS=300000"

client = MongoClient(connection_string)

# Change database name if you do not want to use DB_NAME
db = client["DB_NAME"]

# Change collection if you do not want to use FURNITURE
collection = db["FURNITURE"]

documents = [
  {"type": "dinner table", "category": "Kitchen", "measurements": {"width": 120, "depth": 60, "hight": 75}, "color(s)": ["brown", "black", "white"]},
  {"type": "bed", "category": "bedroom", "measurements": {"width": 165, "depth": 200, "hight": 55}, "color(s)": ["grey", "black", "white"]},
  {"type": "bar chair", "category": "Kitchen", "measurements": {"width": 50, "depth": 45, "hight": 120}, "color(s)": ["red", "green"]},
  {"type": "bedroom closet", "category": "bedroom", "measurements": {"width": 150, "depth": 55, "hight": 200}, "color(s)": ["brown"]},
]

collection.insert_many(documents)

for doc in collection.find():
  print(doc)

Summary

Now please do not hesitate to take a look at your SAP HANA Cloud instance where you will now find the schemas, collections and documents which you tried out in one of the two approaches. If you had any problems with setting it up or you feel like there are features missing, please let me know in the comments or create an issue on Github.

If you are now left with the thought, “hmm, more people need to know about this”, then feel free to share it. Most importantly, share it with colleagues who you think might benefit from this. If you are even one of those who could benefit from this, then please do not hesitate to reach out for further information. To everyone who made it this far: Thank you!

P.S.: If you want more content like this, consider following the Open Source tag, the topic SAP Open Source and of course my profile. You could also have a look at SAP HANA JSON Document Store related tags like: JSON Document Store, DOCSTORE and Document Store. If this topic is overall interesting to you and you feel like you have a lot of knowledge to share, why not try and answer some questions in the community to help others out.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.