Query planning tool

Introduced 0.12.0

The QueryPlanningTool turns a natural-language question into a Lucenia query (query domain-specific language, or DSL) using a large language model (LLM). The tool reads the target index's mapping, asks the LLM to write a query that answers the question against that mapping, validates the result, and returns a structured query object that you can run directly.

The LLM is referenced by ID and can be a local model or any remote connector, so the tool is cloud-agnostic.

Enterprise-safe by default

By default, the tool sends only the index mapping (field names and types) to the LLM — no documents leave your cluster. Sending a sample document can improve query quality, but it is strictly opt-in through include_sample_doc, which defaults to false. This keeps the tool compliance-safe out of the box: you consciously choose to expose data before any document content reaches the model. When you do opt in, route the sampled document through your compliance and redaction controls first.

Prerequisites

Before registering the tool, you need the ID of an LLM deployed through the ML Commons plugin, and the index you want to query.

Step 1: Register a flow agent that will run the QueryPlanningTool

A flow agent runs a sequence of tools in order and returns the last tool's output. To create a flow agent, send the following register agent request:

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_QueryPlanning_tool",
  "type": "flow",
  "description": "this is a test agent for the QueryPlanningTool",
  "tools": [
    {
      "type": "QueryPlanningTool",
      "name": "DemoQueryPlanningTool",
      "parameters": {
        "index": "sample-ecommerce",
        "model_id": "kLj9Bo0Bpc3sThaJdY9x",
        "include_sample_doc": false
      }
    }
  ]
}

For parameter descriptions, see Register parameters.

Lucenia responds with an agent ID:

{
  "agent_id": "9X7xWI0Bpc3sThaJdY9i"
}

Step 2: Run the agent

Run the agent, providing the natural-language question:

POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
{
  "parameters": {
    "question": "orders over $100 placed in the last week"
  }
}

The tool returns a structured object containing the generated query and a flag indicating whether it fell back to the default query:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "result": "{\"query\":{\"bool\":{\"filter\":[{\"range\":{\"total\":{\"gt\":100}}},{\"range\":{\"order_date\":{\"gte\":\"now-7d\"}}}]}},\"used_fallback\":false}"
        }
      ]
    }
  ]
}

If the model can't produce a valid query, the tool returns the fallback_query and sets used_fallback to true.

Register parameters

The following table lists all tool parameters that are available when registering an agent.

Parameter	Type	Required/Optional	Description
index	String	Required	The index the generated query targets. Its mapping is sent to the LLM.
model_id	String	Required	The ID of the LLM that writes the query. The model can be local or any remote connector.
include_sample_doc	Boolean	Optional	When true, includes one sample document from the index in the prompt to help the model write a better query. Default is false, so no document content is sent to the LLM unless you opt in.
fallback_query	Object	Optional	The query returned when the model can't produce a valid query. Default is match_all.

Execute parameters

The following table lists all tool parameters that are available when running the agent.

Parameter	Type	Required/Optional	Description
question	String	Required	The natural-language question to convert into a query. If omitted, the tool falls back to the raw input parameter.

Output

The tool returns a structured object:

Field	Type	Description
query	Object	The generated query DSL (or the fallback_query if generation failed).
used_fallback	Boolean	true if the tool returned the fallback query, false if the model produced the query.