Search Examples

Use POST for complex searches. JSON bodies preserve spaces, &&, parentheses, and geo expressions without extra URL encoding.

Text, phrases, and fields

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "\"wireless keyboard\" OR title:bluetooth",
    "query_by": "title,description,tags",
    "limit": 10
  }'

Other useful query forms include keyboard~2 for typo tolerance, key* for a wildcard, laptop^2 mouse to boost a term, and keyboard !refurbished to exclude a term. See Search parameters before combining advanced syntax.

Filters, sorting, and pagination

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "in_stock:true && price:>=25 && price:<100 && (category:keyboards || category:mice)",
    "sort_by": "price:asc",
    "offset": 0,
    "limit": 20
  }'

Advance offset by limit to request the next page. Keep a deterministic sort_by when page order must remain stable.

Facets for a filter UI

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "laptop",
    "query_by": "title,description",
    "facet_by": "category,brand",
    "max_facet_values": 20,
    "limit": 12
  }'

Render hits from hits and filter counts from facets. When the user selects a facet, add it to filter_by and rerun the same query.

Highlight matches

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "mechanical keyboard",
    "query_by": "title,description",
    "highlight_full_fields": "title,description"
  }'

Treat returned highlight markup as untrusted content when rendering it in HTML.

Suggestions after an empty result

Call the dedicated maybe endpoint only when the primary search is sparse or empty:

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/documents/maybe \
  -H "Content-Type: application/json" \
  -d '{"q":"keybaord","limit":5}'

Search every collection

curl --fail-with-body -X POST http://localhost:9200/search \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["products", "articles", "documentation"],
    "q": "wireless setup",
    "query_by": "title,description,content",
    "limit": 20,
    "offset": 0
  }'

Global search merges and ranks all hits, and each document includes _collection. Use /multi_search instead when you want an independent result set for each query.

Multi-search in one round trip

curl --fail-with-body -X POST http://localhost:9200/multi_search \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"collection":"products","q":"keyboard","query_by":"title"},
      {"collection":"articles","q":"keyboard guide","query_by":"title,content"}
    ]
  }'

Geo radius and nearest-first sorting

First declare location as geo_point and store a value such as [40.7128, -74.0060]. Then search within ten kilometers and sort by distance:

curl --fail-with-body -X POST \
  http://localhost:9200/collections/places/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "coffee",
    "query_by": "name,description",
    "filter_by": "_geo_radius(location,40.7128,-74.0060,10km) && open:true",
    "sort_by": "_geo_distance(location,40.7128,-74.0060):asc"
  }'

Distance-sorted documents include _geo_distance_km.

Vector similarity

The embedding length must match the stored vector field:

curl --fail-with-body -X POST \
  http://localhost:9200/collections/products/vector_search \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "embedding",
    "vector": [0.12, -0.08, 0.44, 0.31],
    "top_k": 10,
    "metric_type": "cosine",
    "filter_by": "in_stock:true",
    "output_fields": ["id", "title", "price"],
    "include_vector": false
  }'

Current vector execution uses a linear scan. The Vector Search API covers multiple embeddings, fusion, thresholds, and hybrid queries.

SQL-style queries

curl --fail-with-body -X POST http://localhost:9200/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT category, AVG(price) AS avg_price FROM products GROUP BY category ORDER BY avg_price DESC;"}'

Use the document and collection APIs for ordinary writes; SQL is useful for interactive selection and aggregation.