> ## 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.

# ALTER SYSTEM SET PROPERTIES

Only a small subset of the system properties can be altered at runtime. See the
[/alter/system/properties](https://docs.kinetica.com/content/api/rest/alter_system_properties_rest.md) endpoint documentation for the
full list. Only users with the `system_admin`
[permission](https://docs.kinetica.com/content/security/sec_concepts.md#security-concepts-permissions) can issue this command.

```sql title="ALTER SYSTEM SET PROPERTIES Syntax" theme={null}
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.

> [accordion] enable\_audit
>
> Enable or disable auditing.

> [accordion] audit\_headers
>
> Enable or disable auditing of request headers.

> [accordion] audit\_body
>
> Enable or disable auditing of request bodies.

> [accordion] audit\_data
>
> Enable or disable auditing of request data.

> [accordion] audit\_response
>
> Enable or disable auditing of response information.

> [accordion] 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`.

> [accordion] 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`.

> [accordion] 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.

> [accordion] concurrent\_kernel\_execution
>
> Enable or disable concurrent kernel execution.

> [accordion] 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`.

> [accordion] 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`.

> [accordion] request\_timeout
>
> Number of minutes after which filtering (e.g., [/filter](https://docs.kinetica.com/content/api/rest/filter_rest.md)) and
> aggregating  (e.g., [/aggregate/groupby](https://docs.kinetica.com/content/api/rest/aggregate_groupby_rest.md)) queries will time out.
> The maximum allowed value is `1440`.

> [accordion] enable\_overlapped\_equi\_join
>
> Enable or disable the overlapped-equi-join filter.

> [accordion] chunk\_size
>
> Number of records per chunk, applied to all new tables.  To disable chunking, use `0`.

> [accordion] 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.

> [accordion] 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.

> [accordion] execution\_mode
>
> Scheme to use for kernel executions.  Possible values:
>
> <table>
>   <thead>
>     <tr>
>       <th>Mode</th>
>       <th>Description</th>
>     </tr>
>   </thead>
>
>   <tbody>
>     <tr>
>       <td>`host`</td>
>       <td>Execute kernels only on the *host* (CPU)</td>
>     </tr>
>
>     <tr>
>       <td>`device`</td>
>       <td>Execute kernels only on the *device* (GPU)</td>
>     </tr>
>
>     <tr>
>       <td>`default`</td>
>       <td>Execution engine decides whether to execute kernels on the *host* or the *device*</td>
>     </tr>
>
>     <tr>
>       <td>`<rows>`</td>
>       <td>Execute kernels on the host if the chunked column contains the given number of rows or fewer; otherwise, execute on the device</td>
>     </tr>
>   </tbody>
> </table>

> [accordion] shadow\_agg\_size
>
> Maximum number of bytes in the *shadow aggregate chunk cache*.  The maximum allowed value
> is `2147483647`.

> [accordion] shadow\_filter\_size
>
> Maximum number of bytes in the *shadow filter chunk cache*.  The maximum allowed value is
> `2147483647`.

> [accordion] 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.

> [accordion] postgres\_proxy\_idle\_connection\_timeout
>
> PostgreSQL Wire Protocol service idle connection timeout, in seconds

> [accordion] postgres\_proxy\_keep\_alive
>
> Enable or disable PostgreSQL Wire Protocol service's keep alive.

> [accordion] ai\_enable\_rag
>
> Enable or disable [SQL-GPT RAG](https://docs.kinetica.com/content/sql-gpt/concepts.md#sql-gpt-overview-rag).

> [accordion] ai\_api\_provider
>
> AI API provider type

> [accordion] ai\_api\_url
>
> AI API URL

> [accordion] ai\_api\_key
>
> AI API key

> [accordion] ai\_api\_embeddings\_model
>
> AI API embeddings model name

> [accordion] ai\_api\_connection\_timeout
>
> AI API connection timeout, in seconds

> [accordion] external\_files\_directory
>
> Root directory path, on the head node of the cluster, from where external table data files
> are accessed.

> [accordion] 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`.

> [accordion] egress\_parquet\_compression
>
> Parquet file compression type.  The supported values are:
>
> * `uncompressed`
> * `snappy`
> * `gzip`

> [accordion] kafka\_batch\_size
>
> Maximum number of Kafka records to be ingested in a single batch.  The maximum allowed
> value is `10000000`.

> [accordion] kafka\_wait\_time
>
> Maximum time, in seconds, to buffer records received from Kafka before ingestion.  The
> maximum allowed value is `120`.

> [accordion] kafka\_poll\_timeout
>
> Maximum time, in milliseconds, for each poll to get records from Kafka.  The maximum
> allowed value is `1000`.

> [accordion] 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.

> [accordion] kifs\_directory\_data\_limit
>
> Default maximum capacity to apply to a newly-created KiFS directory, in bytes.  Use `-1`
> for no limit.

> [accordion] enable\_one\_step\_compound\_equi\_join
>
> Enable or disable the *one-step compound equi-join* algorithm.

> [accordion] datalake\_table\_metadata\_cache\_enabled
>
> Enable or disable caching of data lake table metadata.  When disabled, every query against
> a data lake external table reloads the table metadata from its catalog.

> [accordion] datalake\_table\_metadata\_cache\_size
>
> Maximum number of data lake table entries to retain in the metadata cache, across all
> catalogs.

> [accordion] datalake\_table\_metadata\_cache\_ttl
>
> Time-to-live, in seconds, for a cached data lake table entry.  After this, the next use
> reloads the table from its catalog.

> [accordion] datalake\_table\_metadata\_cache\_snapshot\_check
>
> Enable or disable validating a cached data lake table's snapshot or version against its
> catalog on every use, at the cost of one extra request per query.

> [accordion] datalake\_catalog\_connection\_cache\_size
>
> Maximum number of data lake catalog connections to retain.

> [accordion] iceberg\_manifest\_cache\_enabled
>
> Enable or disable caching of parsed Apache Iceberg manifest & manifest-list files.  When
> disabled, manifests are re-fetched and re-parsed on every scan.

> [accordion] file\_cache.\<cache name>.enabled
>
> Enable or disable the given [file cache](https://docs.kinetica.com/content/config.md#config-main-file-cache).  When disabled,
> reads bypass the cache and go directly to their source.

> [accordion] file\_cache.\<cache name>.max\_disk\_size
>
> Maximum size, in bytes, of the data the given file cache can hold on disk.

> [accordion] file\_cache.\<cache name>.max\_memory\_size
>
> Maximum size, in bytes, of the data the given file cache can hold in memory.

> [accordion] file\_cache.\<cache name>.stats\_window
>
> Time span, in seconds, over which the given file cache's hit & miss statistics are kept.

> [accordion] file\_cache.\<cache name>.clear
>
> Set to `true` to remove all entries from the given file cache, as with
> [CLEAR FILE CACHE](https://docs.kinetica.com/content/sql/system_properties/clear-file-cache.md#sql-clear-file-cache).  This is an action, not a setting; it is
> not retained.

> [accordion] file\_cache.\<cache name>.flush
>
> Set to `true` to move the entries the given file cache holds in memory to disk, as disk
> space allows, freeing the memory they occupied.  This is an action, not a setting; it is
> not retained.

For the `file_cache` properties, `<cache name>` is the name of a file cache
(currently, only `external_files`), or `default` to apply the change to all
file caches.  A file cache's `persistence` and `block_size` can only be
set in the [system configuration](https://docs.kinetica.com/content/config.md#config-main-file-cache), not
while the system is running.  To see a file cache's current settings, use
[DESCRIBE FILE CACHE](https://docs.kinetica.com/content/sql/system_properties/describe-file-cache.md#describe-file-cache).

## Examples

To increase the request timeout and the maximum `/get/records`
size permanently (in the startup configuration):

```sql ALTER SYSTEM SET PROPERTIES Example theme={null}
ALTER SYSTEM SET PROPERTIES (
    'request_timeout' = '25',
    'max_get_records_size' = '25000'
)
```

To set the default [embeddings model](https://docs.kinetica.com/content/vector_search.md#vector-model) until the
database is restarted:

```sql ALTER SYSTEM SET Default Embedding Model Temporarily Example theme={null}
ALTER SYSTEM SET PROPERTIES ('ai_enable_rag' = 'true')
WITH OPTIONS ('persist' = 'false')
```

To reduce the memory available to the external files
[file cache](https://docs.kinetica.com/content/config.md#config-main-file-cache) to 1 GB until the database
is restarted:

```sql ALTER SYSTEM SET File Cache Memory Limit Example theme={null}
ALTER SYSTEM SET PROPERTIES ('file_cache.external_files.max_memory_size' = '1073741824')
WITH OPTIONS ('persist' = 'false')
```

To move the entries held in memory by all file caches to disk:

```sql ALTER SYSTEM SET File Cache Flush Example theme={null}
ALTER SYSTEM SET PROPERTIES ('file_cache.default.flush' = 'true')
```


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