C# / .NET API Reference¶

using Grafeo;

using var db = GrafeoDB.Memory();

db.Execute("INSERT (:Person {name: 'Alix', age: 30})");
db.Execute("INSERT (:Person {name: 'Gus', age: 25})");
db.Execute("INSERT (:Person {name: 'Alix'})-[:KNOWS]->(:Person {name: 'Gus'})");

var result = db.Execute("MATCH (p:Person) RETURN p.name, p.age");

foreach (var row in result.Rows)
{
    Console.WriteLine($"{row["p.name"]}: {row["p.age"]}");
}

Console.WriteLine($"Nodes: {db.NodeCount}, Edges: {db.EdgeCount}");

// In-memory database
using var db = GrafeoDB.Memory();

// Persistent database (opens or creates at path)
using var db = GrafeoDB.Open("/path/to/data");

// Async disposal
await using var db = GrafeoDB.Memory();

// Library version
Console.WriteLine(GrafeoDB.Version);

// GQL (ISO standard)
var result = db.Execute("MATCH (p:Person) RETURN p.name");

// GQL with parameters
var result = db.ExecuteWithParams(
    "MATCH (p:Person) WHERE p.name = $name RETURN p",
    new Dictionary<string, object?> { ["name"] = "Alix" });

// Other query languages
var result = db.ExecuteCypher("MATCH (p:Person) RETURN p.name");
var result = db.ExecuteSparql("SELECT ?s WHERE { ?s a <http://example.org/Person> }");
var result = db.ExecuteGremlin("g.V().hasLabel('Person').values('name')");
var result = db.ExecuteGraphql("{ persons { name } }");
var result = db.ExecuteSql("SELECT p.name FROM GRAPH_TABLE (g MATCH (p:Person)) AS t");

var result = await db.ExecuteAsync("MATCH (p:Person) RETURN p.name");

var result = await db.ExecuteWithParamsAsync(
    "MATCH (p:Person) WHERE p.age > $min RETURN p.name",
    new Dictionary<string, object?> { ["min"] = 18 });

var result = await db.ExecuteCypherAsync("MATCH (p:Person) RETURN p", ct);
var result = await db.ExecuteSparqlAsync(query, ct);
var result = await db.ExecuteGremlinAsync(query, ct);
var result = await db.ExecuteGraphqlAsync(query, ct);
var result = await db.ExecuteSqlAsync(query, ct);

using var tx = db.BeginTransaction();
tx.Execute("INSERT (:Person {name: 'Alix'})");
tx.Execute("INSERT (:Person {name: 'Gus'})");
tx.Commit();

// With isolation level
using var tx = db.BeginTransaction("read_committed");

// Create a node with labels and properties
long nodeId = db.CreateNode(
    ["Person"],
    new Dictionary<string, object?> { ["name"] = "Alix", ["age"] = 30 });

// Get a node by ID (returns null if not found)
Node? node = db.GetNode(nodeId);

// Modify properties
db.SetNodeProperty(nodeId, "city", "Amsterdam");
db.RemoveNodeProperty(nodeId, "city");

// Modify labels
db.AddNodeLabel(nodeId, "Employee");
db.RemoveNodeLabel(nodeId, "Employee");

// Delete
bool deleted = db.DeleteNode(nodeId);

long alixId = db.CreateNode(["Person"], new() { ["name"] = "Alix" });
long gusId = db.CreateNode(["Person"], new() { ["name"] = "Gus" });

// Create an edge with type and optional properties
long edgeId = db.CreateEdge(alixId, gusId, "KNOWS",
    new Dictionary<string, object?> { ["since"] = 2024 });

// Get an edge by ID
Edge? edge = db.GetEdge(edgeId);

// Modify properties
db.SetEdgeProperty(edgeId, "weight", 0.9);
db.RemoveEdgeProperty(edgeId, "weight");

// Delete
bool deleted = db.DeleteEdge(edgeId);

// One transaction each; IDs in input order
var ids = db.BatchCreateNodesWithProps(["Person"], [
    new Dictionary<string, object?> { ["name"] = "Alix" },
    new Dictionary<string, object?> { ["name"] = "Gus" },
]);
var edgeIds = db.BatchCreateEdges([new BatchEdge(ids[0], ids[1], "KNOWS")]);

// Create or update by a key property
UpsertSummary summary = db.UpsertNodes(["File"],
    [new Dictionary<string, object?> { ["path"] = "a.rs" }],
    new UpsertNodesOptions { Key = "path" });
summary = db.UpsertEdges("IMPORTS",
    [new Dictionary<string, object?> { ["id"] = "a-b", ["src"] = "a.rs", ["dst"] = "b.rs" }],
    new UpsertEdgesOptions { EndpointKey = "path", EndpointLabels = ["File"] });

using var trips = db.Graph("trips");
long prague = trips.CreateNode(["City"], new Dictionary<string, object?> { ["name"] = "Prague" });
var result = trips.Execute("MATCH (c:City) RETURN c.name");

using var db = GrafeoDB.Memory(HistoryRetention.For(TimeSpan.FromDays(7)));
using var view = db.AsOf(TimePoint.Ago(TimeSpan.FromMinutes(5)));
var result = view.Execute("MATCH (p:Person) RETURN count(p) AS n");

long nodes = db.NodeCount;
long edges = db.EdgeCount;

IReadOnlyDictionary<string, object?> info = db.Info();
Console.WriteLine(info["version"]);

db.Save("/path/to/backup.grafeo");

// Create a vector index via GQL
db.Execute("CREATE VECTOR INDEX document_embedding ON :Document(embedding) DIMENSION 384");

// Similarity search: returns nearest k nodes
float[] queryVector = GetEmbedding("graph database");
IReadOnlyList<VectorResult> results = db.VectorSearch(
    "Document", "embedding", queryVector, k: 10, ef: 64);

foreach (var hit in results)
{
    Console.WriteLine($"Node {hit.NodeId}, distance: {hit.Distance}");
}

// MMR search: balances relevance with diversity
IReadOnlyList<VectorResult> diverse = db.MmrSearch(
    "Document", "embedding", queryVector,
    k: 10, fetchK: 50, lambda: 0.7f, ef: 64);

// Index management
db.RebuildVectorIndex("Document", "embedding");
db.DropVectorIndex("Document", "embedding");

using var tx = db.BeginTransaction();

tx.Execute("INSERT (:Person {name: 'Alix'})");
tx.Execute("INSERT (:Person {name: 'Gus'})");

var result = tx.ExecuteWithParams(
    "MATCH (p:Person) WHERE p.name = $name RETURN p",
    new Dictionary<string, object?> { ["name"] = "Alix" });

tx.Commit(); // if this line is not reached, the transaction auto-rolls back

var result = db.Execute("RETURN 19.99 AS price");
var price = (GrafeoDecimal)result.Rows[0]["price"];
Console.WriteLine(price.Text);         // 19.99
decimal exact = price.ToDecimal();     // 19.99m

var row = db.Execute("RETURN TIME '12:30:00+02:00' AS opens, DURATION 'P1M' AS term").Rows[0];
var opens = (GrafeoTime)row["opens"]!;  // 12:30:00+02:00, Offset 02:00:00
var term = (GrafeoDuration)row["term"]!; // Months 1

var result = db.ExecuteSparql("SELECT ?o WHERE { <http://ex.org/apple> <http://ex.org/label> ?o }");
var label = (RdfTerm)result.Rows[0]["o"];
Console.WriteLine($"{label.Value} {label.Language}"); // Pomme fr

public sealed record Node(
    long Id,
    IReadOnlyList<string> Labels,
    IReadOnlyDictionary<string, object?> Properties);

public sealed record Edge(
    long Id,
    string Type,
    long SourceId,
    long TargetId,
    IReadOnlyDictionary<string, object?> Properties);

public sealed record QueryResult(
    IReadOnlyList<string> Columns,
    IReadOnlyList<IReadOnlyDictionary<string, object?>> Rows,
    IReadOnlyList<Node> Nodes,
    IReadOnlyList<Edge> Edges,
    double ExecutionTimeMs,
    long RowsScanned);

public sealed record VectorResult(long NodeId, double Distance);

try
{
    db.Execute("INVALID QUERY");
}
catch (QueryException ex)
{
    Console.WriteLine($"Query failed: {ex.Message}");
    Console.WriteLine($"Status: {ex.Status}");
}
catch (GrafeoException ex)
{
    Console.WriteLine($"Grafeo error [{ex.Status}]: {ex.Message}");
}