Nlq

Natural Language Query (NLQ) Protocol

Transforms natural language queries into ObjectQL AST (Abstract Syntax Tree).

Enables business users to query data using natural language instead of writing code.

Source: packages/spec/src/ai/nlq.zod.ts

TypeScript Usage

import { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai';
import type { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai';

// Validate data
const result = Entity.parse(data);

Entity

Properties

Property	Type	Required	Description
type	`Enum<'object' \| 'field' \| 'value' \| 'operator' \| 'function' \| 'timeframe'>`	✅
text	`string`	✅	Original text from query
value	`any`	✅	Normalized value
confidence	`number`	✅	Confidence score
span	`any[]`	optional	Character span in query

FieldSynonymConfig

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
field	`string`	✅	Field name
synonyms	`string[]`	✅	Natural language synonyms
examples	`string[]`	optional	Example queries using synonyms

NLQAnalytics

Properties

Property	Type	Required	Description
totalQueries	`integer`	✅
successfulQueries	`integer`	✅
failedQueries	`integer`	✅
averageConfidence	`number`	✅
intentDistribution	`Record<string, integer>`	✅	Count by intent type
topQueries	`Object[]`	✅
averageParseTime	`number`	✅	Average parse time in milliseconds
averageExecutionTime	`number`	optional
lowConfidenceQueries	`Object[]`	✅
startDate	`string`	✅	ISO timestamp
endDate	`string`	✅	ISO timestamp

NLQFieldMapping

Properties

Property	Type	Required	Description
naturalLanguage	`string`	✅	NL field name (e.g., "customer name")
objectField	`string`	✅	Actual field name (e.g., "account.name")
object	`string`	✅	Object name
field	`string`	✅	Field name
confidence	`number`	✅

NLQModelConfig

Properties

Property	Type	Required	Description
modelId	`string`	✅	Model from registry
systemPrompt	`string`	optional	System prompt override
includeSchema	`boolean`	✅	Include object schema in prompt
includeExamples	`boolean`	✅	Include examples in prompt
enableIntentDetection	`boolean`	✅
intentThreshold	`number`	✅
enableEntityRecognition	`boolean`	✅
entityRecognitionModel	`string`	optional
enableFuzzyMatching	`boolean`	✅	Fuzzy match field names
fuzzyMatchThreshold	`number`	✅
enableTimeframeDetection	`boolean`	✅
defaultTimeframe	`string`	optional	Default timeframe if not specified
enableCaching	`boolean`	✅
cacheTTL	`integer`	✅	Cache TTL in seconds

NLQParseResult

Properties

Property	Type	Required	Description
originalQuery	`string`	✅
intent	`Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>`	✅
intentConfidence	`number`	✅
entities	`Object[]`	✅
targetObject	`string`	optional	Primary object to query
fields	`Object[]`	optional
timeframe	`Object`	optional
ast	`Record<string, any>`	✅	Generated ObjectQL AST
confidence	`number`	✅	Overall confidence
ambiguities	`Object[]`	optional	Detected ambiguities requiring clarification
alternatives	`Object[]`	optional

NLQRequest

Properties

Property	Type	Required	Description
query	`string`	✅	Natural language query
context	`Object`	optional
includeAlternatives	`boolean`	✅	Include alternative interpretations
maxAlternatives	`integer`	✅
minConfidence	`number`	✅	Minimum confidence threshold
executeQuery	`boolean`	✅	Execute query and return results
maxResults	`integer`	optional	Maximum results to return

NLQResponse

Properties

Property	Type	Required	Description
parseResult	`Object`	✅
results	`Record<string, any>[]`	optional	Query results
totalCount	`integer`	optional
executionTime	`number`	optional	Execution time in milliseconds
needsClarification	`boolean`	✅	Whether query needs clarification
tokens	`Object`	optional	Token usage for this query
cost	`number`	optional	Cost for this query in USD
suggestions	`string[]`	optional	Query refinement suggestions

NLQTrainingExample

Properties

Property	Type	Required	Description
query	`string`	✅	Natural language query
context	`Object`	optional
expectedIntent	`Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>`	✅
expectedObject	`string`	optional
expectedAST	`Record<string, any>`	✅	Expected ObjectQL AST
category	`string`	optional	Example category
tags	`string[]`	optional
notes	`string`	optional

QueryContext

Properties

Property	Type	Required	Description
userId	`string`	optional
userRole	`string`	optional
currentObject	`string`	optional	Current object being viewed
currentRecordId	`string`	optional	Current record ID
conversationHistory	`Object[]`	optional
defaultLimit	`integer`	✅
timezone	`string`	✅
locale	`string`	✅

QueryIntent

Allowed Values

select
aggregate
filter
sort
compare
trend
insight
create
update
delete

QueryTemplate

Properties

Property	Type	Required	Description
id	`string`	✅
name	`string`	✅	Template name (snake_case)
label	`string`	✅
pattern	`string`	✅	Query pattern with placeholders
variables	`Object[]`	✅
astTemplate	`Record<string, any>`	✅	AST template with variable placeholders
category	`string`	optional
examples	`string[]`	optional
tags	`string[]`	optional

Timeframe

Properties

Property	Type	Required	Description
type	`Enum<'absolute' \| 'relative'>`	✅
start	`string`	optional	Start date (ISO format)
end	`string`	optional	End date (ISO format)
relative	`Object`	optional
text	`string`	✅	Original timeframe text

On this page