Usage

The tool exposes a single entry point: the reconstruct() function. It takes an R2RML or RML mapping file, an RDF graph, and a destination database, then materializes the reconstructed tables in that database.

Basic invocation

import kgi

kgi.reconstruct(
    mapping="mapping.ttl",
    rdf_graph="output.nq",
    dest_db_url="postgresql+psycopg2://user:password@localhost:5432/restored_db",
)

dest_db_url is required. The function writes the reconstructed rows to that database and returns None.

Using the source database schema

The algorithm infers column types and ordering on its own, but when a source database is available it can read the original schema to resolve ambiguous cases:

kgi.reconstruct(
    mapping="mapping.ttl",
    rdf_graph="output.nq",
    dest_db_url="postgresql+psycopg2://user:password@localhost:5432/restored_db",
    source_db_url="postgresql+psycopg2://user:password@localhost:5432/source_db",
)

With RML mappings that contain D2RQ database definitions, the connection info is extracted directly from the mapping file. When the mapping includes a block like this:

<#DB_source> a d2rq:Database;
  d2rq:jdbcDSN "jdbc:postgresql://localhost:5432/mydb";
  d2rq:username "user";
  d2rq:password "pass" .

the JDBC DSN, username, and password are converted to a SQLAlchemy URL and used as source_db_url automatically. If you pass source_db_url explicitly, it takes precedence over whatever the mapping says.

Destination database

Pass the destination as a SQLAlchemy connection string via dest_db_url:

kgi.reconstruct(
    mapping="mapping.ttl",
    rdf_graph="output.nq",
    dest_db_url="postgresql+psycopg2://user:password@localhost:5432/restored_db",
)

Error handling

Not every mapping can be inverted. When the function encounters an unsupported or non-invertible case, it raises an exception:

from kgi import MappingError, NoDataError, NonInvertibleError, UnsupportedMappingError

try:
    kgi.reconstruct(
        mapping="mapping.ttl",
        rdf_graph="output.nq",
        dest_db_url="postgresql+psycopg2://user:password@localhost:5432/restored_db",
    )
except UnsupportedMappingError as e:
    print(f"Unsupported: {e}")
except MappingError as e:
    print(f"Invalid mapping: {e}")
except NonInvertibleError as e:
    print(f"Non-invertible: {e}")
except NoDataError as e:
    print(f"No data: {e}")

The exceptions are:

Exception	Meaning
UnsupportedMappingError	The mapping uses SQL queries as logical tables, which the algorithm does not handle.
MappingError	The mapping document is syntactically invalid or violates the R2RML specification.
NonInvertibleError	The mapping is valid but leaves no recoverable column for some table. Columns the graph cannot attribute are dropped from the reconstruction instead, without raising. See limitations.
NoDataError	The SPARQL queries returned no results, or the RDF input file does not exist.