AllegrographStore — AllegroGraph semantic-graph / RDF triplestore

AllegrographStore — AllegroGraph semantic-graph / RDF triplestore Overview AllegroGraph is a semantic-graph / RDF triplestore. Its repositories are queried over the SPARQL 1.1 Protocol. It is not a SQL database: there are no rows, no DDL, and no identifier escaping. Data is a set of RDF triples queried and mutated over HTTP via a per-repository endpoint (/repositories/<repo>) used for both queries and updates. Because none of that fits the SQL-shaped Dialect interface, AllegrographStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes SPARQL query/update operations directly. Identity: Property | Value | --------- | ---------------- | name | 'allegrograph' | library | 'fetch' | Driver strategy — prefer HTTP over fetch AllegroGraph ships an agraph-js client, but this store prefers the plain SPARQL/HTTP protocol over the global fetch so it has no hard dependency (hence library='fetch'). The internal client (createFetchClient) POSTs the SPARQL text with Content-Type: application/sparql-query (queries, Accept: application/sparql-results+json) or application/sparql-update (updates). Injected client AllegrographStoreOptions accepts a pre-built client implementing the small SparqlHttpClient interface. When provided it is used verbatim and endpoint is ignored; otherwise the internal fetch-based client is built against endpoint at connect() time. This is how the test suite injects a mock (no network), and how callers can supply their own transport (including agraph-js wrapped to this shape). Queries and updates share the same per-repository path: Getter | Value | Default (repository = 'repo') | ------------- | ----------------------- | ------------------------------- | queryPath | /repositories/<repo> | /repositories/repo | updatePath | /repositories/<repo> | /repositories/repo | Connection Build a store from connection options and call connect(): All options are optional: Option | Type | Purpose | ------------ | ------------------------- | --------------------------------------------------------------------------- | endpoint | string | Base URL of the AllegroGraph server. Defaults to http://localhost:10035. | repository | string | Repository id. Defaults to repo. Drives queryPath / updatePath. | client | SparqlHttpClient | Pre-built client used verbatim; when set, endpoint is ignored. | headers | Record<string, string> | Extra HTTP headers sent with every internal-client request. | Injected-client form Methods Every SPARQL method resolves the client (throwing ConnectionError if not connected), POSTs via the client, and wraps any client failure in a DatabaseError (carrying the SPARQL text as sql). Lifecycle Method | Signature | Behavior | -------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds the internal fetch client. Idempotent. | disconnect | disconnect(): Promise<void> | Clears the client and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): SparqlHttpClient | Returns the underlying (internal or injected) client. Throws ConnectionError if not connected. | SPARQL surface Method | Signature | Behavior | -------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | query | query(sparql: string): Promise<any[]> | Runs a SELECT/CONSTRUCT query against /repositories/<repo>; returns body.results.bindings (or []). | ask | ask(sparql: string): Promise<boolean> | Runs an ASK query against /repositories/<repo>; returns Boolean(body.boolean). | update | update(sparql: string): Promise<any> | Runs a SPARQL UPDATE against the same /repositories/<repo> endpoint; returns the client's response. | add | add(triples: string \| string[], graph?: string): Promise<any> | Issues INSERT DATA { ... }. Arrays are joined with newlines; when graph is given, wraps the body in GRAPH <g> { ... }. | drop | drop(graph?: string): Promise<any> | Issues DROP GRAPH <g> when a graph is given, else DROP ALL. | Example Verification status Unit / mock-verified only. The tests in tests/nosql/allegrograph.test.ts are fully mock-driven: an in-memory SparqlHttpClient is injected via AllegrographStoreOptions.client; it records each request (endpoint path + SPARQL body) and returns a canned SPARQL results envelope. There is no live AllegroGraph server and no network in the test run, and the agraph-js client is not used. What this proves: name/library are 'allegrograph'/'fetch', and queryPath/updatePath both derive from the repository (/repositories/kb). query() and update() both POST to /repositories/repo; query() returns results.bindings, ask() returns the boolean. add() emits INSERT DATA { ... }; drop() emits DROP GRAPH <urn:g> / DROP ALL. Lifecycle: connect/disconnect (idempotent), getClient() returns the injected client, and ConnectionError before connect(). Error wrapping: client failures surface as DatabaseError. What this does not prove: live execution against a real AllegroGraph server. The request shape is verified against the SPARQL 1.1 Protocol contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories