NornicDB

Composite database implementation notes ​

Date: 2024-12-04 Scope: Historical implementation record. Current behavior is documented in the topology guide.

Executive Summary ​

The sections below describe composite database management, query routing, and schema handling at the date recorded above. They do not establish support for every composite query or index combination. Check the current topology guide and the tests in pkg/multidb and pkg/cypher for the selected release.

Completed Features ​

1. Core Composite Database Management ​

  • CREATE COMPOSITE DATABASE
  • DROP COMPOSITE DATABASE
  • SHOW COMPOSITE DATABASES
  • SHOW CONSTITUENTS FOR COMPOSITE DATABASE
  • ALTER COMPOSITE DATABASE ADD ALIAS
  • ALTER COMPOSITE DATABASE DROP ALIAS

2. Query Execution ​

  • Transparent querying across all constituents
  • Result merging with deduplication
  • Write routing (label-based and property-based)
  • Read operations from all constituents
  • Error handling for offline constituents

3. Schema Merging ​

  • Constraints: All constraint types merged (UNIQUE, NODE_KEY, EXISTS)
  • Property Indexes: Merged from all constituents
  • Composite Indexes: Merged from all constituents
  • Full-text Indexes: Merged from all constituents
  • Vector Indexes: Merged from all constituents
  • Range Indexes: Merged from all constituents
  • Deduplication: Duplicate indexes/constraints by name are deduplicated

4. Result Deduplication ​

  • Node deduplication by ID in all query methods
  • Edge deduplication by ID in all query methods
  • Applied to: GetNodesByLabel, GetEdgesByType, AllNodes, AllEdges, ReadAdjacentEdges

5. Edge Case Handling ​

  • Empty composite databases (no constituents)
  • Offline constituents (errors skipped, operations continue)
  • All constituents offline (graceful degradation)
  • Circular dependency prevention (at DatabaseManager level)

6. Integration Tests ​

  • End-to-end Cypher query tests
  • Complex queries with WHERE, WITH, aggregation
  • Relationship queries
  • ALTER COMPOSITE DATABASE commands

7. Documentation ​

  • User guide with examples
  • Architecture documentation
  • Schema merging documentation
  • Limitations documented

Test Coverage ​

Unit Tests ​

  • pkg/multidb/composite.go: 85.9% coverage
  • pkg/multidb/routing.go: 85.9% coverage
  • pkg/storage/composite_engine.go: 74%+ coverage
  • pkg/cypher/composite_commands.go: Full coverage

Test Files ​

  • pkg/multidb/composite_test.go - Composite database management
  • pkg/multidb/routing_test.go - Routing strategies
  • pkg/storage/composite_engine_test.go - Core engine operations
  • pkg/storage/composite_engine_dedup_test.go - Deduplication
  • pkg/storage/composite_engine_edge_cases_test.go - Edge cases
  • pkg/storage/composite_engine_schema_test.go - Schema merging
  • pkg/cypher/composite_commands_test.go - Cypher commands
  • pkg/cypher/composite_integration_test.go - Integration tests

Implementation Analysis ​

Architecture ​

Storage Layer:

  • pkg/storage/composite_engine.go - Implements storage.Engine interface
  • Routes operations to constituent engines
  • Merges results transparently
  • Handles schema merging

Management Layer:

  • pkg/multidb/composite.go - Composite database metadata management
  • pkg/multidb/manager.go - Integration with DatabaseManager
  • pkg/multidb/routing.go - Routing strategies (available but not yet integrated)

Query Layer:

  • pkg/cypher/composite_commands.go - Cypher command handlers
  • pkg/cypher/executor.go - Query routing

Routing Implementation ​

Current State:

  • Basic routing implemented in CompositeEngine.routeWrite()
  • Uses hash-based routing on labels and properties
  • pkg/multidb/routing.go provides advanced routing strategies but not yet integrated

Available but Not Integrated:

  • LabelRouting - Route by label to specific constituents
  • PropertyRouting - Route by property values
  • CompositeRouting - Combine multiple routing strategies
  • FullScanRouting - Query all constituents

Note: The routing strategies in pkg/multidb/routing.go are fully implemented and tested, but CompositeEngine currently uses a simpler hash-based approach. Integration would enable user-configurable routing rules.

Schema Merging ​

Fully Implemented:

  • All constraint types merged
  • All index types merged (property, composite, fulltext, vector, range)
  • Deduplication by name
  • Metadata-only merging (indexed data stays in constituents)

Implementation Details:

  • Uses GetIndexes() to get index metadata from constituents
  • Recreates indexes in merged schema using Add*Index() methods
  • Handles type conversion for all index types
  • Preserves all index properties (dimensions, similarity function, etc.)

Known Limitations (By Design) ​

1. Remote Constituents Are Supported ​

  • Status: Implemented
  • Current Behavior: Composite databases can include remote constituents addressed by URI, with either forwarded caller auth (oidc_forwarding) or explicit service credentials (user_password).
  • Execution Model: Remote constituents participate in routed Fabric execution and explicit remote transaction-handle lifecycles, subject to the same many-read/one-write transaction boundary as local constituents.
  • Design Constraint: This is still a logical distributed graph topology, not a physically merged graph.

2. No Cross-Constituent Relationships ​

  • Status: By design
  • Reason: Relationships require both nodes in same database
  • Workaround: Use composite queries to find related nodes

3. No Distributed Transactions ​

  • Status: By design
  • Reason: Multi-constituent writes are best-effort
  • Future: Two-phase commit could be added

4. Simple Hash-Based Routing ​

  • Status: Functional but basic
  • Reason: Advanced routing strategies exist but not integrated
  • Future: Integrate pkg/multidb/routing.go strategies

5. Index Data Not Merged ​

  • Status: By design
  • Reason: Indexes have internal state (values maps)
  • Note: Schema metadata is merged, actual indexed data stays in constituents
  • Impact: SHOW INDEXES works, but query optimization uses constituent indexes

Potential Enhancements (Future) ​

1. Advanced Routing Integration ​

  • Priority: Medium
  • Effort: 2-3 days
  • Description: Integrate pkg/multidb/routing.go strategies into CompositeEngine
  • Benefit: User-configurable routing rules

2. Query Optimization ​

  • Priority: Medium
  • Effort: 5-7 days
  • Description: AST-based query analysis to skip unnecessary constituents
  • Benefit: Better performance for targeted queries

3. Parallel Query Execution ​

  • Priority: Low (already parallel at engine level)
  • Effort: 1-2 days
  • Description: Explicit parallel execution with goroutines
  • Benefit: Better control over concurrency

4. Remote Constituents ​

  • Priority: Low
  • Effort: 2-3 weeks
  • Description: Support databases in other NornicDB instances
  • Benefit: True distributed databases

5. Distributed Transactions ​

  • Priority: Low
  • Effort: 1-2 weeks
  • Description: Two-phase commit for multi-constituent writes
  • Benefit: ACID guarantees across constituents

Code Quality ​

No Technical Debt ​

  • No TODOs in composite database code
  • No FIXMEs or HACKs
  • Implementation details and limitations are recorded in the sections above
  • Method coverage is limited to the tests listed in this record

Documentation ​

  • All public APIs documented
  • Examples provided
  • User guide complete
  • Architecture docs updated

Testing ​

  • unit tests
  • Integration tests
  • Edge case tests
  • 90%+ coverage for critical paths

Implementation Checklist ​

Core Features ​

Query Execution ​

Schema ​

Data Operations ​

Edge Cases ​

Testing ​

Documentation ​

Conclusion ​

The composite database implementation is complete.

All features from the original requirements have been implemented:

  • ALTER COMPOSITE DATABASE commands
  • Query result deduplication
  • Integration tests
  • Complete schema merging (all index types)
  • Documentation
  • Edge case handling

The only "missing" features are future enhancements (remote constituents, distributed transactions) which are documented as limitations and planned for future releases.

This record does not establish completeness. Routing integration and other limitations described above must be evaluated against the selected source revision.

Analytics privacy