LLM Query Database

LLM Query Database turns a natural-language question into SQL and runs it. Its type is llm-query-database.

Basic usage

The configured question goes to the chosen language model, which produces SQL from the structure described by a semantic layer. The processor runs that SQL and writes both the result and the SQL itself into the variable you name, for later processors.

It differs from the SQL processor in who writes the SQL. The SQL processor needs the statement written in advance, which suits fixed queries; LLM Query Database has the model produce one on the spot, which suits questions that come from users and cannot be enumerated beforehand.

Compared with attaching a semantic layer to LLM Completion, this processor is narrower: it does one question-to-SQL step and runs it, with no multi-turn reasoning and no other tools, so the outcome is more predictable.

This processor can only be configured through the Workflow CRD

Odin's Flow Agent visual editor has no llm-query-database node, and it does not appear in the canvas node menu. Using it means writing the Workflow CRD directly.

The legal values of Workflow.spec.processors[].type are defined by the CRD, and llm-query-database is one of them.

How to configure it

Declare it in spec.processors of the Workflow CRD:

apiVersion: asgard-ai.com/v1alpha1
kind: Workflow
metadata:
  name: wf-sales-question
spec:
  variables: []
  entries:
    - name: entry-main
      handlingProcessor: proc-ask
  exits: []
  processors:
    - name: proc-ask
      type: llm-query-database
      labels:
        display_name: Natural-language query
      configs:
        - name: semanticLayer
          value: sl-retail-pos
        - name: query
          expression: prevMessage
        - name: resultField
          value: queryResult
        - name: completionModel
          value: cm-builtin-balanced
        - name: maxTokens
          value: "4096"

Each config uses exactly one of value, expression or template. The CRD enforces this.

Configuration

semanticLayer (required)

The name of the semantic layer to query. The model produces SQL from the tables and columns that layer describes, so the layer's coverage is the range of questions this processor can answer.

query (required)

The natural-language question to convert. In practice this uses expression to carry the user's question; see Expression introduction — resolving values.

resultField (required)

The variable that receives the result: a JSON object holding both the query result and the SQL the model produced.

Returning the SQL as well is useful when debugging. If the result is not what you expected, you can see exactly what statement was run, and tell whether the problem lies in the semantic layer's descriptions or in how the question was phrased.

completionModel (required)

The name of the language model that produces the SQL.

maxTokens (required)

The token limit on what the model generates.

temperature

The model's randomness. Producing SQL is a task that needs precision, so this is usually set low to reduce variation between statements.

Relationships

success

Once the SQL has been produced and run, the workflow continues from this connection point and the result lands in the variable named by resultField.

failure

If the model cannot produce valid SQL, or the SQL fails to run, the workflow continues from this connection point and a prevError variable holds the error.

Notes

1. The quality of the semantic layer's column descriptions decides whether the SQL is correct. Vague names or missing descriptions make the model pick the wrong table.

2. Connect the failure branch. A question that falls outside the semantic layer's coverage makes this processor fail, which is common with open-ended questions.

3. For a workflow that has to be editable visually, use the SQL processor with a prepared statement, or LLM Completion with a semantic layer attached. Both have nodes in the Flow Agent editor.