nikodem.czarlinski
08/17/2026, 8:13 PMRocky
08/17/2026, 8:14 PMwarehouse_az_a with CNs located in AZ-A and warehouse_az_b with CNs in AZ-B.
* Session Pinning: You can pin a session to a specific warehouse using a session variable:
sql
SET warehouse = 'warehouse_az_a';
* Avoiding Shuffle: When a warehouse is specified, StarRocks schedules all query fragments (including joins and aggregations) only on the CNs within that group. This ensures that all data shuffle occurs over the local high-speed network within the AZ, avoiding cross-AZ egress costs and latency.
* Proxy Automation: You can use a proxy like ProxySQL or an AZ-aware load balancer to handle this automatically:
* ProxySQL: Configure rules to detect the source or target and automatically execute the SET warehouse command upon connection.
* Application Logic: Have your application detect its own AZ and set the appropriate warehouse in the connection string or initialization SQL.
2. Shared-nothing Architecture (BE Nodes)
In the traditional shared-nothing architecture, pinning a session to one AZ is more difficult because data is physically stored on specific BE nodes.
* The Challenge: Even if you pin a session to a "local" FE, that FE must schedule tasks on the BEs that actually hold the data. If your data replicas are distributed across AZs for high availability (which is standard), a query will naturally involve BEs in multiple AZs, leading to cross-AZ shuffle.
* Possible Mitigation: You can use BE Labels and Resource Groups to influence placement, but it is primarily designed for data redundancy (rack awareness) rather than session-based compute pinning. To avoid shuffle here, you would typically rely on Colocate Joins, which keep joined data on the same node regardless of the AZ.
Summary for Implementation
If your goal is to eliminate cross-AZ shuffle costs for arbitrary queries:
1. Deploy in Shared-data mode.
2. Organize CNs into Warehouses based on their physical AZ.
3. Use an AZ-aware Proxy (like ProxySQL) to set the warehouse session variable based on the client's location.
4. Result: Queries will pull data from shared storage (like S3/Azure Blob/HDFS) into the local AZ cache and perform all computation/shuffling within that AZ-shuffling within that AZ.
References
• sql-reference/sql-statements/cluster-management/resource_group/CREATE_RESOURCE_GROUP.md
• administration/management/resource_management/resource_group.mdnikodem.czarlinski
08/17/2026, 8:23 PMnikodem.czarlinski
08/17/2026, 8:29 PMRocky
08/17/2026, 8:29 PMwarehouse_a and CNs in AZ-B to warehouse_b.
2. Pin Session: Use an AZ-aware proxy or application logic to detect the client's AZ and run SET warehouse = 'warehouse_a'; at the start of the session.
3. Local Shuffle: All query fragments, including joins and aggregations, will be scheduled only on the CNs within that warehouse. Shuffling happens locally within the AZ.
──────────
Relevant Documentation Pointers
* Warehouse Session Management:
The SET WAREHOUSE command is used to switch the compute resource for the current session. You can verify the active warehouse using the current_warehouse() function.
* Utility Functions: current_warehouse()
* Shared-data Architecture Overview:
Since warehouses require a shared-data deployment (where data is stored in S3/HDFS), you should first understand the underlying architecture and CN management.
* Shared-data Architecture
* Deploy Shared-data StarRocks
* Monitoring & Information Schema:
You can track warehouse-specific query performance and resource usage via the information_schema.
* information_schema.warehouse_metrics
* information_schema.warehouse_queries
Implementation Strategy
If you are using a proxy like ProxySQL, you can automate the pinning by configuring query rules. For example, if a connection comes from a specific subnet (AZ-A), the proxy can automatically prepend SET warehouse = 'az_a_wh'; to the first query or execute it upon connection.
Note on Shared-nothing (BEs):
In traditional Shared-nothing mode, data is physically bound to BE nodes. Pinning a session to an AZ is harder because the FE must schedule tasks where the data resides. To avoid shuffle here, you would typically use Colocate Joins rather than warehouse isolation-than warehouse isolation.
References
• administration/management/monitoring/metrics-shared-data.md
• administration/management/resource_management/Replica.md
• administration/management/compaction.md
• administration/management/BE_configuration.md
• quick_start/shared-data.mdnikodem.czarlinski
08/17/2026, 8:41 PMRocky
08/17/2026, 8:41 PMsql
CREATE WAREHOUSE warehouse_az_a;
CREATE WAREHOUSE warehouse_az_b;
2. Add CNs to the Respective Warehouse
When adding a Compute Node to the cluster, specify which warehouse it should belong to. If the CN is already in the cluster, it typically resides in the default_warehouse.
To add a new CN directly into a specific warehouse:
sql
ALTER SYSTEM ADD COMPUTE NODE "10.0.1.10:9050" INTO WAREHOUSE warehouse_az_a;
ALTER SYSTEM ADD COMPUTE NODE "10.0.2.10:9050" INTO WAREHOUSE warehouse_az_b;
To move or manage existing CNs:
Currently, StarRocks management of warehouses involves adding nodes to the system and assigning them. You can verify the assignment using:
sql
SHOW COMPUTE NODES;
-- Or to see nodes in a specific warehouse
SHOW NODES FROM WAREHOUSE warehouse_az_a;
3. Pin Query Sessions to the Local AZ
To ensure a query session only uses nodes within its local AZ (avoiding cross-AZ network shuffle), your proxy or application must set the warehouse session variable upon connection.
Manual set:
sql
SET warehouse = 'warehouse_az_a';
Automated (ProxySQL Example):
If you use ProxySQL as your AZ-aware load balancer, you can create a mysql_query_rules entry that detects the incoming connection (e.g., based on the proxy's own IP or a specific user) and executes the SET warehouse command automatically.
Why this avoids Network Shuffle costs:
In StarRocks' MPP architecture, shuffling occurs when data is redistributed across nodes for joins or aggregations. By pinning the session to warehouse_az_a, the FE (Frontend) scheduler is restricted to only using the CNs within that warehouse for all fragments of the query.
* Result: All "shuffling" happens between nodes in the same AZ.
* Data Access: Because this is Shared-data mode, all CNs can see the same data in S3/HDFS. They will simply pull the data into their local AZ-specific cache.
Important Notes:
* Shared-data Only: This multi-warehouse functionality requires StarRocks to be deployed in Shared-data mode. In traditional Shared-nothing mode, you cannot logically group BEs into warehouses this way because data is physically tied to the nodes.
* Default Warehouse: Every cluster starts with a default_warehouse. If you don't specify a warehouse in your session, queries default to this group.
* Checking Current Warehouse: You can check which warehouse your session is currently using with: SELECT current_warehouse();
References
• sql-reference/sql-functions/utility-functions/current_warehouse.md
• sql-reference/information_schema/warehouse_queries.md
• sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_COMPUTE_NODES.md
• sql-reference/sql-statements/cluster-management/nodes_processes/ALTER_SYSTEM.md
• sql-reference/information_schema/warehouse_metrics.md
References
• sql-reference/sql-statements/Database/ALTER_DATABASE.md
• sql-reference/sql-statements/Resource/ALTER_RESOURCE.mdnikodem.czarlinski
08/18/2026, 9:13 AMRocky
08/18/2026, 9:14 AMwarehouse_az_a but connect to an FE_in_az_b, the result data will have to travel from the CNs in AZ-A to the FE in AZ-B before going to your client, incurring cross-AZ egress costs at the final step.
References
• unloading/arrow_flight.md
• sql-reference/http_sql_api.md
• introduction/Architecture.md
• best_practices/query_tuning/query_planning.md
References
• sql-reference/http_sql_api.md
• unloading/arrow_flight.mdnikodem.czarlinski
08/18/2026, 12:27 PMRocky
08/18/2026, 12:28 PMCREATE WAREHOUSE and SET warehouse features were primarily part of the Enterprise edition. However, there has been a significant shift in the project's direction recently.
As of the StarRocks Summit (September 2025), it was announced that the Multi-warehouse (Compute Group) and StarOS features are being open-sourced. If you are using a version released after late 2025 (such as StarRocks v4.0 or later), these features should be available in the Community Edition.
If you are stuck on v3.3 Community Edition, here are the open-source strategies to achieve AZ-aware compute and avoid cross-AZ network shuffle:
1. The "Multi-Cluster" Lakehouse Approach (Best for Lakehouse)
If your primary workload involves querying data in S3/HDFS via External Catalogs (Iceberg, Hive, Delta Lake), the best open-source solution is to deploy two entirely separate StarRocks clusters:
* Cluster A in AZ-A and Cluster B in AZ-B.
* Both clusters point to the same S3 bucket.
* Result: Each cluster operates independently. There is zero network shuffle between AZs because each cluster is an island. They simply share the same underlying data source. Each cluster maintains its own local cache in its respective AZ.
2. Using Resource Groups with Node Tags (Shared-Nothing/Internal Tables)
In the Community Edition, you can use Resource Groups combined with BE node tags to influence where queries run. While not as dynamic as Warehouses, this allows for physical isolation.
1. Tag your BEs: Assign a tag to nodes based on their AZ.
sql
ALTER SYSTEM MODIFY BACKEND "10.0.1.10:9050" SET ("tag.location" = "az_a");
2. Create Resource Groups: Create groups that are restricted to specific tags.
sql
CREATE RESOURCE GROUP group_az_a
PROPERTIES (
"node_tag" = "az_a",
"cpu_core_limit" = "10"
);
3. Classify Queries: Use a classifier to route users or roles to that group.
sql
CREATE USER 'user_az_a'@'%' IDENTIFIED BY 'password';
CREATE RESOURCE GROUP CLASSIFIER cls_a
FOR 'user_az_a' TO group_az_a;
* Limitation: This is more static and requires managing users/roles to determine the AZ affinity, whereas the Warehouse feature allows a simple SET warehouse at the session level.
3. AZ-Aware Load Balancing with FE Proxy
Regardless of the compute grouping, you must ensure the "Final Aggregate" doesn't cross AZs.
* The FE Bottleneck: Even if you isolate CNs, if a client in AZ-A connects to an FE in AZ-B, the result set must travel across AZs.
* Solution: Use an AZ-aware proxy (like HAProxy or ProxySQL) configured with stickiness or subnet routing.
* Route clients from AZ-A subnets to FE nodes in AZ-A.
* Route clients from AZ-B subnets to FE nodes in AZ-B.
Summary Recommendation
* If you can upgrade: Move to v4.0+ where Multi-warehouse is open-source. This allows you to use the SET warehouse command exactly as you intended.
* If you are on v3.3 Community: Use the Multi-Cluster approach for External Catalogs, or Resource Groups with Node Tags for internal tables to provide a level of compute isolation.
References
* StarRocks Summit 2025: Open Sourcing Multi-Warehouse
* Resource Group: Node Tagging
* Shared-data Architecture Overview
References
• release_notes/release-3.3.mdnikodem.czarlinski
08/18/2026, 12:34 PMRocky
08/18/2026, 12:35 PMCREATE WAREHOUSE and ALTER SYSTEM ... INTO WAREHOUSE features are indeed unavailable, as they rely on the Enterprise-only multi-warehouse management layer.
To achieve AZ-aware compute and avoid cross-AZ network shuffle costs today without Enterprise, you should use the Multi-Cluster Shared-Data Architecture.
1. Multi-Cluster Shared-Data Approach
In StarRocks' shared-data mode, the state (data) is decoupled from the compute nodes. You can solve the AZ grouping problem by deploying two (or more) completely independent StarRocks clusters that point to the same underlying storage.
* Cluster A (AZ-A): Deploy 1 FE and 3 CNs in AZ-A. Configure them to point to your S3 bucket.
* Cluster B (AZ-B): Deploy 1 FE and 3 CNs in AZ-B. Point them to the exact same S3 bucket and path.
* How it works: Because all data is in S3, Cluster B will "see" every table and every piece of data created by Cluster A. There is no "shuffling" between Cluster A and Cluster B because they are separate clusters with separate internal RPC networks.
* Benefit: 100% physical isolation. Queries on Cluster A only use AZ-A compute nodes.
2. Implementation Steps
1. Storage Volume: Ensure both clusters are configured with the same storage_volume settings in fe.conf.
2. Metadata: Note that FEs do not share metadata automatically in this mode. You have two options:
* Manual Sync: Run DDLs (Create Table) on both clusters. Since the data is on S3, once the table is created on Cluster B, it will see the data Cluster A has written.
* External Catalog: Use an external Hive/Glue/Iceberg catalog. Both clusters connect to the same Glue/Hive Metastore. This is the most common way to share data across multiple "open-source" StarRocks clusters.
3. Route via AZ-Aware Proxy
To make this transparent to your application, use a proxy like ProxySQL or HAProxy to route traffic based on the client's AZ:
* Configure ProxySQL with two hostgroups (one for FE-AZ-A, one for FE-AZ-B).
* Route application traffic from AZ-A to the AZ-A hostgroup.
* Result: The application remains AZ-local for both the FE connection and the subsequent CN-to-CN shuffle.
4. Why "Resource Groups" won't work for this
In the open-source version, Resource Groups are logical limits within each node. You cannot use them to tell a query "Only use nodes 1, 2, and 3." The StarRocks scheduler in the Community Edition will always attempt to use all available nodes in the cluster to maximize parallelism, which is what causes the cross-AZ shuffle you are trying to avoid.
Summary of Differences
Feature | Enterprise (v3.3+) | Open Source (v3.3)
Logic | Multiple warehouses in 1 cluster | Multiple independent clusters
Metadata | Shared automatically | Shared via External Catalog or manual DDL
Shuffle | Isolated via SET warehouse | Isolated by cluster boundary
Management | Single point of management | Manage 2+ separate clusters
Note on the future: StarRocks has announced that the Multi-warehouse and StarOS features are being open-sourced. These are expected to land in v4.0, which will allow you to use the WAREHOUSE syntax in the Community Edition. If you can wait for a later release.
References
• administration/management/resource_management/resource_group.md
• faq/resource_isolation_faq.mdnikodem.czarlinski
08/18/2026, 12:36 PMRocky
08/18/2026, 12:36 PMmeta directory. In the open-source version, there is no built-in mechanism to sync metadata between two distinct FE groups.
* Solution: You would have to manually run identical DDLs (CREATE TABLE) on both clusters. As long as the table structure and S3 paths are identical, Cluster B will be able to read data written by Cluster A.
3. Why "One Cluster + Two AZs" is difficult in OS
If you put all CNs into one cluster (shared FEs) in the open-source version:
* Cross-AZ Shuffle: During a JOIN or Aggregation, StarRocks will frequently send data from a CN in AZ-A to a CN in AZ-B because the scheduler does not have AZ-affinity logic in the Community Edition.
* Resource Groups: While you can use Resource Groups to limit CPU/Memory, they apply uniformly to all nodes in the cluster. You cannot currently use them to say "Users from AZ-A should only use CNs 1, 2, and 3."
Summary Recommendation
To solve your problem without the Enterprise Warehouse feature:
1. Deploy two independent clusters (separate FEs and CNs) in each AZ.
2. Point both to a common External Catalog (Glue/Hive/Iceberg) for data sharing.
3. Use an AZ-aware Load Balancer (like ProxySQL or an AWS NLB with AZ-affinity) to ensure clients in AZ-A talk to the FE in AZ-A.
Future Note: The StarRocks project has announced that the "Multi-Warehouse" architecture (which allows one FE group to manage isolated "Warehouses" or Compute Groups) is being open-sourced in v4.0. Once that version is released, you will be able to solve this within a single cluster.
References
• introduction/Architecture.md
• deployment/shared_data/s3.md
• administration/management/resource_management/resource_group.md
• administration/management/resource_management/Load_balance.md
References
• introduction/Architecture.mdRocky
08/18/2026, 12:36 PMnikodem.czarlinski
08/18/2026, 12:39 PMnikodem.czarlinski
08/18/2026, 12:39 PMRocky
08/18/2026, 12:40 PMSET warehouse = 'warehouse_a', the FE simply filters its internal list of available CNs and only sends the query tasks to the nodes belonging to warehouse_a.
* Result: There is no "sharing between FEs" because the FEs are already part of the same unified "brain."
2. The Open Source "Multi-Cluster" Approach (Separate FE Clusters)
If you are using the Open Source version and deploying two independent clusters to achieve AZ isolation (e.g., Cluster A in AZ-A and Cluster B in AZ-B), the FEs do not share metadata or data natively.
To make them "share" data, you must use an External Metastore as the bridge:
* The Bridge (Glue/Hive Metastore): Both Cluster A and Cluster B are configured to use the same External Catalog (e.g., an Iceberg catalog or Hive catalog pointing to AWS Glue).
* How it works:
1. Cluster A writes data to S3 and updates the Glue Metastore.
2. *Cluster B*'s FE periodically polls the Glue Metastore (controlled by the enable_background_refresh_connector_metadata setting).
3. Cluster B now "sees" the new data files in S3 and can query them using its own local CNs.
* Result: Data is shared via S3, and metadata is shared via Glue/Hive. The FE nodes of Cluster A never talk directly to the FE nodes of Cluster B.
Summary Table
Feature | Integrated Multi-Warehouse | Multi-Cluster (OS Workaround)
FE Architecture | Unified: One group of FEs for all CNs. | Isolated: Each cluster has its own FEs.
Metadata Sharing | Internal (BDB JE replication). | External (Glue, Hive, or Iceberg Metastore).
Data Sharing | Shared S3/HDFS storage. | Shared S3/HDFS storage.
Consistency | Instant (Strong consistency). | Eventual (based on metastore refresh interval).
Recommendation: Since you are looking for an Open Source solution, the most reliable way to "share" between two isolated AZ-local compute groups is to point both clusters to a Global External Catalog (like Glue or Hive). This allows you to have a "Warehouse A" (Cluster A) and "Warehouse B" (Cluster B) that stay perfectly isolated for network shuffle but still query the same data lake.
References
• introduction/Architecture.md
• table_design/table_design.md
• quick_start/shared-data.md
• data_source/catalog/iceberg/iceberg_catalog.mdRocky
08/18/2026, 12:40 PMSET warehouse = 'warehouse_b') and run a query, the FE looks at the same metadata, generates a query plan, and sends it to the CNs in Warehouse B.
* Data Access: The CNs in Warehouse B then pull the required data blocks directly from the shared S3 bucket.
3. StarOS (The Coordination Layer)
Internally, StarRocks uses a service called StarOS (often running within the FE or as a sidecar) to coordinate data access.
* StarOS keeps track of where data "shards" are located in the remote storage.
* It ensures that even though Warehouse A and Warehouse B are physically isolated compute resources, they have a consistent view of the data because they both talk to the same StarOS/FE metadata layer.
Why this solves your AZ problem
If you use the Multiple Warehouse approach (which is moving to Open Source in v4.0):
1. You create Warehouse_AZ_A (CNs in AZ-A) and Warehouse_AZ_B (CNs in AZ-B).
2. Your FEs (the same set for both) are aware of both groups.
3. When a query is pinned to Warehouse_AZ_A, the FE ensures that all "shuffling" and computation happens only between CNs in AZ-A.
4. Data is "shared" because both warehouses can read the same S3 files, but their compute/network traffic never crosses the AZ boundary during query execution.
Summary of the Flow
1. FE (Metadata): Single source of truth for both warehouses.
2. S3 (Data): Single source of truth for all data files.
3. Warehouses (Compute): Isolated "islands" of CNs that pull from S3 and report to the same FE.
Note for Open Source Users: Since the native Warehouse management is currently an Enterprise feature (until v4.0), the only way to "share" data between two separate Open Source clusters today is via an External Catalog (Iceberg/Hive) as mentioned previously, because two separate clusters cannot share the same FE nodes.nikodem.czarlinski
08/18/2026, 1:19 PMRocky
08/18/2026, 1:19 PMCREATE WAREHOUSE and high-efficiency Shared-Data features to the Community Edition.
References
• introduction/Architecture.md
• table_design/table_design.md
• deployment/shared_data/feature-support-shared-data.md
• quick_start/shared-nothing.md