rust-kgdb 0.2.0 → 0.2.2

package/README.md

@@ -20,15 +20,32 @@ rust-kgdb supports three deployment modes:
 | **Single Node (RocksDB/LMDB)** | Production, persistence needed | Single node, persistent | Via Rust crate |
 | **Distributed Cluster** | Enterprise, 1B+ triples | Horizontal scaling, 9+ partitions | Contact us |
 
-### Need Distributed Cluster?
+### Distributed Cluster Mode (Enterprise)
 
-For enterprise deployments requiring:
-- **Subject-Anchored Partitioning**: All triples for a subject guaranteed on same partition for locality
-- Horizontal scaling across multiple nodes (1B+ triples)
-- HDRF (High-Degree Replicated First) with power-law load balancing
-- **OLAP Query Path**: SQL-based analytical execution for aggregations
-- Subject-Hash Filter for accurate COUNT deduplication across replicas
-- Kubernetes-native deployment with StatefulSet executors
+For enterprise deployments requiring 1B+ triples and horizontal scaling:
+
+**Key Features:**
+- **Subject-Anchored Partitioning**: All triples for a subject are guaranteed on the same partition for optimal locality
+- **Arrow-Powered OLAP**: High-performance analytical queries executed as optimized SQL at scale
+- **Automatic Query Routing**: The coordinator intelligently routes queries to the right executors
+- **Kubernetes-Native**: StatefulSet-based executors with automatic failover
+- **Linear Horizontal Scaling**: Add more executor pods to scale throughput
+
+**How It Works:**
+
+Your SPARQL queries work unchanged. For large-scale aggregations, the cluster automatically optimizes execution:
+
+```sparql
+-- Your SPARQL query
+SELECT (COUNT(*) AS ?count) (AVG(?salary) AS ?avgSalary)
+WHERE {
+  ?employee <http://ex/type> <http://ex/Employee> .
+  ?employee <http://ex/salary> ?salary .
+}
+
+-- Cluster executes as optimized SQL internally
+-- Results aggregated across all partitions automatically
+```
 
 **Request a demo: gonnect.uk@gmail.com**
 
@@ -282,18 +299,17 @@ fs.writeFileSync('backup.nt', ntriples)
 npm install rust-kgdb
 ```
 
-### Platform Support
+### Platform Support (v0.2.1)
 
-| Platform | Architecture | Status | SIMD |
-|----------|-------------|--------|------|
-| **macOS** | Intel (x64) | ✅ | AVX2, BMI2, POPCNT |
-| **macOS** | Apple Silicon (arm64) | ✅ | NEON |
-| **Linux** | x64 | ✅ | AVX2, BMI2, POPCNT |
-| **Linux** | arm64 | ✅ | NEON |
-| **Windows** | x64 | ✅ | AVX2, BMI2, POPCNT |
-| **Windows** | arm64 | ⏳ v0.2.0 | — |
+| Platform | Architecture | Status | Notes |
+|----------|-------------|--------|-------|
+| **macOS** | Intel (x64) | ✅ **Works out of the box** | Pre-built binary included |
+| **macOS** | Apple Silicon (arm64) | ⏳ v0.2.2 | Coming soon |
+| **Linux** | x64 | ⏳ v0.2.2 | Coming soon |
+| **Linux** | arm64 | ⏳ v0.2.2 | Coming soon |
+| **Windows** | x64 | ⏳ v0.2.2 | Coming soon |
 
-**No compilation required**—pre-built native binaries included.
+**This release (v0.2.1)** includes pre-built binary for **macOS x64 only**. Other platforms will be added in the next release.
 
 ---
 
@@ -446,15 +462,64 @@ db.querySelect(`
 ### UPDATE Operations
 
 ```typescript
-// INSERT DATA
+// INSERT DATA - Add new triples
 db.updateInsert(`
-  INSERT DATA { <http://ex/new> <http://ex/prop> "value" }
+  PREFIX ex: <http://example.org/>
+  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+  INSERT DATA {
+    ex:david a foaf:Person ;
+             foaf:name "David" ;
+             foaf:age 28 ;
+             foaf:email "david@example.org" .
+
+    ex:project1 ex:hasLead ex:david ;
+                ex:budget 50000 ;
+                ex:status "active" .
+  }
 `)
 
-// DELETE WHERE
+// Verify insert
+const count = db.count()
+console.log(`Total triples after insert: ${count}`)
+
+// DELETE WHERE - Remove matching triples
 db.updateDelete(`
-  DELETE WHERE { ?s <http://ex/deprecated> ?o }
+  PREFIX ex: <http://example.org/>
+  DELETE WHERE { ?s ex:status "completed" }
+`)
+```
+
+### Bulk Data Loading Example
+
+```typescript
+import { GraphDB } from 'rust-kgdb'
+import { readFileSync } from 'fs'
+
+const db = new GraphDB('http://example.org/bulk-load')
+
+// Load Turtle file
+const ttlData = readFileSync('data/knowledge-graph.ttl', 'utf-8')
+db.loadTtl(ttlData, null)  // null = default graph
+
+// Load into named graph
+const orgData = readFileSync('data/organization.ttl', 'utf-8')
+db.loadTtl(orgData, 'http://example.org/graphs/org')
+
+// Load N-Triples format
+const ntData = readFileSync('data/triples.nt', 'utf-8')
+db.loadNTriples(ntData, null)
+
+console.log(`Loaded ${db.count()} triples`)
+
+// Query across all graphs
+const results = db.querySelect(`
+  SELECT ?g (COUNT(*) AS ?count) WHERE {
+    GRAPH ?g { ?s ?p ?o }
+  }
+  GROUP BY ?g
 `)
+console.log('Triples per graph:', results)
 ```
 
 ---
@@ -614,11 +679,24 @@ Total: ~120 bytes/triple including indexes
 
 ## Version History
 
+### v0.2.2 (2025-12-08) - Enhanced Documentation
+
+- Added comprehensive INSERT DATA examples with PREFIX syntax
+- Added bulk data loading example with named graphs
+- Enhanced SPARQL UPDATE section with real-world patterns
+- Improved documentation for data import workflows
+
+### v0.2.1 (2025-12-08) - npm Platform Fix
+
+- Fixed native module loading for platform-specific binaries
+- This release includes pre-built binary for **macOS x64** only
+- Other platforms coming in next release
+
 ### v0.2.0 (2025-12-08) - Distributed Cluster Support
 
 - **NEW: Distributed cluster architecture** with HDRF partitioning
 - **Subject-Hash Filter** for accurate COUNT deduplication across replicas
-- **DataFusion-powered OLAP** with Arrow-native vectorized execution
+- **Arrow-powered OLAP** query path for high-performance analytical queries
 - Coordinator-Executor pattern with gRPC communication
 - 9-partition default for optimal data distribution
 - **Contact for cluster deployment**: gonnect.uk@gmail.com

package/index.js

@@ -1,4 +1,38 @@
-const { GraphDb, getVersion } = require('./rust-kgdb-napi.node')
+// Platform-specific native module loading for NAPI-RS
+const os = require('os')
+const path = require('path')
+
+function loadNativeBinding() {
+  const platform = os.platform()
+  const arch = os.arch()
+
+  // Map Node.js arch/platform to NAPI-RS naming convention
+  let nativeBinding
+
+  if (platform === 'darwin') {
+    if (arch === 'x64') {
+      nativeBinding = require('./rust-kgdb-napi.darwin-x64.node')
+    } else if (arch === 'arm64') {
+      nativeBinding = require('./rust-kgdb-napi.darwin-arm64.node')
+    }
+  } else if (platform === 'linux') {
+    if (arch === 'x64') {
+      nativeBinding = require('./rust-kgdb-napi.linux-x64-gnu.node')
+    } else if (arch === 'arm64') {
+      nativeBinding = require('./rust-kgdb-napi.linux-arm64-gnu.node')
+    }
+  } else if (platform === 'win32' && arch === 'x64') {
+    nativeBinding = require('./rust-kgdb-napi.win32-x64-msvc.node')
+  }
+
+  if (!nativeBinding) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}. Please contact support.`)
+  }
+
+  return nativeBinding
+}
+
+const { GraphDb, getVersion } = loadNativeBinding()
 
 module.exports = {
   GraphDB: GraphDb,  // Export as GraphDB for consistency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "High-performance RDF/SPARQL database with 100% W3C compliance, WCOJ execution, and distributed cluster support",
   "main": "index.js",
   "types": "index.d.ts",
@@ -56,10 +56,10 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rust-kgdb-win32-x64-msvc": "0.2.0",
-    "rust-kgdb-darwin-x64": "0.2.0",
-    "rust-kgdb-linux-x64-gnu": "0.2.0",
-    "rust-kgdb-darwin-arm64": "0.2.0",
-    "rust-kgdb-linux-arm64-gnu": "0.2.0"
+    "rust-kgdb-win32-x64-msvc": "0.2.2",
+    "rust-kgdb-darwin-x64": "0.2.2",
+    "rust-kgdb-linux-x64-gnu": "0.2.2",
+    "rust-kgdb-darwin-arm64": "0.2.2",
+    "rust-kgdb-linux-arm64-gnu": "0.2.2"
   }
 }