Quickstart: Azure Cosmos DB for Apache Gremlin client library for .NET

Get started with the Azure Cosmos DB for Apache Gremlin client library for .NET to store, manage, and query unstructured data. Follow the steps in this guide to create a new account, install a .NET client library, connect to the account, perform common operations, and query your final sample data.

Library source code | Package (NuGet)

Prerequisites

• An Azure subscription

  • If you don't have an Azure subscription, create a free account before you begin.

• The latest version of the Azure CLI in Azure Cloud Shell.

  • If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the az login command.

• .NET SDK 9.0 or later

Setting up

First, set up the account and development environment for this guide. This section walks you through the process of creating an account, getting its credentials, and then preparing your development environment.

Create an account

Start by creating an API for Apache Gremlin account. Once the account is created, create the database and graph resources.

Get credentials

Now, get the password for the client library to use to create a connection to the recently created account.

Prepare development environment

Then, configure your development environment with a new project and the client library. This step is the last required prerequisite before moving on to the rest of this guide.

1. Start in an empty folder.

2. Create a new .NET console application

   dotnet new console
   

3. Import the Gremlin.Net package from NuGet.

   dotnet add package Gremlin.Net
   

4. Build the project.

   dotnet build
   

Object model

Code examples

• Authenticate client
• Insert data
• Read data
• Query data

Authenticate client

Start by authenticating the client using the credentials gathered earlier in this guide.

1. Open the Program.cs file in your integrated development environment (IDE).

2. Delete any existing content within the file.

3. Add using directives for the following namespaces:

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

4. Create string variables for the credentials collected earlier in this guide. Name the variables hostname and primaryKey.

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Create a GremlinServer using the credentials and configuration variables created in the previous steps. Name the variable server.

   GremlinServer server = new(
       $"{hostname}.gremlin.cosmos.azure.com",
       443,
       enableSsl: true,
       username: "/dbs/cosmicworks/colls/products",
       password: primaryKey
   );
   

6. Now, create a GremlinClient using the server variable and the GraphSON2MessageSerializer configuration.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

Insert data

Next, insert new vertex and edge data into the graph. Before creating the new data, clear the graph of any existing data.

1. Run the g.V().drop() query to clear all vertices and edges from the graph.

   await client.SubmitAsync("g.V().drop()");
   

2. Create a Gremlin query that adds a vertex.

   string insertVertexQuery = """
       g.addV('product')
           .property('id', prop_id)
           .property('name', prop_name)
           .property('category', prop_category)
           .property('quantity', prop_quantity)
           .property('price', prop_price)
           .property('clearance', prop_clearance)
   """;
   

3. Add a vertex for a single product.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       ["prop_name"] = "Yamba Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 12,
       ["prop_price"] = 850.00,
       ["prop_clearance"] = false
   });
   

4. Add two more vertices for two extra products.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_name"] = "Montau Turtle Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 5,
       ["prop_price"] = 600.00,
       ["prop_clearance"] = true
   });
   
   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "cccccccc-2222-3333-4444-dddddddddddd",
       ["prop_name"] = "Noosa Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 31,
       ["prop_price"] = 1100.00,
       ["prop_clearance"] = false
   });
   

5. Create another Gremlin query that adds an edge.

   string insertEdgeQuery = """
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   """;
   

6. Add two edges.

   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
   });
   

Read data

Then, read data that was previously inserted into the graph.

1. Create a query that reads a vertex using the unique identifier and partition key value.

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

2. Then, read a vertex by supplying the required parameters.

   ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   Dictionary<string, object> matchedItem = readResults.Single();
   

Query data

Finally, use a query to find all data that matches a specific traversal or filter in the graph.

1. Create a query that finds all vertices that traverse out from a specific vertex.

   string findVerticesQuery = """
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   """;
   

2. Execute the query specifying the Montau Turtle Surfboard product.

   ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_name"] = "Montau Turtle Surfboard"
   });
   

3. Iterate over the query results.

   foreach (Dictionary<string, object> result in findResults)
   {
       // Do something here with each result
   }
   

Run the code

Run the newly created application using a terminal in your application directory.

dotnet run

Clean up resources

When you no longer need the account, remove the account from your Azure subscription by deleting the resource.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Next step