kvpair clause-OpenSearch(Open Search)-阿里云帮助中心

Use the kvpair clause in a query statement to pass key-value pairs that control query behavior, output format, and optimizer settings.

Syntax

kvpair={key}:{value};{key}:{value};...

Separate multiple key-value pairs with semicolons (;). Do not add spaces before or after a semicolon.

If a configuration item name matches a parameter name in the kvpair clause, the kvpair parameter takes precedence.

Example

query=SELECT brand, COUNT(*) FROM phone &&kvpair=trace:INFO;formatType:full_json

Parameters

Output and format

Parameter	Valid values	Default	Description
`formatType` / `format`	`string`, `json`, `full_json`, `flatbuffers`	`string`	The format of the returned result. Use `full_json` for JSON-format queries. Use `flatbuffers` to improve query performance. For details, see Interpret query results.
`resultReadable`	`true`, `false`	`false`	Specifies whether to add line breaks to results in JSON format for readability. Applies only when `format` is set to `json` or `full_json`.
`searchInfo`	`true`, `false`	`false`	Specifies whether to return search information.
`sqlPlan`	`true`, `false`	`false`	Specifies whether to return SQL plan information.
`forbitMergeSearchInfo`	`true`, `false`	`false`	Specifies whether Query Result Searcher (QRS) merges the search information returned by column searches. Set to `true` to get the details of each column separately.

Query execution

Parameter	Valid values	Default	Description
`trace`	`DISABLE`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE1`, `TRACE2`, `TRACE3`, `SCHEDULE`, `NOTSET`	`DISABLE`	The verbosity level of query process information generated in the frontend.
`timeout`	ulimit	Determined by the SQL statement configuration	The query timeout period, in milliseconds.
`lackResultEnable`	`true`, `false`	`false`	Specifies whether missing columns are allowed in the result. For example, allows a column to be missing if an RPC timeout occurs.
`databaseName`	String	—	The default database name that QRS uses to access the corresponding Searcher. To access multiple Searchers at the same time, specify the database name before the table name using the `dbName.tableName` format in the query statement.

Parallel execution (versions earlier than V3.8.0)

The parallel and parallelTables parameters apply to OpenSearch Retrieval Engine Edition versions earlier than V3.8.0. For V3.8.0 and later, use the new parallel implementation described in Hint. The two implementations are incompatible — do not use them at the same time.

Parameter	Valid values	Default	Description
`parallel`	`1`–`16`	`1`	Enables parallel optimization on the Searcher.
`parallelTables`	String	—	The tables that support splitting and parallel execution in joins. Separate multiple table names with vertical bars (`\|`). Use together with `parallel`.

Query source tracking

Parameter	Valid values	Default	Description
`exec.source.id`	String	`""`	The specific row accessed by the query. Values are generated in chronological order by default. Useful when multiple exchanges exist.
`exec.source.spec`	String	`""`	The source identifier of the business party. Format: `tpp-appid-abid-solutionid-ip` for The Personalization Platform (TPP) scenarios; `Product name-System name-IP address` for other scenarios.

Dynamic parameters

Parameter	Valid values	Default	Description
`dynamic_params`	Two-dimensional array	—	Dynamic query parameters. For details, see Dynamic parameters.
`urlencode_data`	`true`, `false`	`false`	Specifies whether the `dynamic_params` value is URL encoded. Set to `true` if the value is URL encoded.

Optimizer settings (iquan)

Parameter	Valid values	Default	Description
`iquan.optimizer.debug.enable`	`true`, `false`	`false`	Specifies whether to enable debugging in the optimization phase.
`iquan.optimizer.sort.limit.use.together`	`true`, `false`	`true`	Specifies whether a LIMIT clause is required after every ORDER BY clause.
`iquan.optimizer.force.limit.num`	ulimit	`100`	The value used as the LIMIT clause when `iquan.optimizer.force.limit.enable` is set to `true`.
`iquan.optimizer.join.condition.check`	`true`, `false`	`true`	Specifies whether the fields used in a join must be hash fields.
`iquan.optimizer.force.hash.join`	`true`, `false`	`false`	Specifies whether to convert all join nodes to hash join nodes.
`iquan.plan.format.type`	`json`	`json`	The format of the execution plan generated by iquan. Only JSON is supported.
`iquan.plan.prepare.level`	`rel.post.optimize`, `jni.post.optimize`	`jni.post.optimize`	The phase at which iquan caches or substitutes query plan results. Use together with `iquan.plan.cache.enable` and `dynamic_params`. Valid values: `rel.post.optimize` returns results from the Java optimization phase; `jni.post.optimize` returns results from the C++ phase after the Java Native Interface (JNI) call. Set to `jni.post.optimize` for best performance.
`iquan.plan.cache.enable`	`true`, `false`	`false`	Specifies whether to cache the current query plan results.