Skip to main content

Search API

Search is the core hlquery API surface. This page covers lexical queries, distributed execution, filtering, sorting, faceting, and related request controls.

Implementation note: /collections/{name}/documents/search handles lexical search and can also activate vector/hybrid logic when vector fields are present (for example vector_query, vector, vector_queries, embedding, plus optional hybrid_alpha). /collections/{name}/vector_search remains the dedicated endpoint for full vector request shapes.

hlquery also exposes a direct SQL-style route.

Endpoint: GET /sql or POST /sql

The collection is resolved from the SQL FROM clause, so no collection path segment is required. POST bodies also accept exec as an alias for SQL execution payloads, which is useful for mutating statements. sql and exec are equivalent on the HTTP route; exec is mainly a clearer name for statements like INSERT or DELETE.

Example Requests​

curl "http://localhost:9200/sql?sql=SELECT%20*%20FROM%20products%20LIMIT%203%3B"
curl "http://localhost:9200/sql?sql=SELECT%20COUNT(*)%20AS%20total_docs%20FROM%20products%3B"
curl "http://localhost:9200/sql?sql=SELECT%20category%2C%20AVG(score)%20AS%20avg_score%20FROM%20products%20GROUP%20BY%20category%20ORDER%20BY%20avg_score%20DESC%3B"

POST Form​

curl -X POST "http://localhost:9200/sql" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT COUNT(*) AS total_docs FROM products;"}'
curl -X POST "http://localhost:9200/sql" \
  -H "Content-Type: application/json" \
  -d '{"exec":"INSERT INTO products (id, title, price) VALUES (\"prod_10\", \"Keyboard\", 49.99);"}'

Notes​

  • Use sql or exec in POST JSON bodies.
  • exec is helpful when the client separates read-style and write-style SQL runs.
  • The talk REPL maps sql: and exec: to this same /sql endpoint.

SQL Result Shapes​

  • SELECT * ... returns hit-style results under hits.
  • Aggregate-only queries return aggregations.
  • Grouped aggregate queries return row-oriented results under rows.
  • INSERT ... VALUES (...) returns a document-create acknowledgement with message and id.

Run a text query over one collection.

Endpoint: GET /collections/{name}/documents/search or POST /collections/{name}/documents/search

Query Parameters​

ParameterTypeRequiredDefaultMaxDescription
qstringYes--Search query string
query_bystringNoall fields-Comma-separated list of fields to search
limitintegerNo10250Number of results to return
offsetintegerNo0-Number of results to skip
include_created_atbooleanNofalse-If true, includes created_at field (ISO 8601 format) for each hit
distributedstringNoserver default-Per-request distributed override: on, off, local, remote, force

Example Request​

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

Example Response​

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop",
        "price": 1299.99
      },
      "score": 1.0945
    }
  ],
  "page": 1,
  "request_params": {
    "q": "laptop",
    "query_by": "title,description"
  }
}

Use the distributed query parameter to force execution across configured cluster links. The same query syntax is supported in both local and distributed modes.

Examples:

# Force distributed search
curl "http://localhost:9200/collections/products/documents/search?q=\"gaming laptop\"&distributed=on"

# Force local-only search
curl "http://localhost:9200/collections/products/documents/search?q=laptop&distributed=off"

Responses include an execution hint header: X-HLQ-Execution-Mode with values like local, distributed, or distributed-global.

Search responses do not include inline suggestion payloads. Use /collections/{name}/documents/maybe when you need spelling or fallback suggestions for a query.

Search multiple collections and receive one globally ranked, paginated result set.

Endpoint: GET /search or POST /search

Omit collection/collections to search every accessible collection. Use collection=*, collection=all, or collections:["*"] as explicit all-collection aliases. To restrict the search, pass a comma-separated collections value with GET or a string array with POST.

Unlike /multi_search, which returns one independent response per request, /search merges hits from all target collections, sorts the merged set, and then applies pagination. Every returned document contains _collection, identifying its source.

GET examples​

# Every accessible collection
curl "http://localhost:9200/search?q=research&query_by=title,content&limit=20&offset=0"

# Only selected collections
curl "http://localhost:9200/search?q=research&query_by=title,content&collections=universities,science&limit=20"

# Explicit all-collection alias
curl "http://localhost:9200/search?q=technology&collection=all&limit=10"

POST example​

curl -X POST http://localhost:9200/search \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["universities", "science"],
    "q": "research",
    "query_by": "title,content",
    "filter_by": "status:published",
    "sort_by": "rank:desc",
    "facet_by": "category",
    "limit": 20,
    "offset": 0
  }'

Pagination and totals​

  • limit/per_page is the size of the merged page, not a per-collection limit.
  • offset is applied after all target collections have been merged and globally sorted.
  • found and out_of report totals across all searched collections, before pagination.
  • offset + limit (or offset + per_page) must not exceed 10000.
  • The response includes offset, searched_collection_count, and searched_collections.
  • A request whose selected collection names do not exist returns 404.

Example response shape:

{
  "found": 42,
  "out_of": 42,
  "offset": 0,
  "per_page": 20,
  "searched_collection_count": 2,
  "searched_collections": ["universities", "science"],
  "hits": [
    {
      "document": {
        "id": "university-harvard",
        "_collection": "universities",
        "title": "Harvard University"
      },
      "score": 8.25
    }
  ]
}

Cross-collection behavior​

  • query_by, filters, sort fields, facets, highlights, and field projection use the same syntax as collection search. Collections without a referenced optional field simply do not contribute matches/counts for that field.
  • Without sort_by, candidates from every collection are merged by effective search score; collection-specific default sort fields do not replace global relevance ordering.
  • Facet counts are added across the searched collections before page slicing, then sorted by global count and limited by max_facet_values.
  • API-key collection scopes are evaluated for every target collection. The response lists only collections that were actually searched.
  • Add distributed=on&distributed_collections=true to include collection names advertised by configured links. X-HLQ-Execution-Mode reports global or distributed-global.

CLI equivalent​

hlquery-cli search --all "research" 20 0 --json
hlquery-cli search --all "research" 20 0 --collections=universities,science --json

Maybe Suggestions​

Use the maybe endpoint when the query is sparse, misspelled, or likely needs a fallback suggestion.

Endpoint: GET /collections/{name}/documents/maybe or POST /collections/{name}/documents/maybe

curl "http://localhost:9200/collections/products/documents/maybe?q=lapotp&limit=5"
curl -X POST http://localhost:9200/collections/products/documents/maybe \
  -H "Content-Type: application/json" \
  -d '{"q":"lapotp","limit":5}'

Multi-search supports distributed execution when distributed=on is set on the request URL.

curl -X POST "http://localhost:9200/multi_search?distributed=on" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"collection": "products", "q": "laptop", "query_by": "title,description"},
      {"collection": "articles", "q": "hardware", "query_by": "title,content"}
    ]
  }'

Advanced Search (POST)​

For complex queries, use POST with a JSON body. This is easier to format and read.

Endpoint: POST /collections/{name}/documents/search

Request Body​

{
  "q": "search query",
  "query_by": "field1,field2",
  "filter_by": "field:value",
  "sort_by": "field:asc",
  "facet_by": "field1,field2",
  "limit": 10,
  "offset": 0,
  "include_created_at": true
}

Example Request​

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "filter_by": "price:>1000",
    "sort_by": "price:asc",
    "limit": 10
  }'

Search Parameters​

Query String (q)​

The search query. Supports multiple advanced query types. Distributed search uses the same query parser as local search (quoted phrases, wildcards, boolean operators, etc. work in both).

TypeSyntaxExampleDescription
Simple termstermlaptopBasic keyword search
Phrases"phrase""laptop computer"Exact phrase match
NOT!term or NOT term!apple or NOT appleExclude documents matching term
FIELDfield:valuetitle:laptop or price:100Search specific field
RANGEfield:[min TO max] or field:{min TO max}price:[100 TO 500] or price:{100 TO 500}Range query (inclusive/exclusive)
WILDCARDterm*, *term, term*termlaptop*, *laptop, lap*topWildcard pattern matching
REGEXfield:/pattern/title:/laptop.*computer/Regular expression matching
FUZZYterm~ or term~2laptop~ or laptop~2Fuzzy matching with typo tolerance
BOOSTterm^2.0 or term^2laptop^2.0 or laptop^2Boost relevance score
Boolean ANDterm1 AND term2laptop AND computerBoth terms must match
Boolean ORterm1 OR term2laptop OR notebookEither term matches
Required+term+laptopTerm must be present
Excluded-term-appleTerm must not be present

Advanced Query Examples:

# Search only in title field
curl "http://localhost:9200/collections/products/documents/search?q=title:laptop"

Request (POST):

{
  "q": "title:laptop",
  "query_by": "title"
}

Response:

{
  "found": 3,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99
      },
      "score": 2.5
    }
  ]
}

Example 2: Range Query​

# Find products in price range $100-$500
curl "http://localhost:9200/collections/products/documents/search?q=price:[100 TO 500]"

Request (POST):

{
  "q": "price:[100 TO 500]",
  "query_by": "title,description"
}

Response:

{
  "found": 15,
  "hits": [
    {
      "document": {
        "id": "product2",
        "title": "Wireless Mouse",
        "price": 29.99
      },
      "score": 1.0
    }
  ]
}

Example 3: Fuzzy Search (Typo Tolerance)​

# Find "laptop" even if user types "laptp" or "laptpo"
curl "http://localhost:9200/collections/products/documents/search?q=laptp~2"

Request (POST):

{
  "q": "laptp~2",
  "query_by": "title,description",
  "num_typos": 2
}

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop"
      },
      "score": 1.8
    }
  ]
}

Example 4: Boost Term Importance​

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

Request (POST):

{
  "q": "laptop^2.0 computer",
  "query_by": "title,description"
}

Response:

{
  "found": 8,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop computer"
      },
      "score": 3.2
    }
  ]
}

Example 5: Regex Pattern Matching​

# Find titles matching pattern "laptop.*computer"
curl "http://localhost:9200/collections/products/documents/search?q=title:/laptop.*computer/"

Request (POST):

{
  "q": "title:/laptop.*computer/",
  "query_by": "title"
}

Response:

{
  "found": 2,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer System",
        "price": 1299.99
      },
      "score": 1.5
    }
  ]
}

Example 6: Wildcard Matching​

# Find all products starting with "lap"
curl "http://localhost:9200/collections/products/documents/search?q=lap*"

Request (POST):

{
  "q": "lap*",
  "query_by": "title,description"
}

Response:

{
  "found": 12,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop",
        "price": 1299.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product5",
        "title": "Laptop Stand",
        "price": 49.99
      },
      "score": 0.8
    }
  ]
}

Example 7: NOT Operator​

# Find laptops but exclude Apple products
curl "http://localhost:9200/collections/products/documents/search?q=laptop !apple"

Request (POST):

{
  "q": "laptop !apple",
  "query_by": "title,description"
}

Response:

{
  "found": 8,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Dell Laptop",
        "price": 999.99
      },
      "score": 1.2
    }
  ]
}

Example 8: Boolean AND​

# Find documents with both "laptop" AND "gaming"
curl "http://localhost:9200/collections/products/documents/search?q=laptop AND gaming"

Request (POST):

{
  "q": "laptop AND gaming",
  "query_by": "title,description"
}

Response:

{
  "found": 3,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance gaming laptop"
      },
      "score": 2.1
    }
  ]
}

Example 9: Boolean OR​

# Find documents with "laptop" OR "notebook"
curl "http://localhost:9200/collections/products/documents/search?q=laptop OR notebook"

Request (POST):

{
  "q": "laptop OR notebook",
  "query_by": "title,description"
}

Response:

{
  "found": 15,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "price": 1299.99
      },
      "score": 1.5
    },
    {
      "document": {
        "id": "product8",
        "title": "Notebook Computer",
        "price": 899.99
      },
      "score": 1.3
    }
  ]
}
# Find exact phrase "laptop computer"
curl "http://localhost:9200/collections/products/documents/search?q=\"laptop computer\""

Request (POST):

{
  "q": "\"laptop computer\"",
  "query_by": "title,description"
}

Response:

{
  "found": 2,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer System",
        "description": "This is a laptop computer"
      },
      "score": 2.8
    }
  ]
}

Example 11: Combined Complex Query​

# Complex query: title contains "laptop", price between 100-500, exclude Apple
curl "http://localhost:9200/collections/products/documents/search?q=title:laptop AND price:[100 TO 500] !apple"

Request (POST):

{
  "q": "title:laptop AND price:[100 TO 500] !apple",
  "query_by": "title",
  "filter_by": "price:[100 TO 500]"
}

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product2",
        "title": "Budget Laptop",
        "price": 299.99
      },
      "score": 1.9
    }
  ]
}

Query By (query_by)​

Specify which fields to search. Comma-separated list:

query_by=title,description

Tip: Specifying fields improves performance and relevance.

Filter By (filter_by)​

Filter results by field values. Supports these operators:

OperatorExampleDescription
:category:ElectronicsExact match
>price:>1000Greater than
>=price:>=1000Greater than or equal
<price:<1000Less than
<=price:<=1000Less than or equal
!=category:!=ElectronicsNot equal
~title:~laptopContains
[value1,value2]category:[Electronics,Computers]In array
_geo_radius(...)_geo_radius(location,40.7128,-74.0060,10km)Keep documents within a radius
_geo_box(...)_geo_box(location,40.92,-74.30,40.50,-73.70)Keep documents inside a bounding box
&&price:>1000 && in_stock:trueAND operator
||category:Electronics || category:ComputersOR operator

Note: The q parameter also supports advanced query syntax (NOT, FIELD, RANGE, WILDCARD, REGEX, FUZZY, BOOST) which can be combined with filter_by for powerful search and filtering.

Examples:

Example 1: Single Filter​

# Find products over $1000
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=price:>1000"

Request (POST):

{
  "q": "*",
  "filter_by": "price:>1000",
  "query_by": "title"
}

Response:

{
  "found": 8,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99,
        "category": "Electronics"
      },
      "score": 1.0
    }
  ]
}

Example 2: Multiple Filters with AND​

# Find expensive electronics in stock
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=price:>1000&&category:Electronics&&in_stock:true"

Request (POST):

{
  "q": "*",
  "filter_by": "price:>1000&&category:Electronics&&in_stock:true",
  "query_by": "title"
}

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99,
        "category": "Electronics",
        "in_stock": true
      },
      "score": 1.0
    }
  ]
}

Example 3: Multiple Filters with OR​

# Find electronics OR computers
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=category:Electronics||category:Computers"

Request (POST):

{
  "q": "*",
  "filter_by": "category:Electronics||category:Computers",
  "query_by": "title"
}

Response:

{
  "found": 25,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "category": "Electronics"
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product10",
        "title": "Desktop Computer",
        "category": "Computers"
      },
      "score": 1.0
    }
  ]
}

Example 4: Range Filter​

# Find products between $100 and $500
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=price:[100 TO 500]"

Request (POST):

{
  "q": "*",
  "filter_by": "price:[100 TO 500]",
  "query_by": "title"
}

Response:

{
  "found": 12,
  "hits": [
    {
      "document": {
        "id": "product2",
        "title": "Wireless Mouse",
        "price": 29.99
      },
      "score": 1.0
    }
  ]
}

Example 5: Array Filter (IN)​

# Find products in specific categories
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=category:[Electronics,Computers,Accessories]"

Request (POST):

{
  "q": "*",
  "filter_by": "category:[Electronics,Computers,Accessories]",
  "query_by": "title"
}

Response:

{
  "found": 30,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "category": "Electronics"
      },
      "score": 1.0
    }
  ]
}

Example 6: Not Equal Filter​

# Find all products except electronics
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=category:!=Electronics"

Request (POST):

{
  "q": "*",
  "filter_by": "category:!=Electronics",
  "query_by": "title"
}

Response:

{
  "found": 45,
  "hits": [
    {
      "document": {
        "id": "product3",
        "title": "Office Chair",
        "category": "Furniture"
      },
      "score": 1.0
    }
  ]
}

Example 7: Complex Combined Filter​

# Find expensive electronics in stock, excluding Apple
curl "http://localhost:9200/collections/products/documents/search?q=*&filter_by=price:>1000&&category:Electronics&&in_stock:true&&brand:!=Apple"

Request (POST):

{
  "q": "*",
  "filter_by": "price:>1000&&category:Electronics&&in_stock:true&&brand:!=Apple",
  "query_by": "title"
}

Response:

{
  "found": 3,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99,
        "category": "Electronics",
        "in_stock": true,
        "brand": "Dell"
      },
      "score": 1.0
    }
  ]
}

Geo search works on fields declared as geo_point, geopoint, geo, or latlon. Document values can be stored as [lat, lon], { "lat": 40.7128, "lon": -74.0060 }, { "latitude": 40.7128, "longitude": -74.0060 }, or "40.7128,-74.0060".

Radius Filter​

Use _geo_radius(field, lat, lon, radius) inside filter_by. Radius values default to kilometers and also accept m, km, mi, mile, or miles.

curl "http://localhost:9200/collections/places/documents/search?q=*&filter_by=_geo_radius(location,40.7128,-74.0060,5km)"
{
  "q": "*",
  "filter_by": "_geo_radius(location,40.7128,-74.0060,5km)"
}

You can combine geo filters with regular filters:

curl "http://localhost:9200/collections/places/documents/search?q=coffee&query_by=name,description&filter_by=_geo_radius(location,40.7128,-74.0060,2km)&&open:true"

Bounding Box Filter​

Use _geo_box(field, top_left_lat, top_left_lon, bottom_right_lat, bottom_right_lon). Boxes that cross the antimeridian are supported by giving a west longitude greater than the east longitude.

curl "http://localhost:9200/collections/places/documents/search?q=*&filter_by=_geo_box(location,40.92,-74.30,40.50,-73.70)"

Distance Sort​

Use _geo_distance(field, lat, lon):asc in sort_by to rank nearest results first. When distance sorting is used, each returned document includes _geo_distance_km.

curl "http://localhost:9200/collections/places/documents/search?q=*&filter_by=_geo_radius(location,40.7128,-74.0060,10km)&sort_by=_geo_distance(location,40.7128,-74.0060):asc"
{
  "q": "*",
  "filter_by": "_geo_radius(location,40.7128,-74.0060,10km)",
  "sort_by": "_geo_distance(location,40.7128,-74.0060):asc"
}

Example hit:

{
  "document": {
    "id": "cafe_1",
    "name": "Canal Cafe",
    "location": "[40.7191,-74.0020]",
    "_geo_distance_km": "0.824512"
  },
  "score": 1.0
}

Shorthand Parameters​

The search API also accepts shorthand request parameters:

geo_radius=location,40.7128,-74.0060,5km
geo_box=location,40.92,-74.30,40.50,-73.70
geo_sort=location,40.7128,-74.0060

These expand to the same filter_by and _geo_distance(...) sort syntax internally.

Implementation note: Geo filtering currently runs as post-processing over candidate hits. It is exact and supports all search modes, but it is not yet backed by a spatial index. For large collections, combine geo filters with selective text or metadata filters.

Sort By (sort_by)​

Sort results by field(s). Format: field:direction. Geo distance sorting uses _geo_distance(field, lat, lon):direction.

DirectionDescriptionExample
ascAscending orderprice:asc
descDescending orderprice:desc

Examples:

Example 1: Single Field Sort (Ascending)​

# Sort by price (lowest first)
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=price:asc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "price:asc"
}

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product5",
        "title": "Budget Laptop",
        "price": 299.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product2",
        "title": "Mid-Range Laptop",
        "price": 599.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99
      },
      "score": 1.0
    }
  ]
}

Example 2: Single Field Sort (Descending)​

# Sort by price (highest first)
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=price:desc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "price:desc"
}

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product2",
        "title": "Mid-Range Laptop",
        "price": 599.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product5",
        "title": "Budget Laptop",
        "price": 299.99
      },
      "score": 1.0
    }
  ]
}

Example 3: Multiple Field Sort​

# Sort by category first, then by price (descending)
curl "http://localhost:9200/collections/products/documents/search?q=*&sort_by=category:asc,price:desc"

Request (POST):

{
  "q": "*",
  "query_by": "title",
  "sort_by": "category:asc,price:desc"
}

Response:

{
  "found": 50,
  "hits": [
    {
      "document": {
        "id": "product10",
        "title": "Premium Accessory",
        "category": "Accessories",
        "price": 199.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product11",
        "title": "Basic Accessory",
        "category": "Accessories",
        "price": 29.99
      },
      "score": 1.0
    },
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "category": "Electronics",
        "price": 1299.99
      },
      "score": 1.0
    }
  ]
}

Example 4: Sort by Relevance (Default)​

# Sort by relevance score (default when no sort_by specified)
curl "http://localhost:9200/collections/products/documents/search?q=laptop"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description"
}

Example 5: Sort by Document ID (Alphabetical)​

# Sort by document ID alphabetically
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=id:asc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "id:asc"
}

Example 6: Sort by Title (Alphabetical)​

# Sort by title alphabetically (A-Z)
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=title:asc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "title:asc"
}

Example 7: Sort by Date (Newest First)​

# Sort by creation date (newest first)
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=created_at:desc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "created_at:desc"
}

Example 8: Sort by Text Match Score​

# Sort by relevance score explicitly (high to low)
curl "http://localhost:9200/collections/products/documents/search?q=laptop&sort_by=_text_match:desc"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "sort_by": "_text_match:desc"
}

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99
      },
      "score": 2.5
    },
    {
      "document": {
        "id": "product2",
        "title": "Laptop Stand",
        "price": 49.99
      },
      "score": 1.8
    }
  ]
}

Facet By (facet_by)​

Get facet counts for fields. Comma-separated list:

facet_by=category,brand

Example Request with Facets:

# Get facet counts for category and brand
curl "http://localhost:9200/collections/products/documents/search?q=laptop&facet_by=category,brand"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "facet_by": "category,brand",
  "limit": 10
}

Example Response with Facets:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "category": "Electronics",
        "brand": "Dell",
        "price": 1299.99
      },
      "score": 1.5
    }
  ],
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 5},
        {"value": "Accessories", "count": 3},
        {"value": "Computers", "count": 2}
      ]
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 3},
        {"value": "HP", "count": 2},
        {"value": "Lenovo", "count": 2},
        {"value": "Apple", "count": 3}
      ]
    }
  ]
}

Example: Facets with Filters​

# Get facets for expensive products only
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "price:>1000",
    "facet_by": "category,brand",
    "limit": 10
  }'

Response:

{
  "found": 8,
  "hits": [...],
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 6},
        {"value": "Computers", "count": 2}
      ]
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 4},
        {"value": "Apple", "count": 2},
        {"value": "HP", "count": 2}
      ]
    }
  ]
}

Pagination​

Control result pagination:

ParameterTypeDescriptionExample
pageintegerPage number (1-based)page=1
per_pageintegerResults per pageper_page=10
offsetintegerNumber of results to skipoffset=0
limitintegerMaximum results to returnlimit=10

Examples:

Example 1: Using Page and Per Page​

# Get page 1 with 10 results per page
curl "http://localhost:9200/collections/products/documents/search?q=laptop&page=1&per_page=10"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "page": 1,
  "per_page": 10
}

Response:

{
  "found": 25,
  "hits": [...],
  "page": 1,
  "per_page": 10,
  "out_of": 25
}

Example 2: Using Offset and Limit​

# Skip first 10 results, get next 10
curl "http://localhost:9200/collections/products/documents/search?q=laptop&offset=10&limit=10"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "offset": 10,
  "limit": 10
}

Response:

{
  "found": 25,
  "hits": [...],
  "offset": 10,
  "limit": 10
}

Example 3: Pagination Through Multiple Pages​

# Page 1
curl "http://localhost:9200/collections/products/documents/search?q=laptop&page=1&per_page=10"

# Page 2
curl "http://localhost:9200/collections/products/documents/search?q=laptop&page=2&per_page=10"

# Page 3
curl "http://localhost:9200/collections/products/documents/search?q=laptop&page=3&per_page=10"

Request (POST) - Page 2:

{
  "q": "laptop",
  "query_by": "title,description",
  "page": 2,
  "per_page": 10
}

Response:

{
  "found": 25,
  "hits": [
    {
      "document": {
        "id": "product11",
        "title": "Laptop Bag",
        "price": 39.99
      },
      "score": 1.0
    }
  ],
  "page": 2,
  "per_page": 10,
  "out_of": 25
}

Example 4: Large Result Set Pagination​

# Get first 50 results
curl "http://localhost:9200/collections/products/documents/search?q=*&limit=50&offset=0"

# Get next 50 results
curl "http://localhost:9200/collections/products/documents/search?q=*&limit=50&offset=50"

Request (POST):

{
  "q": "*",
  "query_by": "title",
  "limit": 50,
  "offset": 0
}

Response:

{
  "found": 150,
  "hits": [...],
  "offset": 0,
  "limit": 50
}

Advanced Features​

Typo Tolerance​

Control typo tolerance for fuzzy matching:

ParameterTypeDefaultDescription
num_typosinteger2Maximum number of typos allowed
typo_tolerance_thresholdfloat-Percentage threshold for typo tolerance

Example 1: Basic Typo Tolerance

# Find "laptop" even if user types "laptp"
curl "http://localhost:9200/collections/products/documents/search?q=laptp&num_typos=2"

Request (POST):

{
  "q": "laptp",
  "query_by": "title,description",
  "num_typos": 2
}

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop"
      },
      "score": 1.8
    }
  ]
}

Example 2: Custom Typo Distance

# Allow up to 3 typos
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptpo",
    "query_by": "title,description",
    "num_typos": 3
  }'

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop"
      },
      "score": 1.5
    }
  ]
}

Example 3: Using Fuzzy Query Syntax

# Use fuzzy syntax directly in query (allows 2 character differences)
curl "http://localhost:9200/collections/products/documents/search?q=laptop~2"

Request (POST):

{
  "q": "laptop~2",
  "query_by": "title,description"
}

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop"
      },
      "score": 1.6
    }
  ]
}

Example 4: Typo Tolerance Threshold

# Only match if typo tolerance is below 50%
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptp",
    "query_by": "title,description",
    "num_typos": 2,
    "typo_tolerance_threshold": 0.5
  }'

Tip: You can also use fuzzy query syntax (term~ or term~2) directly in the query string for explicit fuzzy matching with custom distance.

Highlighting​

Highlight matching terms in results:

ParameterTypeDescription
highlight_full_fieldsstringComma-separated fields to highlight

Example 1: Basic Highlighting

# Highlight matching terms in title and description
curl "http://localhost:9200/collections/products/documents/search?q=laptop&highlight_full_fields=title,description"

Request (POST):

{
  "q": "laptop",
  "query_by": "title,description",
  "highlight_full_fields": "title,description"
}

Response includes highlights:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop with great features"
      },
      "score": 1.5,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Laptop</mark> Computer",
          "value": "Laptop Computer"
        },
        {
          "field": "description",
          "snippet": "High-performance <mark>laptop</mark> with great features",
          "value": "High-performance laptop with great features"
        }
      ]
    }
  ]
}

Example 2: Highlighting Multiple Terms

# Highlight both "laptop" and "gaming" in results
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop gaming",
    "query_by": "title,description",
    "highlight_full_fields": "title,description"
  }'

Response:

{
  "found": 3,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance gaming laptop"
      },
      "score": 2.1,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Gaming</mark> <mark>Laptop</mark>",
          "value": "Gaming Laptop"
        },
        {
          "field": "description",
          "snippet": "High-performance <mark>gaming</mark> <mark>laptop</mark>",
          "value": "High-performance gaming laptop"
        }
      ]
    }
  ]
}

Example 3: Highlighting with Phrase Search

# Highlight exact phrase
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "\"laptop computer\"",
    "query_by": "title,description",
    "highlight_full_fields": "title,description"
  }'

Response:

{
  "found": 2,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer System",
        "description": "This is a laptop computer"
      },
      "score": 2.8,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Laptop Computer</mark> System",
          "value": "Laptop Computer System"
        },
        {
          "field": "description",
          "snippet": "This is a <mark>laptop computer</mark>",
          "value": "This is a laptop computer"
        }
      ]
    }
  ]
}

Prioritization​

Control result ranking:

ParameterTypeDefaultDescription
prioritize_exact_matchbooleantruePrioritize exact matches
prioritize_token_positionbooleanfalsePrioritize by token position
prioritize_num_matching_fieldsbooleanfalsePrioritize by number of matching fields

Example 1: Prioritize Exact Matches

# Exact matches appear first
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "prioritize_exact_match": true
  }'

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop",
        "price": 999.99
      },
      "score": 3.0
    },
    {
      "document": {
        "id": "product2",
        "title": "Laptop Stand",
        "price": 49.99
      },
      "score": 1.5
    }
  ]
}

Example 2: Prioritize by Token Position

# Documents where term appears earlier rank higher
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "prioritize_token_position": true
  }'

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "description": "High-performance laptop"
      },
      "score": 2.5
    },
    {
      "document": {
        "id": "product2",
        "title": "Gaming Computer",
        "description": "Laptop for gaming"
      },
      "score": 1.8
    }
  ]
}

Example 3: Prioritize by Number of Matching Fields

# Documents matching in more fields rank higher
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description,tags",
    "prioritize_num_matching_fields": true
  }'

Response:

{
  "found": 10,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance laptop",
        "tags": ["laptop", "gaming"]
      },
      "score": 3.2
    },
    {
      "document": {
        "id": "product2",
        "title": "Laptop Stand",
        "description": "Stand for laptops"
      },
      "score": 1.5
    }
  ]
}

Example 4: Combined Prioritization

# Use multiple prioritization strategies
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "prioritize_exact_match": true,
    "prioritize_token_position": true,
    "prioritize_num_matching_fields": true
  }'

Enable exhaustive search for better recall:

ParameterTypeDefaultDescription
exhaustive_searchbooleanfalsePerform exhaustive search

Example 1: Basic Exhaustive Search

# Enable exhaustive search for maximum recall
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "exhaustive_search": true
  }'

Response:

{
  "found": 25,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Laptop Computer",
        "price": 1299.99
      },
      "score": 1.5
    }
  ]
}

Example 2: Exhaustive Search with Filters

# Exhaustive search on filtered results
curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "filter_by": "price:>1000",
    "exhaustive_search": true,
    "limit": 50
  }'

Tip: Use exhaustive search when you need maximum recall, but it may be slower. Best for smaller collections or when precision is more important than speed.

Search across multiple collections simultaneously.

Endpoint: GET /multi_search or POST /multi_search

Both methods accept the same { "searches": [...] } request shape. POST is recommended for normal HTTP interoperability; GET is supported for clients that can send a JSON request body with GET.

Request Body​

{
  "searches": [
    {
      "collection": "products",
      "q": "laptop",
      "query_by": "title"
    },
    {
      "collection": "articles",
      "q": "laptop",
      "query_by": "title,content"
    }
  ]
}

Example Request​

curl -X POST http://localhost:9200/multi_search \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "laptop"
      },
      {
        "collection": "articles",
        "q": "laptop"
      }
    ]
  }'

Example Response​

{
  "results": [
    {
      "collection": "products",
      "found": 5,
      "hits": [
        {
          "document": {
            "id": "product1",
            "title": "Gaming Laptop",
            "price": 1299.99
          },
          "score": 1.5
        }
      ]
    },
    {
      "collection": "articles",
      "found": 3,
      "hits": [
        {
          "document": {
            "id": "article1",
            "title": "Best Laptops 2024",
            "content": "Review of top laptops..."
          },
          "score": 1.8
        }
      ]
    }
  ]
}

Example 2: Multi-Search with Different Parameters​

curl -X POST http://localhost:9200/multi_search \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "laptop",
        "query_by": "title",
        "filter_by": "price:>1000",
        "limit": 5
      },
      {
        "collection": "articles",
        "q": "laptop",
        "query_by": "title,content",
        "sort_by": "published_date:desc",
        "limit": 10
      },
      {
        "collection": "reviews",
        "q": "laptop",
        "query_by": "title,review_text",
        "facet_by": "rating",
        "limit": 20
      }
    ]
  }'

Response:

{
  "results": [
    {
      "collection": "products",
      "found": 3,
      "hits": [
        {
          "document": {
            "id": "product1",
            "title": "Gaming Laptop",
            "price": 1299.99
          },
          "score": 1.5
        }
      ]
    },
    {
      "collection": "articles",
      "found": 8,
      "hits": [
        {
          "document": {
            "id": "article1",
            "title": "Best Laptops 2024",
            "published_date": "2024-01-15"
          },
          "score": 1.8
        }
      ]
    },
    {
      "collection": "reviews",
      "found": 15,
      "hits": [...],
      "facet_counts": [
        {
          "field_name": "rating",
          "counts": [
            {"value": "5", "count": 8},
            {"value": "4", "count": 5},
            {"value": "3", "count": 2}
          ]
        }
      ]
    }
  ]
}

Example 3: Multi-Search with Vector Queries​

curl -X POST http://localhost:9200/multi_search \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "laptop",
        "query_by": "title"
      },
      {
        "collection": "products",
        "vector_query": [0.1, 0.2, 0.3, ...],
        "limit": 10
      }
    ]
  }'

Facet Counts​

Get facet counts without full search results.

Endpoint: POST /collections/{name}/documents/facet_counts

Request Body​

{
  "facet_by": "category,brand",
  "filter_by": "price:>1000"
}

Example Request​

curl -X POST http://localhost:9200/collections/products/documents/facet_counts \
  -H "Content-Type: application/json" \
  -d '{
    "facet_by": "category,brand"
  }'

Example Response​

{
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 25},
        {"value": "Accessories", "count": 15},
        {"value": "Computers", "count": 10}
      ]
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 12},
        {"value": "HP", "count": 8},
        {"value": "Apple", "count": 10},
        {"value": "Lenovo", "count": 5}
      ]
    }
  ]
}

Example 2: Facet Counts with Filters​

curl -X POST http://localhost:9200/collections/products/documents/facet_counts \
  -H "Content-Type: application/json" \
  -d '{
    "facet_by": "category,brand",
    "filter_by": "price:>1000"
  }'

Response:

{
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 8},
        {"value": "Computers", "count": 5}
      ]
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 5},
        {"value": "Apple", "count": 4},
        {"value": "HP", "count": 4}
      ]
    }
  ]
}

Example 3: Facet Counts with Query​

curl -X POST http://localhost:9200/collections/products/documents/facet_counts \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "facet_by": "category,brand"
  }'

Response:

{
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 10},
        {"value": "Computers", "count": 5}
      ]
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 6},
        {"value": "HP", "count": 4},
        {"value": "Apple", "count": 5}
      ]
    }
  ]
}

Export Documents​

Export documents matching search criteria.

Endpoint: POST /collections/{name}/documents/export

Request Body​

{
  "q": "*",
  "filter_by": "category:Electronics",
  "export_fields": "id,title,price"
}

Example Request​

curl -X POST http://localhost:9200/collections/products/documents/export \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "export_fields": "id,title,price"
  }'

Example Response (NDJSON Format)​

Response: Newline-delimited JSON (NDJSON) format

{"id":"product1","title":"Gaming Laptop","price":1299.99}
{"id":"product2","title":"Wireless Mouse","price":29.99}
{"id":"product3","title":"Keyboard","price":79.99}
{"id":"product4","title":"Monitor","price":299.99}
{"id":"product5","title":"Headphones","price":149.99}

Example 2: Export with Filters​

curl -X POST http://localhost:9200/collections/products/documents/export \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "category:Electronics&&price:>1000",
    "export_fields": "id,title,price,category"
  }'

Response:

{"id":"product1","title":"Gaming Laptop","price":1299.99,"category":"Electronics"}
{"id":"product6","title":"High-End Monitor","price":599.99,"category":"Electronics"}
{"id":"product10","title":"Workstation","price":2499.99,"category":"Electronics"}

Example 3: Export All Fields​

curl -X POST http://localhost:9200/collections/products/documents/export \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "in_stock:true"
  }'

Response (all fields exported):

{"id":"product1","title":"Gaming Laptop","description":"High-performance laptop","price":1299.99,"category":"Electronics","in_stock":true,"tags":["gaming","laptop"]}
{"id":"product2","title":"Wireless Mouse","description":"Ergonomic mouse","price":29.99,"category":"Accessories","in_stock":true,"tags":["mouse","wireless"]}

Example 4: Export with Query​

curl -X POST http://localhost:9200/collections/products/documents/export \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "export_fields": "id,title,price",
    "limit": 100
  }'

Response:

{"id":"product1","title":"Gaming Laptop","price":1299.99}
{"id":"product5","title":"Budget Laptop","price":299.99}
{"id":"product8","title":"Laptop Stand","price":49.99}

Search Ranking​

hlquery uses adaptive ranking algorithms:

  • BM25+: Default ranking algorithm for full-text search
  • TF-IDF: Alternative ranking algorithm
  • Hybrid Search: Combines keyword and semantic search

Ranking parameters (k1, b) are automatically adjusted based on:

  • Query length
  • Collection properties
  • Document features

Tip: The adaptive algorithm automatically optimizes ranking for your data - no manual tuning needed!

Best Practices​

  1. Use specific fields: Specify query_by to search only relevant fields
  2. Index properly: Ensure searchable fields are properly indexed
  3. Use filters: Combine search with filters for better performance
  4. Limit results: Use pagination to limit result sets
  5. Cache queries: Cache frequently used queries for better performance

Error Handling​

Invalid Query​

Status Code: 400 Bad Request

{
  "error": "Invalid search query",
  "message": "Query parameter 'q' is required"
}

Collection Not Found​

Status Code: 404 Not Found

{
  "error": "Collection not found",
  "name": "nonexistent"
}

Advanced Query Syntax Verification​

For comprehensive verification that all advanced query syntax features are supported across the daemon, REST API, client libraries, and hanalyzer web interface, see the Advanced Query Verification Guide.

This guide includes:

  • Complete syntax reference for all query types
  • Verification checklists for each component
  • Test queries and examples
  • filter_by parameter support verification
  • Testing scripts and procedures

Real-World Examples​

Complete product search with filtering, sorting, and faceting:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "gaming laptop",
    "query_by": "title,description,tags",
    "filter_by": "price:[500 TO 2000]&&in_stock:true&&category:Electronics",
    "sort_by": "price:asc",
    "facet_by": "brand,category,rating",
    "highlight_full_fields": "title,description",
    "limit": 20,
    "page": 1
  }'

Response:

{
  "found": 15,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance gaming laptop with RTX 4090",
        "price": 1299.99,
        "brand": "Dell",
        "category": "Electronics",
        "rating": 4.5,
        "in_stock": true
      },
      "score": 2.5,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Gaming</mark> <mark>Laptop</mark>",
          "value": "Gaming Laptop"
        }
      ]
    }
  ],
  "facet_counts": [
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 5},
        {"value": "HP", "count": 4},
        {"value": "Lenovo", "count": 6}
      ]
    },
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 15}
      ]
    },
    {
      "field_name": "rating",
      "counts": [
        {"value": "5", "count": 8},
        {"value": "4", "count": 5},
        {"value": "3", "count": 2}
      ]
    }
  ],
  "page": 1,
  "per_page": 20
}

Example 2: Content Search with Typo Tolerance​

Search articles with typo tolerance and highlighting:

curl -X POST http://localhost:9200/collections/articles/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "artifical inteligence",
    "query_by": "title,content",
    "num_typos": 2,
    "highlight_full_fields": "title,content",
    "filter_by": "published:true&&category:Technology",
    "sort_by": "published_date:desc",
    "limit": 10
  }'

Response:

{
  "found": 8,
  "hits": [
    {
      "document": {
        "id": "article1",
        "title": "Artificial Intelligence in 2024",
        "content": "Artificial intelligence is transforming...",
        "published": true,
        "category": "Technology",
        "published_date": "2024-01-15"
      },
      "score": 1.8,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Artificial</mark> <mark>Intelligence</mark> in 2024",
          "value": "Artificial Intelligence in 2024"
        },
        {
          "field": "content",
          "snippet": "<mark>Artificial</mark> <mark>intelligence</mark> is transforming...",
          "value": "Artificial intelligence is transforming..."
        }
      ]
    }
  ]
}

Example 3: Advanced Filtering and Range Queries​

Complex search with multiple filters and range queries:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop price:[500 TO 1500]",
    "query_by": "title,description",
    "filter_by": "price:[500 TO 1500]&&category:[Electronics,Computers]&&rating:>=4&&in_stock:true",
    "sort_by": "rating:desc,price:asc",
    "facet_by": "brand,rating",
    "limit": 25
  }'

Response:

{
  "found": 12,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "price": 1299.99,
        "category": "Electronics",
        "rating": 4.8,
        "in_stock": true,
        "brand": "Dell"
      },
      "score": 2.1
    }
  ],
  "facet_counts": [
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 5},
        {"value": "HP", "count": 4},
        {"value": "Lenovo", "count": 3}
      ]
    },
    {
      "field_name": "rating",
      "counts": [
        {"value": "5", "count": 6},
        {"value": "4", "count": 6}
      ]
    }
  ]
}

Example 4: Boolean Search with Exclusions​

Search with boolean operators and exclusions:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "(laptop OR notebook) AND gaming !apple",
    "query_by": "title,description",
    "filter_by": "price:>1000&&brand:!=Apple",
    "highlight_full_fields": "title,description",
    "limit": 10
  }'

Response:

{
  "found": 5,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance gaming laptop",
        "price": 1299.99,
        "brand": "Dell"
      },
      "score": 2.3,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Gaming</mark> <mark>Laptop</mark>",
          "value": "Gaming Laptop"
        }
      ]
    }
  ]
}

Using wildcards and regex for flexible matching:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "title:/laptop.*gaming/i OR title:lap*",
    "query_by": "title,description",
    "filter_by": "price:>500",
    "limit": 20
  }'

Response:

{
  "found": 8,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop Pro",
        "price": 1299.99
      },
      "score": 2.0
    },
    {
      "document": {
        "id": "product5",
        "title": "Laptop Stand",
        "price": 49.99
      },
      "score": 1.2
    }
  ]
}

Prioritizing certain terms in search:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop^3.0 gaming^2.0 computer",
    "query_by": "title,description",
    "sort_by": "price:asc",
    "limit": 15
  }'

Response:

{
  "found": 12,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop Computer",
        "price": 1299.99
      },
      "score": 4.5
    },
    {
      "document": {
        "id": "product2",
        "title": "Laptop Computer",
        "price": 999.99
      },
      "score": 3.2
    }
  ]
}

Example 7: Complete Search with All Features​

Combining all search features:

curl -X POST http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop^2.0 gaming",
    "query_by": "title,description,tags",
    "filter_by": "price:[500 TO 2000]&&category:Electronics&&in_stock:true&&rating:>=4",
    "sort_by": "rating:desc,price:asc",
    "facet_by": "brand,category,rating",
    "highlight_full_fields": "title,description",
    "num_typos": 1,
    "prioritize_exact_match": true,
    "prioritize_num_matching_fields": true,
    "page": 1,
    "per_page": 20
  }'

Response:

{
  "found": 18,
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop",
        "description": "High-performance gaming laptop",
        "price": 1299.99,
        "category": "Electronics",
        "brand": "Dell",
        "rating": 4.8,
        "in_stock": true,
        "tags": ["gaming", "laptop", "computer"]
      },
      "score": 4.2,
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Gaming</mark> <mark>Laptop</mark>",
          "value": "Gaming Laptop"
        },
        {
          "field": "description",
          "snippet": "High-performance <mark>gaming</mark> <mark>laptop</mark>",
          "value": "High-performance gaming laptop"
        }
      ]
    }
  ],
  "facet_counts": [
    {
      "field_name": "brand",
      "counts": [
        {"value": "Dell", "count": 8},
        {"value": "HP", "count": 5},
        {"value": "Lenovo", "count": 5}
      ]
    },
    {
      "field_name": "category",
      "counts": [
        {"value": "Electronics", "count": 18}
      ]
    },
    {
      "field_name": "rating",
      "counts": [
        {"value": "5", "count": 10},
        {"value": "4", "count": 8}
      ]
    }
  ],
  "page": 1,
  "per_page": 20,
  "out_of": 18
}

Next Steps​