Query environment

IGremlinQueryEnvironment is the central configuration object that every Gremlinq query carries with it. It bundles the graph model, serializer and deserializer chains, typed options, a logger, and the executor that dispatches queries to the database. The environment is immutable: every Configure* method returns a new instance; the original is left untouched.

What the environment holds

Property	Type	What it holds
Model	IGraphModel	Vertex and edge type registrations and property metadata
Serializer	ITransformer	Chain converting .NET objects to database wire format
Deserializer	ITransformer	Chain converting database wire format to .NET objects
NativeTypes	IImmutableSet<Type>	Types the database recognises as first-class scalars
Options	IGremlinqOptions	Typed option bag (GremlinqOption<T> values)
Logger	ILogger	Microsoft.Extensions.Logging sink for query diagnostics
Executor	IGremlinQueryExecutor	Sends serialized queries to the server and returns raw results
Debugger	IGremlinQueryDebugger	Intercepts queries before execution (used by the Diagnostics extension)
FeatureSet	IFeatureSet	Backend capability flags — transactions, custom IDs, upserts, …

Modifying the environment

ConfigureEnvironment on IGremlinQuerySource is the primary entry point. It takes a function from the current environment to the new one and returns a reconfigured query source. Because every Configure* method also returns the environment, multiple changes can be combined in a single call:

Combining options and logger in one ConfigureEnvironment call

C#

var _g = g
    .UseGremlinServer<Vertex, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson())
    .ConfigureEnvironment(env => env
        .ConfigureOptions(opts => opts
            .SetValue(GremlinqOption.FilterLabelsVerbosity, FilterLabelsVerbosity.Minimum))
        .UseLogger(NullLogger.Instance));

Note

Provider setup methods (UseGremlinServer, UseCosmosDb, etc.) internally call ConfigureEnvironment to wire the executor, feature set, and serialization support. User calls to ConfigureEnvironment layer on top of that.

Graph model

ConfigureModel(Func<IGraphModel, IGraphModel>) transforms the graph model — the registry that maps .NET types to graph labels and drives type-safe querying. In practice, the model is set once during provider setup (UseGremlinServer<TVertex, TEdge>(...)) and rarely touched directly afterwards; label conventions and per-type overrides are the common reasons to call it.

➜ Graph Model — full reference for labels, conventions, and overrides.

Options

ConfigureOptions(Func<IGremlinqOptions, IGremlinqOptions>) adjusts the typed option bag. All built-in options live as static properties on GremlinqOption. The two mutating methods on IGremlinqOptions are:

• SetValue<TValue>(GremlinqOption<TValue>, TValue) — replaces the current value.
• ConfigureValue<TValue>(GremlinqOption<TValue>, Func<TValue, TValue>) — transforms it.

➜ Gremlinq Options — full list of built-in options with examples.

Serialization and deserialization

ConfigureSerializer and ConfigureDeserializer extend the transformer chains that convert between .NET types and the database wire format. ConfigureNativeTypes registers additional scalar types so Gremlinq treats them as first-class values rather than decomposing them structurally.

➜ Transformer — how the pipeline works (IConverterFactory, IConverter, chain ordering).
➜ Custom types — registering enums, Vogen value objects, and other domain types.

Logger

ConfigureLogger(Func<ILogger, ILogger>) replaces or wraps the logger Gremlinq uses for query diagnostics. The convenience overload UseLogger(ILogger) sets it directly.

Wiring a logger

C#

var _g = g
    .UseGremlinServer<Vertex, Edge>(_ => _.AtLocalhost())
    .ConfigureEnvironment(env => env.UseNewtonsoftJson())
    .ConfigureEnvironment(env => env
        .UseLogger(NullLogger.Instance));

Replace NullLogger.Instance with any ILogger from your application — typically one obtained from ILoggerFactory via dependency injection.

What Gremlinq logs and at what level is controlled by two options:

• GremlinqOption.QueryLogLogLevel — the LogLevel at which queries are emitted (default: Debug).
• GremlinqOption.QueryLogVerbosity — whether bindings are included alongside the query text.

➜ Gremlinq Options → Logging for details and examples.

Executor, Debugger, and FeatureSet

These three are managed almost entirely by provider packages and extension packages; most applications never need to touch them directly.

ConfigureExecutor replaces the component that sends serialized queries to the database. Providers register their own executor during setup. Only override this if you are building a custom provider or need to intercept every request at the lowest level.

ConfigureDebugger wires a query interceptor that receives the serialized query before it is sent. The Diagnostics extension uses this hook to expose OpenTelemetry traces and the query debugger API.

ConfigureFeatureSet adjusts the backend capability flags that Gremlinq consults when generating queries. Provider packages set the appropriate flags for their target database (e.g. disabling transactions on GremlinServer). Override only when targeting a database whose capabilities differ from the provider's defaults.

---

See also: Graph Model  |  Transformer  |  Gremlinq Options  |  Custom types