Home

Awesome

A Guided Tour of Azure Cosmos DB Gremlin API#

This sample application shows how to interact with Azure CosmosDB Gremlin (Graph) API and visualize the results. The query language used is Gremlin which is a graph traversal language that uses vertices and edges as primary constructs. This sample shows how to put your data into Cosmos DB through a console application using the Azure DocumentDB graph library as well as querying the data using the Gremlin language specification from a user interface.

Prerequisites

Contents of the Sample

The Sample has two projects:

How to run the sample

Uploading the sample data

Uploading the sample data is done via the console application project included in this quick start. The sample app is already configured to point to your collection you created as part of the quick start experience in the portal. 2. Open the <font color='lightblue'>/tools/GraphDataUploaderSample.sln</font> solution in Visual Studio. 3. Verify your collection information in the App.Config. if you downloaded this sample from Azure portal quickstart blade, this is all already pre-configured for you. If you downloaded the sample from the github, you need to create the collection yourself and set these settings.

AppSettingValue
endpointCosmos DB service endpoint (https://{your instance}.documents.azure.com)
authKeyCosmos DB authentication key
databaseCosmos DB database name
collectionCosmos DB collection name
  1. Run the console app. The documents should be imported into your Cosmos DB. You can use the document explorer to view the JSON content. This process can take some time, so be patient. When it is finished, you'll see a message letting you know. NOTE: The console app attempts to synchronize the settings you specify in App.Config with the GraphExplorer's appsettings.json project. If this process fails for any reason, you will see a message, but don't worry. You can always edit the appsettings.json file manually.

Running the GraphExplorer front-end application

  1. Under ./Web/GraphExplorer/ run the npm install command. You might need an elevated command-prompt here.
  2. Open the <font color='lightblue'>/web/GraphExplorer.sln</font> solution in Visual Studio.
  3. Verify your settings in the appsettings.json. if you downloaded this sample from Azure portal quickstart blade, this is all already pre-configured for you. if you downloaded the sample from the github repository, this step is also likely unnecessay. If the console uploader app ran successfully, the appsettings.json file should already be updated for you. But you can double-check just to be sure. If anything doesn't look right, go ahead and edit it now, by entering your Cosmos DB connection parameters for the following values in appsettings.json:
AppSettingValue
endpointCosmos DB service endpoint (https://{your instance}.documents.azure.com)
authKeyCosmos DB authentication key generated by Azure (this is marked as the Primary Key and must be Read-Write)
databaseCosmos DB database name
  1. Run the application (F5).

Enabling Azure Active Directory Authentication (optional)

  1. Register GraphExplorer with your Active Directory tenant (see <a href="https://docs.microsoft.com/en-us/azure/active-directory/active-directory-app-registration"> https://docs.microsoft.com/en-us/azure/active-directory/active-directory-app-registration</a>) and find the Application ID.
  2. Run the following Cmdlet in Powershell and login to get your Tenant ID:
Login-AzureRmAccount
  1. In the file boot.ts change alwaysRequireLogin to true and replace {TenantID} in both URLs with your Tenant ID.
  2. Edit Web.config and set the value of "AuthenticationEnabled" to true.
  3. Additionally replace the value of ida:Tenant with your Tenant ID and the value of ida:Audience with your Application ID.

Basic Description of the Application

The web application allows you to run Gremlin queries against the sample data as well as data you create yourself. It also allows you to assign icons and colors to vertices and edges and the default label for them to beautify the visualization of the graph. Other features on the web application are:

Running a Query <br /> Running a query

1. Enter your gremlin query and execute.
2. If the output is a graph, it will show on the network graph surface.
3. All output are shown on the console area.  This is especially important if your query returns a string or an array of strings instead of a graph.

  Properties

Clicking on any of the nodes or edges will bring up the property pane.  There is a search box to filter properties based on a substring search of the property name.

The Console Area <br /> Console

The console shows any output from the gremlin query including errors
1. There are 2 views on the console, standard summarizes what was returned.  The JSON view shows the raw JSON output.
2. There are some basic controls for the console, including clearing the console content and sizing the console window (expand, collapse, default).

Changing the Icons and Colors of Vertices and Edges <br /> Icons and Colors

1. The icons and colors can be changed globally by either clicking on the Configure Graph button at the bottom left of the window to show all the current node types loaded on the graph and selecting an icon or color for them or
2. You can click on a node and the properties panel also has the Change Color and Change Icon functionality.  Additionally, we can also change the label shown on the graph for the node type.

Note: The application saves your choices so the next time your query loads data with the same node types, they will show the icons and colors you have previously selected.

Saving and Loading Queries <br /> Saving and loading

1. Use the Load Query and Save Query links to open the Save and Load Query dialogs.

Starting a New Collection <br /> New collection

1. Click on the New Collection link to create a new collection.  
2. Give your collection a name.  Note: this creates a new collection on your Cosmos DB and you will be charged for it if you are using Azure instead of the Cosmos DB emulator.
3. You can switch between collections on the Collection drop down.

Open Source libraries used in the sample

This quick start application used some open source libraries (see also ThirdPartyNotices.txt for licenses):