StardogStore — Stardog knowledge-graph / RDF triplestore

StardogStore — Stardog knowledge-graph / RDF triplestore Overview Stardog is an enterprise knowledge-graph / RDF triplestore. It speaks the SPARQL 1.1 Protocol over HTTP. 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. A Stardog database exposes a query endpoint (/<db>/query) and an update endpoint (/<db>/update). Because none of that fits the SQL-shaped Dialect interface, StardogStore 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 | 'stardog' | library | 'fetch' | Driver strategy — prefer HTTP over fetch Stardog publishes a stardog npm 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 StardogStoreOptions 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 the official stardog client wrapped to this shape). The endpoint paths are derived from the database name: Getter | Value | Default (database = 'db') | ------------- | ---------------- | --------------------------- | queryPath | /<db>/query | /db/query | updatePath | /<db>/update | /db/update | Connection Build a store from connection options and call connect(): All options are optional: Option | Type | Purpose | ---------- | ------------------------- | ---------------------------------------------------------------------- | endpoint | string | Base URL of the Stardog server. Defaults to http://localhost:5820. | database | string | Database name. Defaults to db. 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 queryPath; returns body.results.bindings (or []). | ask | ask(sparql: string): Promise<boolean> | Runs an ASK query against queryPath; returns Boolean(body.boolean). | update | update(sparql: string): Promise<any> | Runs a SPARQL UPDATE against updatePath; 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/stardog.test.ts are fully mock-driven: an in-memory SparqlHttpClient is injected via StardogStoreOptions.client; it records each request (endpoint path + SPARQL body) and returns a canned SPARQL results envelope. There is no live Stardog server and no network in the test run, and the stardog npm client is not used. What this proves: name/library are 'stardog'/'fetch', and paths derive from the database (/myDb/query, /myDb/update). query() POSTs to /db/query and returns results.bindings; ask() returns the boolean; update() POSTs to /db/update. 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 Stardog 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