pub struct SqlHints  /* private fields */

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:

Inline hints: Embedded in the SQL statement as comments (/* KI_HINT_… */)
Options hints: Passed in the options map of the execute_sql API

This struct supports both approaches.

Example

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

impl SqlHints

Source

pub fn new() -> Self

Create a new empty SqlHints builder.

Source

pub fn update_on_existing_pk(self, value: bool) -> 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.

INSERT INTO table /* KI_HINT_UPDATE_ON_EXISTING_PK */ (id, value) VALUES (1, 'test')

Source

pub fn ignore_existing_pk(self, value: bool) -> 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.

INSERT INTO table /* KI_HINT_IGNORE_EXISTING_PK */ (id, value) VALUES (1, 'test')

Source

pub fn batch_size(self, size: usize) -> 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.

INSERT INTO table /* KI_HINT_BATCH_SIZE(10000) */ (id, value) VALUES (1, 'test')

Source

pub fn get_batch_size(&self) -> Option<usize>

Get the batch size hint.

Source

pub fn distributed_operations(self, value: bool) -> Self

Set the distributed_operations hint.

When true, enables the use of distributed operations in servicing the given query.

Source

pub fn distributed_joins(self, value: bool) -> Self

Set the distributed_joins hint.

When true, enables the use of distributed joins in servicing the given query.

Source

pub fn cost_based_optimization(self, value: bool) -> Self

Set the cost_based_optimization hint.

When false, disables the cost-based optimization of the given query.

Source

pub fn rule_based_optimization(self, value: bool) -> Self

Set the rule_based_optimization hint.

When false, disables rule-based rewrite optimizations.

Source

pub fn parallel_execution(self, value: bool) -> Self

Set the parallel_execution hint.

When false, disables the parallel step execution of the given query.

Source

pub fn plan_cache(self, value: bool) -> Self

Set the plan_cache hint.

When false, disables plan caching for the given query.

Source

pub fn results_caching(self, value: bool) -> Self

Set the results_caching hint.

When false, disables caching of the results of the given query.

Source

pub fn late_materialization(self, value: bool) -> Self

Set the late_materialization hint.

When true, Joins/Filters results will always be late materialized.

Source

pub fn ssq_optimization(self, value: bool) -> Self

Set the ssq_optimization hint.

When false, scalar subqueries will be translated into joins.

Source

pub fn preserve_dict_encoding(self, value: bool) -> 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

pub fn ttl(self, minutes: i32) -> Self

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

-1 indicates no timeout.

Source

pub fn paging_table(self, table_name: impl Into<String>) -> 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

pub fn paging_table_ttl(self, minutes: i32) -> Self

Set the TTL for the paging table in minutes.

-1 indicates no timeout. Setting this option also creates a paging table.

Source

pub fn prepare_mode(self, value: bool) -> Self

Set the prepare_mode hint.

When true, compiles a query into an execution plan and saves it for later execution.

Source

pub fn query_parameters(self, json: impl Into<String>) -> Self

Set query parameters in JSON array format.

This can be used instead of binary-encoded data for parameterized queries.

Source

pub fn validate_change_column(self, value: bool) -> Self

Set the validate_change_column hint.

When changing a column using ALTER TABLE, validate the change before applying it.

Source

pub fn use_approx_count_distinct(self, value: bool) -> 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

pub fn add_custom_hint(self, hint: impl Into<String>) -> 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:

KI_HINT_GROUP_BY_PK
KI_HINT_INDEX(column)
KI_HINT_PROJECT_MATERIALIZED_VIEW
KI_HINT_JOBID_PREFIX(prefix)

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

pub fn to_inline_hint(&self) -> String

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_*).

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

pub fn to_options_map(&self) -> HashMap<String, String>

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

pub fn merge_into(&self, options: &mut HashMap<String, String>)

Merge these hints into an existing options map.

Hints from this struct will overwrite existing values in the map.

Source

pub fn is_empty(&self) -> bool

Check if any hints are set.

Source

pub fn get_update_on_existing_pk(&self) -> Option<bool>

Get the update_on_existing_pk setting.

Source

pub fn get_ignore_existing_pk(&self) -> Option<bool>

Get the ignore_existing_pk setting.

Trait Implementations

Source

impl Clone for SqlHints

Source

fn clone(&self) -> SqlHints

Returns a duplicate of the value. Read more

1.0.0 (const: unstable) · Source

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source

impl Debug for SqlHints

Source

fn fmt(&self, f: &mut Formatter<’_>) -> Result

Formats the value using the given formatter. Read more

Source

impl Default for SqlHints

Source

fn default() -> SqlHints

Returns the “default value” for a type. Read more

​Hint Types

​Example

​Implementations

​impl SqlHints

​pub fn new() -> Self

​pub fn update_on_existing_pk(self, value: bool) -> Self

​pub fn ignore_existing_pk(self, value: bool) -> Self

​pub fn batch_size(self, size: usize) -> Self

​pub fn get_batch_size(&self) -> Option<usize>

​pub fn distributed_operations(self, value: bool) -> Self

​pub fn distributed_joins(self, value: bool) -> Self

​pub fn cost_based_optimization(self, value: bool) -> Self

​pub fn rule_based_optimization(self, value: bool) -> Self

​pub fn parallel_execution(self, value: bool) -> Self

​pub fn plan_cache(self, value: bool) -> Self

​pub fn results_caching(self, value: bool) -> Self

​pub fn late_materialization(self, value: bool) -> Self

​pub fn ssq_optimization(self, value: bool) -> Self

​pub fn preserve_dict_encoding(self, value: bool) -> Self

​pub fn ttl(self, minutes: i32) -> Self

​pub fn paging_table(self, table_name: impl Into<String>) -> Self

​pub fn paging_table_ttl(self, minutes: i32) -> Self

​pub fn prepare_mode(self, value: bool) -> Self

​pub fn query_parameters(self, json: impl Into<String>) -> Self

​pub fn validate_change_column(self, value: bool) -> Self

​pub fn use_approx_count_distinct(self, value: bool) -> Self

​pub fn add_custom_hint(self, hint: impl Into<String>) -> Self

​pub fn to_inline_hint(&self) -> String

​pub fn to_options_map(&self) -> HashMap<String, String>

​pub fn merge_into(&self, options: &mut HashMap<String, String>)

​pub fn is_empty(&self) -> bool

​pub fn get_update_on_existing_pk(&self) -> Option<bool>

​pub fn get_ignore_existing_pk(&self) -> Option<bool>

​Trait Implementations

​impl Clone for SqlHints

​fn clone(&self) -> SqlHints

​fn clone_from(&mut self, source: &Self)

​impl Debug for SqlHints

​fn fmt(&self, f: &mut Formatter<’_>) -> Result

​impl Default for SqlHints

​fn default() -> SqlHints

Hint Types

Example

Implementations

impl SqlHints

pub fn new() -> Self

pub fn update_on_existing_pk(self, value: bool) -> Self

pub fn ignore_existing_pk(self, value: bool) -> Self

pub fn batch_size(self, size: usize) -> Self

pub fn get_batch_size(&self) -> Option<usize>

pub fn distributed_operations(self, value: bool) -> Self

pub fn distributed_joins(self, value: bool) -> Self

pub fn cost_based_optimization(self, value: bool) -> Self

pub fn rule_based_optimization(self, value: bool) -> Self

pub fn parallel_execution(self, value: bool) -> Self

pub fn plan_cache(self, value: bool) -> Self

pub fn results_caching(self, value: bool) -> Self

pub fn late_materialization(self, value: bool) -> Self

pub fn ssq_optimization(self, value: bool) -> Self

pub fn preserve_dict_encoding(self, value: bool) -> Self

pub fn ttl(self, minutes: i32) -> Self

pub fn paging_table(self, table_name: impl Into<String>) -> Self

pub fn paging_table_ttl(self, minutes: i32) -> Self

pub fn prepare_mode(self, value: bool) -> Self

pub fn query_parameters(self, json: impl Into<String>) -> Self

pub fn validate_change_column(self, value: bool) -> Self

pub fn use_approx_count_distinct(self, value: bool) -> Self

pub fn add_custom_hint(self, hint: impl Into<String>) -> Self

pub fn to_inline_hint(&self) -> String

pub fn to_options_map(&self) -> HashMap<String, String>

pub fn merge_into(&self, options: &mut HashMap<String, String>)

pub fn is_empty(&self) -> bool

pub fn get_update_on_existing_pk(&self) -> Option<bool>

pub fn get_ignore_existing_pk(&self) -> Option<bool>

Trait Implementations

impl Clone for SqlHints

fn clone(&self) -> SqlHints

fn clone_from(&mut self, source: &Self)

impl Debug for SqlHints

fn fmt(&self, f: &mut Formatter<’_>) -> Result

impl Default for SqlHints

fn default() -> SqlHints