> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SqlHints

> SqlHints — Kinetica Rust API

[gpudb\_api](https://docs.kinetica.com/content/api/rust/index.md)::<wbr />[sql](https://docs.kinetica.com/content/api/rust/sql/index.md)
[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L177-L216)&#x20;

<pre>`pub struct SqlHints { /* private fields */ }`</pre>

SQL hints that can be embedded in statements or passed as execute\_sql options.Kinetica supports SQL hints (KI\_HINT) that can be added as comments within queries to control query execution behavior. This struct provides a builder interface for configuring hints programmatically.

## Hint Types

There are two ways to apply hints:

<ol>
  <li>**Inline hints**: Embedded in the SQL statement as comments (`/* KI_HINT_... */`)</li>
  <li>**Options hints**: Passed in the `options` map of the execute\_sql API</li>
</ol>

This struct supports both approaches.

## Example

```rust theme={null}
use gpudb_api::SqlHints;

// Create hints for upsert operation
let hints = SqlHints::new()
    .update_on_existing_pk(true)
    .distributed_operations(true);

// Convert to inline SQL comment
let sql_with_hints = format!(
    "INSERT INTO my_table {} (id, name) VALUES (1, 'test')",
    hints.to_inline_hint()
);
// Result: "INSERT INTO my_table /* KI_HINT_UPDATE_ON_EXISTING_PK */ (id, name) VALUES (1, 'test')"

// Or convert to options map for execute_sql API
let options = hints.to_options_map();
```

## Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L218-L640)
impl [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L220-L222)
pub fn [new](#method.new)() -> Self

Create a new empty SqlHints builder.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L239-L242)
pub fn [update\_on\_existing\_pk](#method.update_on_existing_pk)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `update_on_existing_pk` hint (KI\_HINT\_UPDATE\_ON\_EXISTING\_PK).When `true`, enables upsert functionality - inserts new records and updates existing ones matched by primary key. If the target table has no primary key, this hint will be ignored.

##### Example

```sql theme={null}
INSERT INTO table /* KI_HINT_UPDATE_ON_EXISTING_PK */ (id, value) VALUES (1, 'test')
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L254-L257)
pub fn [ignore\_existing\_pk](#method.ignore_existing_pk)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `ignore_existing_pk` hint (KI\_HINT\_IGNORE\_EXISTING\_PK).When `true`, discards duplicate records (by primary key) during insertion without throwing errors. Only effective when `update_on_existing_pk` is `false`.

##### Example

```sql theme={null}
INSERT INTO table /* KI_HINT_IGNORE_EXISTING_PK */ (id, value) VALUES (1, 'test')
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L269-L272)
pub fn [batch\_size](#method.batch_size)(self, size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)) -> Self

Set the batch size hint (KI\_HINT\_BATCH\_SIZE).Specifies the batch size for bulk INSERT operations. This controls how many records are sent to the server in each batch during ingestion.

##### Example

```sql theme={null}
INSERT INTO table /* KI_HINT_BATCH_SIZE(10000) */ (id, value) VALUES (1, 'test')
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L275-L277)
pub fn [get\_batch\_size](#method.get_batch_size)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)>

Get the batch size hint.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L286-L289)
pub fn [distributed\_operations](#method.distributed_operations)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `distributed_operations` hint.When `true`, enables the use of distributed operations in servicing the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L294-L297)
pub fn [distributed\_joins](#method.distributed_joins)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `distributed_joins` hint.When `true`, enables the use of distributed joins in servicing the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L302-L305)
pub fn [cost\_based\_optimization](#method.cost_based_optimization)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `cost_based_optimization` hint.When `false`, disables the cost-based optimization of the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L310-L313)
pub fn [rule\_based\_optimization](#method.rule_based_optimization)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `rule_based_optimization` hint.When `false`, disables rule-based rewrite optimizations.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L318-L321)
pub fn [parallel\_execution](#method.parallel_execution)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `parallel_execution` hint.When `false`, disables the parallel step execution of the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L326-L329)
pub fn [plan\_cache](#method.plan_cache)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `plan_cache` hint.When `false`, disables plan caching for the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L334-L337)
pub fn [results\_caching](#method.results_caching)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `results_caching` hint.When `false`, disables caching of the results of the given query.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L342-L345)
pub fn [late\_materialization](#method.late_materialization)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `late_materialization` hint.When `true`, Joins/Filters results will always be late materialized.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L350-L353)
pub fn [ssq\_optimization](#method.ssq_optimization)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `ssq_optimization` hint.When `false`, scalar subqueries will be translated into joins.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L359-L362)
pub fn [preserve\_dict\_encoding](#method.preserve_dict_encoding)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `preserve_dict_encoding` hint.When `true`, columns that were dict encoded in the source table will be dict encoded in the result table.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L371-L374)
pub fn [ttl](#method.ttl)(self, minutes: [i32](https://doc.rust-lang.org/1.98.1/std/primitive.i32.html)) -> Self

Set the TTL (time-to-live) in minutes for intermediate result tables.-1 indicates no timeout.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L380-L383)
pub fn [paging\_table](#method.paging_table)(self, table\_name: impl [Into](https://doc.rust-lang.org/1.98.1/core/convert/trait.Into.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>) -> Self

Set the paging table name for paginated queries.When specified, the system will create a paging table to hold query results between pagination calls.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L388-L391)
pub fn [paging\_table\_ttl](#method.paging_table_ttl)(self, minutes: [i32](https://doc.rust-lang.org/1.98.1/std/primitive.i32.html)) -> Self

Set the TTL for the paging table in minutes.-1 indicates no timeout. Setting this option also creates a paging table.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L400-L403)
pub fn [prepare\_mode](#method.prepare_mode)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `prepare_mode` hint.When `true`, compiles a query into an execution plan and saves it for later execution.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L412-L415)
pub fn [query\_parameters](#method.query_parameters)(self, json: impl [Into](https://doc.rust-lang.org/1.98.1/core/convert/trait.Into.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>) -> Self

Set query parameters in JSON array format.This can be used instead of binary-encoded data for parameterized queries.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L424-L427)
pub fn [validate\_change\_column](#method.validate_change_column)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `validate_change_column` hint.When changing a column using ALTER TABLE, validate the change before applying it.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L437-L440)
pub fn [use\_approx\_count\_distinct](#method.use_approx_count_distinct)(self, value: [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)) -> Self

Set the `use_approx_count_distinct` hint.When `true`, for all COUNT\_DISTINCT aggregate functions, use the faster but less accurate APPROXIMATE\_COUNT\_DISTINCT aggregate function.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L463-L466)
pub fn [add\_custom\_hint](#method.add_custom_hint)(self, hint: impl [Into](https://doc.rust-lang.org/1.98.1/core/convert/trait.Into.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>) -> Self

Add a custom inline hint that will be included in the SQL comment.Use this for hints not covered by the typed methods, like:

<ul>
  <li>`KI_HINT_GROUP_BY_PK`</li>
  <li>`KI_HINT_INDEX(column)`</li>
  <li>`KI_HINT_PROJECT_MATERIALIZED_VIEW`</li>
  <li>`KI_HINT_JOBID_PREFIX(prefix)`</li>
</ul>

##### Example

```rust theme={null}
use gpudb_api::SqlHints;

let hints = SqlHints::new()
    .add_custom_hint("KI_HINT_GROUP_BY_PK")
    .add_custom_hint("KI_HINT_INDEX(my_column)");
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L488-L511)
pub fn [to\_inline\_hint](#method.to_inline_hint)(\&self) -> [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)

Convert the hints to an inline SQL comment string.Returns an empty string if no inline hints are set. Only includes hints that can be expressed as inline comments (KI\_HINT\_\*).

##### Example

```rust theme={null}
use gpudb_api::SqlHints;

let hints = SqlHints::new()
    .update_on_existing_pk(true)
    .ignore_existing_pk(false);

assert_eq!(hints.to_inline_hint(), "/* KI_HINT_UPDATE_ON_EXISTING_PK */");
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L517-L595)
pub fn [to\_options\_map](#method.to_options_map)(\&self) -> [HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>

Convert the hints to an options map for the execute\_sql API.Returns a HashMap containing all set hints as key-value pairs suitable for passing to the execute\_sql `options` parameter.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L600-L604)
pub fn [merge\_into](#method.merge_into)(\&self, options: \&mut [HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>)

Merge these hints into an existing options map.Hints from this struct will overwrite existing values in the map.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L607-L629)
pub fn [is\_empty](#method.is_empty)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Check if any hints are set.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L632-L634)
pub fn [get\_update\_on\_existing\_pk](#method.get_update_on_existing_pk)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)>

Get the update\_on\_existing\_pk setting.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L637-L639)
pub fn [get\_ignore\_existing\_pk](#method.get_ignore_existing_pk)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)>

Get the ignore\_existing\_pk setting.

## Trait Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
impl [Clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html) for [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
fn [clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)(\&self) -> [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

Returns a duplicate of the value. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)

1.0.0 (const: [unstable](https://github.com/rust-lang/rust/issues/142757)) · [Source](https://doc.rust-lang.org/1.98.1/src/core/clone.rs.html#245-247)
fn [clone\_from](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)(\&mut self, source: \&Self)

Performs copy-assignment from `source`. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
impl [Debug](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html) for [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
fn [fmt](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html#tymethod.fmt)(\&self, f: \&mut [Formatter](https://doc.rust-lang.org/1.98.1/core/fmt/struct.Formatter.html)\<'\_>) -> [Result](https://doc.rust-lang.org/1.98.1/core/fmt/type.Result.html)

Formats the value using the given formatter. [Read more](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html#tymethod.fmt)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
impl [Default](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html) for [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L176)
fn [default](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html#tymethod.default)() -> [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

Returns the “default value” for a type. [Read more](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html#tymethod.default)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.