Microsoft Cosmos DB Graph and Dropwizard-TinkerPop

Azure Cosmos DB is Microsoft’s multi-model database, offering document, relational and graph APIs for developers to build their applications on top of. Graph queries are performed using a large subset of the Apache TinkerPop Gremlin query language. Queries can be submitted via the Cosmos DB API or the Apache TinkerPop Gremlin driver. As an aside, Microsoft’s implementation is, at least as far as I’m aware of, the first non-JVM implementation of a Gremlin virtual machine.

A few months ago we released Dropwizard TinkerPop to provide developers an easy way to integrate TinkerPop connectivity into their Dropwizard applications. This short post will outline how this library can be used to connect to a Cosmos DB graph. For a more in-depth introduction to Dropwizard and Dropwizard TinkerPop, please refer to Building a Microservice using Dropwizard and JanusGraph.

Dependencies

Dropwizard TinkerPop binaries can be pulled from Maven Central using the following coordinates:

       <dependency>

            <groupId>com.experoinc</groupId>

           <artifactId>dropwizard-tinkerpop</artifactId>

            <version>1.0.1</version>

        </dependency>

‍

After adding this to your Dropwizard application’s POM, you’re ready to configure a connection.

Configuration

Dropwizard TinkerPop configuration is set in your Dropwizard config.yml. Cosmos DB connections are secure, over SSL, and require a username and password. We’ll discuss these components using this sample config.

logging:

  level: INFO

  loggers:

    com.experoinc: DEBUG

tinkerPop:

  contactPoints:

    - blog.graphs.azure.com (1)

 port: 443

  serializer:

    type: graphSONMessageSerializerV1d0 (2)

 ssl:

    enabled: true (3)

 auth:

    type: plainText (4)

   username: /dbs/blog/colls/driver-test (5)

   password: your-cosmos-db-key (6)

‍

Your contact point will be filled in using your databases URI (1). As of the writing of this post, Cosmos DB only supports GraphSON V1 serialization (2). Please refer to the Cosmos docs for the latest options. The communication with Cosmos happens over a secure connection so be sure to enable SSL (3).

Finally, set the auth type to plainText (4) and fill in the username and password. The username is in the format /dbs/YOUR-DB-NAME/colls/YOUR-COLLECTION-NAME. Figure 2 (5) shows this hierarchy for our sample graph so that you can see what maps to what. The database name in this case is blog and the collection is driver-test. Use one of your Cosmos DB API keys as the password (6).

Accessing the graph

At this point, If you are familiar with Dropwizard, you can create a graph configuration that will provide access to the Dropwizard TinkerPop TinkerPopFactory object. The build method on that factory will produce an instance of a TinkerPop Cluster from which you can create a TinkerPop client. If this is your first time using the Apache TinkerPop driver, please refer to http://tinkerpop.apache.org/docs/3.2.6/reference/#connecting-via-java for more details. It is important to note that Cosmos DB does not currently support calls via RemoteGraph or the Gremlin Language Variants (GLV). This means that your queries cannot be language embedded and must be constructed as strings and executed using one of the variations of client.submit().

If you are unfamiliar with Dropwizard, or would like more details on including Dropwizard TinkerPop in your application, the preceding steps are described in more detail in Building a Microservice using Dropwizard and JanusGraph.

Conclusion

If you would like to try this out, and are not currently an Azure customer, you can sign up for a free trial at https://azure.microsoft.com/en-us/. Comprehensive Cosmos DB docs can be found at https://docs.microsoft.com/en-us/azure/cosmos-db/introduction. For the definitive Apache TinkerPop reference check out http://tinkerpop.apache.org/docs/3.2.6/reference/. From what I can tell, Cosmos DB currently supports TinkerPop 3.2.5+. Development is moving rapidly though, so be sure to check the Cosmos DB docs to ensure that your TinkerPop driver and reference documentation versions match up with what is supported.