RocksetStore — Rockset real-time analytics store

RocksetStore — Rockset real-time analytics store Overview Rockset is a real-time analytics database that indexes streaming and document data (a "converged index" over row, columnar, and inverted indexes) and serves low-latency SQL over it. It is a schemaless, document-oriented, HTTP/JSON service with an official client (@rockset/client); there is no relational connection, no server-side transactions, and ingestion is document-based (addDocuments), so it does not fit the SQL-shaped Dialect interface. RocksetStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) and exposes Rockset's query + document API directly. Identity: Property | Value | --------- | ------------------- | name | 'rockset' | library | '@rockset/client' | Driver: @rockset/client, lazy-loaded The @rockset/client package is an optional peer dependency. It is lazily required inside connect() — resolving mod.default ?? mod and calling factory(apiKey, host) — so importing this module never forces it to be installed. It is only needed when the store actually connects. Injected client RocksetStoreOptions accepts a pre-built client — a @rockset/client instance (or a compatible mock) implementing the small RocksetClientLike shape. When provided, connect() uses it directly and skips require('@rockset/client') entirely. This is how the test suite injects a mock without the real driver installed. Connection Build a store from connection options and call connect(): Connection options (all optional): Option | Type | Purpose | --------- | ------------------- | ----------------------------------------------------------------------------- | apiKey | string | Rockset API key used to authenticate the client. | host | string | Rockset API server host, e.g. 'https://api.usw2a1.rockset.com'. | client | RocksetClientLike | Pre-built @rockset/client instance (or mock). When set, require('@rockset/client') is skipped. | Injected-client form Methods Failures from the client are wrapped in a DatabaseError (via DatabaseError.from, message prefixed Rockset query failed: / Rockset ingest failed:). Using query/ingest/getClient before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client, otherwise lazy-requires @rockset/client and builds it from apiKey/host. Idempotent. Failures wrapped in ConnectionError. | disconnect | disconnect(): Promise<void> | Clears the client and connection state (no network teardown). | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): RocksetClientLike | Returns the underlying @rockset/client instance. Throws ConnectionError if not connected. | Query + ingest Method | Signature | Behavior | -------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | query | query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> | Runs a SQL query via client.queries.query({ sql: { query, parameters } }) (parameters included only when non-empty) and returns the results array from the response. | ingest | ingest(target: string, docs: Array<Record<string, unknown>>): Promise<any> | Ingests docs into target via client.documents.addDocuments(workspace, collection, { data }). target is a workspace.collection path; a bare name defaults the workspace to commons. Returns the client response. | Example Verification status Unit / mock-verified only. The tests in tests/nosql/rockset.test.ts are fully mock-driven: @rockset/client is not installed, so every test injects a mock client (with queries.query and documents.addDocuments spies) via RocksetStoreOptions.client, which makes connect() skip require('@rockset/client'). There is no network and no live Rockset service. What this proves: query() calls queries.query with the correct { sql: { query } } envelope (and adds parameters when provided), returning response.results. ingest() splits workspace.collection and calls addDocuments(workspace, collection, { data }), defaulting the workspace to commons when only a collection is given. Lifecycle: connecting via an injected client, idempotent connect(), disconnect() clearing state, and ConnectionError before connect() (from both getClient() and query()). Error handling: failing query() and ingest() calls wrapped in DatabaseError. What this does not prove: live execution against the real Rockset service. Request/response shapes are asserted against the @rockset/client documented 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