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

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

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
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, 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;
}
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.