jm96441n/gremlin

Overview

This skill helps write Gremlin graph traversal queries using the github.com/apache/tinkerpop/gremlin-go/v3/driver library against AWS Neptune. The codebase has a two-layer architecture:

1. gremlin.Store (internal/storage/gremlin/store.go) - Low-level connection management
2. graph.Store (internal/storage/graph/store.go) - Higher-level node/edge operations

Key Patterns

Getting a Traversal Source

Always obtain traversals through the Store, specifying read-only or read-write:

// For read operations
g, err := s.gremlinStore.ReadOnlyTraversal(customerID)

// For write operations
g, err := s.gremlinStore.ReadWriteTraversal(customerID)

The customerID is used as a partition key for multi-tenancy via PartitionStrategy.

Reserved Properties

These internal properties are prefixed with _ and managed automatically:

| Property | Constant | Purpose | |----------|----------|---------| | _modified_time | gremlin.ModifiedTimeProperty | Last modification timestamp | | _owner | gremlin.OwnerProperty | Resource owner identifier | | CustomerID | gremlin.PartitionKey | Multi-tenant partition key |

Common Traversal Patterns

Get a vertex by ID with all properties:

result, err := g.V(nodeID).ValueMap().With(gremlingo.WithOptions.Tokens).ToList()

Filter vertices by label:

g.V().HasLabel("INSTANCE", "SECURITY_GROUP")

Filter by property value:

g.V().Has("name", gremlingo.P.Eq("my-resource"))
g.V().Has(gremlin.ModifiedTimeProperty, gremlingo.P.Gte(modTime))

Traverse edges (outgoing):

g.V(sourceID).OutE("ATTACHES_TO").InV()

Traverse edges (incoming):

g.V(destID).InE("BELONGS_TO").OutV()

Get edge with source and destination:

g.V(source).OutE(label).Where(gremlingo.T__.InV().HasId(dest))

Project specific fields from edges:

g.E().
    Project("id", "label", "mod", "out", "in", "customer", "owner").
    By(gremlingo.T.Id).
    By(gremlingo.T.Label).
    By(modifiedTimeProperty).
    By(gremlingo.T__.OutV().Id()).
    By(gremlingo.T__.InV().Id()).
    By(partitionKey).
    By(ownerProperty).
    ToList()

Upsert Pattern (Merge)

Use MergeV for vertices and MergeE for edges:

// Upsert vertex
g.MergeV(map[any]any{gremlingo.T.Id: nodeID}).
    Option(gremlingo.Merge.OnCreate, map[any]any{
        gremlingo.T.Label: label,
        gremlingo.T.Id:    id,
        "prop1":           gremlingo.CardinalityValue.Single(value),
    }).
    Option(gremlingo.Merge.OnMatch, updateTraversal).
    ToList()

// Upsert edge
g.MergeE(map[any]any{
    gremlingo.T.Label:        edgeLabel,
    gremlingo.Direction.To:   destNodeID,
    gremlingo.Direction.From: sourceNodeID,
}).
    Option(gremlingo.Merge.OnCreate, createMap).
    Option(gremlingo.Merge.OnMatch, updateTraversal).
    Next()

Conditional Updates

Only update if the incoming data is newer:

gremlingo.T__.Choose(
    gremlingo.T__.Or(
        gremlingo.T__.Not(gremlingo.T__.Has(modifiedTimeProperty)),
        gremlingo.T__.Values(modifiedTimeProperty).Is(gremlingo.P.Lt(newModTime)),
    ),
    // If true: update
    updateTraversal,
    // Else: no-op
    gremlingo.T__.Identity(),
).Constant(map[any]any{})

Anonymous Traversals

Use gremlingo.T__ for anonymous traversals (filter conditions, nested steps):

// Check property exists
gremlingo.T__.Has("propertyName")

// Check property does not exist
gremlingo.T__.HasNot("propertyName")

// Combine conditions
gremlingo.T__.And(condition1, condition2)
gremlingo.T__.Or(condition1, condition2)

Delete Operations

// Delete a vertex (also removes connected edges)
g.V(nodeID).Drop().Iterate()

// Delete an edge
g.V(sourceID).OutE(label).Where(gremlingo.T__.InV().HasId(destID)).Drop().Iterate()

// Clear all data for a customer
g.E().Drop().Iterate()
g.V().Drop().Iterate()

Path Queries (Query API)

The query API uses path traversals for returning connected subgraphs:

g.V().
    HasLabel("EC2_INSTANCE").
    OutE("ATTACHES_TO").InV().
    Order().By(gremlingo.T.Id).
    Range(low, high).
    Path().By(gremlingo.T__.ElementMap()).
    ToList()

Transaction Management

For atomic multi-step operations, use transactions:

// Open transaction
tx, gts, err := s.gremlinStore.ReadWriteTxTraversal(customerID)

// Perform operations using gts...

// Commit or rollback
err = tx.Commit()
// or
err = tx.Rollback()

The graph.Store provides higher-level transaction management:

s.OpenTx(customerID)
// ... operations ...
s.CommitTx(customerID)

Predicates

| Predicate | Usage | |-----------|-------| | gremlingo.P.Eq(val) | Equals | | gremlingo.P.Neq(val) | Not equals | | gremlingo.P.Lt(val) | Less than | | gremlingo.P.Lte(val) | Less than or equal | | gremlingo.P.Gt(val) | Greater than | | gremlingo.P.Gte(val) | Greater than or equal |

Result Handling

Results come back as []*gremlingo.Result. Extract data like:

results, err := g.V().ToList()
for _, result := range results {
    data, ok := result.Data.(map[any]any)
    // Process data...
}

// For single result
result, err := g.V(id).Next()

Testing Gremlin Queries

Use testutil.SetupDataStores to get a real Gremlin container:

func TestMyGremlinQuery(t *testing.T) {
    t.Parallel()
    ctx := context.Background()
    ds := testutil.SetupDataStores(ctx, t)
    
    // ds.GremlinStore is a *gremlin.Store
    // ds.GraphStore is a *graph.Store
}

Common Gotchas

1. Always use ToList() or Iterate() - These terminate the traversal and return the connection to the pool
2. Property values are wrapped in arrays - When using ValueMap(), values come back as []any
3. Type assertions are required - Results are any type, always check casts
4. Partition strategy is automatic - Don't manually filter by CustomerID, it's handled by the strategy
5. Time comparisons - Use time.Time directly, it's serialized correctly

Files Reference

• internal/storage/gremlin/store.go - Connection and traversal management
• internal/storage/graph/store.go - Node/edge CRUD operations
• internal/queryapi/processor.go - Complex query building for the Query API