Configuration parameters

You can configure analytics behavior and performance using PostgreSQL configuration parameters. You can set these parameters at the session, database, user, or DB cluster parameter group level using standard PostgreSQL commands.

The following table lists all analytics configuration parameters.

aurora_analytics.enabled

Enables the aurora_analytics extension.

This parameter is the primary switch for the analytics feature. Set it to true in your DB cluster parameter group to enable the feature. Because it's a dynamic parameter, the change is applied immediately without a reboot. Once enabled, you can install the extension (CREATE EXTENSION aurora_analytics) in each database.

aurora_analytics.query_mem

(KB) Sets the maximum memory that a single aurora_analytics query can use.

This parameter controls the maximum memory that the analytics execution engine allocates for processing a single query. This memory is used for hash tables, sorting, aggregation buffers, and intermediate results. You can specify the value as a string with a unit suffix (for example, '4GB') or as an integer in kilobytes (kB), where 1 kB is 1024 bytes, following the PostgreSQL memory-unit convention.

When a query's memory usage approaches this limit, the engine spills intermediate results to temporary local storage. Spilling allows the query to complete but with reduced performance.

Default calculation

Aurora derives the default from instance memory, using the smallest of three terms:

query_mem = LEAST(
    48 GiB,                                  -- ceiling for the derived default
    DBInstanceClassMemory x 12.5%,           -- lower bound on smaller instances
    DBInstanceClassMemory x 3.125% + 8 GiB   -- lower bound on larger instances
)

The following table shows approximate default values by instance class:

These values are approximate because the derivation uses DBInstanceClassMemory, which is slightly lower than the instance class's nominal memory.

When to increase this value:

When to decrease this value:

Usage examples

Set different limits for different user roles:

-- Heavy analytics users
ALTER USER data_scientist SET aurora_analytics.query_mem = '16GB';
-- Light reporting users
ALTER USER dashboard_user SET aurora_analytics.query_mem = '8GB';

Use a session-level setting for a specific complex query:

SET aurora_analytics.query_mem = '16GB';
SELECT complex_aggregation FROM ft_large_table;
RESET aurora_analytics.query_mem;

aurora_analytics.lowercase_unquoted_column_name

Lowercases unquoted column names when inferring aurora_analytics foreign table columns.

When Aurora PostgreSQL infers the schema of a foreign table (created with empty parentheses), it reads column names from Parquet or Iceberg metadata. Parquet files often contain mixed-case column names such as OrderDate or CustomerID.

When set to true (default), column names are lowercased to follow PostgreSQL's standard unquoted identifier behavior. For example, OrderDate becomes orderdate.

When set to false, mixed-case column names are preserved. You must use double-quoted identifiers to reference them (for example, SELECT "OrderDate" FROM ft_orders).

aurora_analytics.skip_unsupported_columns

Skips columns with unsupported data types or conflicting names when inferring aurora_analytics foreign table columns.

When set to false (default), Aurora PostgreSQL raises an error if it encounters an unsupported column type during schema inference.

When set to true, unsupported columns are silently skipped. The foreign table is created with only the supported columns, allowing you to query the remaining data.

Set this parameter to true when your source data contains a mix of supported and unsupported column types and you only need a subset of columns.

aurora_analytics.enable_logging

Enables logging for aurora_analytics.

When enabled, the analytics engine writes diagnostic messages to the PostgreSQL error log at the verbosity level specified by aurora_analytics.logging_level.

aurora_analytics.logging_level

Sets detailed logging for aurora_analytics.

This parameter controls the verbosity of analytics engine messages written to the PostgreSQL error log. Use DEBUG1 or higher for troubleshooting. Use WARNING (default) or ERROR for production workloads to minimize log volume.

This parameter requires aurora_analytics.enable_logging to be set to true.

aurora_analytics.track_detailed_metrics

Collects detailed per-query performance metrics for aurora_analytics.

When enabled, Aurora PostgreSQL collects detailed per-query metrics such as cache hit ratios and data transfer statistics. You can retrieve these metrics using the analytics statistics functions.

Enable this parameter when you need to analyze cache performance or diagnose slow queries. For more information, see Resource management.