Loading Scripts in the Gremlin Console with the :load Command

      The Gremlin Console is designed to support exploratory graph work, experimentation, and iterative learning. As graphs and console configurations become more involved, repeatedly typing setup commands quickly becomes inefficient and error-prone. The :load command addresses this problem by allowing an entire Groovy script to be executed inside the console with a single instruction.

 

At its core, :load enables repeatable environment initialization. Rather than treating the console as a blank slate on every restart, you can externalize graph creation, configuration, and data loading into a reusable script file and apply it consistently whenever the console starts.

 

What the :load Command Does

The :load command instructs the Gremlin Console to read a Groovy file from disk and execute it line by line, as though each statement were typed directly into the console.

 

Key characteristics include:

·      The file is executed in the current console session

·      All variables defined in the script become available interactively

·      Errors are surfaced immediately, just as they would be with manual input

·      The command can be invoked multiple times during a session

 

This makes :load especially suitable for initializing graphs, defining traversal sources, importing data, and enabling console options.

 

Applying :load to Graph Initialization

Suppose I have following groovy script.

 

sample-graph.groovy

graph = TinkerGraph.open()
g = graph.traversal()

// People
alice = g.addV('person').property('name', 'Alice').property('role', 'Engineer').next()
bob = g.addV('person').property('name', 'Bob').property('role', 'Engineer').next()
carol = g.addV('person').property('name', 'Carol').property('role', 'Manager').next()

// Projects
apollo = g.addV('project').property('name', 'Apollo').property('status', 'Active').next()
zeus = g.addV('project').property('name', 'Zeus').property('status', 'Completed').next()


// People working on projects
g.addE('works_on').from(alice).to(apollo).property('since', 2022)
g.addE('works_on').from(alice).to(zeus).property('since', 2021)

g.addE('works_on').from(bob).to(apollo).property('since', 2023)
g.addE('works_on').from(bob).to(zeus).property('since', 2022)

// Management relationships
g.addE('manages').from(carol).to(apollo)

// Collaboration between people
g.addE('collaborates_with').from(alice).to(bob)
g.addE('collaborates_with').from(bob).to(alice)

// Reporting structure
g.addE('reports_to').from(alice).to(carol)
g.addE('reports_to').from(bob).to(carol)

// Oversight
g.addE('oversees').from(carol).to(zeus)

   

We can load this groovy script into Gremlin console by executing below statement.

:load /Users/Shared/graph/sample-graph.groovy

gremlin> :load /Users/Shared/graph/sample-graph.groovy
==>tinkergraph[vertices:0 edges:0]
==>graphtraversalsource[tinkergraph[vertices:0 edges:0], standard]
==>true
==>v[0]
==>v[3]
==>v[6]
==>true
==>v[9]
==>v[12]
==>true
==>e[15][0-works_on->9]
==>e[16][0-works_on->12]
==>e[17][3-works_on->9]
==>e[18][3-works_on->12]
==>true
==>e[19][6-manages->9]
==>true
==>e[20][0-collaborates_with->3]
==>e[21][3-collaborates_with->0]
==>true
==>e[22][0-reports_to->6]
==>e[23][3-reports_to->6]
==>true
==>e[24][6-oversees->12]
gremlin>

   

Since the groovy script is loaded completely, we can start querying the Graph.

 

gremlin> g.V().valueMap(true)
==>[id:0,label:person,role:[Engineer],name:[Alice]]
==>[id:3,label:person,role:[Engineer],name:[Bob]]
==>[id:6,label:person,role:[Manager],name:[Carol]]
==>[id:9,label:project,name:[Apollo],status:[Active]]
==>[id:12,label:project,name:[Zeus],status:[Completed]]

Why Script Based Loading Matters?

Using :load is not merely a convenience; it is a best practice for serious Gremlin work.

 

·      Consistency: A scripted setup ensures the same graph configuration is used every time. This is particularly important when examples rely on specific ID types, traversal sources, or graph features.

·      Speed and Focus: With setup automated, attention can be directed immediately toward traversal design and graph exploration rather than environment preparation.

·      Reduced Cognitive Load: Complex configuration details—such as ID manager settings—are captured once and reused, eliminating the need to remember or retype them accurately.

·      Reproducibility: Scripts can be shared across teams, books, or training materials, ensuring that readers and practitioners start from an identical baseline.

 

File Location and Path Considerations

The :load command resolves file paths relative to the console’s current working directory. For this reason, using absolute paths is strongly recommended, particularly when scripts reference external resources such as GraphML files.

 

Example

 

:load /full/path/to/sample-graph.groovy

   

This avoids ambiguity and prevents file-not-found errors that can arise when directory contexts change between sessions or systems.

 

In summary, the :load command plays a role similar to a bootstrap script in other development environments. It establishes the foundation upon which all subsequent work depends. By separating environment setup from interactive querying, it promotes clarity, discipline, and reproducibility qualities that align well with professional graph development practices.

 

Previous                                                    Next                                                    Home