📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

CREATE WAREHOUSE

Creates a new warehouse for compute resources.

Syntax

CREATE WAREHOUSE [ IF NOT EXISTS ] <warehouse_name>
    [ WITH ] warehouse_size = <size>
    [ WITH ] auto_suspend = <nullable_unsigned_number>
    [ WITH ] initially_suspended = <bool>
    [ WITH ] auto_resume = <bool>
    [ WITH ] max_cluster_count = <nullable_unsigned_number>
    [ WITH ] min_cluster_count = <nullable_unsigned_number>
    [ WITH ] comment = '<string_literal>'
    [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] )
ParameterDescription
IF NOT EXISTSOptional. If specified, the command succeeds without changes if the warehouse already exists.
warehouse_name3–63 characters, containing only A-Z, a-z, 0-9, and -.

Options

OptionType / ValuesDefaultDescription
WAREHOUSE_SIZEXSmall, Small, Medium, Large, XLarge, 2XLarge–6XLarge (case-insensitive)SmallControls compute size.
AUTO_SUSPENDNULL, 0, or ≥300 seconds600 secondsIdle timeout before automatic suspend. 0/NULL means never suspend; values below 300 are rejected.
INITIALLY_SUSPENDEDBooleanFALSEIf TRUE, the warehouse remains suspended after creation until explicitly resumed.
AUTO_RESUMEBooleanTRUEControls whether incoming queries wake the warehouse automatically.
MAX_CLUSTER_COUNTNULL or non-negative integer0Upper bound for auto-scaling clusters. 0 disables auto-scale.
MIN_CLUSTER_COUNTNULL or non-negative integer0Lower bound for auto-scaling clusters; should be ≤ MAX_CLUSTER_COUNT.
COMMENTStringEmptyFree-form text surfaced by SHOW WAREHOUSES.
TAGKey-value pairs: TAG ( key1 = 'value1', key2 = 'value2' )NoneResource tags for categorization and organization (similar to AWS tags). Used for cost allocation, environment identification, or team ownership.
  • Options may appear in any order and may repeat (the later value wins).
  • AUTO_SUSPEND, MAX_CLUSTER_COUNT, and MIN_CLUSTER_COUNT accept = NULL to reset to 0.

Examples

This example creates an XLarge warehouse with auto-scaling and custom settings:

CREATE WAREHOUSE IF NOT EXISTS 'etl-wh'
    WITH warehouse_size = XLarge
    auto_suspend = 600
    initially_suspended = TRUE
    auto_resume = FALSE
    max_cluster_count = 4
    min_cluster_count = 2
    comment = 'Nightly ETL warehouse'
    TAG (environment = 'production', team = 'data-engineering', cost_center = 'analytics');

This example creates a basic Small warehouse:

CREATE WAREHOUSE 'my-warehouse'
    WITH warehouse_size = Small;

Was this page helpful?