@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 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
Copy

Usage

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();
Copy

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" }`);
});
Copy

Implementing a Connector

A backend connector implements the Repository interface (ask, select, construct, update, 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.

A minimal connector has the shape:

import type { Repository, SPARQL } from "@metreeca/wire-sparql";

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

	const repository: Repository = {

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

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

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

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

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

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

	};

	return repository;
}
Copy

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.