@metreeca/wire-sparql

SPARQL 1.1 query language framework for @metreeca/wire storage connectors.

Provides a uniform Repository interface for issuing SPARQL queries and updates and for writing RDF data into graphs against any backend (an embedded store, a remote endpoint, or a managed server), without binding application code to a specific store or client. It also bundles combinators for composing SPARQL queries and updates from typed fragments, and exchanges data as the RDF terms and statements of @metreeca/trio, which it pulls in as a direct dependency.

Installation

Install this framework together with a backend connector for your target engine, plus any peer dependency the connector requires:

npm install @metreeca/wire-sparql                # the SPARQL query API (this framework)
npm install @metreeca/wire-sparql-<backend>      # backend connector from the table below
npm install <peer-dependency>                    # connector's peer dependency, where required

[!WARNING]

TypeScript consumers must use "moduleResolution": "nodenext"/"node16"/"bundler" in tsconfig.json. The legacy "node" resolver is not supported.

| Connector Package | Peer Dependency | Engine | |----------------------------------|--------------------|---------------------------------| | @metreeca/wire-sparql-http | - | SPARQL 1.1 Protocol endpoint | | @metreeca/wire-sparql-rdf4j | - | RDF4J REST API endpoint | | @metreeca/wire-sparql-oxigraph | oxigraph >=0.5.0 | Oxigraph in-memory WASM store |

Usage

[!NOTE]

This section introduces essential concepts; for complete coverage, see the API reference.

Querying a Backend

Obtain a Repository from any backend connector, then run SPARQL queries and updates through its methods:

import { createHTTPRepository } from "@metreeca/wire-sparql-http";

const repository = createHTTPRepository({
	query: "https://example.org/sparql",
	update: "https://example.org/sparql/statements"
});

await repository.update(`
	INSERT DATA { <https://example.org/widget> <https://schema.org/name> "Widget" }
`);

const tuples = await repository.select(`
	SELECT ?name { ?product <https://schema.org/name> ?name }
`); // readonly Tuple[]: each maps the ?name token to a Term

const present = await repository.ask(`ASK { ?s ?p ?o }`);

const triples = await repository.construct(`
	CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }
`); // readonly Triple[]

await repository.close();

Targeting a Dataset

Pass a Dataset as second argument to run a query or update against explicit graphs instead of those it declares:

const tuples = await repository.select(`SELECT ?name { ?product <https://schema.org/name> ?name }`, {
	default: ["https://example.org/catalog"]
});

[!WARNING]

An update given a dataset must declare none of its own through USING, USING NAMED or WITH clauses. Backends reject the combination, and some connectors do not support update datasets at all.

Writing RDF Data

Write RDF triples into a graph with merge, which adds them to the graph content, or with store, which replaces it. Both take the triples as terms rather than as SPARQL text, so connectors can upload large data sets in bulk:

import { named, triple, typed } from "@metreeca/trio";

const widget = triple(
	named("https://example.org/widget"),
	named("https://schema.org/name"),
	typed("Widget")
);

await repository.merge([widget], "https://example.org/catalog"); // adds to the named graph
await repository.store([widget]); // replaces the default graph content

Transactions

Bracket related operations with execute: the task runs on a per-call RepositoryClient and commits together, or rolls back if it throws:

await repository.execute(async tx => {
	await tx.update(`DELETE WHERE { <https://example.org/widget> ?p ?o }`);
	await tx.update(`INSERT DATA { <https://example.org/widget> <https://schema.org/name> "Gadget" }`);
});

[!IMPORTANT]

Transaction isolation is backend-dependent. A backend with native transactions brackets the task for atomic commit and rollback; one without runs the task directly against the same Repository, with no atomicity or rollback. Each connector documents the level it provides on its factory function.

Implementing a Connector

A backend connector implements the Repository interface (ask, select, construct, update, merge, store, execute, and close), lifting native backend nodes into the shared term model with the named, tagged, and typed constructors of @metreeca/trio, and parsing or serialising RDF payloads with its @metreeca/trio/ntriples codec, as the bundled HTTP connectors do for query results and graph uploads.

A minimal connector has the shape:

import type { IRI } from "@metreeca/core/resource";
import type { Triple } from "@metreeca/trio";
import type { Dataset, Repository, SPARQL } from "@metreeca/wire-sparql";

function createMyRepository(/* endpoint, client, … */): Repository {

	const repository: Repository = {

		ask: async (query: SPARQL, dataset?: Dataset) => { /* run ASK; return the boolean */ },

		select: async (query: SPARQL, dataset?: Dataset) => { /* run SELECT; map bindings to Tuples of Terms */ },

		construct: async (query: SPARQL, dataset?: Dataset) => { /* run CONSTRUCT; map statements to Triples */ },

		update: async (update: SPARQL, dataset?: Dataset) => { /* apply the UPDATE */ },

		merge: async (triples: readonly Triple[], graph?: IRI) => { /* add the triples to the graph */ },

		store: async (triples: readonly Triple[], graph?: IRI) => { /* replace the graph content */ },

		execute: async task => task(repository),  // or bracket the task in a backend transaction

		close: async () => { /* release resources, or no-op */ }

	};

	return repository;
}

[!TIP]

Each SPARQL connector in the @metreeca/wire monorepo is a complete, working implementation that you can read to learn the approach or adapt for a new engine.

Support

• open an issue to report a problem or to suggest a new feature
• start a discussion to ask a how-to question or to share an idea

License

This project is licensed under the Apache 2.0 License – see LICENSE file for details.