Azure Cosmos DB for Gremlin graph support and compatibility with TinkerPop features

APPLIES TO: Gremlin

Azure Cosmos DB supports Apache Tinkerpop's graph traversal language, known as Gremlin. You can use the Gremlin language to create graph entities (vertices and edges), modify properties within those entities, perform queries and traversals, and delete entities.

Azure Cosmos DB Graph engine closely follows Apache TinkerPop traversal steps specification but there are differences in the implementation that are specific for Azure Cosmos DB. In this article, we provide a quick walkthrough of Gremlin and enumerate the Gremlin features that are supported by the API for Gremlin.

Compatible client libraries

The following table shows popular Gremlin drivers that you can use against Azure Cosmos DB:

Supported Graph Objects

TinkerPop is a standard that covers a wide range of graph technologies. Therefore, it has standard terminology to describe what features are provided by a graph provider. Azure Cosmos DB provides a persistent, high concurrency, writeable graph database that can be partitioned across multiple servers or clusters.

The following table lists the TinkerPop features that are implemented by Azure Cosmos DB:

Gremlin wire format

Azure Cosmos DB uses the JSON format when returning results from Gremlin operations. Azure Cosmos DB currently supports the JSON format. For example, the following snippet shows a JSON representation of a vertex returned to the client from Azure Cosmos DB:

  {
    "id": "a7111ba7-0ea1-43c9-b6b2-efc5e3aea4c0",
    "label": "person",
    "type": "vertex",
    "outE": {
      "knows": [
        {
          "id": "3ee53a60-c561-4c5e-9a9f-9c7924bc9aef",
          "inV": "04779300-1c8e-489d-9493-50fd1325a658"
        },
        {
          "id": "21984248-ee9e-43a8-a7f6-30642bc14609",
          "inV": "a8e3e741-2ef7-4c01-b7c8-199f8e43e3bc"
        }
      ]
    },
    "properties": {
      "firstName": [
        {
          "value": "Thomas"
        }
      ],
      "lastName": [
        {
          "value": "Andersen"
        }
      ],
      "age": [
        {
          "value": 45
        }
      ]
    }
  }

The properties used by the JSON format for vertices are described below:

Each property can store multiple values within an array.

And the edge contains the following information to help with navigation to other parts of the graph.

Gremlin steps

Now let's look at the Gremlin steps supported by Azure Cosmos DB. For a complete reference on Gremlin, see TinkerPop reference.

The write-optimized engine provided by Azure Cosmos DB supports automatic indexing of all properties within vertices and edges by default. Therefore, queries with filters, range queries, sorting, or aggregates on any property are processed from the index, and served efficiently. For more information on how indexing works in Azure Cosmos DB, see our paper on schema-agnostic indexing.

Behavior differences

• Azure Cosmos DB Graph engine runs breadth-first traversal while TinkerPop Gremlin is depth-first. This behavior achieves better performance in horizontally scalable system like Azure Cosmos DB.

Unsupported features

• Gremlin Bytecode is a programming language agnostic specification for graph traversals. Azure Cosmos DB Graph doesn't support it yet. Use GremlinClient.SubmitAsync() and pass traversal as a text string.

• property(set, 'xyz', 1) set cardinality isn't supported today. Use property(list, 'xyz', 1) instead. To learn more, see Vertex properties with TinkerPop.

• The match() step isn't currently available. This step provides declarative querying capabilities.

• Objects as properties on vertices or edges aren't supported. Properties can only be primitive types or arrays.

• Sorting by array properties order().by(<array property>) isn't supported. Sorting is supported only by primitive types.

• Non-primitive JSON types aren't supported. Use string, number, or true/false types. null values aren't supported.

• GraphSONv3 serializer isn't currently supported. Use GraphSONv2 Serializer, Reader, and Writer classes in the connection configuration. The results returned by the Azure Cosmos DB for Gremlin don't have the same format as the GraphSON format.

• Lambda expressions and functions aren't currently supported. This includes the .map{<expression>}, the .by{<expression>}, and the .filter{<expression>} functions. To learn more, and to learn how to rewrite them using Gremlin steps, see A Note on Lambdas.

• Transactions aren't supported because of distributed nature of the system. Configure appropriate consistency model on Gremlin account to "read your own writes" and use optimistic concurrency to resolve conflicting writes.

Known limitations

• Index utilization for Gremlin queries with mid-traversal .V() steps: Currently, only the first .V() call of a traversal will make use of the index to resolve any filters or predicates attached to it. Subsequent calls will not consult the index, which might increase the latency and cost of the query.

Assuming default indexing, a typical read Gremlin query that starts with the .V() step would use parameters in its attached filtering steps, such as .has() or .where() to optimize the cost and performance of the query. For example:

g.V().has('category', 'A')

However, when more than one .V() step is included in the Gremlin query, the resolution of the data for the query might not be optimal. Take the following query as an example:

g.V().has('category', 'A').as('a').V().has('category', 'B').as('b').select('a', 'b')

This query will return two groups of vertices based on their property called category. In this case, only the first call, g.V().has('category', 'A') will make use of the index to resolve the vertices based on the values of their properties.

A workaround for this query is to use subtraversal steps such as .map() and union(). This is exemplified below:

// Query workaround using .map()
g.V().has('category', 'A').as('a').map(__.V().has('category', 'B')).as('b').select('a','b')

// Query workaround using .union()
g.V().has('category', 'A').fold().union(unfold(), __.V().has('category', 'B'))

You can review the performance of the queries by using the Gremlin executionProfile() step.

Next steps

• Get started building a graph application using our SDKs
• Learn more about graph support in Azure Cosmos DB