Native SDK Reference (Self-Hosted Only)

Note: This SDK is only available for self-hosted deployments. For hosted Konnektr Graph, use the Azure Digital Twins SDK instead.

Overview

The AgeDigitalTwins SDK provides a .NET client for direct database access to your self-hosted Konnektr Graph instance. It connects directly to PostgreSQL with Apache AGE, bypassing the HTTP API layer for maximum performance.

When to Use This SDK

✅ Use the Native SDK when:

You have a self-hosted Konnektr Graph deployment
You need maximum performance with direct database access
You want to perform bulk operations efficiently
You need advanced Cypher query capabilities
You require transaction support

❌ Don't use this SDK if:

You're using hosted Konnektr Graph (not accessible)
You want to migrate to/from Azure Digital Twins easily
You prefer standard REST API patterns

Hosted vs Self-Hosted SDK Comparison

Feature	Hosted (Azure SDK)	Self-Hosted (Native SDK)
Connection	HTTPS REST API	Direct PostgreSQL
Authentication	Auth0 JWT	Database credentials
Performance	Good	Excellent
Bulk Operations	Standard	Optimized
Transactions	Not supported	Full support
Migration	Easy to/from ADT	Custom required

Installation

To install the SDK, use the following NuGet command:

Install-Package AgeDigitalTwins

Usage

Initialization

using AgeDigitalTwins;
using Npgsql;

var connectionString = "Host=localhost;Username=postgres;Password=yourpassword;Database=agedb";
var dataSource = NpgsqlDataSource.Create(connectionString);
var client = new AgeDigitalTwinsClient(dataSource, "digitaltwins");

Managing Digital Twins

Create or Replace a Digital Twin

var twin = new
{
    $dtId = "room1",
    name = "Room 1",
    $metadata = new { $model = "dtmi:com:adt:dtsample:room;1" }
};
await client.CreateOrReplaceDigitalTwinAsync("room1", twin);

Get a Digital Twin

var twin = await client.GetDigitalTwinAsync<object>("room1");
Console.WriteLine(twin);

Delete a Digital Twin

await client.DeleteDigitalTwinAsync("room1");

Querying the Graph

Execute a Query

var query = "SELECT * FROM DIGITALTWINS";
await foreach (var result in client.QueryAsync<object>(query))
{
    Console.WriteLine(result);
}

Managing Models

Create Models

var models = new[]
{
    "{ \"@id\": \"dtmi:com:adt:dtsample:room;1\", \"@type\": \"Interface\", \"displayName\": \"Room\" }"
};
await client.CreateModelsAsync(models);

List Models

await foreach (var model in client.GetModelsAsync<object>())
{
    Console.WriteLine(model);
}

Delete a Model

await client.DeleteModelAsync("dtmi:com:adt:dtsample:room;1");

Advanced Query Examples

Complex Graph Traversal

var query = @"
    MATCH (room:DigitalTwin {$dtId: 'room1'})
    MATCH (room)-[:contains]->(sensor:DigitalTwin)
    WHERE sensor.Temperature > 25.0
    RETURN room.$dtId, sensor.$dtId, sensor.Temperature
";

await foreach (var result in client.QueryAsync<object>(query))
{
    Console.WriteLine(result);
}

Bulk Insert with Transaction

using (var transaction = dataSource.CreateTransaction())
{
    var client = new AgeDigitalTwinsClient(transaction, "digitaltwins");
    
    // Insert multiple twins in a transaction
    for (int i = 0; i < 1000; i++)
    {
        var twin = new { $dtId = $"sensor{i}", Temperature = 20.0 + i };
        await client.CreateOrReplaceDigitalTwinAsync($"sensor{i}", twin);
    }
    
    await transaction.CommitAsync();
}

Performance Benefits

The native SDK provides significant performance advantages:

Direct Database Access: No HTTP serialization overhead
Connection Pooling: Efficient PostgreSQL connection management
Bulk Operations: Optimized batch inserts and updates
Transactions: ACID compliance with rollback support
Streaming: Memory-efficient query result streaming

Error Handling

try
{
    await client.CreateOrReplaceDigitalTwinAsync("twin1", twinData);
}
catch (AgeDigitalTwinsException ex) when (ex.ErrorCode == "ModelNotFound")
{
    Console.WriteLine($"Model not found: {ex.Message}");
}
catch (NpgsqlException ex)
{
    Console.WriteLine($"Database error: {ex.Message}");
}

Compatibility

.NET 6.0+: Full support for modern .NET
Async/Await: All operations are asynchronous
PostgreSQL 13+: Requires Apache AGE extension
Connection Pooling: Built-in Npgsql connection pooling

Migration Considerations

From Azure Digital Twins SDK to Native SDK

// Before (Azure Digital Twins SDK)
var client = new DigitalTwinsClient(endpoint, credential);
var twin = await client.GetDigitalTwinAsync<BasicDigitalTwin>("twin1");

// After (Native SDK)
var client = new AgeDigitalTwinsClient(dataSource, "digitaltwins");  
var twin = await client.GetDigitalTwinAsync<object>("twin1");

From Native SDK to Azure Digital Twins SDK

For migration to hosted Konnektr Graph or Azure Digital Twins, you'll need to:

Replace database connections with HTTP endpoints
Implement Auth0 or Azure AD authentication
Update query syntax to ADT query language
Handle API rate limits and pagination

For Hosted Users: Azure Digital Twins SDK Guide
Self-Hosted Setup: Self-Hosted Deployment
Performance Tuning: Advanced Topics