Quickstart: Traverse vertices and edges with the Gremlin console and Azure Cosmos DB for Apache Gremlin

Azure Cosmos DB for Apache Gremlin is a fully managed graph database service implementing the popular Apache Tinkerpop, a graph computing framework using the Gremlin query language. The API for Gremlin gives you a low-friction way to get started using Gremlin with a service that can grow and scale out as much as you need with minimal management.

In this quickstart, you use the Gremlin console to connect to a newly created Azure Cosmos DB for Gremlin account.

Prerequisites

• An Azure account with an active subscription.
  • No Azure subscription? Sign up for a free Azure account.
• Docker host
  • Don't have Docker installed? Try this quickstart in GitHub Codespaces.
• Azure Command-Line Interface (CLI)

Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To use Azure Cloud Shell:

1. Start Cloud Shell.

2. Select the Copy button on a code block (or command block) to copy the code or command.

3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

4. Select Enter to run the code or command.

Create an API for Gremlin account and relevant resources

The API for Gremlin account should be created prior to using the Gremlin console. Additionally, it helps to also have the database and graph in place.

1. Create shell variables for accountName, resourceGroupName, and ___location.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   ___location="westus"
   
   # Variable for account name with a randomly generated suffix
   
   let suffix=$RANDOM*$RANDOM
   accountName="msdocs-gremlin-$suffix"
   

2. If you haven't already, sign in to the Azure CLI using az login.

3. Use az group create to create a new resource group in your subscription.

   az group create \
       --name $resourceGroupName \
       --___location $___location
   

4. Use az cosmosdb create to create a new API for Gremlin account with default settings.

   az cosmosdb create \
       --resource-group $resourceGroupName \
       --name $accountName \
       --capabilities "EnableGremlin" \
       --locations regionName=$___location \
       --enable-free-tier true
   

   Note

   You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. If this command fails to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

5. Get the API for Gremlin endpoint NAME for the account using az cosmosdb show.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "name"
   

6. Find the KEY from the list of keys for the account with az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

7. Record the NAME and KEY values. You use these credentials later.

8. Create a database named cosmicworks using az cosmosdb gremlin database create.

   az cosmosdb gremlin database create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --name "cosmicworks"
   

9. Create a graph using az cosmosdb gremlin graph create. Name the graph products, then set the throughput to 400, and finally set the partition key path to /category.

   az cosmosdb gremlin graph create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category" \
       --throughput 400
   

Start and configure the Gremlin console using Docker

For the gremlin console, this quickstart uses the tinkerpop/gremlin-console container image from Docker Hub. This image ensures that you're using the appropriate version of the console (3.4) for connection with the API for Gremlin. Once the console is running, connect from your local Docker host to the remote API for Gremlin account.

1. Pull the 3.4 version of the tinkerpop/gremlin-console container image.

   docker pull tinkerpop/gremlin-console:3.4
   

2. Create an empty working folder. In the empty folder, create a remote-secure.yaml file. Add this YAML configuration to the file.

   hosts: [<account-name>.gremlin.cosmos.azure.com]
   port: 443
   username: /dbs/cosmicworks/colls/products
   password: <account-key>
   connectionPool: {
     enableSsl: true,
     sslEnabledProtocols: [TLSv1.2]
   }
   serializer: {
     className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0,
     config: {
       serializeResultToString: true
     }
   }
   

   Note

   Replace the <account-name> and <account-key> placeholders with the NAME and KEY values obtained earlier in this quickstart.

3. Open a new terminal in the context of your working folder that includes the remote-secure.yaml file.

4. Run the Docker container image in interactive (--interactive --tty) mode. Ensure that you mount the current working folder to the /opt/gremlin-console/conf/ path within the container.

   docker run -it --mount type=bind,source=.,target=/opt/gremlin-console/conf/ tinkerpop/gremlin-console:3.4
   

5. Within the Gremlin console container, connect to the remote (API for Gremlin) account using the remote-secure.yaml configuration file.

   :remote connect tinkerpop.server conf/remote-secure.yaml
   

Create and traverse vertices and edges

Now that the console is connected to the account, use the standard Gremlin syntax to create and traverse both vertices and edges.

1. Add a vertex for a product with the following properties:

   	Value
   label	product
   id	68719518371
   name	Kiama classic surfboard
   price	285.55
   category	surfboards

   :> g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')
   

   Important

   Don't forget the :> prefix. THis prefix is required to run the command remotely.

2. Add another product vertex with these properties:

   	Value
   label	product
   id	68719518403
   name	Montau Turtle Surfboard
   price	600
   category	surfboards

   :> g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600).property('category', 'surfboards')
   

3. Create an edge named replaces to define a relationship between the two products.

   :> g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))
   

4. Count all vertices within the graph.

   :> g.V().count()
   

5. Traverse the graph to find all vertices that replaces the Kiama classic surfboard.

   :> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Kiama classic surfboard').inE('replaces').outV()
   

6. Traverse the graph to find all vertices that Montau Turtle Surfboard replaces.

   :> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()
   

Clean up resources

When you no longer need the API for Gremlin account, delete the corresponding resource group.

1. Create a shell variable for resourceGroupName if it doesn't already exist.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   

2. Use az group delete to delete the resource group.

   az group delete \
       --name $resourceGroupName
   

How did we solve the problem?

Azure Cosmos DB for Apache Gremlin solved our problem by offering Gremlin as a service. With this offering, you aren't required to stand up your own Gremlin server instances or manage your own infrastructure. Even more, you can scale your solution as your needs grow over time.

To connect to the API for Gremlin account, you used the tinkerpop/gremlin-console container image to run the gremlin console in a manner that didn't require a local installation. Then, you used the configuration stored in the remote-secure.yaml file to connect from the running container the API for Gremlin account. From there, you ran multiple common Gremlin commands.