Add R2RML virtual graph support with advanced mapping features

[bplatz]

Summary

This PR adds R2RML (RDB to RDF Mapping Language) support for virtualizing relational databases as RDF graphs in Fluree DB. R2RML is a W3C standard that enables SPARQL queries over SQL databases without data migration.

📚 Documentation: See docs/r2rml-guide.md for usage guide and examples.

Features Implemented

Core R2RML Support

• Logical Tables

  • rr:tableName - Direct table mapping
  • rr:sqlQuery - SQL query results mapping (with JOINs, aggregations, computed columns)

• Subject Maps

  • rr:template - Generate subject IRIs from column values
  • rr:class - Specify RDF classes

• Predicate-Object Maps

  • rr:column - Map database columns to RDF objects
  • rr:template - Create composite values from multiple columns
  • rr:constant - Use fixed literal or IRI values
  • rr:datatype - XSD datatype specification
  • rr:language - Language tags for internationalization

Format Support

• Turtle (.ttl) format for R2RML mappings
• JSON-LD format for R2RML mappings
• Inline mapping definitions
• File-based mapping definitions

Technical Implementation

The implementation follows a pattern-collection approach similar to BM25:

1. SPARQL patterns are collected during the match phase
2. Patterns are analyzed to determine the appropriate R2RML mapping
3. SQL is generated based on the patterns and mapping
4. Results are transformed to RDF according to the mapping rules

Key Components

• Pattern Analysis: Selects R2RML mappings based on query patterns
• SQL Generation: Generates SQL with column aliasing and filtering
• Result Transformation: Handles templates, datatypes, language tags, and constants
• Database Support: Works with H2, PostgreSQL, MySQL, SQL Server via JDBC

Query Support

Supports both FQL and SPARQL query patterns:

;; FQL Query
{"from" ["vg/persons"]
 "select" ["?person" "?name"]
 "where" [{"@id" "?person"
          "@type" "http://xmlns.com/foaf/0.1/Person"
          "http://xmlns.com/foaf/0.1/name" "?name"}]}

-- SPARQL Equivalent
SELECT ?person ?name
WHERE {
  ?person a foaf:Person ;
          foaf:name ?name .
}

Testing

Test suite includes 19 tests covering:

• Basic table mapping
• SQL query mapping with aggregations
• Template-based object values
• Constant values
• XSD datatypes
• Language tags
• JSON-LD format support
• Filter expressions
• Complex SQL queries

Example Usage

;; Define R2RML mapping
(def mapping
  "@prefix rr: <http://www.w3.org/ns/r2rml#> .
   @prefix ex: <http://example.com/> .
   
   ex:PersonMap a rr:TriplesMap ;
     rr:logicalTable [ rr:tableName \"persons\" ] ;
     rr:subjectMap [
       rr:template \"http://example.com/person/{id}\" ;
       rr:class ex:Person
     ] ;
     rr:predicateObjectMap [
       rr:predicate ex:name ;
       rr:objectMap [ rr:column \"name\" ]
     ] .")

;; Publish virtual graph
(nameservice/publish publisher
  {:vg-name "vg/persons"
   :vg-type "fidx:R2RML"
   :engine  :r2rml
   :config  {:mappingInline mapping
             :rdb {:jdbcUrl "jdbc:postgresql://localhost/db"
                   :driver  "org.postgresql.Driver"}}})

Implementation Notes

• Query Pushdown: Filters are converted to SQL WHERE clauses
• Column Selection: Only required columns are selected from database
• Template Processing: Templates are expanded during result processing
• Result Streaming: Results are streamed through core.async channels

Not Yet Implemented

R2RML features not included in this PR:

• rr:parentTriplesMap - Foreign key relationships
• rr:joinCondition - Join conditions between mappings
• rr:graphMap - Named graph support
• rr:termType - Explicit term type specification
• Dynamic predicates from columns

Breaking Changes

None - this is a new feature addition.

Test Plan

Run the R2RML test suite:

clojure -M:cljtest -m kaocha.runner --focus fluree.db.virtual-graph.r2rml-test

All 19 tests should pass.

[bplatz]

R2RML is now being used primarily by the iceberg feature in #1185 which includes most of these R2RML features, so closing this PR.