An Entity Framework-styled tool for accessing Gremlin-based graph databases like Azure Cosmos DB and Apache TinkerPop.
Overview
Stardust.Paradox.Data provides a modern, type-safe approach to working with graph databases using Gremlin traversals. It offers an intuitive API similar to Entity Framework for relational databases, but designed specifically for graph data structures.
Key Features
Entity Framework-like API for graph databases
Multi-targeting support for .NET Standard 2.0, .NET 6, 7, 8, and 9
Type-safe Gremlin queries with LINQ-style syntax
Support for Azure Cosmos DB and Apache TinkerPop
Vertex and Edge modeling with attributes and relationships
Code generation for graph entity classes
Dependency injection integration
Change tracking and batch operations
Fluent configuration for relationships
In-memory testing with comprehensive scenario framework
using Stardust.Paradox.Data;
using Microsoft.Extensions.DependencyInjection;
public class MyGraphContext : GraphContextBase
{
static MyGraphContext()
{
PartitionKeyName = "pk"; // For CosmosDB compatibility
}
public MyGraphContext(IGremlinLanguageConnector connector)
: base(connector, CreateServiceProvider())
{
}
private static IServiceProvider CreateServiceProvider()
{
var services = new ServiceCollection();
// Register entity binding for code generation
services.AddEntityBinding((entity, implementation) =>
{
services.AddTransient(entity, implementation);
});
return services.BuildServiceProvider();
}
public IGraphSet<IPerson> People => GraphSet<IPerson>();
public IGraphSet<ICompany> Companies => GraphSet<ICompany>();
public IEdgeGraphSet<IEmployment> Employments => EdgeGraphSet<IEmployment>();
protected override bool InitializeModel(IGraphConfiguration configuration)
{
configuration
.ConfigureCollection<IPerson>()
.In(p => p.Parents, "parent").Out<IPerson>(p => p.Children)
.Out(p => p.Employers, "employer").In<ICompany>(c => c.Employees)
.ConfigureCollection<ICompany>()
.In(c => c.Employees, "employer").Out<IPerson>(p => p.Employers)
.ConfigureCollection<IEmployment>();
return true;
}
}
3. Use the Context
// Dependency injection setup
services.AddSingleton<IGremlinLanguageConnector>(provider =>
new GremlinNetLanguageConnector("hostname", "database", "collection", "key"));
services.AddScoped<MyGraphContext>();
// Usage in your application
using var context = serviceProvider.GetService<MyGraphContext>();
// Create and save new entities
var person = context.CreateEntity<IPerson>("person-1");
person.FirstName = "John";
person.LastName = "Doe";
person.Adult = true;
var company = context.CreateEntity<ICompany>("company-1");
company.Name = "Microsoft";
company.Industry = "Technology";
// Create relationships using EdgeGraphSet
var employment = context.Employments.Create(person, company);
employment.HiredDate = DateTime.UtcNow.AddYears(-2);
employment.Manager = "Jane Smith";
await context.SaveChangesAsync();
// Query entities using GraphSet methods
var retrievedPerson = await context.People.GetAsync("person-1");
var allPeople = await context.People.AllAsync();
var techWorkers = await context.PeopleProfiles.GetAsync(g=>g.V().Has("name","John");
Supported Databases
Azure Cosmos DB (Gremlin API)
Apache TinkerPop compatible databases
In-memory graph database (for testing via Stardust.Paradox.Data.InMemory)
Advanced Features
Custom Traversals with GraphContext
// Complex traversal queries using VAsync
var friendsOfFriends = await context.VAsync<IPerson>(g =>
g.V().HasLabel("person")
.Has("firstName", "John")
.Out("knows")
.Out("knows") // Friends of friends
.Dedup()
.Limit(10));
// Aggregation queries using ExecuteAsync
var companySizes = await context.ExecuteAsync<dynamic>(g =>
g.V().HasLabel("company")
.Group()
.By("industry")
.By(__.In("employer").Count()));
// Direct vertex queries by ID
var specificPerson = await context.VAsync<IPerson>("person-1");
// Partition key support for Cosmos DB
var personWithPK = await context.VAsync<IPerson>("person-1", "partition-key");
IGraphSet<T> Operations
// Get by ID
var person = await context.People.GetAsync("person-1");
// Get by ID with partition key (Cosmos DB)
var person = await context.People.GetAsync("person-1", "partition-key");
// Filter operations
var techWorkers = await context.People.FilterAsync(p => p.FirstName, "John");
// Get all with pagination
var allPeople = await context.People.AllAsync();
var pagedPeople = await context.People.GetAsync(page: 0, pageSize: 20);
// Create operations
var newPerson = context.People.Create(); // Auto-generated ID
var specificPerson = context.People.Create("specific-id");
var initializedPerson = context.People.Create("id", p => {
p.FirstName = "John";
p.LastName = "Doe";
return p;
});
// Delete operations
await context.People.DeleteAsync("person-1");
await context.People.DeleteAsync("person-1", "partition-key");
// Attach existing entities
context.People.Attach(existingPerson);
IEdgeGraphSet<T> Operations
// Create edges between vertices
var employment = context.Employments.Create(person, company);
// Get edge by vertices
var employment = await context.Employments.GetAsync("person-1", "company-1");
// Get edges by vertex ID
var personEmployments = await context.Employments.GetByInIdAsync("person-1");
var companyEmployments = await context.Employments.GetByOutIdAsync("company-1");
// For entities implementing IDynamicGraphEntity
public interface IPerson : IVertex, IDynamicGraphEntity
{
// ... other properties
}
// Usage
if (person is IDynamicGraphEntity dynamicPerson)
{
dynamicPerson.SetProperty("customField", "customValue");
dynamicPerson.SetProperty("rating", 4.5);
await context.SaveChangesAsync();
var customValue = dynamicPerson.GetProperty("customField");
var propertyNames = dynamicPerson.DynamicPropertyNames;
}
Configuration Examples
Azure Cosmos DB Connection
using Stardust.Paradox.Data.Providers.Gremlin;
// Cosmos DB connection
var connector = new GremlinNetLanguageConnector(
gremlinHostname: "your-account.gremlin.cosmos.azure.com",
databaseName: "your-database",
graphName: "your-collection",
accessKey: "your-primary-key");
Apache TinkerPop Connection
// TinkerPop Server connection
var connector = new GremlinNetLanguageConnector(
gremlinHostname: "localhost",
username: "",
password: "",
port: 8182,
enableSsl: false);
In-Memory Testing
using Stardust.Paradox.Data.InMemory;
using Stardust.Paradox.Data.InMemory.Factory;
// In-memory connector for testing
var connector = InMemoryConnectorFactory.CreateForTesting();
// Or with predefined scenarios
var connector = InMemoryConnectorFactory.CreateSocialNetwork();
using var context = new MyGraphContext(connector);
// Perfect for unit testing - no external dependencies!
Testing with InMemory Provider
using Microsoft.VisualStudio.TestTools.UnitTesting;
using Stardust.Paradox.Data.InMemory.Factory;
[TestClass]
public class GraphTests
{
private MyGraphContext _context;
[TestInitialize]
public void Setup()
{
var connector = InMemoryConnectorFactory.CreateForTesting();
_context = new MyGraphContext(connector);
}
[TestMethod]
public async Task TestPersonCreation()
{
// Arrange
var person = _context.CreateEntity<IPerson>("test-1");
person.FirstName = "John";
person.Adult = true;
// Act
await _context.SaveChangesAsync();
var retrieved = await _context.VAsync<IPerson>("test-1");
// Assert
Assert.IsNotNull(retrieved);
Assert.AreEqual("John", retrieved.FirstName);
Assert.IsTrue(retrieved.Adult);
}
[TestMethod]
public async Task TestRelationshipCreation()
{
// Arrange
var person = _context.CreateEntity<IPerson>("person-1");
person.FirstName = "Alice";
var company = _context.CreateEntity<ICompany>("company-1");
company.Name = "TechCorp";
// Create employment edge
var employment = _context.Employments.Create(person, company);
employment.Manager = "Bob";
// Act
await _context.SaveChangesAsync();
// Assert - Test navigation
var employers = await person.Employers.ToVerticesAsync();
Assert.AreEqual(1, employers.Count());
Assert.AreEqual("TechCorp", employers.First().Name);
}
[TestCleanup]
public void Cleanup()
{
_context?.Dispose();
}
}
Performance and Monitoring
// Monitor Request Units (Cosmos DB)
Console.WriteLine($"RU consumed: {context.ConsumedRU}");
// Enable parallel save execution
GremlinContext.ParallelSaveExecution = true;
// Performance tracking with events
context.SavingChanges += (sender, args) => {
var stopwatch = Stopwatch.StartNew();
// Track save performance
};