System Properties

Kinetica provides a SQL interface for managing system properties, which control everything from GPUs, hostnames, storage, graph server, and more.

The ability to manage system properties is available through SQL, using the following commands:

ALTER SYSTEM SET PROPERTIES
SHOW SYSTEM PROPERTIES

ALTER SYSTEM SET PROPERTIES

Only a small subset of the system properties can be altered at runtime. See the /alter/system/properties endpoint documentation for the full list. Only users with the system_admin permission can issue this command.

ALTER SYSTEM SET PROPERTIES Syntax
1
2
ALTER SYSTEM SET PROPERTIES ('<property key>' = '<property value>'[,...])
[WITH OPTIONS ('persist' = < 'true' | 'false' >)]

Use the WITH OPTIONS clause to specify whether the setting should be saved to the system configuration to be used after future database restarts. Set the persist option to false to only change the property temporarily, until the database is restarted. By default, the change will be persisted.

Alterable Properties

Not all system properties can be modified while the system is running. The following is a list of those that can be modified.

Property Description

enable_audit Enable or disable auditing.

audit_headers Enable or disable auditing of request headers.

audit_body Enable or disable auditing of request bodies.

audit_data Enable or disable auditing of request data.

audit_response Enable or disable auditing of response information.

tps_per_tom Size of the worker rank data processing thread pool. This includes operations such as inserts, updates, & deletes on table data. Multi-head inserts are not affected by this limit. The minimum allowed value is 2. The maximum allowed value is 8192.

tcs_per_tom Size of the worker rank data calculation thread pool. This is primarily used for computation-based operations such as aggregates and record retrieval. The minimum allowed value is 2. The maximum allowed value is 8192.

subtask_concurrency_limit Maximum number of simultaneous threads allocated to a given request, per rank. Note that thread allocation may also be limited by resource group limits and/or system load.

concurrent_kernel_execution Enable or disable concurrent kernel execution.

max_concurrent_kernels Maximum number of kernels that can be running at the same time on a given GPU. Set to 0 for no limit. Only takes effect if concurrent_kernel_execution is true. The maximum allowed value is 256.

max_get_records_size The maximum number of records the database will serve for a given data retrieval call. The maximum allowed value is 1000000.

request_timeout Number of minutes after which filtering (e.g., /filter) and aggregating (e.g., /aggregate/groupby) queries will time out. The maximum allowed value is 1440.

enable_overlapped_equi_join Enable or disable the overlapped-equi-join filter.

chunk_size Number of records per chunk, applied to all new tables. To disable chunking, use 0.

chunk_column_max_memory Maximum data size, in bytes, for each column in a chunk, applied to all new tables. Use 0 for no maximum.

chunk_max_memory Maximum data size for all columns in a chunk, applied to all new tables. Use 0 for no maximum; use -1 to use the default, based on RAM tier limits or host memory per rank.

execution_mode

Scheme to use for kernel executions. Possible values:

Mode	Description
`host`	Execute kernels only on the host (CPU)
`device`	Execute kernels only on the device (GPU)
`default`	Execution engine decides whether to execute kernels on the host or the device
`<rows>`	Execute kernels on the host if the chunked column contains the given number of rows or fewer; otherwise, execute on the device

shadow_agg_size Maximum number of bytes in the shadow aggregate chunk cache. The maximum allowed value is 2147483647.

shadow_filter_size Maximum number of bytes in the shadow filter chunk cache. The maximum allowed value is 2147483647.

telm_persist_query_metrics Enable or disable persisting of query metrics in a table. If disabled, metrics will still be available for point-in-time export.

postgres_proxy_idle_connection_timeout PostgreSQL Wire Protocol service idle connection timeout, in seconds

postgres_proxy_keep_alive Enable or disable PostgreSQL Wire Protocol service's keep alive.

ai_enable_rag Enable or disable SQL-GPT RAG.

ai_api_provider AI API provider type

ai_api_url AI API URL

ai_api_key AI API key

ai_api_embeddings_model AI API embeddings model name

ai_api_connection_timeout AI API connection timeout, in seconds

external_files_directory Root directory path, on the head node of the cluster, from where external table data files are accessed.

egress_single_file_max_size Maximum file size, in MB, to allow saving to a single file. May be overridden by target limitations. The maximum allowed value is 200000.

egress_parquet_compression

Parquet file compression type. The supported values are:

uncompressed
snappy
gzip

kafka_batch_size Maximum number of Kafka records to be ingested in a single batch. The maximum allowed value is 10000000.

kafka_wait_time Maximum time, in seconds, to buffer records received from Kafka before ingestion. The maximum allowed value is 120.

kafka_poll_timeout Maximum time, in milliseconds, for each poll to get records from Kafka. The maximum allowed value is 1000.

system_metadata_retention_period For persistent metadata tables, the time, in seconds, to retain rows prior to deletion. Note that records are deleted periodically, so this retention period is the minimum lifetime of a given metadata record.

kifs_directory_data_limit Default maximum capacity to apply to a newly-created KiFS directory, in bytes. Use -1 for no limit.

enable_one_step_compound_equi_join Enable or disable the one-step compound equi-join algorithm.

ALTER SYSTEM Examples

For example, to increase the request timeout and the maximum /get/records size permanently (in the startup configuration):

ALTER SYSTEM SET PROPERTIES Example
1
2
3
4
ALTER SYSTEM SET PROPERTIES (
    'request_timeout' = '25', 
    'max_get_records_size' = '25000'
)

To set the default embeddings model until the database is restarted:

ALTER SYSTEM SET Default Embedding Model Temporarily Example
1
2
ALTER SYSTEM SET PROPERTIES ('ai_enable_rag' = 'true')
WITH OPTIONS ('persist' = 'false')

SHOW SYSTEM PROPERTIES

System properties can be shown by any user.

SHOW SYSTEM PROPERTIES Syntax
1
2
SHOW SYSTEM PROPERTIES
[WITH OPTIONS ('properties' = '<config parameter name>[,...]')]

For example, to show all system properties:

SHOW SYSTEM PROPERTIES Example
1
SHOW SYSTEM PROPERTIES

To show the internal & external cluster node URLs:

SHOW SYSTEM PROPERTIES Individually Example
1
2
SHOW SYSTEM PROPERTIES
WITH OPTIONS ('properties' = 'conf.worker_http_server_urls,conf.worker_http_server_urls_private')

To show all RAM tier properties:

SHOW RAM Tier Properties Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
SHOW SYSTEM PROPERTIES
WITH OPTIONS
(
    'properties' =
    '
        conf.tier.ram.default.high_watermark,
        conf.tier.ram.default.limit,
        conf.tier.ram.default.low_watermark,
        conf.tier.ram.rank0.high_watermark,
        conf.tier.ram.rank0.limit,
        conf.tier.ram.rank0.low_watermark,
        conf.tier.ram.rank1.high_watermark,
        conf.tier.ram.rank1.limit,
        conf.tier.ram.rank1.low_watermark,
        conf.tier.ram.rank2.high_watermark,
        conf.tier.ram.rank2.limit,
        conf.tier.ram.rank2.low_watermark
    '
)