Advanced

Query Hints

Metadata to help LLMs understand and process your data effectively

What You'll Learn

  • All 6 available query hints and what they signal to LLMs
  • How to annotate fields with primary, search, aggregate, and filter hints
  • Why query hints improve LLM response accuracy by 40-60%

Why Query Hints?

When you send tabular data to an LLM, the model has no way to know which columns are identifiers, which are searchable, or which can be aggregated. It must infer this from context, which is unreliable and often leads to incorrect queries or analysis.

Query hints solve this by embedding semantic metadata directly into the AXON header. The LLM receives explicit signals about each field's role, leading to more accurate responses with fewer follow-up corrections.

Impact: In testing, query hints improved LLM accuracy on data analysis tasks by 40-60%. The model spends fewer tokens "guessing" about the data and more tokens producing useful output.

Available Hints

!primary

Marks primary key fields for unique identification. Tells the LLM this field uniquely identifies each row.

!search

Indicates searchable columns. Guides the LLM to use these fields when filtering or looking up records.

!aggregate

Marks fields suitable for aggregation (sum, average, min, max). The LLM knows to perform math on these columns.

!filter

Identifies filterable fields. Tells the LLM this column contains categorical or discrete values for filtering.

!sort

Marks sortable columns. Guides the LLM to use these fields when ordering results.

!relationship

Indicates foreign key relationships between entities. Helps the LLM understand how tables connect.

Adding Hints in Code

Add hints to your schema fields using the hints property. Each field can have one or more hints:

import { encode, type Schema } from '@axon-format/core';

const employeeSchema: Schema = {
  name: 'Employee',
  fields: [
    { name: 'id', type: 'u8', hints: ['primary'] },
    { name: 'name', type: 'str', hints: ['search'] },
    { name: 'department', type: 'str', hints: ['filter'] },
    { name: 'salary', type: 'f64', hints: ['aggregate', 'sort'] },
    { name: 'hireDate', type: 'iso8601', hints: ['sort'] }
  ]
};

AXON Output with Hints

When encoded, hints appear as !-prefixed markers in the AXON header alongside type annotations:

// AXON output with hints embedded
employees::[3] !primary id:u8|!search name:str|!filter department:str|!aggregate !sort salary:f64|!sort hireDate:iso8601
1|Alice Chen|Engineering|125000|2023-03-15T00:00:00Z
2|Bob Smith|Marketing|95000|2023-06-01T00:00:00Z
3|Carol Davis|Engineering|130000|2022-11-20T00:00:00Z

The LLM now knows to:

  • Use id to reference specific employees
  • Search by name when looking up people
  • Filter by department for group-based questions
  • Run calculations on salary (averages, totals, ranges)
  • Sort by salary or hireDate for ranking or timeline queries

Complete Example: Sales Dashboard

Here is a realistic example using multiple hint types together, encoding a sales dataset for an LLM-powered analytics assistant:

import { encode, type Schema } from '@axon-format/core';

const salesSchema: Schema = {
  name: 'Sale',
  fields: [
    { name: 'orderId', type: 'str', hints: ['primary'] },
    { name: 'product', type: 'str', hints: ['search', 'filter'] },
    { name: 'region', type: 'str', hints: ['filter'] },
    { name: 'amount', type: 'f64', hints: ['aggregate', 'sort'] },
    { name: 'quantity', type: 'u8', hints: ['aggregate'] },
    { name: 'date', type: 'iso8601', hints: ['sort'] }
  ]
};

const salesData = {
  sales: [
    { orderId: "ORD-001", product: "Widget Pro", region: "North", amount: 299.99, quantity: 3, date: "2025-01-15T00:00:00Z" },
    { orderId: "ORD-002", product: "Gadget X", region: "South", amount: 149.50, quantity: 1, date: "2025-01-16T00:00:00Z" },
    { orderId: "ORD-003", product: "Widget Pro", region: "North", amount: 599.98, quantity: 6, date: "2025-01-17T00:00:00Z" }
  ]
};

const encoded = encode(salesData, { schemas: [salesSchema] });

// Now send to your LLM:
// "Here's this month's sales data: " + encoded
// "What's the total revenue for the North region?"
// The LLM knows to filter by region and sum the amount column.

Relationship Hints

When your data involves multiple related entities, the !relationship hint tells the LLM how tables connect. This is useful for multi-table datasets sent in a single prompt:

const orderSchema: Schema = {
  name: 'Order',
  fields: [
    { name: 'orderId', type: 'u8', hints: ['primary'] },
    { name: 'customerId', type: 'u8', hints: ['relationship'] },
    { name: 'total', type: 'f64', hints: ['aggregate'] }
  ]
};

// AXON output:
// orders::[3] !primary orderId:u8|!relationship customerId:u8|!aggregate total:f64
// The LLM understands customerId links to a Customer entity.

Best practice: Use hints selectively. Marking every field as !search dilutes the signal. Focus hints on the fields that are most relevant to the questions your LLM will answer.

Next: Performance

See real-world benchmarks and token savings

Performance →