A modular Node.js client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Node.js API?

The hlquery Node.js API is the official Node.js client for hlquery. It wraps the REST interface in a modular service-style client with helpers for collections, documents, search, SQL, and SAM.

It is a good fit for backend services, scripts, dashboards, and apps that want hlquery integration without repeating request code.

Why use it?

Use the Node.js client when you want hlquery calls to read like regular application code. The client is organized around familiar modules such as client.collections(), client.documents(), and client.sam(), with Redis-style dynamic route helpers for module APIs and custom endpoints.

It also keeps the repetitive parts in one place: authentication, request parameters, endpoint paths, and parsed responses are handled consistently across the client. Common hlquery workflows are covered by default, while raw request access is still available when you need a custom route.

Install

$ npm install hlquery-node-client

For local development inside this repository:

const Client = require('./lib/Client');

Quick Start

const Client = require('hlquery-node-client');

const client = new Client(process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200', {
  token: process.env.HLQ_TOKEN,
  auth_method: 'bearer'
});

const health = await client.system().health();

/* Print the HTTP status code from the health response. */
console.log('status:', health.getStatusCode());

const collections = await client.collections().list(0, 10);

/* Print the collection list response body. */
console.log(collections.body);

Auth

const client = new Client('http://localhost:9200', {
  token: 'your_token_here',
  auth_method: 'bearer'
});

client.setAuthToken('your_token_here', 'bearer');
client.setAuthToken('your_api_key_here', 'api-key');

Operational routes

The client includes wrappers for the common server and cluster routes used by dashboards, scripts, and maintenance jobs:

const status = await client.status();
const health = await client.health();
const etc = await client.etc();

const links = await client.links();
const ping = await client.linksPing();
const connect = await client.linksConnect('http://node-b:9200');
const disconnect = await client.linksDisconnect('http://node-b:9200');

const flush = await client.flush();

Routes that do not have a dedicated wrapper can still be called through executeRequest():

const response = await client.executeRequest('GET', '/modules/<name>/<route>', null, {
  q: 'example query'
});

console.log(response.body);

For module routes and custom endpoints, the client also supports a Redis-style fluent API:

const result = await client.module('<name>').route('<route>').get({
  q: 'example query'
});

console.log(result.body);

const indexed = await client.module('<name>').route('index').post({
  id: 'doc_1',
  title: 'Example'
});

const modules = await client.modules().list();
const syntax = await client.modules().syntax('<name>');
const raw = await client.route('etc').get();

console.log(indexed.body);
console.log(modules.body);
console.log(syntax.body);
console.log(raw.body);

SAM

SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.

const sam = client.sam();

const status = await sam.status('books');
const history = await sam.history('books', 5);
const results = await sam.search('books', 'distributed systems', {
  limit: 10
});

/* Print the SAM status response body. */
console.log(status.body);
/* Print the SAM search history response body. */
console.log(history.body);
/* Print the SAM search results response body. */
console.log(results.body);

SQL

const rows = await client.sql('SHOW COLLECTIONS;');
const execResult = await client.execSql(
  "INSERT INTO books (id, title) VALUES ('book_4', 'Inserted via SQL');"
);
const books = await client.sqlSearch(
  'books',
  'SELECT id, title FROM books ORDER BY title ASC LIMIT 3;'
);

/* Print the SQL query response body. */
console.log(rows.body);
/* Print the SQL execution response body. */
console.log(execResult.body);
/* Print the collection SQL search response body. */
console.log(books.body);

Contributing

We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.

How to Contribute

• Check existing issues or create new ones
• Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
• Test and report bugs
• Improve documentation

Community

• 📖 Documentation
• 🐦 X (Twitter)
• 📦 GitHub

License

hlquery is licensed under the BSD 3-Clause License.