Quickstart: Azure Cosmos DB for Apache Gremlin client library for Node.js

2025-07-21
Applies to: ✅ Apache Gremlin

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

Library source code | Package (npm)

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.

Node.js 22 or newer

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.

Azure CLI
Azure portal

If you don't already have a target resource group, use the az group create command to create a new resource group in your subscription.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use the az cosmosdb create command to create a new Azure Cosmos DB for Apache Gremlin account with default settings.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableGremlin"

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

az cosmosdb gremlin database create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Use the az cosmosdb gremlin graph create command to create a new graph named products.

az cosmosdb gremlin graph create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category"

Sign in to the Azure portal (https://portal.azure.com).
Enter Azure Cosmos DB in the global search bar.
Within Services, select Azure Cosmos DB.
In the Azure Cosmos DB pane, select Create, and then Azure Cosmos DB for Apache Gremlin within the Others tab.

Within the Basics pane, configure the following options, and then select Review + create:

	Value
Workload Type	Learning
Subscription	Select your Azure subscription
Resource Group	Create a new resource group or select an existing resource group
Account Name	Provide a globally unique name
Availability Zones	Disable
Location	Select a supported Azure region for your subscription

Tip

You can leave any unspecified options to their default values. You can also configure the account to limit total account throughput to 1,000 request units per second (RU/s) or enable free tier to minimize your costs.

On the Review + create pane, wait for validation of your account to finish successfully, and then select Create.
The portal automatically navigates to the Deployment pane. Wait for the deployment to complete.
Once the deployment is complete, select Go to resource to navigate to the new API for Apache Gremlin account.
In the resource menu, select the Data Explorer option.
In the Data Explorer, select + New Graph.
In the Add Graph dialog, configure the following options, and then select OK:

Value

Database Create new

Database name cosmicworks

Graph name products

Partition key /category

Tip

You can leave any unspecified options to their default values.

	Value
Database	Create new
Database name	`cosmicworks`
Graph name	`products`
Partition key	`/category`

Get credentials

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

Azure CLI
Azure portal

Use az cosmosdb show to get the host for the account.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{host:name}"

Record the value of the host property from the previous commands' output. This property' value is the host you use later in this guide to connect to the account with the library.

Use az cosmosdb keys list to get the keys for the account.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Record the value of the primaryMasterKey property from the previous commands' output. This property's value is the key you use later in this guide to connect to the account with the library.

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.

Start in an empty folder.
Initialize a new module.
```
npm init es6 --yes
```
Install the gremlin package from Node Package Manager (npm).
```
npm install --save gremlin
```
Create the index.js file.

Start in an empty folder.
Initialize a new module.
```
npm init es6 --yes
```
Install the typescript package from Node Package Manager (npm).
```
npm install --save-dev typescript
```
Install the tsx package from npm.
```
npm install --save-dev tsx
```
Install the gremlin package from npm.
```
npm install --save gremlin
```
Install the @types/node package from npm.
```
npm install --save-dev @types/node
```
Install the @types/gremlin package from npm.
```
npm install --save-dev @types/gremlin
```

Initialize the TypeScript project using the compiler (tsc).

npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

Create the index.ts file.

Object model

	Description
`DriverRemoteConnection`	Represents the connection to the Gremlin server
`GraphTraversalSource`	Used to construct and execute Gremlin traversals

Authenticate client

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

Open the index.js file in your integrated development environment (IDE).

Import the gremlin package and required types:

import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

Create string variables for the credentials collected earlier in this guide. Name the variables hostname and primaryKey.
```
const hostname = '<host>';
const primaryKey = '<key>';
```
Create an object of type PlainTextSaslAuthenticator using the credentials and configuration variables created in the previous steps. Store the object in a variable named authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Create a Client object using the authenticator variable. Name the variable client.

const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

Open the index.ts file in your integrated development environment (IDE).

Import the gremlin package and required types:

import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

Create string variables for the credentials collected earlier in this guide. Name the variables hostname and primaryKey.
```
const hostname: string = '<host>';
const primaryKey: string = '<key>';
```
Create an object of type PlainTextSaslAuthenticator using the credentials and configuration variables created in the previous steps. Store the object in a variable named authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Create a Client object using the authenticator variable. Name the variable client.

const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

Insert data

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

Run the g.V().drop() query to clear all vertices and edges from the graph.
```
await client.submit('g.V().drop()');
```

Create a Gremlin query that adds a vertex.

const insert_vertex_query = `
    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)
`;

Add a vertex for a single product.

await client.submit(insert_vertex_query, {
    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,
});

Add two more vertices for two extra products.

await client.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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,
});

Create another Gremlin query that adds an edge.

const insert_edge_query = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

Add two edges.

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
});

Run the g.V().drop() query to clear all vertices and edges from the graph.
```
await client.submit('g.V().drop()');
```

Create a Gremlin query that adds a vertex.

const insert_vertex_query: string = `
    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)
`;

Add a vertex for a single product.

await client.submit(insert_vertex_query, {
    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,
});

Add two more vertices for two extra products.

await client.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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,
});

Create another Gremlin query that adds an edge.

const insert_edge_query: string = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

Add two edges.

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    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.

Create a query that reads a vertex using the unique identifier and partition key value.
```
const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
```

Then, read a vertex by supplying the required parameters.

let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

Create a query that reads a vertex using the unique identifier and partition key value.
```
const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
```

Then, read a vertex by supplying the required parameters.

let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

Query data

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

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

const find_vertices_query = `
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
`;

Execute the query specifying the Montau Turtle Surfboard product.

let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

Iterate over the query results.

for (const item of find_results._items) {
    // Do something here with each result
}

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

const find_vertices_query: string = `
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
`;

Execute the query specifying the Montau Turtle Surfboard product.

let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

Iterate over the query results.

for (const item of find_results._items) {
    // Do something here with each result
}

Run the code

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

node index.js

npx tsx index.ts

Clean up resources

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

Azure CLI
Azure portal

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

Next step

Overview of Azure Cosmos DB for Apache Gremlin