API Clients Overview

hlquery keeps client libraries and examples for C++, Go, Java, Node.js, Perl, PHP, Python, Ruby, Rust, and TypeScript. These clients follow the same HTTP route contract where practical, so request and response behavior stays consistent across languages.

Available Clients

• C++ Client - Native C++ client and examples
• Go Client - Go client package and examples
• Java Client - Java client resources
• Node.js Client - JavaScript client with async support
• Perl Client - Perl wrapper with service objects
• PHP Client - PHP client using cURL and JSON
• Python Client - Python client with optional PDF helpers
• Ruby Client - Ruby client for scripts and applications
• Rust Client - Async Rust client
• TypeScript Client - Typed TypeScript client

Common Features

• Consistent API design: collections, documents, search, SQL, aliases, synonyms, stopwords, overrides, and system calls use similar shapes where supported
• Authentication support: bearer token and X-API-Key flows
• Validation: client-side parameter checks before sending requests in the fuller clients
• Error handling: structured response wrappers and exception types
• Raw requests: most maintained clients expose a lower-level request helper for new routes and module APIs
• Operational APIs: maintained clients expose cache, active configuration-file, metrics-history, and debug-counter inspection where the server supports them
• Search presets: all bundled clients expose list/get/create/update/delete helpers for /presets

Quick Comparison

Client	Location	Notes
C++	etc/api/cpp	Native client headers, source, and examples
Go	etc/api/go	Go module with collection, document, search, SQL, and system helpers
Java	etc/api/java	Java client resources and tests
Node.js	etc/api/node	Async JavaScript client, optional PDF parser, route conformance tests
Perl	etc/api/perl	Service objects and parsed Hlquery::Response values
PHP	etc/api/php	cURL-backed client with service classes
Python	etc/api/python	Standard-library client, optional PDF parser
Ruby	etc/api/ruby	Ruby client and examples
Rust	etc/api/rust	Async Rust client using Tokio
TypeScript	etc/api/typescript	Typed client source and generated dist output

Installation

Use the language-specific README for exact installation commands. Some clients are package-ready, while others are local source distributions in this repository.

Basic Usage

const client = new Client('http://localhost:9200');
const health = await client.health();

client = Client('http://localhost:9200')
health = client.health()

$client = new Client('http://localhost:9200');
$health = $client->health();

Search Across Collections

All maintained clients support /search, which produces one merged and globally paginated result set. Omit collections for every accessible collection, or provide a collection list to restrict the merge. Each hit includes document._collection.

Client	All-collection helper
C++	searchAll (globalSearch remains supported)
Go	SearchAll / SearchAllGET (Global / GlobalGET)
Java	searchAll (globalSearch)
Node.js	searchAll (globalSearch)
Perl	SearchAll / search_all (GlobalSearch)
PHP	searchAll (globalSearch)
Python	search_all (global_search)
Ruby	search_all / searchAll (global_search)
Rust	search_all (global_search)
TypeScript	searchAll (globalSearch)

const results = await client.searchAll({
  q: 'research',
  collections: 'universities,science',
  limit: 20,
  offset: 0
});

See Global Search for GET/POST collection-list shapes, pagination guarantees, response metadata, distributed behavior, and limits.

Search Presets and Diagnostics

Preset names are URL-encoded by each client. Use the language's presets service (or the corresponding direct Java methods) to manage reusable search parameter objects. System services also provide wrappers for GET /cache, GET /config-files, GET /metrics/history, and GET /debug/counters where applicable.

Testing

Test coverage is split between shared endpoint tests and client-specific smoke or conformance tests:

• Shared endpoint tests live in etc/api/tests
• Client-specific tests live under each client directory where available
• Node.js includes a route conformance test against the current server route contract

Next Steps

• Start with API Overview for route behavior.
• Use the client pages in this section for language-specific setup and examples.
• Check etc/api/README.md in the repository for the full client directory map.