# 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.

```plaintext
// 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()
```