Skip to main content

Examples

This section is a copy-and-paste cookbook for hlquery. It starts with a complete local workflow, then branches into focused recipes for search, data management, relevance, security, operations, and client libraries.

All HTTP examples assume a server at http://localhost:9200. Set these shell variables once if your server or credentials differ:

export HLQUERY_URL="http://localhost:9200"
export HLQUERY_API_KEY=""

When authentication is enabled, add -H "X-API-Key: $HLQUERY_API_KEY" to each curl command. Examples use POST bodies for complex searches so shell quoting does not alter operators such as &&.

Choose a recipe​

GoalGuide
Create, read, update, import, export, and delete dataData management
Search text, filters, facets, geo points, many collections, and vectorsSearch recipes
Tune synonyms, stopwords, overrides, presets, and rankingRelevance recipes
Add scoped keys, health checks, diagnostics, and error handlingSecurity and operations
Run the bundled SDK examples in nine languagesClient examples

Five-minute end-to-end example​

1. Check the server​

curl --fail-with-body "$HLQUERY_URL/health"

2. Create a collection​

curl --fail-with-body -X POST "$HLQUERY_URL/collections" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_products",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "description", "type": "string"},
      {"name": "category", "type": "string"},
      {"name": "price", "type": "float"},
      {"name": "in_stock", "type": "bool"},
      {"name": "tags", "type": "string[]"}
    ],
    "default_sorting_field": "price"
  }'

3. Import several documents​

curl --fail-with-body -X POST \
  "$HLQUERY_URL/collections/example_products/documents/import" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "keyboard-1",
      "title": "Compact Wireless Keyboard",
      "description": "Bluetooth keyboard for travel and office use",
      "category": "keyboards",
      "price": 49.99,
      "in_stock": true,
      "tags": ["wireless", "bluetooth"]
    },
    {
      "id": "keyboard-2",
      "title": "Mechanical Gaming Keyboard",
      "description": "Wired keyboard with tactile switches",
      "category": "keyboards",
      "price": 109.00,
      "in_stock": true,
      "tags": ["gaming", "mechanical"]
    },
    {
      "id": "mouse-1",
      "title": "Wireless Travel Mouse",
      "description": "Small rechargeable mouse",
      "category": "mice",
      "price": 29.50,
      "in_stock": false,
      "tags": ["wireless", "travel"]
    }
  ]'

4. Search, filter, sort, and facet​

curl --fail-with-body -X POST \
  "$HLQUERY_URL/collections/example_products/documents/search" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "keyboard",
    "query_by": "title,description,tags",
    "filter_by": "in_stock:true && price:<100",
    "sort_by": "price:asc",
    "facet_by": "category",
    "highlight_full_fields": "title,description",
    "limit": 10
  }'

Look at found for the total and iterate over hits. Each hit contains a document and its relevance score; facet counts are returned separately.

5. Update and fetch a document​

curl --fail-with-body -X PUT \
  "$HLQUERY_URL/collections/example_products/documents/keyboard-1" \
  -H "Content-Type: application/json" \
  -d '{"price": 44.99}'

curl --fail-with-body \
  "$HLQUERY_URL/collections/example_products/documents/keyboard-1"

6. Clean up​

The following command permanently removes the example collection:

curl --fail-with-body -X DELETE \
  "$HLQUERY_URL/collections/example_products"

Useful reference pages​