Skip to main content

Quick Start: Basic Operations

This guide walks through the core workflow: verify server health, create a collection, add documents, and run basic searches.

Time to complete: ~4 minutes
Prerequisites: hlquery installed and running
Goal: Create your first searchable collection and perform searches

Prerequisites​

Before starting, ensure you have:

  • hlquery server installed (see Installation Guide)
  • Server running on http://localhost:9200 (default)
  • HTTP client available (curl, Postman, or browser)
  • Optional: API key if authentication is enabled

Tip: If hlquery is not installed yet, complete the Installation Guide first.

Alternative: Use the Web Interface (hanalyzer)​

Prefer a graphical interface? hlquery includes hanalyzer, a modern web UI for managing your server:

# Navigate to hanalyzer directory
cd hanalyzer

# Install dependencies (first time only)
npm install

# Start the web interface
npm run dev

Then open http://localhost:5173 in your browser to use the graphical interface for all the operations below.

See the Web Interface Guide for detailed instructions.

Note: The rest of this guide uses curl commands, but all operations can be performed via hanalyzer's UI.

Step 1: Verify Server is Running (30 seconds)​

Let's confirm the server is up and healthy:

# Health check
curl http://localhost:9200/health

Expected response:

{
  "status": "healthy",
  "engine": "hlquery",
  "version": "1.0"
}

Success indicator: You should see "status": "healthy" in the response.

If it fails: Check that the server is running with ps aux | grep hlquery or restart it.

Alternative: Check Server Info​

# Get detailed server information
curl http://localhost:9200/

# Get server statistics
curl http://localhost:9200/stats

What you'll see: Server stats including uptime, memory usage, and collection counts.

Step 2: Create Your First Collection (1 minute)​

A collection is like a database table - it defines the schema for your documents.

Let's create a collection for an e-commerce product catalog:

curl -X POST http://localhost:9200/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "fields": [
      {"name": "title", "type": "string", "facet": false},
      {"name": "description", "type": "string", "facet": false},
      {"name": "price", "type": "float", "facet": true},
      {"name": "category", "type": "string", "facet": true},
      {"name": "in_stock", "type": "bool", "facet": true}
    ],
    "default_sorting_field": "price"
  }'

Expected response:

{
  "message": "Collection created successfully",
  "name": "products",
  "num_documents": 0
}

Understanding Collection Schema​

Field Types:

  • string: Text fields (searchable)
  • float: Decimal numbers
  • int32: Integer numbers
  • bool: True/false values
  • float[]: Vector embeddings (for semantic search)

Field Options:

  • facet: true: Enable faceting on this field (for filtering)
  • optional: true: Field can be omitted in documents
  • index: true: Field is searchable (default for string fields)

Verify Collection Created​

# List all collections
curl http://localhost:9200/collections

# Get collection details
curl http://localhost:9200/collections/products

Step 3: Add Documents (2 minutes)​

Now let's populate our collection with some product data:

Add First Document​

curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product1",
    "title": "Laptop Computer",
    "description": "High-performance laptop with 16GB RAM and 1TB SSD storage. Perfect for developers and content creators.",
    "price": 1299.99,
    "category": "Electronics",
    "in_stock": true
  }'

Expected response:

{
  "id": "product1",
  "title": "Laptop Computer",
  "price": 1299.99,
  "created_at": "2024-11-28T10:00:00Z"
}

Add More Documents​

# Add a wireless mouse
curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product2",
    "title": "Wireless Mouse",
    "description": "Ergonomic wireless mouse with long battery life and precision tracking",
    "price": 29.99,
    "category": "Accessories",
    "in_stock": true
  }'

# Add a mechanical keyboard
curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product3",
    "title": "Mechanical Keyboard",
    "description": "RGB mechanical keyboard with Cherry MX switches and programmable keys",
    "price": 149.99,
    "category": "Accessories",
    "in_stock": false
  }'

# Add a monitor
curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product4",
    "title": "4K Monitor",
    "description": "27-inch 4K UHD monitor with HDR support and 144Hz refresh rate",
    "price": 449.99,
    "category": "Electronics",
    "in_stock": true
  }'

# Add a laptop stand
curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product5",
    "title": "Adjustable Laptop Stand",
    "description": "Ergonomic aluminum laptop stand with adjustable height and angle",
    "price": 39.99,
    "category": "Accessories",
    "in_stock": true
  }'

Verify Documents Added​

# List all documents
curl http://localhost:9200/collections/products/documents

# Get specific document
curl http://localhost:9200/collections/products/documents/product1

Step 4: Search Documents (1 minute)​

Now for the fun part - let's search! hlquery's adaptive BM25+ algorithm automatically adjusts to your queries for optimal relevance.

# Search for "laptop"
curl "http://localhost:9200/collections/products/documents/search?q=laptop"

Expected response:

{
  "found": 2,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop with 16GB RAM...",
        "price": 1299.99,
        "category": "Electronics"
      },
      "text_match": 0.9845
    },
    {
      "document": {
        "id": "product5",
        "title": "Adjustable Laptop Stand",
        "description": "Ergonomic aluminum laptop stand...",
        "price": 39.99,
        "category": "Accessories"
      },
      "text_match": 0.7234
    }
  ],
  "page": 1,
  "search_time_ms": 2.3
}

More Search Examples​

# Search for "mechanical keyboard"
curl "http://localhost:9200/collections/products/documents/search?q=mechanical%20keyboard"

# Search for "monitor" with highlighting
curl "http://localhost:9200/collections/products/documents/search?q=monitor&highlight=true&highlight_fields=title,description"

# Search in specific fields only
curl "http://localhost:9200/collections/products/documents/search?q=ergonomic&query_by=title,description"

# Advanced query types
# Field-specific search
curl "http://localhost:9200/collections/products/documents/search?q=title:laptop"

# Range query
curl "http://localhost:9200/collections/products/documents/search?q=price:[100 TO 500]"

# Fuzzy search (tolerates typos)
curl "http://localhost:9200/collections/products/documents/search?q=laptop~2"

# Wildcard search
curl "http://localhost:9200/collections/products/documents/search?q=laptop*"

# Boost term importance
curl "http://localhost:9200/collections/products/documents/search?q=laptop^2.0 computer"

# NOT operator
curl "http://localhost:9200/collections/products/documents/search?q=!apple"

# Combined queries
curl "http://localhost:9200/collections/products/documents/search?q=title:laptop AND price:[100 TO 500]"

Understanding Search Results​

Each search result includes:

  • document: The full document object
  • text_match: Relevance score (0-1, higher is better)
  • highlights: Matching terms highlighted with <mark> tags (if enabled)
  • search_time_ms: How long the search took

Congratulations!​

You've successfully:

  • Verified server is running
  • Created a collection with schema
  • Added multiple documents
  • Performed keyword searches

Next Steps​

Continue with: