Search

Three search modes are available: full-text, vector (embedding-based), and hybrid (blended).

Full-Text Search

POST /api/teams/{teamName}/datasets/{dataSetName}/search

curl -X POST https://your-host/api/teams/acme/datasets/products/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "wireless headphones", "maxNumberOfRecordsToReturn": 20}'

With Coverage

{
  "text": "wireless headphones",
  "maxNumberOfRecordsToReturn": 30,
  "enableCoverage": true,
  "coverageDepth": 500
}

With Facets and Filter

{
  "text": "headphones",
  "maxNumberOfRecordsToReturn": 20,
  "enableFacets": true,
  "filter": {"hashString": "abc123..."}
}

With Per-Field Boosts (BM25F mode only)

fieldBoosts adjusts how much each field counts for one search, without reconfiguring or rebuilding the index. Keys are field names, values are multipliers.

{
  "text": "noise cancelling",
  "maxNumberOfRecordsToReturn": 10,
  "fieldBoosts": {
    "title": 3.0,
    "description": 0.5
  }
}

• A boost multiplies the field's configured weight; it does not replace it. A field with weight: 2.0 and a boost of 3.0 counts 6×. Fields you leave out keep their configured weight (a boost of 1.0).
• Every key must be a searchable field. Here title and description must both have searchable: true in the dataset's field configuration.
• A key that is not a searchable field empties the whole search. The response is 200 with no records and a reason naming the field ("FieldBoosts contains unknown or non-searchable field: 'x'"), so read reason before showing "no results". If a search that used to return results suddenly returns none, check fieldBoosts against the field configuration first — making a field non-searchable does not remove it from boosts your code still sends.
• Boosts only apply in BM25F mode, which a dataset is in when every searchable field has the same bM25k1 (the default; check with GET fields/configuration). If bM25k1 differs between searchable fields the dataset scores each field separately and ignores fieldBoosts — valid keys have no effect, and an invalid key still empties the search.

Browse / Empty Search

{
  "text": "",
  "maxNumberOfRecordsToReturn": 50,
  "sortBy": "rating",
  "sortAscending": false,
  "enableFacets": true
}

Vector Search

POST /api/teams/{teamName}/datasets/{dataSetName}/search/vector

Approximate nearest-neighbour search against a field marked Embeddable. The query vector must match the field's embedding dimensions. Any length is accepted: Indx brings it to unit length, so scores are cosine similarity.

curl -X POST https://your-host/api/teams/acme/datasets/products/search/vector \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "embedding",
    "vector": [0.12, -0.45, 0.33, ...],
    "maxResults": 10
  }'

Returns an array of EmbeddingResultEntry with scores in [0, 1] (cosine similarity).

Hybrid Search

POST /api/teams/{teamName}/datasets/{dataSetName}/search/hybrid

Blends text search and vector search scores. The combined score is:

score = alpha × embeddingScore + (1 − alpha) × normalisedTextScore

curl -X POST https://your-host/api/teams/acme/datasets/products/search/hybrid \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "comfortable headphones",
    "embeddingField": "embedding",
    "vector": [0.12, -0.45, 0.33, ...],
    "alpha": 0.6,
    "maxNumberOfRecordsToReturn": 20
  }'

Returns an array of EmbeddingResultEntry with blended scores in [0, 1].

Retrieving Full Documents

Search endpoints return keys and scores only. Use documents/lookup to fetch the full JSON for a set of keys.

POST /api/teams/{teamName}/datasets/{dataSetName}/documents/lookup

curl -X POST https://your-host/api/teams/acme/datasets/products/documents/lookup \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[42, 17, 305]'

Returns a string[] of JSON documents in the same order as the input keys.