Vertex Properties

In Apache TinkerPop, vertex properties are first-class elements of the graph — they have their own identity (an id and a label) and can carry meta-properties: key-value annotations attached to the property itself. This is specific to vertices; edges use ordinary Property<TValue> objects that do not support meta-properties.

Gremlinq models this with two generic types in ExRam.Gremlinq.Core.GraphElements:

Type	When to use
VertexProperty<TValue>	The property may have meta-properties but you only care about the value.
VertexProperty<TValue, TMeta>	The meta-properties are important and you want them typed.

Both types implicitly convert from TValue, so you can assign plain values when constructing entities.

VertexProperty<TValue>

Use VertexProperty<TValue> when you want Gremlinq to treat a property as a TinkerPop vertex property (giving it an identity and allowing meta-properties to be written to the graph) but you do not need to query the meta-properties by name in your .NET code.

Entity definition

Declare the property with the VertexProperty<TValue> type. Making it nullable (?) is idiomatic — the property might not exist on every vertex.

C#

public class Contact : Vertex
{
    public VertexProperty<string>? Email { get; set; }
}

The implicit conversion from string (or whichever TValue you use) means you can assign a plain value anywhere a VertexProperty<TValue> is expected.

VertexProperty<TValue, TMeta>

Use VertexProperty<TValue, TMeta> when you want to read or write meta-properties using a strongly-typed class. TMeta is a plain class whose properties map to the meta-property keys on the graph.

Entity definition with meta-properties

Define a TMeta class for the annotations, then use VertexProperty<TValue, TMeta> on the entity.

C#

public class PhoneNumberMeta
{
    public string? Location { get; set; }
}

public class PhoneContact : Vertex
{
    public VertexProperty<string, PhoneNumberMeta>? Phone { get; set; }
}

Working with Vertex Properties

Adding vertices

Because VertexProperty<TValue> implicitly converts from TValue, you can assign a plain value when building the vertex object. Gremlinq translates the implicit conversion into the correct TinkerPop property() step.

Adding a vertex with a VertexProperty

C#

var source = g
    .UseGremlinServer<Contact, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

source.AddV(new Contact { Email = "alice@example.com" });

Querying vertex property values

Use .Values<TValue>(p => p.Property!) to retrieve the underlying value of a vertex property directly — this is a shorthand for .Properties(p => p.Property!).Value().

Retrieving values of a vertex property

C#

var source = g
    .UseGremlinServer<Contact, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

source.V<Contact>().Values<string>(p => p.Email!);

Querying meta-properties

Call .Properties(p => p.Property!) on a vertex query to obtain an IVertexPropertyGremlinQuery. When the vertex property is typed with TMeta, you can then call .Properties<TMetaValue>(m => m.MetaField!) to navigate to a specific meta-property.

Navigating to a meta-property

C#

var source = g
    .UseGremlinServer<PhoneContact, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

source.V<PhoneContact>().Properties(p => p.Phone!).Properties<string>(m => m.Location!);

---

Related: Custom types — registering converters for non-native property value types  |  Property Metadata — renaming properties and controlling write behaviour.