Getting started with Azure Cosmos DB: Graph API

Azure Cosmos DB is a globally distributed, multi-model database for mission critical applications. Azure Cosmos DB provides the Graph API for applications that need to model, query, and traverse large graphs efficiently using the Gremlin standard.

About this sample: Using the Gremlin.Net open-source connector with Cosmos DB and its advantages.

This sample uses the open-source Gremlin.Net driver to connect to an Azure Cosmos DB Graph API account and run some basic Create, Read, Update, Delete Gremlin queries.

Getting Started


The only dependency is the Gremlin.Net driver version 3.4.13, which you can install with the following instructions:

  • Using .NET CLI:

    dotnet add package Gremlin.Net
  • Using Powershell Package Manager:

    Install-Package Gremlin.Net -Version 3.4.13
  • For .NET CORE use the nuget command-line utility:

    nuget install Gremlin.Net

Input your database identifiers

The program will take the database connection parameters from the environment variables. You'll need to specify the following variables:

  • Host: The endpoint to your Gremlin database. This has the following format
  • PrimaryKey: Your unique access key to your database. This is a long, secure combination of characters and numbers.
  • DatabaseName: The name of your database that groups your containers.
  • ContainerName: The name of the container, also known as graph, where your data is direclty stored.

You can set an environment variable like this:

  • Powershell: $env:YourVariable="value"
  • CMD: setx YourVariable="value"

Build & Run

From the command prompt where you specified the input environment variables:

  1. Go to GremlinNetSample folder.
  2. Run this command: dotnet run

The sample will run the sequence of queries and print the results and response attributes returned by the Cosmos DB Gremlin API.


The following dictionary, under Program.cs, includes all the Gremlin queries that will be executed serially:

Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    { "Cleanup",        "g.V().drop()" },
    { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44)" },
    { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39)" },
    { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller')" },
    { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield')" },
    { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
    { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
    { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
    { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
    { "CountVertices",  "g.V().count()" },
    { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
    { "Project",        "g.V().hasLabel('person').values('firstName')" },
    { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
    { "Traverse",       "g.V('thomas').outE('knows').inV().hasLabel('person')" },
    { "Traverse 2x",    "g.V('thomas').outE('knows').inV().hasLabel('person').outE('knows').inV().hasLabel('person')" },
    { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
    { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
    { "CountEdges",     "g.E().count()" },
    { "DropVertex",     "g.V('thomas').drop()" },

Graph database support overview

Azure Cosmos DB provides you with a fully-managed graph database service with global distribution, elastic scaling of storage and throughput, automatic indexing and query, tunable consistency levels, and supports the Gremlin standard. It also provides the ability to use multiple models like document and graph over the same data. For example, you can use a document collection to store graph data side by side with documents, and use both SQL queries over JSON and Gremlin queries to query the collection. For Graph API, this documentation page lists all the supported Gremlin steps: Azure Cosmos DB Gremlin Graph Support.