Perl client resources for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Perl API?

The Perl API directory contains the hlquery Perl client resources, packaging metadata, runnable examples, and usage notes. It is the Perl entry point for talking to hlquery without building raw HTTP requests around LWP::UserAgent by hand.

Why use it?

Use the Perl API when you want hlquery integration to feel like part of your application instead of a stack of hand-written LWP::UserAgent calls and JSON handling. It cuts down repetitive transport code, keeps authentication and request behavior consistent, and gives you a cleaner path into collections, documents, search, and admin operations from normal Perl code.

Install

Install dependencies:

$ cpanm --installdeps .

Or install the runtime modules directly:

$ cpanm LWP::UserAgent JSON JSON::MaybeXS URI URI::Escape Digest::MD5 Mojolicious Promises

When loading from a local checkout:

use lib '/path/to/hlquery/etc/api/perl/lib';
use Hlquery::Client;

Quick Start

use Hlquery::Client;

my $base_url = $ENV{HLQ_BASE_URL}
    // $ENV{HLQUERY_BASE_URL}
    // 'http://localhost:9200';

my $client = Hlquery::Client->new($base_url);

my $health = $client->Health();
print "Health status: " . $health->GetStatusCode() . "\n";

my $collections = $client->ListCollections(0, 10);
if ($collections->IsSuccess()) {
    my $body = $collections->GetBody();
    print "Collections: " . scalar(@{$body->{collections} || []}) . "\n";
}

Auth

my $client = Hlquery::Client->new('http://localhost:9200', {
    token => 'your_token_here',
    auth_method => 'bearer',
});

$client->SetAuthToken('your_token_here', 'bearer');
$client->SetAuthToken('your_api_key_here', 'api-key');

SAM

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

my $sam = $client->SAM();

my $status = $sam->Status('music');
my $history = $sam->History('music', 5);
my $results = $sam->Search('music', 'queen of pop', { limit => 10 });

SQL

my $sql = $client->SQL();

my $rows = $sql->Query('SHOW COLLECTIONS;');
my $exec = $sql->Exec("INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');");

my $products = $sql->Search('products',
    'SELECT id, title FROM products ORDER BY id DESC LIMIT 3;',
    { highlight => 0 }
);

Reduce Text Example

Use the same raw request path for custom module routes:

my $module_response = $client->ExecuteRequest('GET', '/modules/<name>/<route>', undef, {
    q => 'example query',
});

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.