Connection Setup

Azure Cosmos DB Gremlin API

GremlinStudio connects to Azure Cosmos DB using the Gremlin API. To establish a connection, you need credentials from the Azure Portal and a database with the Gremlin (Graph) API enabled. This guide walks through finding your credentials, configuring your connection, and resolving common issues.

Finding Your Credentials in the Azure Portal

Follow these steps to locate the required connection details:

1. Sign in to the Azure Portal.
2. In the left sidebar, select Resource groups and open the resource group containing your Cosmos DB account.
3. Click on your Azure Cosmos DB account resource.
4. To find your Gremlin Endpoint: In the account overview blade, look for the Gremlin Endpoint field. It follows the format your-account.gremlin.cosmos.azure.com. You can also find this under Settings > Keys in the Gremlin Endpoint row.
5. To find your access key: Navigate to Settings > Keys in the left menu. Copy either the Primary Key or Secondary Key from this page.
6. To confirm your Database and Container names: Navigate to Data Explorer in the left menu. Your database appears in the tree, and the graph container is nested beneath it.

Gremlin Endpoint vs SQL Endpoint

A common mistake when connecting to Azure Cosmos DB Gremlin is using the wrong endpoint. Cosmos DB exposes multiple API endpoints depending on the API type, and they are not interchangeable.

• Correct (Gremlin): your-account.gremlin.cosmos.azure.com
• Incorrect (SQL/Document): your-account.documents.azure.com

If you use the SQL endpoint, connections will fail with authentication or protocol errors. Always verify that your Cosmos DB connection string uses the .gremlin.cosmos.azure.com hostname. The Gremlin endpoint is specifically listed in the Settings > Keys blade in the Azure Portal.

Connection Fields

Field	Description	Example
Name	Friendly label for this connection	”Production Graph”
Endpoint	Gremlin endpoint hostname (no https:// prefix)	your-account.gremlin.cosmos.azure.com
Port	Connection port	443
Database	Database name	graphdb
Container	Graph container name	persons
Key	Primary or secondary access key	abc123...

Connection Limits

• Starter tier: Up to 5 saved connections
• Pro tier: Up to 10 saved connections
• Team tier: Unlimited connections

Connection Security

Your connection credentials are stored locally in a SQLite database on your machine. Keys are never transmitted to any external service and are only sent directly to your Azure Cosmos DB endpoint when executing queries.

For additional safety, consider using a read-only key from the Azure Portal (Settings > Keys > Read-only Keys). Read-only keys allow you to run Gremlin traversals that read data (such as g.V() and g.E()) but prevent any mutations. This is useful when exploring production databases where accidental writes could cause issues.

Azure Discovery

Pro and Team users can use Azure Discovery to automatically find Cosmos DB Gremlin accounts in their Azure subscription. Click the cloud icon in the Connections panel to scan for available databases. This eliminates the need to manually copy endpoints and database names, reducing the chance of configuration errors.

Bulk Import Connections

Bulk Import uses the same saved connection profile shown in the Connections sidebar. Before opening the import wizard, verify that your profile points to the intended database and container.

• Wizard help: Bulk Import
• For Azure-hosted accounts, GremlinStudio derives the Cosmos SDK endpoint from your Gremlin hostname.
• For local emulator workflows, set the profile to localhost with the emulator key and confirm the target container exists.

Using the Azure Cosmos DB Emulator

You can use the Azure Cosmos DB Emulator for local development and testing without incurring Azure costs. The emulator supports the Gremlin API with the following connection details:

Field	Value
Endpoint	localhost
Port	8901
Key	C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Database	Your chosen database name
Container	Your chosen container name

Before connecting from GremlinStudio, you must pre-create the database and graph container in the emulator. Open the emulator’s Data Explorer at https://localhost:8081/_explorer/index.html, create a new database with the Gremlin API, and add a graph container with a partition key. Then use the values above in the GremlinStudio connection form.

Troubleshooting

Connection Refused

• Verify your endpoint URL contains only the hostname, without an https:// prefix.
• Ensure the port is set to 443.
• Check that your Cosmos DB firewall allows your IP address. Navigate to Networking in the Azure Portal and add your current IP under Firewall > IP Rules.

Authentication Failed

• Double-check your primary or secondary key for typos. Copy the key again from Settings > Keys in the Azure Portal.
• Keys can be regenerated in the Azure Portal, but note that regenerating a key immediately invalidates the old one.

Timeout Errors

• Check your internet connection and DNS resolution.
• Verify the Cosmos DB account status is Online in the Azure Portal overview.
• Try increasing the timeout value in the connection settings.

Partition Key Errors

• If you receive errors related to partition keys when creating vertices, ensure your Gremlin queries include the partition key property. For example, if your container uses /category as the partition key, every vertex must include a category property: g.addV('product').property('category', 'electronics').
• You can find your container’s partition key in Data Explorer > your container > Scale & Settings.

Request Rate Too Large (HTTP 429)

• This error means your queries exceeded the provisioned Request Units (RU/s) on your Cosmos DB container. Each Gremlin operation consumes a certain number of RUs based on complexity.
• Short-term fix: Retry the query after a brief pause. GremlinStudio displays the RU charge for each query in the status bar, which helps you identify expensive traversals.
• Long-term fix: Increase the provisioned throughput on your container in the Azure Portal under Scale & Settings, or switch to autoscale throughput.

SSL/TLS Certificate Issues

• When connecting to the local Cosmos DB Emulator, your system may not trust the emulator’s self-signed certificate. Export the emulator certificate and install it in your trusted root certificate store.
• For Azure-hosted Cosmos DB, SSL errors typically indicate a proxy or corporate firewall intercepting traffic. Check with your network administrator.