Testing a Query Template

A query template is a Handlebars template that turns a query into a request body, query string, and headers. Before committing a template to an evaluation and running it across hundreds of queries, it's worth confirming it renders cleanly. Releval exposes two test endpoints for this:

• Test against a saved query set — render the template with the first few queries from an existing query set.
• Test against ad-hoc queries — render the template with queries you supply in the request body.

Both return the generated body, query string, and headers per query, plus the inferred schema (text or json).

In the UI

The query template editor includes a Test panel where you can pick a query set and see the rendered request for the first five queries. Use this to spot Handlebars syntax errors, missing variables, or encoding issues before you save.

Test against a saved query set

Renders the template with the first five queries from a query set. Useful when iterating on a template that you intend to use against that set.

curl -X POST "https://${RELEVAL_HOST}/api/v1/query-templates/test/${QUERY_SET_ID}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "body": "{\"query\":{\"match\":{\"title\":\"{{query}}\"}},\"size\":10}",
    "content_type": "application/json"
  }'

The response:

{
  "format": "text",
  "query_templates": [
    {
      "query": "running shoes",
      "body": "{\"query\":{\"match\":{\"title\":\"running shoes\"}},\"size\":10}",
      "query_string": null,
      "headers": null
    },
    ...
  ]
}

format is text for plain-string query sets, or json for query sets whose entries are JSON objects.

Test against ad-hoc queries

Renders the template with queries you supply directly. Useful when prototyping a template before you've created a query set, or when you want to test edge-case queries that aren't in your usual set.

curl -X POST "https://${RELEVAL_HOST}/api/v1/query-templates/test" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "queries": ["running shoes", "kids waterproof jackets size 7"],
    "body": "{\"query\":{\"match\":{\"title\":\"{{query}}\"}},\"size\":10}",
    "content_type": "application/json"
  }'

Queries can be either plain strings or JSON objects:

{
  "queries": [
    { "query": "running shoes", "filter": "size:9" },
    { "query": "kids jackets", "filter": "category:outerwear" }
  ],
  "body": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{query}}\"}}]}},\"post_filter\":\"{{filter}}\"}",
  "content_type": "application/json"
}

The two forms cannot be mixed within a single request — all queries must be strings, or all must be objects.

What you can test

The test endpoints validate three template parts:

• body — the request body template, with the matching content_type (application/json, application/x-ndjson, etc.).
• query_string — the URL query string template.
• headers — a map of header templates.

Any of the three can be omitted. Whatever is supplied is compiled and rendered against each query. A Handlebars syntax error or runtime failure is returned as a validation problem pointing at the offending field, so you can surface helpful errors in your own tooling.

Iterating from the API

Pair the test endpoint with a small script to iterate on a template fast:

TEMPLATE_BODY='{"query":{"match":{"title":"{{query}}"}},"size":{{size}}}'

curl -X POST "https://${RELEVAL_HOST}/api/v1/query-templates/test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d "{
    \"queries\": [{\"query\": \"running shoes\", \"size\": 10}],
    \"body\": $(echo "$TEMPLATE_BODY" | jq -Rs .),
    \"content_type\": \"application/json\"
  }" | jq '.query_templates[0].body'

Once the rendered output looks right, save the template via POST /api/v1/query-templates and use it in an evaluation.