Graph Query Language

The Curiosity Graph Query Language is a fluent C# interface for traversing and querying the knowledge graph. Two distinct IQuery interfaces exist depending on the context:

Context	How to obtain	Interface	Results
Endpoints / Shell	`Q()` / `Query()` global methods	`Mosaik.GraphDB.IQuery` — full feature set	Return `Emit(...)` directly, or materialize with `AsEnumerable()` / `ToList()` / etc.
Data Connectors	Lambda in `await graph.QueryAsync(q => q...)`	`Curiosity.Library.IQuery` — focused subset	`QueryResults` returned by `graph.QueryAsync`; use `GetEmitted()` / `GetEmittedCount()`.

Starting Points

Method	Backend	Library	Notes
`StartAt(string nodeType)`	✓	✓	All nodes of the given type.
`StartAt(Node node)`	✓	✓	Start from a specific node. Library uses `Node.FromKey()`.
`StartAt(Node[] nodes)`	✓	✓	Start from a set of nodes.
`StartAt(string nodeType, string[] keys)`	—	✓	Start from nodes of a type identified by multiple keys.
`StartAt(string type, string key)`	✓	—	Start from a single node by type and key.
`StartAt(UID128 uid)` / `StartAt(IEnumerable<UID128>)`	✓	—	Start from one or more UIDs.
`StartSearch(string nodeType, string field, ISearchExpression query)`	✓	—	Full-text search on a specific field.
`StartAtSimilarTextAsync(string text, int count, string[] nodeTypes, ...)`	✓	—	Semantic similarity search.
`StartNearTo(string nodeType, string field, GeoPoint point, double radius)`	✓	—	Nodes within a geographic radius.
`StartWhereString(string nodeType, string field, string value)`	✓	✓	Nodes where a string field matches a value.
`StartWhereString(string nodeType, string field, string[] values)`	✓	✓	Nodes where a string field matches any of a set.
`StartWhere(string nodeType, string field, Func<dynamic, bool> predicate)`	✓	—	Nodes filtered by a field predicate.

Node references: In the backend, use Node.GetUID(type, key) to reference a node by key. In the library, use Node.FromKey(type, key).

// Backend (endpoint/shell)
Q().StartAt(N.Device.Type, "MacBook Air")
Q().StartAt(Node.GetUID(N.Device.Type, "MacBook Air"))

// Library (data connector)
await graph.QueryAsync(q => q.StartAt(Node.FromKey(nameof(Nodes.Device), "MacBook Air")).Emit("N"))
await graph.QueryAsync(q => q.StartAt(nameof(Nodes.Device), new[] { "MacBook Air", "MacBook Pro" }).Emit("N"))

Traversal

Method	Backend	Library	Notes
`Out()`	✓	✓	Traverse all outgoing edges.
`Out(string nodeType)`	✓	✓	Traverse to a specific node type.
`Out(string nodeType, string edgeType)`	✓	✓	Traverse via a specific edge type.
`Out(string nodeType, string[] edgeTypes)`	✓	✓	Traverse via multiple edge types.
`Out(string[] nodeTypes, string edgeType)`	✓	✓	Traverse to multiple node types via one edge type.
`Out(string[] nodeTypes, string[] edgeTypes)`	✓	✓	Traverse to multiple types via multiple edge types.
`OutMany(int levels, string[] nodeTypes, string[] edgeTypes, bool distinct)`	✓	✓	Multi-hop traversal.
`OutWhere(string nodeType, string edgeType, Func<Edge, bool> predicate)`	✓	—	Traverse with a predicate on the edge.
`Search(string nodeType, string field, ISearchExpression query)`	✓	—	Full-text search within the current result set.
`PathBetween(UID128 from, UID128 to, int maxLevels)`	✓	—	Find paths between two nodes.

// Backend
Q().StartAt(N.Manufacturer.Type, "Apple")
   .Out(N.Device.Type)
   .Out(N.SupportCase.Type)

// Library (data connector)
await graph.QueryAsync(q =>
    q.StartAt(Node.FromKey(nameof(Nodes.Manufacturer), "Apple"))
     .Out(nameof(Nodes.Device))
     .Out(nameof(Nodes.SupportCase))
     .Emit("Cases"))

Filtering

Method	Backend	Library	Notes
`OfType(string nodeType)`	✓	✓	Keep only nodes of the given type.
`OfTypes(...)`	✓	✓	Keep only nodes of any of the given types.
`ExceptType(string nodeType)`	✓	✓	Remove nodes of the given type.
`ExceptTypes(...)`	✓	✓	Remove nodes of any of the given types.
`IsRelatedTo(Node node)`	✓	✓	Keep nodes related to a specific node.
`IsRelatedTo(Node[] nodes)`	✓	✓	Keep nodes related to any of the given nodes.
`IsRelatedTo(string nodeType)`	✓	✓	Keep nodes related to any node of the given type.
`IsRelatedTo(string[] nodeTypes)`	✓	✓	Keep nodes related to any of the given types.
`IsRelatedToVia(Node node, string edgeType)`	✓	✓	Keep nodes related to a specific node via a specific edge.
`IsRelatedToVia(string nodeType, string edgeType)`	✓	✓	Keep nodes related via matching node/edge type.
`IsRelatedToVia(string[] nodeTypes, string[] edgeTypes)`	✓	✓	Keep nodes related via any matching combination.
`IsNotRelatedTo(...)`	✓	✓	Remove nodes related to the given node(s)/type(s).
`IsNotRelatedToVia(...)`	✓	✓	Remove nodes related via the given edge type.
`WhereString(string nodeType, string field, string value)`	✓	✓	Keep nodes where a string field matches.
`WhereString(string nodeType, string field, string[] values)`	✓	✓	Keep nodes where a string field matches any of a set.
`WhereNotString(string nodeType, string field, string value)`	✓	✓	Keep nodes where a string field does not match.
`WhereTimestamp(DateTimeOffset from, DateTimeOffset to, bool insideBoundary)`	—	✓	Filter by timestamp (library uses `DateTimeOffset`).
`WhereTimestamp(Time from, Time to, bool insideBoundary)`	✓	—	Filter by timestamp (backend uses `Time`).
`Where(Func<ReadOnlyNode, bool> predicate)`	✓	—	Keep nodes matching a predicate.
`Where(string field, Func<dynamic, bool> predicate)`	✓	—	Keep nodes where a field satisfies a predicate.
`Except(UID128 uid)` / `Except(IQuery other)`	✓	—	Set difference.
`Intersect(IQuery other)`	✓	—	Set intersection.
`Union(IQuery other)`	✓	—	Set union.
`Distinct()`	✓	—	Deduplicate results.

// Library (data connector)
await graph.QueryAsync(q =>
    q.StartAt(nameof(Nodes.SupportCase))
     .IsRelatedTo(Node.FromKey(nameof(Nodes.Device), "MacBook Air"))
     .WhereString(nameof(Nodes.SupportCase), nameof(Nodes.SupportCase.Status), "Open")
     .WhereTimestamp(DateTimeOffset.UtcNow.AddDays(-7), DateTimeOffset.UtcNow, insideBoundary: true)
     .Emit("N"))

// Backend (endpoint/shell)
Q().StartAt(N.SupportCase.Type)
   .IsRelatedTo(Node.GetUID(N.Device.Type, "MacBook Air"))
   .WhereString(N.SupportCase.Type, N.SupportCase.Status, "Open")
   .WhereTimestamp(Time.Now().Add(TimeSpan.FromDays(-7)), Time.Now(), insideBoundary: true)

Sorting and Pagination

Method	Backend	Library	Notes
`SortByTimestamp(bool oldestFirst)`	✓	✓	Sort by creation time.
`SortByLastUpdated(bool newestFirst)`	✓	✓	Sort by modification time.
`SortByConnectivity(bool mostConnectedFirst)`	✓	✓	Sort by edge count.
`SortByConnectivityTo(string[] nodeTypes, string[] edgeTypes, bool mostConnectedFirst)`	✓	—	Sort by connections to specific types.
`SortByDistanceFromNow()`	✓	—	Sort by time distance from now.
`SortByBoostValue()`	✓	—	Sort by relevance score.
`SortByRepetition(bool mostOftenFirst)`	✓	—	Sort by repetition frequency.
`Sort(Func<...> sorter)`	✓	—	Custom in-memory sort.
`Skip(int count)`	✓	✓	Skip the first N results.
`Take(int count)`	✓	✓	Limit to N results.

Output

Emit methods

Available in both contexts. In endpoints/shell, Emit(...) returned from the endpoint serializes to the HTTP response. In data connectors, it configures what is included in the QueryResults returned by graph.QueryAsync().

Method	Backend	Library	Notes
`Emit(string key)`	✓	✓	Return matched nodes under a key.
`Emit(string key, string[] fields)`	✓	✓	Return nodes, restricted to specific fields.
`EmitCount(string key)`	✓	✓	Return only the count under a key.
`EmitWithEdges(string key)`	✓	✓	Return nodes with their edge data.
`EmitWithEdges(string key, string[] fields)`	✓	✓	Return nodes with edges, restricted to specific fields.
`EmitWithScores(string name)`	✓	—	Return nodes with relevance scores.
`EmitUIDs(string name)`	✓	—	Return only UIDs.
`EmitUIDsWithScores(string name)`	✓	—	Return UIDs with scores.
`EmitSummary(string name)`	✓	—	Return a structural graph summary (shell).
`EmitNeighborsSummary(string name)`	✓	—	Return an edge-type summary (shell).
`Similar(string index, int count, float tolerance)`	—	✓	Find similar nodes via a named index.
`Similar(IndexTypes?, IndexUID, int count)`	✓	—	Find similar nodes via backend index reference.

// Library (data connector) — results via QueryResults
var r = await graph.QueryAsync(q =>
    q.StartAt(nameof(Nodes.Device)).Take(10).Emit("N", [nameof(Nodes.Device.Name)]));
var nodes = r.GetEmitted("N");

var r2 = await graph.QueryAsync(q => q.StartAt(nameof(Nodes.Device)).EmitCount("C"));
var count = r2.GetEmittedCount("C");

// Backend (endpoint/shell) — return directly
return Q().StartAt(N.Part.Type).Skip(page * 50).Take(50).Emit();
return Q().StartAt(N.SupportCase.Type).EmitNeighborsSummary();
return Q().EmitSummary();

In-memory materialization (Backend / Endpoints and Shell only)

These methods execute the query and return C# objects. They are not available in the library IQuery.

Method	Return Type	Description
`AsEnumerable()`	`IEnumerable<ReadOnlyNode>`	Lazy enumerable.
`AsEnumerableAsync(...)`	`IAsyncEnumerable<ReadOnlyNode>`	Async lazy enumerable.
`AsUIDEnumerable()`	`IEnumerable<UID128>`	Raw UIDs only.
`AsTypedUIDEnumerable()`	`IEnumerable<TypedUID128>`	UID + type pairs.
`AsScoredUIDEnumerable()`	`IEnumerable<ScoredUID>`	UIDs with relevance scores.
`ToList()`	`List<ReadOnlyNode>`	Materialize to a list.
`ToListWithEdges()`	`List<ReadOnlyNodeWithEdges>`	All results with edge data.
`ToUIDList()`	`List<UID128>`	All UIDs as a list.
`ToScoredUIDList()`	`List<ScoredUID>`	All scored UIDs as a list.
`ToArrayAsync(int concurrency)`	`Task<ReadOnlyNode[]>`	Async array materialization.
`ToJsonAsync()`	`Task<string>`	Serialize to JSON string.
`ToWorkbookAsync()`	`Task<IWorkbook>`	Export as a workbook.
`ToCsvAsync(Stream stream)`	`Task`	Write as CSV to a stream.
`Count()`	`int`	Total count.
`Any()`	`bool`	True if any results exist.
`CollectUIDs(out List<TypedUID128> uids)`	`IQuery`	Capture UIDs mid-pipeline.
`CollectNodes(out List<ReadOnlyNodeWithEdges> nodes)`	`IQuery`	Capture nodes mid-pipeline.

// Iterate in endpoint code
foreach (var node in Q().StartAt(N.SupportCase.Type).AsEnumerable())
{
    var summary = node.GetString(N.SupportCase.Summary);
}

// Materialize to list
var recent = Q().StartAt(N.SupportCase.Type)
               .SortByTimestamp(oldestFirst: false)
               .Take(20)
               .ToList();

// Check existence
bool hasOpen = Q().StartWhereString(N.SupportCase.Type, N.SupportCase.Status, "Open").Any();

Reading Node Properties

In endpoints and shell, nodes returned from AsEnumerable(), ToList(), or inside a Where() predicate expose typed accessors:

Accessor	Type
`GetString(key)` / `GetStringList(key)`	`string` / `IReadOnlyList<string>`
`GetInt(key)` / `GetIntList(key)`	`int` / `IReadOnlyList<int>`
`GetBool(key)` / `GetBoolList(key)`	`bool` / `IReadOnlyList<bool>`
`GetFloat(key)` / `GetFloatList(key)`	`float` / `IReadOnlyList<float>`
`GetDouble(key)` / `GetDoubleList(key)`	`double` / `IReadOnlyList<double>`
`GetLong(key)` / `GetLongList(key)`	`long` / `IReadOnlyList<long>`
`GetTime(key)` / `GetTimeList(key)`	`Time` / `IReadOnlyList<Time>`
`GetUID128(key)` / `GetUID128List(key)`	`UID128` / `IReadOnlyList<UID128>`
`node[key]`	`dynamic`

In data connectors, EmittedNode (from QueryResults.GetEmitted()) provides GetField<T>(string field).

Use auto-generated constants to avoid string typos:

foreach (var node in Q().StartAt(N.SupportCase.Type).AsEnumerable())
{
    var id      = node.GetString(N.SupportCase.Id);
    var summary = node.GetString(N.SupportCase.Summary);
    var time    = node.GetTime(N.SupportCase.Time);
}

Next Steps

Data connector query usage: Querying in Data Connectors
Endpoint scope reference: Execution Scope
Auto-generated type/edge helpers: Auto-generated Helpers