{"id":10972,"library":"gremlin","title":"Gremlin JavaScript Driver for Apache TinkerPop","description":"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.","status":"active","version":"3.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/apache/tinkerpop","tags":["javascript","graph","gremlin","tinkerpop","apache-tinkerpop","connection","glv","driver","database"],"install":[{"cmd":"npm install gremlin","lang":"bash","label":"npm"},{"cmd":"yarn add gremlin","lang":"bash","label":"yarn"},{"cmd":"pnpm add gremlin","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Client } from 'gremlin';","symbol":"Client","correct":"import { Client } from 'gremlin/lib/driver/client';"},{"note":"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.","wrong":"const DriverRemoteConnection = require('gremlin').driver.DriverRemoteConnection;","symbol":"DriverRemoteConnection","correct":"import { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection';"},{"note":"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.","wrong":"import { traversal } from 'gremlin';\nconst g = traversal().withRemote(connection);","symbol":"process.AnonymousTraversalSource.traversal","correct":"import { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source';\nconst g = AnonymousTraversalSource.traversal().withRemote(connection);"},{"note":"`P` (predicates like `eq`, `gt`, `lt`) and other traversal statics are grouped under `statics` within the `process/traversal` module.","wrong":"import { P } from 'gremlin';","symbol":"statics.P","correct":"import { statics } from 'gremlin/lib/process/traversal';\nconst { P } = statics;"}],"quickstart":{"code":"import { Client } from 'gremlin/lib/driver/client';\nimport { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection';\nimport { Graph } from 'gremlin/lib/structure/graph';\nimport { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source';\n\nconst gremlinServerUrl = process.env.GREMLIN_SERVER_URL ?? 'ws://localhost:8182/gremlin';\n\nasync function runGremlinQuery() {\n  let connection: DriverRemoteConnection | null = null;\n  try {\n    // Establish a remote connection to the Gremlin Server\n    connection = new DriverRemoteConnection(gremlinServerUrl);\n    \n    // Create a GraphTraversalSource (g) for fluent Gremlin traversals\n    const g = AnonymousTraversalSource.traversal().withRemote(connection);\n\n    // Execute a simple traversal: count all vertices\n    const vertexCount = await g.V().count().next();\n    console.log(`Number of vertices in the graph: ${vertexCount.value}`);\n\n    // Add a new vertex and retrieve it\n    const newVertex = await g.addV('person').property('name', 'Alice').next();\n    console.log(`Added vertex with ID: ${newVertex.value.id} and label: ${newVertex.value.label}`);\n\n    // Count all 'person' vertices\n    const personCount = await g.V().hasLabel('person').count().next();\n    console.log(`Number of 'person' vertices: ${personCount.value}`);\n\n  } catch (err) {\n    console.error('Error during Gremlin traversal:', err);\n  } finally {\n    if (connection) {\n      await connection.close();\n      console.log('Gremlin connection closed.');\n    }\n  }\n}\n\nrunGremlinQuery();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Older 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.","severity":"breaking","affected_versions":"<3.3.3"},{"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.","message":"Gremlin 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=3.5.0"},{"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.","message":"Performing 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment is running version 20 or higher to maintain compatibility with `gremlin` 3.8.x and future releases.","message":"The `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.","severity":"breaking","affected_versions":"<3.8.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Server error (no request information): Invalid OpProcessor requested [null] (499)"},{"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.","cause":"The Gremlin Server is not running, is inaccessible at the specified URL, or a firewall is blocking the connection.","error":"WebSocket connection to 'ws://localhost:8182/gremlin' failed: WebSocket is closed before the connection is established."},{"fix":"Ensure `g` is correctly initialized by chaining `AnonymousTraversalSource.traversal().withRemote(connection)` after establishing a `DriverRemoteConnection`. This pattern creates the fluent traversal source.","cause":"The `g` object (GraphTraversalSource) was not correctly initialized, or the `withRemote` method was not properly used to attach a connection.","error":"TypeError: g.V is not a function"},{"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.","cause":"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.","error":"Error: AnySerializer.deserialize(...): unknown {type_code}"}],"ecosystem":"npm"}