Skip to main content

Python Client Examples

Comprehensive examples for the hlquery Python client library.

Example Files​

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

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

Running Examples​

Main Example File​

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

# Run all examples (default)
python example.py

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

Individual Example Files​

# Basic usage
python examples/basic_usage.py

# Collections
python examples/collections.py

# Documents
python examples/documents.py

# Search
python examples/search.py

Basic Operations​

Initialize Client​

from lib import Client

# Basic initialization
client = Client('http://localhost:9200')

# With authentication
client = Client('http://localhost:9200', {
    'token': 'your_token_here',
    'auth_method': 'bearer'
})

Health Check​

def check_health():
    health = client.health()
    if health.is_success():
        body = health.get_body()
        print(f"Status: {body.get('status')}")

Collection Management​

Create Collection​

def create_collection():
    schema = {
        'fields': [
            {'name': 'title', 'type': 'string'},
            {'name': 'price', 'type': 'float'},
            {'name': 'category', 'type': 'string'}
        ]
    }
    result = client.create_collection('products', schema)
    if result.is_success():
        print('Collection created')

List Collections​

def list_collections():
    result = client.list_collections(0, 10)
    if result.is_success():
        body = result.get_body()
        for col in body.get('collections', []):
            print(f"- {col.get('name')}")

Document Operations​

Add Document​

def add_product():
    product = {
        'id': 'prod_001',
        'title': 'Laptop',
        'price': 999.99,
        'category': 'electronics'
    }
    result = client.add_document('products', product)
    if result.is_success():
        print('Product added')

Bulk Import​

def import_products():
    products = [
        {'id': 'prod_001', 'title': 'Laptop', 'price': 999.99},
        {'id': 'prod_002', 'title': 'Mouse', 'price': 29.99}
    ]
    result = client.import_documents('products', products)
    if result.is_success():
        print(f"Imported {len(products)} products")

Search Examples​

def search_products(query):
    result = client.search('products', {
        'q': query,
        'query_by': 'title,description',
        'limit': 10
    })
    if result.is_success():
        body = result.get_body()
        for hit in body.get('hits', []):
            print(f"- {hit['document']['title']}")

Search with Filters​

def search_with_filters():
    result = client.search('products', {
        'q': 'laptop',
        'filter_by': 'price:>500 && in_stock:true',
        'sort_by': 'price:asc'
    })
    if result.is_success():
        print(f"Found {result.get_body().get('found')} results")

Error Handling​

from lib.exceptions import HlqueryException, AuthenticationException

try:
    result = client.create_collection('test', schema)
except AuthenticationException as e:
    print(f"Auth failed: {e}")
except HlqueryException as e:
    print(f"Error: {e}")

Status Command​

The status command provides concise server information:

python example.py 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/python/example.py - Full example file with all features