Native SDK Reference

Note: This SDK talks to PostgreSQL directly, so it needs database access. For HTTP integrations use the Python SDK (konnektr-graph, the ADT-compatible client with search and pgvector support) or the Azure Digital Twins SDK.

Overview

The AgeDigitalTwins SDK provides a .NET client for direct database access to your 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 Konnektr Graph deployment and access to its PostgreSQL database
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 integrating over HTTP without database access
You want to migrate to/from Azure Digital Twins easily
You prefer standard REST API patterns

Native SDK vs REST API Comparison

Feature	REST API (ADT / Python SDK)	Native SDK
Connection	HTTPS REST API	Direct PostgreSQL
Authentication	OAuth 2.1 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
TrackLastUpdatedBy: Fully supported. The native SDK's custom JSON converters handle $lastUpdatedBy at both the twin-level ($metadata.$lastUpdatedBy) and per-property ($metadata.<property>.lastUpdatedBy) metadata. See Security for details.

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 the HTTP API (Konnektr Graph or Azure Digital Twins), you'll need to:

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

HTTP API Clients: Python SDK (ADT-compatible, adds search and pgvector) and Azure Digital Twins SDK Guide
Deployment: Self-Hosted Deployment
Performance Tuning: Advanced Topics

Native SDK Reference

On this page