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 AirportWithNotes : Vertex
{
    public VertexProperty<string>? Note { 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 DataSourceMeta
{
    public string? DataSource { get; set; }
}

public class AirportWithDataSource : Vertex
{
    public VertexProperty<string, DataSourceMeta>? Website { 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 _g = g
    .UseGremlinServer<AirportWithNotes, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

_g.AddV(new AirportWithNotes { Note = "Hub airport, 24h operations" });

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 _g = g
    .UseGremlinServer<AirportWithNotes, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

_g.V<AirportWithNotes>().Values(p => p.Note!);

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 _g = g
    .UseGremlinServer<AirportWithDataSource, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson());

_g.V<AirportWithDataSource>().Properties(p => p.Website!).Properties(m => m.DataSource!);

---

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