Summary
The Node API client has drifted behind the server surface and currently exposes only a subset of hlquery’s operational and search endpoints. This should be treated as a high-priority SDK parity issue: Node users are forced to bypass the client for core capabilities, and route usage is inconsistent with the canonical API.
Context
The current Node client entry points in index.js, lib/Client.js, lib/Search.js, lib/Documents.js, and lib/Keys.js cover collections, documents, search, vector search, keys, and a few cluster helpers, but they do not provide first-class access to several server features that already exist in src/api/http_server.cpp, including aliases, overrides, synonyms, stopwords, metrics, connections, RocksDB stats, export, and facet-count operations.
There is also a route drift signal in lib/Search.js: it targets /collections/{name}/documents/search, while the server supports the canonical /collections/{name}/search route in addition to legacy compatibility handling. That makes the Node client more brittle as the API evolves and weakens the value of having an SDK in the first place.
For a high-performance search engine, SDK parity matters beyond developer convenience. Missing operational endpoints prevent Node services from observing cluster health, metrics, and storage state without dropping to raw HTTP calls, and missing search-management endpoints makes automation around synonyms, overrides, and stopwords inconsistent across languages.
Proposed Implementation
- Expand the Node client surface to cover the full public API already routed by the server, starting with:
- aliases
- overrides
- synonyms
- stopwords
- metrics/connections/RocksDB/system stats
- facet counts and export
- Normalize the search client onto canonical routes such as
/collections/{name}/search and /collections/{name}/vector_search, while preserving backward compatibility where needed.
- Introduce a Node SDK conformance test that maps client methods to the public server endpoints and fails when a routed endpoint has no Node wrapper.
- Make the conformance test part of the regular API test matrix so future server features cannot ship without an explicit Node decision: supported, intentionally omitted, or marked experimental.
- Update the Node README/examples to reflect the canonical routes and the expanded API surface.
Impact
This would turn the Node client from a partial wrapper into a reliable production SDK. The immediate benefits are better API correctness, fewer raw HTTP escape hatches in Node services, lower maintenance cost from route drift, and stronger cross-language consistency. It also improves operability for Node-based ingestion/search services by exposing metrics and storage endpoints directly through the client, which is a meaningful reliability gain for a high-performance RocksDB-backed search engine.
Summary
The Node API client has drifted behind the server surface and currently exposes only a subset of hlquery’s operational and search endpoints. This should be treated as a high-priority SDK parity issue: Node users are forced to bypass the client for core capabilities, and route usage is inconsistent with the canonical API.
Context
The current Node client entry points in
index.js,lib/Client.js,lib/Search.js,lib/Documents.js, andlib/Keys.jscover collections, documents, search, vector search, keys, and a few cluster helpers, but they do not provide first-class access to several server features that already exist insrc/api/http_server.cpp, including aliases, overrides, synonyms, stopwords, metrics, connections, RocksDB stats, export, and facet-count operations.There is also a route drift signal in
lib/Search.js: it targets/collections/{name}/documents/search, while the server supports the canonical/collections/{name}/searchroute in addition to legacy compatibility handling. That makes the Node client more brittle as the API evolves and weakens the value of having an SDK in the first place.For a high-performance search engine, SDK parity matters beyond developer convenience. Missing operational endpoints prevent Node services from observing cluster health, metrics, and storage state without dropping to raw HTTP calls, and missing search-management endpoints makes automation around synonyms, overrides, and stopwords inconsistent across languages.
Proposed Implementation
/collections/{name}/searchand/collections/{name}/vector_search, while preserving backward compatibility where needed.Impact
This would turn the Node client from a partial wrapper into a reliable production SDK. The immediate benefits are better API correctness, fewer raw HTTP escape hatches in Node services, lower maintenance cost from route drift, and stronger cross-language consistency. It also improves operability for Node-based ingestion/search services by exposing metrics and storage endpoints directly through the client, which is a meaningful reliability gain for a high-performance RocksDB-backed search engine.