The ~id field

Overview

This page describes the special properties of the ~id field in Gremlin.

Using the ~id keyword

~id is a special keyword in Gremlin.

• You can perform a direct lookup of a vertex or edge by its value with the ~id field.
• You can specify the ~id field for a vertex when loading data, or it can be generated by AGS. For edges, the ~id field is generated by AGS and cannot be user-supplied.
• T.id is an alias for ~id.
• id is not a reserved word. It is a regular property.

Examples

The following Gremlin commands demonstrate ways to use the ~id field.

// Creates a vertex with label 'person', ~id of 1, and property 'name' with value 'Lyndon'
g.addV("person").property(T.id, 1).property("name", "Lyndon").iterate();

// Creates a vertex with label 'person', ~id of 2, and property 'name' with value 'Grant'
g.addV("person").property(T.id, 2).property("name", "Grant").iterate();

// Creates a vertex with label 'person', ~id of 3, and property 'name' with value 'Simon'
g.addV("person").property(T.id, 3).property("name", "Simon").iterate();

// Returns an error, vertex with ~id of 3 already exists
g.addV("person").property(T.id, 3).property("name", "Joe").iterate();

// Performs a direct lookup of the vertex record with ~id of 1
g.V(1).next();

// Performs a batch read of the vertex records with ~id of 1, 2, and 3
g.V(1, 2, 3).toList();

// Creates a vertex with label 'person', property 'id' with value 4, and property 'name' with value 'Joe'
g.addV("person").property("id", 4).property("name", "Joe").iterate();

// This command fails. There is no vertex with ~id of 4
g.V(4).next();

// Returns the vertex with property 'id' with value 4 (the vertex with name 'Joe').
// This command requires running a secondary index query or scan.
g.V().has("id", 4).next();

// Creates a vertex with property 'name' with value 'Steve', no ~id specified
g.addV("person").property("name", "Steve").iterate();

// Returns the AGS-generated ~id
g.V().has("name", "Steve").id().next()