gremlin

library0.6jsnpmunverified

The `gremlin` package provides the official JavaScript Gremlin Language Variant (GLV) for Apache TinkerPop, enabling developers to interact with any TinkerPop-enabled graph database. Currently stable at version 3.8.1, this driver is actively maintained with typically 3-4 releases per year, often aligning with major/minor TinkerPop versions. It differentiates itself by being the official Apache project, supporting bytecode-based traversals (the recommended approach over string-based scripts for better performance, portability, and security), and runs on Node.js (version 20 and higher) with experimental support for Web APIs. The driver establishes a WebSocket connection to a remote Gremlin Server or a compatible graph provider, translating JavaScript method calls into Gremlin traversals for execution on the server-side.

database http-networking serialization

npm install gremlin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GREMLIN

gremlin

databasejavascriptv0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ import { Client } from 'gremlin/lib/driver/client';

✗ import { Client } from 'gremlin';

The Client class is typically imported from its specific driver path for direct WebSocket client interactions, while the top-level 'gremlin' import groups several modules. Named imports are standard for ESM.

DriverRemoteConnection

✓ import { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection';

✗ const DriverRemoteConnection = require('gremlin').driver.DriverRemoteConnection;

Prior to TinkerPop 3.3.3, `DriverRemoteConnection` was not properly exported from the main `gremlin` module, requiring a deep import. While fixed, specific path import remains a robust pattern. CommonJS `require` is also shown as a legacy usage.

process.AnonymousTraversalSource.traversal

✓ import { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source'; const g = AnonymousTraversalSource.traversal().withRemote(connection);

✗ import { traversal } from 'gremlin'; const g = traversal().withRemote(connection);

The traversal source `g` is typically instantiated from `AnonymousTraversalSource.traversal()`. Direct top-level import of `traversal` is not the standard pattern. Using `g` is a convention for the graph traversal source.

statics.P

✓ import { statics } from 'gremlin/lib/process/traversal'; const { P } = statics;

✗ import { P } from 'gremlin';

`P` (predicates like `eq`, `gt`, `lt`) and other traversal statics are grouped under `statics` within the `process/traversal` module.

This quickstart demonstrates how to establish a connection to a Gremlin Server, create a graph traversal source, execute a simple vertex count, add a new vertex with properties, and then count specific vertices, showcasing fundamental Gremlin operations.

import { Client } from 'gremlin/lib/driver/client'; import { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection'; import { Graph } from 'gremlin/lib/structure/graph'; import { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source'; const gremlinServerUrl = process.env.GREMLIN_SERVER_URL ?? 'ws://localhost:8182/gremlin'; async function runGremlinQuery() { let connection: DriverRemoteConnection | null = null; try { // Establish a remote connection to the Gremlin Server connection = new DriverRemoteConnection(gremlinServerUrl); // Create a GraphTraversalSource (g) for fluent Gremlin traversals const g = AnonymousTraversalSource.traversal().withRemote(connection); // Execute a simple traversal: count all vertices const vertexCount = await g.V().count().next(); console.log(`Number of vertices in the graph: ${vertexCount.value}`); // Add a new vertex and retrieve it const newVertex = await g.addV('person').property('name', 'Alice').next(); console.log(`Added vertex with ID: ${newVertex.value.id} and label: ${newVertex.value.label}`); // Count all 'person' vertices const personCount = await g.V().hasLabel('person').count().next(); console.log(`Number of 'person' vertices: ${personCount.value}`); } catch (err) { console.error('Error during Gremlin traversal:', err); } finally { if (connection) { await connection.close(); console.log('Gremlin connection closed.'); } } } runGremlinQuery();

Debug

Known issues

breakingOlder versions of the `gremlin` driver (pre-TinkerPop 3.3.3) did not support GraphSON3, which became the default serialization format for Gremlin Server 3.3+. This led to serialization errors. The current driver (v3.8.1) uses GraphBinary as its default serialization. Ensure your Gremlin Server and client use compatible serialization protocols.

fix

Upgrade to `gremlin` version 3.3.3 or newer. If using an older server with a newer client, explicitly configure the `mimeType` in `DriverRemoteConnection` options to `application/vnd.gremlin-v2.0+json` on the client side, and ensure the server is configured to use GraphSON2.

affects: <3.3.3

gotchaGremlin operations with the `gremlin` driver are inherently transactional on the server side: each bytecode-based request constitutes a single transaction (commit on success, rollback on failure). Extending transactions over multiple requests typically requires using sessions with script-based submissions, which is generally not recommended due to portability, security, and future deprecation concerns.

fix

Design your graph mutations to be idempotent where possible. For complex multi-step updates, consider using server-side transactions if your graph database supports them, or restructure your traversals to fit within single bytecode requests. Avoid relying on explicit client-side transaction management that spans multiple requests unless using Gremlin Server sessions, which should be done with caution.

affects: >=3.0.0

gotchaWhen querying AWS Neptune, the `profile()` and `explain()` traversal steps may fail or return incomplete results when using Graph Binary serialization due to Neptune's specific query optimization.

fix

For query profiling and explanation on AWS Neptune, prefer using Neptune's dedicated `/profile` and `/explain` APIs instead of the Gremlin `profile()` and `explain()` steps.

affects: >=3.5.0

gotchaPerforming full graph scans with `g.V().count()` can be very resource-intensive on large graph databases, as it typically forces the traversal to visit all vertices across all partitions. This can lead to performance degradation.

fix

Avoid `g.V().count()` for general size checks on large production graphs. Instead, use more targeted traversals, maintain a separate count in an external system, or leverage specific graph database features for estimating graph size if available. Use indexed traversals (e.g., `g.V().hasLabel('person').count()`) when counting specific subsets.

affects: >=3.0.0

breakingThe `gremlin` package has increased its minimum Node.js version requirement over time. As of TinkerPop 3.8.0, the minimum supported Node.js version is 20. Using older Node.js versions will result in compatibility issues.

fix

Ensure your Node.js environment is running version 20 or higher to maintain compatibility with `gremlin` 3.8.x and future releases.

affects: <3.8.0

Errors

Common errors & fixes

Error: Server error (no request information): Invalid OpProcessor requested [null] (499)

This error typically indicates a mismatch in the serialization configuration between the Gremlin client and the Gremlin Server, or the client attempting an operation not supported by the server's configured OpProcessors.

fix

Ensure the Gremlin Server is configured with the expected serializers (e.g., GraphSON3 or GraphBinary) and that the client's `mimeType` option in `DriverRemoteConnection` matches. For specific graph providers like Azure Cosmos DB, ensure necessary authentication and specific `mimeType` settings are applied.

WebSocket connection to 'ws://localhost:8182/gremlin' failed: WebSocket is closed before the connection is established.

The Gremlin Server is not running, is inaccessible at the specified URL, or a firewall is blocking the connection.

fix

Verify that your Gremlin Server is running and listening on the correct host and port. Check network connectivity and firewall rules. Ensure the `gremlinServerUrl` in your client code is accurate.

TypeError: g.V is not a function

The `g` object (GraphTraversalSource) was not correctly initialized, or the `withRemote` method was not properly used to attach a connection.

fix

Ensure `g` is correctly initialized by chaining `AnonymousTraversalSource.traversal().withRemote(connection)` after establishing a `DriverRemoteConnection`. This pattern creates the fluent traversal source.

Error: AnySerializer.deserialize(...): unknown {type_code}

A serialization error occurred during deserialization of a response from the Gremlin Server, often indicating a data type that the client's current serializer does not understand or a mismatch in Graph Binary/GraphSON versions.

fix

This can happen with complex data types or specific traversal steps (like `profile()`) not fully supported by the client's default serializer or the remote graph's capabilities. Check compatibility between your Gremlin driver version, Gremlin Server version, and specific graph database. For AWS Neptune, this error can appear with `profile()` and `explain()` steps.

Upgrade

Version history

0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/apache/tinkerpop ↗

packagehttps://www.npmjs.com/package/gremlin ↗

homepagehttps://tinkerpop.apache.org ↗