rust-kgdb 0.6.81 → 0.6.83

package/examples/rpc-virtual-tables-demo.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * ================================================================================
+ * RpcFederationProxy: Virtual Tables Demo
+ * Session-Bound Query Result Materialization
+ * ================================================================================
+ *
+ * Virtual Tables in HyperFederate:
+ * - Session-bound materialization of federation query results
+ * - Stored as RDF triples in KGDB (self-describing)
+ * - Access control via shared_with and shared_with_groups
+ * - Refresh policies: on_demand, ttl, on_source_change
+ * - No ETL required - real-time query materialization
+ *
+ * Architecture:
+ * - Heavy lifting in Rust core (DataFusion, Arrow, KGDB storage)
+ * - TypeScript SDK provides thin RPC proxy layer
+ *
+ * Run: node examples/rpc-virtual-tables-demo.js
+ *
+ * @requires HyperFederate server running at http://localhost:30180
+ */
+
+const {
+  RpcFederationProxy,
+  WasmSandbox,
+  ProofDAG
+} = require('../index.js')
+
+// ================================================================================
+// DEMO: Virtual Tables
+// ================================================================================
+
+async function runDemo() {
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     RpcFederationProxy: Virtual Tables Demo                          ║')
+  console.log('║     Session-Bound Query Result Materialization                       ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝\n')
+
+  // Create RpcFederationProxy
+  const federation = new RpcFederationProxy({
+    endpoint: process.env.HYPERFEDERATE_URL || 'http://localhost:30180',
+    identityId: 'risk-analyst-001'
+  })
+
+  console.log(`Federation Endpoint: ${federation.endpoint}`)
+  console.log(`Session ID: ${federation.sessionId}`)
+  console.log(`Identity ID: ${federation.identityId}`)
+  console.log()
+
+  // ============================================================================
+  // 1. Create Virtual Table from Federation Query
+  // ============================================================================
+  console.log('1. Create Virtual Table from Federation Query')
+  console.log('═'.repeat(70))
+
+  const createVtQuery = `
+    -- High-risk customers: KGDB risk scores + Snowflake account data
+    SELECT
+      kg.person AS kg_entity,
+      kg.riskScore AS risk_level,
+      entity_type(kg.person) AS entity_types,
+      sf.C_NAME AS customer_name,
+      sf.C_ACCTBAL AS account_balance,
+      sf.C_MKTSEGMENT AS market_segment
+    FROM graph_search('
+      PREFIX finance: <https://gonnect.ai/domains/finance#>
+      PREFIX tpch: <https://gonnect.ai/tpch#>
+      SELECT ?person ?riskScore ?custKey WHERE {
+        ?risk finance:assessedFor ?person ;
+              finance:riskScore ?riskScore .
+        ?person tpch:custKey ?custKey .
+        FILTER(?riskScore > 0.7)
+      }
+    ') kg
+    JOIN snowflake_tpch.CUSTOMER sf
+      ON CAST(kg.custKey AS INTEGER) = sf.C_CUSTKEY
+    WHERE sf.C_ACCTBAL > 50000
+  `
+
+  console.log('   SQL Query:')
+  console.log(createVtQuery.trim().split('\n').map(l => '     ' + l).join('\n'))
+  console.log()
+
+  try {
+    const vt = await federation.createVirtualTable('high_risk_customers', createVtQuery, {
+      refreshPolicy: 'on_demand',
+      ttlSeconds: 3600,
+      sharedWith: ['risk-analyst-002', 'compliance-officer-001'],
+      sharedWithGroups: ['team-risk-analytics', 'team-compliance']
+    })
+
+    console.log('   Virtual Table Created:')
+    console.log(`     ID: ${vt.id}`)
+    console.log(`     Name: ${vt.name}`)
+    console.log(`     URI: ${vt.uri}`)
+    console.log(`     Columns: ${vt.columns.join(', ')}`)
+    console.log(`     Row Count: ${vt.rowCount}`)
+    console.log(`     Refresh Policy: ${vt.refreshPolicy}`)
+    console.log(`     Created At: ${vt.createdAt}`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Demo mode - Server not running]`)
+    console.log(`   Virtual table would be created with:`)
+    console.log(`     Name: high_risk_customers`)
+    console.log(`     Refresh Policy: on_demand`)
+    console.log(`     TTL: 3600 seconds`)
+    console.log(`     Shared With: risk-analyst-002, compliance-officer-001`)
+    console.log(`     Shared Groups: team-risk-analytics, team-compliance`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 2. Query Virtual Table (No Re-execution)
+  // ============================================================================
+  console.log('2. Query Virtual Table (Materialized Results)')
+  console.log('═'.repeat(70))
+  console.log('   Virtual tables are materialized - no query re-execution needed.')
+  console.log()
+  console.log('   Query: SELECT * FROM virtual.high_risk_customers WHERE account_balance > 100000')
+  console.log()
+
+  try {
+    const result = await federation.queryVirtualTable('high_risk_customers', 'account_balance > 100000')
+    console.log(`   Result: ${result.rowCount} rows in ${result.duration}ms`)
+    console.log(`   (Materialized data, not re-executed)`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Demo mode - Would query materialized virtual table]`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 3. Virtual Table Use Cases
+  // ============================================================================
+  console.log('3. Virtual Table Use Cases')
+  console.log('═'.repeat(70))
+  const useCases = [
+    {
+      name: 'Risk Dashboard',
+      query: `CREATE VIRTUAL TABLE risk_dashboard AS
+        SELECT entity, risk_score, neighbors(entity, 1) AS network
+        FROM high_risk_customers`,
+      refresh: 'ttl (5 min)',
+      shared: 'team-risk-analytics'
+    },
+    {
+      name: 'Compliance Audit',
+      query: `CREATE VIRTUAL TABLE compliance_audit AS
+        SELECT entity, risk_score, entity_properties(entity) AS all_props
+        FROM high_risk_customers WHERE risk_score > 0.9`,
+      refresh: 'on_source_change',
+      shared: 'compliance-officers'
+    },
+    {
+      name: 'Customer 360',
+      query: `CREATE VIRTUAL TABLE customer_360 AS
+        SELECT kg.*, sf.*, bq.name_popularity
+        FROM graph_search(...) kg
+        JOIN snowflake.CUSTOMER sf ON ...
+        LEFT JOIN bigquery.usa_names bq ON ...`,
+      refresh: 'on_demand',
+      shared: 'team-customer-success'
+    }
+  ]
+
+  for (const useCase of useCases) {
+    console.log(`   ${useCase.name}`)
+    console.log(`     Refresh: ${useCase.refresh}`)
+    console.log(`     Shared With: ${useCase.shared}`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 4. Access Control Model
+  // ============================================================================
+  console.log('4. Access Control Model')
+  console.log('═'.repeat(70))
+  console.log(`
+   Virtual tables support fine-grained access control:
+
+   ┌─────────────────────────────────────────────────────────────────────┐
+   │  Virtual Table: high_risk_customers                                 │
+   │  Owner: risk-analyst-001 (creator)                                  │
+   ├─────────────────────────────────────────────────────────────────────┤
+   │  shared_with (individuals):                                         │
+   │    - risk-analyst-002        [Full access]                          │
+   │    - compliance-officer-001  [Full access]                          │
+   │                                                                     │
+   │  shared_with_groups (teams):                                        │
+   │    - team-risk-analytics     [All members have access]              │
+   │    - team-compliance         [All members have access]              │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   Access check: has_access(identity_id, groups) → boolean
+  `)
+
+  // ============================================================================
+  // 5. RDF Storage (Self-Describing)
+  // ============================================================================
+  console.log('5. Virtual Table RDF Storage (Self-Describing)')
+  console.log('═'.repeat(70))
+  console.log(`
+   Virtual tables are stored as RDF triples in KGDB:
+
+   <urn:hyperfederate:vt:${federation.sessionId}:high_risk_customers>
+       a hf:VirtualTable ;
+       hf:name "high_risk_customers" ;
+       hf:sessionId "${federation.sessionId}" ;
+       hf:ownerId "${federation.identityId}" ;
+       hf:query "SELECT kg.person, kg.riskScore..." ;
+       hf:refreshPolicy "on_demand" ;
+       hf:rowCount "42"^^xsd:integer ;
+       hf:createdAt "2024-12-21T12:00:00Z"^^xsd:dateTime ;
+       hf:sourceLineage "kgdb", "snowflake" ;
+       hf:sharedWith "risk-analyst-002", "compliance-officer-001" ;
+       hf:sharedWithGroups "team-risk-analytics", "team-compliance" .
+
+   This makes virtual tables queryable via SPARQL!
+  `)
+
+  // ============================================================================
+  // 6. ProofDAG Integration
+  // ============================================================================
+  console.log('6. ProofDAG Integration (Provenance Tracking)')
+  console.log('═'.repeat(70))
+
+  const proof = new ProofDAG('Risk analysis for high-value customers')
+
+  // Add virtual table creation as evidence
+  const vtNode = proof.addVirtualTableEvidence(
+    proof.rootId,
+    'high_risk_customers',
+    createVtQuery,
+    42  // rowCount
+  )
+
+  console.log(`   Root claim: ${proof.rootClaim}`)
+  console.log(`   Evidence type: virtual_table`)
+  console.log(`   Proof hash: ${proof.computeHash()}`)
+  console.log()
+
+  // ============================================================================
+  // Summary
+  // ============================================================================
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     Demo Complete!                                                   ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝')
+  console.log(`
+Virtual Table Benefits:
+  - No ETL Pipeline: Real-time query materialization
+  - Session Isolation: Each user sees only their tables
+  - Access Control: Fine-grained sharing via identities/groups
+  - Self-Describing: Stored as RDF, queryable via SPARQL
+  - Refresh Policies: on_demand, ttl, on_source_change
+  - Provenance: Full lineage tracking via ProofDAG
+
+Architecture Principle:
+  - Materialization logic in Rust core (DataFusion + KGDB)
+  - TypeScript SDK provides thin RPC proxy layer
+  - Heavy computation happens server-side
+
+Audit Log Entries: ${federation.getAuditLog().length}
+`)
+}
+
+// Run the demo
+runDemo().catch(console.error)