Skip to main content

Quick Start: Advanced Features

This guide explains advanced query features: filtering, sorting, faceting, highlighting, and document management.

Time to complete: ~3 minutes
Prerequisites: Completed Basic Operations

Step 5: Advanced Search Features (1 minute)​

hlquery supports advanced search features out of the box. The examples below show common patterns you can use immediately.

Search with Filtering​

Find only products in the "Electronics" category:

curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=category:Electronics"

Find products under $100:

curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=price:<100"

Find in-stock electronics:

curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=category:Electronics%26%26in_stock:true"

Filter operators: = (equals), != (not equals), >, <, >=, <=, ~ (contains)

Search with Sorting​

Sort by price (lowest first):

curl "http://localhost:9200/collections/products/documents/search?q=*&sort_by=price:asc"

Sort by price (highest first):

curl "http://localhost:9200/collections/products/documents/search?q=*&sort_by=price:desc"

Multi-field sorting (category, then price):

curl "http://localhost:9200/collections/products/documents/search?q=*&sort_by=category:asc,price:desc"

Search with Facets​

Get category distribution:

curl "http://localhost:9200/collections/products/documents/search?q=*&facet_by=category"

Response includes facets:

{
  "hits": [...],
  "facets": {
    "category": [
      {"value": "Electronics", "count": 2},
      {"value": "Accessories", "count": 3}
    ]
  }
}

Get multiple facets:

curl "http://localhost:9200/collections/products/documents/search?q=*&facet_by=category,in_stock"

Search with Highlighting​

Highlight matching terms in results:

curl "http://localhost:9200/collections/products/documents/search?q=laptop&highlight=true&highlight_fields=title,description"

Response with highlights:

{
  "hits": [
    {
      "document": {...},
      "highlights": {
        "title": "<mark>Laptop</mark> Computer",
        "description": "High-performance <mark>laptop</mark> with 16GB RAM..."
      }
    }
  ]
}

Combining Features​

Search for laptops under $1500, sorted by price, with category facets:

curl "http://localhost:9200/collections/products/documents/search?q=laptop&filter_by=price:<1500&sort_by=price:asc&facet_by=category&highlight=true"

Step 6: Using the CLI Tool (Optional)​

hlquery includes a powerful command-line interface for administration and testing:

Check Server Status​

# Quick health check
./run/hlquery cli health

# Get detailed statistics
./run/hlquery cli stats

# Show uptime
./run/hlquery cli uptime

Manage Collections​

# List all collections
./run/hlquery cli cols

# Create collection via CLI
./run/hlquery cli create products title description price category

# Delete collection
./run/hlquery cli delete products

Search Using CLI​

# Basic search
./run/hlquery cli search products "laptop"

# Search with filters
./run/hlquery cli search products "laptop" 20 0 "price:asc" --highlight

# Get help
./run/hlquery cli help

CLI Benefits:

  • Quick testing without writing curl commands
  • Scripting and automation
  • Pretty-printed JSON output
  • Built-in validation and error messages

Use stats for the CLI monitoring view. If you need the JSON metrics endpoint directly, call curl http://localhost:9200/metrics.

Step 7: View Collections​

List all collections:

curl http://localhost:9200/collections

Get details about a specific collection:

curl http://localhost:9200/collections/products

Step 8: Update and Delete Documents​

Update a Document​

curl -X PUT http://localhost:9200/collections/products/documents/product1 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Laptop Computer - Updated",
    "description": "High-performance laptop with 32GB RAM and 1TB SSD storage",
    "price": 1499.99,
    "category": "Electronics"
  }'

Delete a Document​

curl -X DELETE http://localhost:9200/collections/products/documents/product1

Congratulations!​

You've successfully:

  • Used advanced search features (filtering, sorting, faceting, highlighting)
  • Learned about the CLI tool
  • Managed collections and documents

Next Steps​

Beginner Path (Learn the Basics)​

  1. Explore the Web Interface: Visual tool for testing

    • Open http://localhost:9200 in your browser
    • Test queries interactively
    • View collection schemas

  2. Try More Examples: Examples Guide

    • Real-world use cases
    • Complete code samples
    • Best practices

  3. Learn the API: API Overview

    • All available endpoints
    • Request/response formats
    • Authentication

Intermediate Path (Add Features)​

  1. Set up Synonyms: Synonyms Guide

    # Make "laptop" and "notebook" equivalent
    curl -X POST http://localhost:9200/collections/products/synonyms/laptop-syn \
      -H "Content-Type: application/json" \
      -d '{"root": "laptop", "synonyms": ["notebook", "portable computer"]}'

  2. Configure Stopwords: Stopwords Guide

    # Remove common words from indexing
    curl -X POST http://localhost:9200/collections/products/stopwords \
      -H "Content-Type: application/json" \
      -d '{"word": "the"}'

  3. Manage API Keys: API Keys Guide

    # Create a search-only key for 'products'
    curl -X POST http://localhost:9200/keys \
      -H "X-API-Key: admin-token" \
      -d '{"description": "Web Search", "collections": ["products"], "actions": ["search"]}'

  4. Try Vector Search: Vector Search Guide

    # Semantic similarity search
    curl -X POST http://localhost:9200/collections/products/vector_search \
      -H "Content-Type: application/json" \
      -d '{"vector_query": [0.1, 0.2, 0.3], "limit": 10}'

Advanced Path (Production Deployment)​

  1. Configure for Production: Configuration Guide

    • Performance tuning
    • Security settings
    • Resource limits

  2. Set up Monitoring: System Endpoints

    • JSON metrics (minimal): GET /metrics
    • Health checks: GET /health
    • Performance stats: GET /stats

  3. Use Client Libraries: Client Overview

    • Node.js: Type-safe client
    • Python: Async support
    • PHP: PSR-compliant

  4. Deploy as Daemon: Installation Guide

    # Start as background daemon
    ./hlquery start

    # Check status
    ./hlquery status

    # Stop gracefully
    ./hlquery stop

Learn More​