CockroachDB supports column-oriented ("vectorized") query execution on all CockroachDB data types.
Many SQL databases execute query plans one row of table data at a time. Row-oriented execution models can offer good performance for online transaction processing (OLTP) queries, but suboptimal performance for online analytical processing (OLAP) queries. The CockroachDB vectorized execution engine dramatically improves performance over row-oriented execution by processing each component of a query plan on type-specific batches of column data.
Configure vectorized execution
By default, vectorized execution is enabled in CockroachDB.
You can configure vectorized execution with the vectorize session variable. The following options are supported:
| Option | Description |
|---|---|
on |
Turns on vectorized execution for all queries on rows over the vectorize_row_count_threshold (0 rows, by default, meaning all queries will use the vectorized engine).Default: vectorize=on |
off |
Turns off vectorized execution for all queries. |
For information about setting session variables, see SET <session variable>.
To see if CockroachDB will use the vectorized execution engine for a query, run a simple EXPLAIN statement on the query. If vectorize is true, the query will be executed with the vectorized engine. If it is false, the row-oriented execution engine is used instead.
Set the row threshold for vectorized execution
The efficiency of vectorized execution increases with the number of rows processed. If you are querying a table with a small number of rows, it is more efficient to use row-oriented execution.
By default, vectorized execution is enabled for all queries.
For performance tuning, you can change the minimum number of rows required to use the vectorized engine to execute a query plan in the current session with the vectorize_row_count_threshold session variable.
How vectorized execution works
When you issue a query, the gateway node (i.e., the node from which you issue the query) parses the query and creates a physical plan for execution on each node that receives the plan. If vectorized execution is enabled, the physical plan is sent to each node to be executed by the vectorized execution engine.
To see a detailed view of the vectorized execution plan for a query, run the EXPLAIN(VEC) statement on the query.
For information about vectorized execution in the context of the CockroachDB architecture, see Query Execution.
For detailed examples of vectorized query execution for hash and merge joins, see the blog posts 40x faster hash joiner with vectorized execution and Vectorizing the merge joiner in CockroachDB.
Disk-spilling operations
The following disk-spilling operations require memory buffering during execution. If there is not enough memory allocated for a disk-spilling operation, CockroachDB will spill the intermediate execution results to disk.
- Global sorts
- Unordered aggregations
- Hash joins
- Merge joins on non-unique columns. Merge joins on columns that are guaranteed to have one row per value, also known as "key columns", can execute entirely in-memory.
- Window functions.
By default, the memory limit allocated per disk-spilling operation is 64MiB. This limit applies to a single operation within a single query, and is configured with the sql.distsql.temp_storage.workmem cluster setting.
To increase the limit, change the cluster setting:
SET CLUSTER SETTING sql.distsql.temp_storage.workmem = '100MiB';
Operations that do not support disk spilling ignore the sql.distsql.temp_storage.workmem limit.
The --max-disk-temp-storage flag sets the maximum on-disk storage capacity for disk spilling. If the maximum on-disk storage capacity is reached, the query will return an error during execution.
You can also configure a node's total budget for in-memory query processing with the --max-sql-memory flag at node startup. This limit applies globally to all sessions at any point in time. When this limit is exceeded by an operation, it will result in an error instead of spilling to disk. For more details on --max-sql-memory, see Cache and SQL memory size.
Known limitations
Unsupported queries
The vectorized engine does not support queries containing:
- A join filtered with an
ONexpression. See tracking issue.
Spatial features
The vectorized engine does not support working with spatial data. Queries with geospatial functions or spatial data will revert to the row-oriented execution engine.
Unordered distinct operations
Disk spilling isn't supported when running UPSERT statements that have nulls are distinct and error on duplicate markers. You can check this by using EXPLAIN and looking at the statement plan.
├── distinct | |
│ │ | distinct on | ...
│ │ | nulls are distinct |
│ │ | error on duplicate |
Yes
No