Microsoft Azure Cosmos DB is a globally distributed, multi-model database service supporting document, key-value, graph, and column-family data models. Azure Cosmos DB provides a graph database service via the Gremlin API on a fully managed database service designed for any scale.

Azure Cosmos DB's Gremlin API is built based on the graph computing framework Apache TinkerPop 3.2.  The Gremlin API in Azure Cosmos DB uses the Gremlin query language.  To be clear, Hackolade is not a graph visualization tool, but a tool for data modeling of Cosmos DB Gremlin graph databases.  

To perform data modeling for Cosmos DB Gremlin API with Hackolade, you must first download the Cosmos DB Gremlin API plugin.  You can find more details on graph-specific controls in this page.

Hackolade was specially adapted to support the data modeling of vertices and adges and their respective properties. The application closely follows the terminology of the database.

The data model in the picture below results from the reverse-engineering of a sample graph imported in Cosmos DB.  Two views of the data model are available:

1) a graph view, with familiar circular vertex labels:

2) an Entity-Relationship Diagram (ERD) view, with the advantage of displaying properties for both vertex labels and edge labels:

Vertex labels

Vertex labels are a semantic representation of vertices in the graph.  Vertex labels are used to represent the role of the vertex in the domain, making it possible to query the graph, to define constraints, and add indexes for properties.  Labels can also be used to mark temporary states of a vertex.


A vertex label usually has attributes, called "properties" where the name (or key) is a string.

Property data types

The supported property types are:

  • Number
  • String
  • Boolean

Edge labels

Edge labels are a semantic representation of relationships in the graph. Every relationship must have one and only type, and 2 nodes can be linked by several relationship types.  Relationship types are used during complex traversals across the graph, when only certain kinds of paths from node to node are necessary for a specific query.

In Cosmos DB, edges are unidirectional, going from one vertex label to another vertex label.  In Hackolade we also represent edge labels that are implicitly bi-directional.  For example, IS_MARRIED_TO should not require 2 edge labels, but instead be considered bi-directional.  Since Gremlin does not support the bi-directional concept, marking an edge label as bi-directional in Hackolade is for documentation purposes only.

As Cosmos DB Gremlin is a type of graph database known as 'property graph', edge labels may have attributes, or properties, just like vertex labels:


By default, all Azure Cosmos DB data is indexed.  And while many customers are happy to let Azure Cosmos DB automatically handle all aspects of indexing, it also supports specifying a custom indexing policy for collections during creation.  More information can be found here.

Stored Procedures, database triggers, and user-defined function

Azure Cosmos DB's language integrated transactional execution of JavaScript lets developers write stored procedures, triggers, and user-defined function (UDFs) natively.  Developers can write application logic that be executed on the database storage partitions.  More details can be found here.


Cosmos DB does not provide an abstraction for schemas. Gremlin is a functional, data-flow language that enables users to succinctly express complex traversals on (or queries of) their application's property graph.  In order to provide added-value in forward-engineering, Hackolade provides a graph example in Gremlin syntax for the data model.  The script also includes the creation of indexes, stored Procedures, triggers, and UDFs, and it can be applied to the Azure instance.


For the Gremlin API, the connection is established using a connection string including URI address and port (typically 443), and authentication using an account key. Details on how to connect Hackolade to a Cosmos DB instance can be found on this page.

For more information on Cosmos DB in general, please consult the website.