# Querying the Graph (Query)

The Query interface is a fluent API for constructing and executing queries against the Curiosity Graph Database. It allows you to select starting nodes, filter them, traverse relationships, and shape the final output.

You typically obtain a Query instance by calling Graph.Query() or G.Q().

# Starting a Query

Every query must start with a selection of nodes.

Method	Description
`StartAt(string nodeType)`	Starts with all nodes of a specific type (e.g., "Person").
`StartAt(UID128 uid)`	Starts with a specific node by its UID.
`StartAt(string type, string key)`	Starts with a specific node by Type and Key.
`StartSearch(type, field, query)`	Starts by running a full-text search expression.
`StartWhereString(type, field, val)`	Starts with nodes where a specific field matches a value (using an index if available).
`StartNearTo(type, field, point, r)`	Starts with nodes within a geographical radius.

// Start with all Person nodes
var q = Graph.Query().StartAt("Person");

// Start with a specific user
var q = Graph.Query().StartAt("User", "john@example.com");

// Start with search results
var q = Graph.Query().StartSearch("Document", "content", Search.Parse("project alpha"));

# Accessing Properties

When you access nodes (e.g. inside a Where clause or when materializing results), you can use strongly-typed accessor methods.

Data Type	Scalar Accessor	List Accessor	Description
String	`GetString(key)`	`GetStringList(key)`	Text values.
Integer	`GetInt(key)`	`GetIntList(key)`	32-bit signed integers.
Boolean	`GetBool(key)`	`GetBoolList(key)`	True/False values.
Float	`GetFloat(key)`	`GetFloatList(key)`	Single-precision floating point.
Double	`GetDouble(key)`	`GetDoubleList(key)`	Double-precision floating point.
Decimal	`GetDecimal(key)`	`GetDecimalList(key)`	High-precision decimal.
Long	`GetLong(key)`	`GetLongList(key)`	64-bit signed integers.
DateTime	`GetTime(key)`	`GetTimeList(key)`	Date and time values.
UID	`GetUID128(key)`	`GetUID128List(key)`	Unique Identifiers.
GeoPoint	`GetGeoPoint(key)`	`GetGeoPointList(key)`	Geographical coordinates.
Language	`GetLanguage(key)`	`GetLanguageList(key)`	Language enums.
Dynamic	`node[key]`	-	Returns value as dynamic object.

Dictionary Access:

GetDictionary(key): Returns an IReadOnlyDictionaryAccessor for nested objects.

// Accessing scalar
string name = node.GetString("name");

// Accessing list
var tags = node.GetStringList("tags");

// Accessing dictionary
var meta = node.GetDictionary("metadata");
string source = meta.GetString("source");

# Filtering

Refine the set of nodes currently in the query pipeline.

Method	Description
`Where(node => bool)`	Filters nodes using a lambda (requires loading properties).
`WhereString(field, value)`	Filters nodes where a field matches a value (fast).
`WhereNotString(field, value)`	Filters nodes where a field does NOT match.
`WhereTimestamp(from, to, in)`	Filters nodes based on creation timestamp.
`Except(query)`	Removes nodes present in another query (Set Difference).
`Intersect(query)`	Keeps only nodes present in both queries.

// Filter by property (string optimized)
q.WhereString("status", "Active");

// General filter
q.Where(node => node.GetFloat("confidence") > 0.8f);

# Traversing Relationships

Move from the current set of nodes to related nodes.

Method	Description
`Out(nodeType, edgeType)`	Traverses outgoing edges to target nodes.
`OutMany(levels, ...)`	Traverses multiple hops deep.
`IsRelatedTo(uid)`	Filters nodes that have a relationship to a specific UID (keep origin).
`IsNotRelatedTo(uid)`	Filters nodes that do NOT have a relationship.

// Get friends of people
q.StartAt("Person").Out("Person", "Friend");

// Get friends of friends (2 hops)
q.StartAt("Person").OutMany(2, new[] { "Person" });

// Find people related to a specific Project
q.StartAt("Person").IsRelatedTo(projectUID);

# Sorting and Paging

Order and limit the results.

Method	Description
`SortByTimestamp(oldestFirst)`	Sorts by creation time.
`SortByLastUpdated(newestFirst)`	Sorts by modification time.
`SortByConnectivity()`	Sorts by number of edges (degree).
`Sort(func)`	Custom in-memory sort.
`Take(count)`	Limits the number of results.
`Skip(count)`	Skips the first N results.

// Top 10 most connected people
q.StartAt("Person")
 .SortByConnectivity(mostConnectedFirst: true)
 .Take(10);

# Shaping Output

Control what data is returned in the final result.

Method	Description
`Emit(fields...)`	Includes specific properties in the output.
`EmitWithEdges(fields...)`	Includes edges in the output.
`EmitCount(name)`	Includes the total count of results.

# Materializing Results

Execute the query and get the data.

Method	Description	Use Case
`AsEnumerable()`	`IEnumerable<ReadOnlyNode>`	Best for Endpoints/Code. Iterate over nodes objects directly.
`ToList()`	`List<ReadOnlyNode>`	Best for Endpoints/Code. Materialize all nodes into a list.
`ToJsonAsync()`	`string`	Best for Shell/Debugging. Returns a JSON string of the results.
`ToWorkbookAsync()`	`IWorkbook`	Exports results to an Excel-compatible workbook.
`Count()`	`int`	Returns the number of results.

// Iterate over results (Code/Endpoints)
foreach (var node in q.AsEnumerable())
{
    Console.WriteLine(node.UID);
}

// Return JSON (Shell/Debugging)
return await q.ToJsonAsync();