The config clause is an optional part of a query statement. Use it to control paging, result format, timeouts, deduplication, and ranking behavior.
Syntax
The value of the config clause is a JSON object containing one or more parameters.
{
"config": {
}
}
Parameters
Paging
| Parameter | Type | Default | Description |
|---|
start | NUMBER | 0 | The start offset in the result set from which documents are returned. |
hit | NUMBER | 10 | The maximum number of documents to return per query. |
Example — paging through results 20 at a time:
// Page 1
{
"config": {
"start": 0,
"hit": 20,
"format": "xml"
}
}
// Page 2
{
"config": {
"start": 20,
"hit": 20,
"format": "xml"
}
}
Result format
| Parameter | Valid values | Default | Description |
|---|
format | json, xml | xml | The format of the query results. |
Timeouts
| Parameter | Type | Default | Description |
|---|
timeout | NUMBER | 0 | The total query timeout in milliseconds. Must be a non-negative number. |
seek_timeout | NUMBER | 0 | The timeout for the seeking phase, in milliseconds. By default, the specified timeout period multiplied by 0.7 is used as the seeking timeout period. Set this explicitly when you need per-phase timeout control instead of relying on the derived value. |
Deduplication
| Parameter | Valid values | Default | Description |
|---|
dedup | yes, no | yes | Whether to automatically remove duplicate documents based on the primary key. |
Ranking and truncation
These parameters control how many documents are processed at each stage of the two-phase ranking pipeline. When set to 0, the value from the cluster configuration file is used.
| Parameter | Type | Default | Description |
|---|
rank_size | NUMBER | 0 | The number of documents to roughly sort, or the truncation count for a dynamic index. |
rerank_size | NUMBER | 0 | The number of documents to finely sort in the first scoring phase. When set to 0, the value in the configuration file is used. |
total_rank_size | NUMBER | 0 | The total number of roughly sorted documents across all partitions, or the dynamic index truncation count. |
total_rerank_size | NUMBER | 0 | The total number of documents finely sorted in the first scoring phase across all partitions. |
rerank_hint | BOOL | false | Whether to run the second scoring phase. |
rank_trace | FATAL | ERROR | INFO | DEBUG | WARN | TRACE1 | TRACE2 | TRACE3 | No default value | The verbosity level for scoring debug output in the frontend. |
Example — increasing candidates for fine sorting:
{
"config": {
"start": 1,
"hit": 20,
"rerank_size": 1000
}
}
Searcher and hits
| Parameter | Type | Default | Description |
|---|
searcher_return_hits | NUMBER | 0 | The number of records the searcher returns. When set to 0, the number is determined by start and hit. Cannot exceed 5,000. |
actual_hits_limit | NUMBER | 0 | Controls whether totalhits in the response is an actual count or an estimate. See the behavior note below. |
no_summary | false, true | false | When true, runs only a phase-1 query without fetching summaries. |
research_threshold | NUMBER | 0 | If the number of returned records is fewer than this value, the query runs again. |
How `actual_hits_limit` works:
| Condition | totalhits value |
|---|
Actual record count < actual_hits_limit | Actual count |
Actual record count >= actual_hits_limit | Estimated count |
| Actual record count = 0 | Estimated count |
numeric_limits<uint32_t>::max() condition is met | Actual count |
Summary fetching
| Parameter | Valid values | Default | Description |
|---|
fetch_summary_type | docid, pk, rawpk | docid | The method used to fetch summaries. pk uses the hash value of the primary key. rawpk uses the original primary key value. |
pk or rawpk is recommended over docid.
Replica selection
| Parameter | Type | Default | Description |
|---|
sourceid | string | No default value | A source ID used to select a replica for the query. When omitted, a replica is selected randomly per query, which may return stale data during incremental index updates. When set, the replica is selected based on the hash value of sourceid, so queries with the same sourceid can target the same replica and return the latest data. |
Default query settings
| Parameter | Type | Default | Description |
|---|
default_index | string | "" | The default index for the query. Falls back to the index specified in query_config in the cluster configuration file. If the query itself specifies an index, that index takes precedence. |
default_operator | AND, OR | "" | The default Boolean operator for the query. Falls back to the operator specified in query_config in the cluster configuration file. If the query specifies an operator, it takes precedence. |
Examples
Configure paging — 20 documents per page:
// Page 1
{
"config": {
"start": 0,
"hit": 20,
"format": "xml"
}
}
// Page 2
{
"config": {
"start": 20,
"hit": 20,
"format": "xml"
}
}
Set the number of documents for fine sorting to 1,000:
{
"config": {
"start": 1,
"hit": 20,
"rerank_size": 1000
}
}