Skip to main content

Perl Client Examples

Comprehensive examples for the hlquery Perl client library.

Repositories​

Example Files​

The Perl client includes several example files demonstrating different aspects of the API:

  • basic_usage.pl - Basic client initialization and simple operations
  • collections.pl - Collection management operations
  • documents.pl - Document CRUD operations
  • search.pl - Various search patterns and options

Running Examples​

Main Example File​

The main example file (example.pl) provides a comprehensive demonstration of all API features:

# From the hlquery repo root
cd etc/api/perl

# Run all examples (default)
perl example.pl

# Run specific command
perl example.pl cols          # List collections
perl example.pl docs my_collection  # List documents in collection
perl example.pl status         # Show server health and status
perl example.pl help          # Show help message

Individual Example Files​

# From the hlquery repo root
cd etc/api/perl

# Basic usage
perl examples/basic_usage.pl

# Collections
perl examples/collections.pl

# Documents
perl examples/documents.pl

# Search
perl examples/search.pl

Basic Operations​

Initialize Client​

use Hlquery::Client;

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

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

Health Check​

my $health = $client->health();
if ($health->is_success()) {
    my $body = $health->get_body();
    print "Status: " . $body->{status} . "\n";
}

Collection Management​

Create Collection​

my $schema = {
    fields => [
        {name => 'title', type => 'string'},
        {name => 'price', type => 'float'}
    ]
};
my $result = $client->create_collection('products', $schema);
if ($result->is_success()) {
    print "Collection created\n";
}

Document Operations​

Add Document​

my $product = {
    id => 'prod_001',
    title => 'Laptop',
    price => 999.99
};
my $result = $client->add_document('products', $product);

Bulk Import​

my $products = [
    {id => 'prod_001', title => 'Laptop', price => 999.99},
    {id => 'prod_002', title => 'Mouse', price => 29.99}
];
my $result = $client->import_documents('products', $products);

Search Examples​

my $result = $client->search('products', {
    q => 'laptop',
    query_by => 'title',
    limit => 10
});
if ($result->is_success()) {
    my $body = $result->get_body();
    foreach my $hit (@{$body->{hits}}) {
        print $hit->{document}->{title} . "\n";
    }
}

Error Handling​

use Hlquery::HlqueryException;
use Hlquery::AuthenticationException;

eval {
    my $result = $client->create_collection('test', $schema);
};
if ($@) {
    if ($@->isa('Hlquery::AuthenticationException')) {
        print "Auth failed: " . $@->message() . "\n";
    } else {
        print "Error: " . $@->message() . "\n";
    }
}

Status Command​

The status command provides concise server information:

perl example.pl status

This will show:

  • Health status
  • Server statistics
  • Protocol codes
  • Server status
  • Root status response

Next Steps​

  • API Reference - Complete API documentation
  • Tests - Comprehensive test suite
  • Main Example: etc/api/perl/example.pl - Full example file with all features