Azure Cosmos DB: How to query with the Graph API (preview)?

The Azure Cosmos DB Graph API (preview) supports Gremlin queries. This article provides sample documents and queries to get you started. A detailed Gremlin reference is provided in the Gremlin support article.

This article covers the following tasks:

  • Querying data with Gremlin


For these queries to work, you must have an Azure Cosmos DB account and have graph data in the container. Don't have any of those? Complete the 5-minute quickstart or the developer tutorial to create an account and populate your database. You can run the following queries using the Azure Cosmos DB .NET graph library, Gremlin console, or your favorite Gremlin driver.

Count vertices in the graph

The following snippet shows how to count the number of vertices in the graph:



You can perform filters using Gremlin's has and hasLabel steps, and combine them using and, or, and not to build more complex filters. Azure Cosmos DB provides schema-agnostic indexing of all properties within your vertices and degrees for fast queries:

g.V().hasLabel('person').has('age', gt(40))


You can project certain properties in the query results using the values step:


So far, we've only seen query operators that work in any database. Graphs are fast and efficient for traversal operations when you need to navigate to related edges and vertices. Let's find all friends of Thomas. We do this by using Gremlin's outE step to find all the out-edges from Thomas, then traversing to the in-vertices from those edges using Gremlin's inV step:


The next query performs two hops to find all of Thomas' "friends of friends", by calling outE and inV two times.


You can build more complex queries and implement powerful graph traversal logic using Gremlin, including mixing filter expressions, performing looping using the loop step, and implementing conditional navigation using the choose step. Learn more about what you can do with Gremlin support!

Next steps

In this tutorial, you've done the following:

  • Learned how to query using Graph

You can now proceed to the next tutorial to learn how to distribute your data globally.