Symbol

SYMBOL is a data type designed for columns with repetitive string values. Internally, symbols use dictionary encoding—each unique string is stored once in a lookup table, and rows store integer references to that table. This is the same approach used by columnar formats like Parquet and Arrow. The result is much faster filtering and grouping compared to regular strings.

When to use SYMBOL

Use SYMBOL for categorical data with a limited set of repeated values:

• Stock tickers (AAPL, GOOGL, MSFT)
• Country or region codes (US, EU, APAC)
• Status values (pending, completed, failed)
• Device or sensor IDs
• Any column frequently used in WHERE or GROUP BY

CREATE TABLE trades (
    timestamp TIMESTAMP,
    symbol SYMBOL,        -- Good: limited set of tickers
    side SYMBOL,          -- Good: just BUY/SELL
    price DOUBLE,
    quantity DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;

When to use VARCHAR instead

Use VARCHAR when values are unique or very high cardinality:

• User-generated text (comments, descriptions)
• Log messages
• UUIDs or unique identifiers (consider the UUID type instead)
• Columns with hundreds of millions of distinct values

Why SYMBOL is fast

Symbols provide:

• Faster queries — integer comparisons instead of string operations
• Lower storage — strings stored once in a dictionary, rows store integers
• Index support — symbol columns can be indexed for even faster lookups

Creating SYMBOL columns

CREATE TABLE orders (
    timestamp TIMESTAMP,
    symbol SYMBOL,
    side SYMBOL,
    order_type SYMBOL,
    price DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;

Symbol capacity scales automatically as new values are added. No manual configuration is needed.

Prior to QuestDB 9.0.0, symbol capacity required manual configuration. You had to estimate the number of distinct values upfront and set the capacity explicitly. Undersizing caused performance issues; oversizing wasted memory.

From 9.0.0 onwards, symbol capacity is fully automatic. The CAPACITY setting is now obsolete and can be removed from your table definitions.

NOCACHE option

By default, QuestDB caches the symbol dictionary in memory for fast lookups. For columns with very high cardinality (10 million+ distinct values), this cache can consume significant memory.

Use NOCACHE to disable dictionary caching:

CREATE TABLE trades (
    timestamp TIMESTAMP,
    client_id SYMBOL NOCACHE,
    symbol SYMBOL
) TIMESTAMP(timestamp) PARTITION BY DAY;

Trade-off: NOCACHE reduces memory usage but makes dictionary lookups slower. Only use it for symbols with millions of distinct values where memory is a concern.

To toggle caching on an existing column:

-- Disable cache
ALTER TABLE trades ALTER COLUMN client_id NOCACHE;

-- Re-enable cache
ALTER TABLE trades ALTER COLUMN client_id CACHE;

Indexing symbols

For columns frequently used in WHERE clauses, add an index:

CREATE TABLE trades (
    timestamp TIMESTAMP,
    symbol SYMBOL INDEX,
    price DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;

Or add an index later:

ALTER TABLE trades ALTER COLUMN symbol ADD INDEX;

See Indexes for more information.