G GremlinStudio

Getting Started

Install GremlinStudio and run your first Gremlin query in under 5 minutes.

GremlinStudio is a desktop graph database IDE built for Azure Cosmos DB Gremlin API. This guide walks you through installation, connecting to your first database, and running a query. Whether you are exploring a new graph dataset or managing production data, GremlinStudio provides a complete Gremlin IDE setup with an integrated editor, real-time visualization, and debugging tools.

System Requirements

Before installing, make sure your machine meets the following minimum requirements:

RequirementMinimum
Operating SystemWindows 10 or later, macOS 12 (Monterey) or later, Ubuntu 20.04 or later
RAM4 GB (8 GB recommended for large graph datasets)
Disk Space200 MB for the application
NetworkInternet connection required for Azure Cosmos DB connectivity
BrowserAny modern browser (Chrome, Edge, Firefox, Safari) — opens automatically on launch

GremlinStudio runs as a local web server and opens your default browser. No cloud account is required to install the application itself, though you will need access to an Azure Cosmos DB Gremlin account or the Cosmos DB Emulator to query graph data.

Download & Install

Download the latest version from the Download page or GitHub Releases.

Windows

  1. Extract GremlinStudio-win-x64.zip to a folder of your choice
  2. Run GremlinStudio.exe — if Windows SmartScreen appears, click More info then Run anyway
  3. Your browser opens automatically to the GremlinStudio interface

macOS

  1. Extract the zip (osx-arm64 for Apple Silicon, osx-x64 for Intel Macs)
  2. Open Terminal, navigate to the extracted folder, and run:
chmod +x GremlinStudio
xattr -dr com.apple.quarantine .
./GremlinStudio

The xattr command clears the macOS Gatekeeper quarantine flag. This is required for apps not distributed through the App Store.

Linux

  1. Extract GremlinStudio-linux-x64.zip to a folder of your choice
  2. Open a terminal and run:
chmod +x GremlinStudio
./GremlinStudio

Your browser opens automatically (requires xdg-open).

Add Your First Connection

To start querying, you need a connection profile pointing to your Azure Cosmos DB Gremlin account. If you do not have an Azure account yet, you can use the Cosmos DB Emulator for local development.

  1. Click the Connections icon in the left Activity Bar
  2. Click + New Connection
  3. Enter your Azure Cosmos DB details:
    • Name: A friendly label (e.g., “My Graph DB”)
    • Endpoint: Your Cosmos DB Gremlin endpoint (e.g., your-account.gremlin.cosmos.azure.com)
    • Port: 443 (default for Cosmos DB)
    • Database: Your database name
    • Container: Your graph container name
    • Key: Your Cosmos DB primary or secondary key
  4. Click Save — GremlinStudio connects automatically

Finding Your Credentials in the Azure Portal

Open the Azure Portal and navigate to your Cosmos DB account. Under Settings, click Keys to find your primary key and connection strings. Your Gremlin endpoint is listed on the Overview page.

Make sure your Cosmos DB account uses the Gremlin API (also called the Graph API), not the SQL API or MongoDB API. The Gremlin endpoint follows the format your-account.gremlin.cosmos.azure.com. If your endpoint contains .documents.azure.com, you are looking at the SQL API endpoint and queries will not work.

When creating a new graph database and container in the Azure Portal, you will be asked for a partition key. This is a property path (e.g., /category or /pk) that Cosmos DB uses to distribute data. Choose a property that exists on most of your vertices and provides good cardinality. GremlinStudio does not require a specific partition key — it works with whatever partition strategy your database uses.

Working with the Cosmos DB Emulator

For local development and testing without an Azure subscription, you can use the Azure Cosmos DB Emulator. Once the emulator is running, create a connection in GremlinStudio with these settings:

  • Endpoint: localhost
  • Port: 8901
  • Key: The standard emulator key (found in the emulator’s local web UI at https://localhost:8081/_explorer/index.html)
  • Database / Container: The database and graph container you created in the emulator

The emulator supports the Gremlin API and is a good way to prototype graph schemas before deploying to Azure.

Understanding the Interface

When GremlinStudio opens, you will see a workspace divided into several areas:

  • Activity Bar (left edge): Icons for switching between Connections, Schema, History, Templates, and Settings panels
  • Sidebar (left panel): Displays the content for whichever Activity Bar icon is selected, such as your saved connections or schema tree
  • Query Editor (center): A Monaco-based code editor with Gremlin syntax highlighting, autocomplete, and multi-tab support. Press Ctrl+Enter to execute the current query
  • Results Panel (below editor): Shows query output across multiple views — Graph, Table, JSON, and Raw tabs
  • Graph View: An interactive Sigma.js visualization where you can pan, zoom, and click on vertices and edges to inspect their properties

You can resize panels by dragging the dividers between them. The results panel includes a maximize button to expand the graph and results to fill the entire window, which is useful when exploring large datasets.

Run Your First Query

With a connection active, type a Gremlin query in the editor:

g.V().limit(10)

Press Ctrl+Enter (or click the Run button) to execute. Results appear in the panel below as:

  • Graph — Interactive visualization of vertices and edges
  • Table — Sortable, searchable result grid with CSV export
  • JSON — Collapsible JSON tree view
  • Raw — Unformatted server response

Try a few more queries to explore your data:

g.V().hasLabel('person').limit(5)
g.V().has('name','Alice').bothE()
g.E().limit(10)

Edge queries automatically fetch connected vertices so the graph visualization can display complete relationships.

What’s Next?

Now that you have GremlinStudio running and connected, explore these features to get the most out of your graph database IDE: