@inferagraph/gremlin

@inferagraph/gremlin

Gremlin datasource for @inferagraph/core. Targets the Gremlin protocol — works against any TinkerPop-compatible server, including Apache TinkerPop and Azure Cosmos DB Gremlin API.

Installation

pnpm add @inferagraph/gremlin @inferagraph/core

Migrating from @inferagraph/gremlin-datasource

The package was renamed from @inferagraph/gremlin-datasource to @inferagraph/gremlin in 0.2.0. The class was also renamed from GremlinDatasource to GremlinDataSource (PascalCase S) and a new gremlinDataSource(...) factory is the recommended on-ramp.

pnpm remove @inferagraph/gremlin-datasource
pnpm add @inferagraph/gremlin

- import { GremlinDatasource } from '@inferagraph/gremlin-datasource';
- const datasource = new GremlinDatasource({ endpoint: 'wss://...' });
+ import { gremlinDataSource } from '@inferagraph/gremlin';
+ const datasource = gremlinDataSource({ endpoint: 'wss://...' });

The class is still exported as the escape hatch:

import { GremlinDataSource } from '@inferagraph/gremlin';
const datasource = new GremlinDataSource({ endpoint: 'wss://...' });

Quick start

import { gremlinDataSource } from '@inferagraph/gremlin';

const datasource = gremlinDataSource({
  endpoint: 'wss://your-gremlin-server:443/',
});

await datasource.connect();
const graph = await datasource.getInitialView({ limit: 50 });
await datasource.disconnect();

Configuration

GremlinDataSourceConfig options:

Option	Type	Description
endpoint	string	Gremlin server WebSocket URL (wss://host:port/). Required.
key	string	Auth key. Required for Cosmos DB; omit for an unauthenticated TinkerPop server.
database	string	Cosmos DB database id. Used in the SASL username /dbs/<database>/colls/<container>.
container	string	Cosmos DB container (graph) id.
ssl	boolean	Enable TLS (rarely needed — wss:// already enables it).
poolSize	number	Connection pool size hint.
getCompositeKey	(id: string) => string | [string, string]	Map a logical vertex id to the value(s) passed to g.V(...). Default: identity. See Composite keys.
getType	(vertex: GremlinVertex) => string | undefined	Resolve the semantic type of a vertex. Default: v.label. See Vertex type resolution.
nameProperty	string	Vertex property used for search() and filter({ search }). Default: 'name'. See Name property.

Composite keys (Cosmos DB)

Cosmos DB Gremlin containers are partitioned. Looking a vertex up by id alone does not work — you must pass the partition value too, in the form g.V(['<partitionValue>', '<id>']).

Configure getCompositeKey to translate logical ids into the tuples Cosmos needs. The library uses this everywhere a vertex is identified — getNode, getNeighbors, getContent, the path traversal in findPath, and the bulk edge fetches.

// Cosmos with partitionKey == id (the simplest scheme — what Bible Graph uses):
gremlinDataSource({
  endpoint: 'wss://my-cosmos.gremlin.cosmos.azure.com:443/',
  key: process.env.COSMOS_KEY,
  database: 'mydb',
  container: 'mygraph',
  getCompositeKey: (id) => [id, id],
});

// Cosmos with a partition value derived from the id:
gremlinDataSource({
  // ...endpoint, key, database, container...
  getCompositeKey: (id) => [getPartitionFor(id), id],
});

// Apache TinkerPop / unpartitioned: omit getCompositeKey entirely.
gremlinDataSource({ endpoint: 'wss://localhost:8182/' });

The library does not bake in any partition scheme. Every host-specific mapping is supplied via this option.

Vertex type resolution

By TinkerPop convention, the vertex label IS the type — addV('person') makes the vertex a person. Some hosts use a single label for every vertex and store the actual type in a property instead. getType lets such hosts tell the library where to find the real type.

// Default behavior — equivalent to NOT supplying getType:
gremlinDataSource({
  endpoint,
  getType: (v) => v.label,
});

// Host stores type in a `type` property (every vertex has the same label):
gremlinDataSource({
  endpoint,
  getType: (v) => {
    const t = v.properties?.type as Array<{ value?: unknown }> | undefined;
    return (t?.[0]?.value as string | undefined) ?? v.label;
  },
});

If getType returns undefined, the library falls back to v.label.

GremlinVertex is exported for typing custom resolvers:

import type { GremlinVertex } from '@inferagraph/gremlin';

Name property

search(query) and filter({ search }) issue g.V().has('<nameProperty>', TextP.containing(query)). By default <nameProperty> is 'name' — override when your vertices store the searchable display name on a different property.

// Default — searches the `name` property:
gremlinDataSource({ endpoint });

// Host whose vertices use `title` as the display name:
gremlinDataSource({ endpoint, nameProperty: 'title' });

Usage

await datasource.connect();

const graph     = await datasource.getInitialView({ limit: 50 });
const node      = await datasource.getNode('some-vertex-id');
const neighbors = await datasource.getNeighbors('some-vertex-id', 2);
const path      = await datasource.findPath('alice', 'bob');
const results   = await datasource.search('search term');
const filtered  = await datasource.filter({ types: ['person'] });
const content   = await datasource.getContent('some-vertex-id');

await datasource.disconnect();

Cosmos DB Gremlin notes

• Cosmos containers are partitioned. Always configure getCompositeKey.
• The library uses the composite-key-safe traversal g.V(<keys>).bothE().dedup() for bulk edge fetches and filters dangling endpoints client-side, instead of the more obvious where(otherV().hasId(within(ids))). The latter is unreliable on Cosmos when <ids> is a list of partition tuples.
• findPath terminates with has(T.id, toId) rather than hasId(toId). On Cosmos, T.id compares the document id (the second half of the composite key); on TinkerPop it compares the vertex id directly.

Compatibility

Tested against:

• Apache TinkerPop (Gremlin Server)
• Azure Cosmos DB Gremlin API

The library targets the Gremlin protocol, so it should work against any TinkerPop-compatible server. Hosts whose vertex shape diverges from the defaults can adapt via getCompositeKey and getType.

License

MIT