Konnektr.Npgsql.Age
2.1.0
dotnet add package Konnektr.Npgsql.Age --version 2.1.0
NuGet\Install-Package Konnektr.Npgsql.Age -Version 2.1.0
<PackageReference Include="Konnektr.Npgsql.Age" Version="2.1.0" />
<PackageVersion Include="Konnektr.Npgsql.Age" Version="2.1.0" />
<PackageReference Include="Konnektr.Npgsql.Age" />
paket add Konnektr.Npgsql.Age --version 2.1.0
#r "nuget: Konnektr.Npgsql.Age, 2.1.0"
#:package Konnektr.Npgsql.Age@2.1.0
#addin nuget:?package=Konnektr.Npgsql.Age&version=2.1.0
#tool nuget:?package=Konnektr.Npgsql.Age&version=2.1.0
Konnektr.Npgsql.Age
What is Apache AGE?
Apache AGE is an open-source extension for PostgreSQL which provides it with the capabilities of a graph database. This package is a plugin for the Npgsql library which allows you to interact with Apache AGE from C#.
Installation
dotnet add package Konnektr.Npgsql.Age
Then register the type plugin on your NpgsqlDataSourceBuilder:
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseAge();
await using var dataSource = dataSourceBuilder.Build();
Quickstart
using Npgsql;
using Npgsql.Age;
using Npgsql.Age.Types;
var dataSourceBuilder = new NpgsqlDataSourceBuilder("Host=...");
dataSourceBuilder.UseAge();
await using var dataSource = dataSourceBuilder.Build();
await using var connection = await dataSource.OpenConnectionAsync();
// Create graph
await using (var cmd = connection.CreateGraphCommand("graph1"))
await cmd.ExecuteNonQueryAsync();
// Add vertices
await using (var cmd = connection.CreateCypherCommand(
"graph1", "CREATE (:Person {name: 'Alice', age: 30}), (:Person {name: 'Bob', age: 25})"))
await cmd.ExecuteNonQueryAsync();
// Retrieve vertices
await using (var cmd = connection.CreateCypherCommand(
"graph1", "MATCH (n:Person) RETURN n"))
await using (var reader = await cmd.ExecuteReaderAsync())
{
while (await reader.ReadAsync())
{
var agtype = await reader.GetFieldValueAsync<Agtype>(0);
Vertex person = agtype.GetVertex();
Console.WriteLine($"{person.Label}: id={person.Id}, age={person.Properties["age"]}");
}
}
// Drop graph
await using (var cmd = connection.DropGraphCommand("graph1"))
await cmd.ExecuteNonQueryAsync();
Using Cypher Parameters
Parameters are referenced in Cypher queries using the $ prefix (e.g., $name, $age).
Using a Dictionary
var parameters = new Dictionary<string, object?>
{
["name"] = "Alice",
["age"] = 30
};
await using (var cmd = connection.CreateCypherCommand(
"graph1",
"CREATE (p:Person {name: $name, age: $age}) RETURN p",
parameters))
await using (var reader = await cmd.ExecuteReaderAsync())
{
while (await reader.ReadAsync())
{
var agtype = await reader.GetFieldValueAsync<Agtype>(0);
Vertex person = agtype.GetVertex();
Console.WriteLine($"Created: {person.Label}");
}
}
Using a JSON String
string parametersJson = """{"name": "Bob", "age": 25}""";
await using (var cmd = connection.CreateCypherCommand(
"graph1",
"CREATE (p:Person {name: $name, age: $age}) RETURN p",
parametersJson))
await cmd.ExecuteNonQueryAsync();
Complex Parameters
var parameters = new Dictionary<string, object?>
{
["person"] = new Dictionary<string, object>
{
["name"] = "Charlie",
["age"] = 35,
["hobbies"] = new[] { "reading", "cycling" }
}
};
await using (var cmd = connection.CreateCypherCommand(
"graph1",
"CREATE (p:Person {name: $person.name, age: $person.age}) RETURN p",
parameters))
await cmd.ExecuteNonQueryAsync();
Working with Agtype
The Agtype struct is the core type representing ag_catalog.agtype values from PostgreSQL.
Type Detection
Agtype value = await reader.GetFieldValueAsync<Agtype>(0);
if (value.IsVertex) { /* vertex */ }
else if (value.IsEdge) { /* edge */ }
else if (value.IsPath) { /* path */ }
else if (value.IsArray) { /* JSON array */ }
else if (value.IsMap) { /* JSON object */ }
else if (value.IsNull) { /* null */ }
Explicit Cast Operators
Vertex vertex = (Vertex)agtype;
Edge edge = (Edge)agtype;
string text = (string)agtype;
int number = (int)agtype;
double dbl = (double)agtype;
List<object?> list = (List<object?>)agtype;
Dictionary<string, object?> map = (Dictionary<string, object?>)agtype;
Generic Deserialization
// Deserialize to any compatible type
var person = agtype.Get<Vertex>();
// Typed properties
var personTyped = agtype.Get<Vertex<Dictionary<string, object?>>>();
Working with Paths
Agtype result = await reader.GetFieldValueAsync<Agtype>(0);
Path path = result.GetPath();
// Alternate access
foreach (var segment in path.Segments)
{
if (segment is Vertex v)
Console.WriteLine($"Vertex: {v.Label}");
else if (segment is Edge e)
Console.WriteLine($"Edge: {e.Label} ({e.StartId} -> {e.EndId})");
}
// Or use filtered helpers
foreach (var v in path.Vertices) { /* vertices only */ }
foreach (var e in path.Edges) { /* edges only */ }
Number Type Inference
When deserializing dynamic types via Get<object?>() or Get<List<object?>>(), numbers are inferred in this order:
| JSON value | C# type |
|---|---|
| Integer (fits int) | int |
| Integer (fits long) | long |
| Fractional | decimal |
| Scientific notation | double |
Special AGE literals (Infinity, -Infinity, NaN, ::numeric) are handled transparently through custom JSON converters.
Strongly-Typed Entities
For structured access to vertex/edge properties, use the generic variants:
public record Person(string Name, int Age);
// Query
var result = agtype.Get<Vertex<Person>>();
Console.WriteLine($"Name: {result.Properties.Name}, Age: {result.Properties.Age}");
Acknowledgements
- This project is a fork of pg-age and incorporates improvements from erdomke/npgsql-age.
- The project relies heavily on the work of the Npgsql team.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Konnektr.Npgsql.Age:
| Package | Downloads |
|---|---|
|
Konnektr.AgeDigitalTwins
Digital Twins SDK for Apache Age |
|
|
Cvoya.Graph.Age
CVOYA Graph provider for PostgreSQL and Apache AGE, with LINQ support for the Cvoya.Graph abstraction. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.1.0 | 449 | 10/1/2026 |
| 2.0.0 | 6,081 | 5/28/2026 |
| 1.3.0 | 454 | 5/14/2026 |
| 1.2.1 | 13,084 | 12/16/2025 |
| 1.2.0 | 326 | 12/16/2025 |
| 1.1.0 | 1,256 | 10/22/2025 |
| 1.0.9 | 241 | 10/22/2025 |
| 1.0.8 | 569 | 9/3/2025 |
| 1.0.7 | 351 | 8/11/2025 |
| 1.0.6 | 735 | 7/16/2025 |
| 1.0.5 | 1,197 | 4/14/2025 |
| 1.0.4 | 870 | 2/11/2025 |
| 1.0.3 | 422 | 1/6/2025 |
| 1.0.2 | 248 | 1/6/2025 |
| 1.0.1 | 208 | 1/6/2025 |
| 0.4.0 | 757 | 12/6/2024 |
| 0.3.9 | 236 | 12/5/2024 |
| 0.3.8 | 210 | 12/5/2024 |
| 0.3.7 | 246 | 12/3/2024 |
| 0.3.6 | 207 | 12/3/2024 |