< Rocky> how to know pipeline dop size for my query if pipel StarRocks #questions-and-troubleshooting

Join Slack

<@U0A71G31CDV> how to know pipeline dop size for m...

# questions-and-troubleshooting

RonJay

06/30/2026, 1:23 AM

@Rocky how to know pipeline dop size for my query if pipeline_dop is set default.

Rocky

06/30/2026, 1:24 AM

When

pipeline_dop

is set to the default value of

, StarRocks automatically determines the parallelism for your query. How the Default DOP is Calculated The effective DOP is generally determined by the following logic: * Default Calculation: It usually defaults to half the number of physical CPU cores on the Backend (BE) nodes. * Adaptive Capping (v3.2.0+): StarRocks introduced

max_pipeline_dop

(default is 64) as an upper bound. The effective DOP is calculated as

min(max_pipeline_dop, backend_default_dop)

. * Adaptive Adjustment: Since v3.0, StarRocks can also adaptively adjust this variable based on the system's overall query concurrency and resource pressure. How to Find the Actual DOP for Your Query Since the value is calculated dynamically, the best way to see the exact DOP used for a specific query is to check the Query Profile. Method 1: Using
EXPLAIN ANALYZE
This is the simplest way to execute a query and immediately see its execution details.

Copy code

sql
EXPLAIN ANALYZE <your_query>;

In the output, look for the Pipeline section. You will see a metric named DegreeOfParallelism. Method 2: Using the Query Profile If you have already run the query, you can retrieve its profile: 1. Enable profiling (if not already enabled):

Copy code

sql
    SET enable_profile = true;

2. Run your query, then get the `query_id`:

Copy code

sql
    SELECT last_query_id();

3. View the profile:

Copy code

sql
    SELECT get_query_profile('your_query_id_here')\G

4. Locate the metric: Search for DegreeOfParallelism
within the

Pipeline

level of the profile text. Method 3: Via FE Web UI 1. Navigate to

http://<FE_IP>:<FE_HTTP_PORT>/query

in your browser. 2. Find your query in the list and click the Profile link. 3. Look for the DegreeOfParallelism metric in the visualized or text-based profile. Key Metrics to Look For * DegreeOfParallelism: The parallelism of a single pipeline instance on a BE. * TotalDegreeOfParallelism: The sum of DOP across all instances of that pipeline (if it runs on multiple BEs multiple BEs). References • best_practices/query_tuning/query_profile_operator_metrics.md • sql-reference/System_variable.md • best_practices/query_tuning/query_planning.md • knowledge/usage/best-practice.md • best_practices/query_tuning/query_profile_overview.md • faq/Sql_faq.md

RonJay

06/30/2026, 4:42 AM

@Rocky Tell me description of exec_mem_limit, and query_mem_limit. whats difference

Rocky

06/30/2026, 4:42 AM

Both

exec_mem_limit

and

query_mem_limit

are used to control the memory consumption of queries in StarRocks, but they operate at different levels of granularity and are used in different execution contexts. 1.
query_mem_limit
(Per-Query per-BE) * Description: This variable sets the memory limit for a single query on each Backend (BE) node. * Scope: It is a cumulative limit for all tasks/instances of that specific query running on a single BE. * Context: It specifically takes effect when the Pipeline Engine is enabled (which is the default from StarRocks 2.3+). * Default:

(In recent versions,

typically means it defaults to the value of

exec_mem_limit

). * Best Practice: Use this to prevent a single complex query from exhausting all memory on a BE node. If you see "Memory Exceed Limit" errors for a query, this is often the variable you should increase. 2.
exec_mem_limit
(Per-Instance or Fallback) * Description: Historically, this was the primary variable for query memory limits. In modern StarRocks versions using the Pipeline Engine, it often acts as the limit for a single fragment instance or as a fallback for

query_mem_limit

. * Scope: If multiple "instances" of a query are running on one BE (controlled by

pipeline_dop

), each instance is restricted by this limit. * Default: Typically

2GB

(or

2147483648

bytes). * Behavior: If

query_mem_limit

is set to

, StarRocks uses

exec_mem_limit

to bound the memory. ────────── Key Differences Feature | query_mem_limit
| exec_mem_limit
Granularity | Per-Query on each BE node. | Per-Instance (or fragment) on each BE node. Total Memory | Caps the sum of all memory used by the query on that BE. | The total query memory can be

exec_mem_limit * number_of_instances

. Engine | Specific to the Pipeline Engine. | Applies to both the old engine and Pipeline Engine. Primary Use | The modern way to limit a query's total BE footprint. | Older variable; now often acts as a per-thread/instance limit. Summary Example If you have a query running with a

pipeline_dop

of 8 (meaning 8 parallel instances on a BE): * If

exec_mem_limit = 2G

and `query_mem_limit = 0`: The query could theoretically use up to 16GB on that BE (8 instances * 2GB). _ If

exec_mem_limit = 2G

and `query_mem_limit = 4G`: The query will be killed if the _combined* memory of all 8 instances exceeds 4GB, even if no single instance reached 2GB. Recommendation: For most modern StarRocks use cases, tune

query_mem_limit

to control query memory usage. References • faq/resource_isolation_faq.md • sql-reference/System_variable.md • faq/Sql_faq.md • administration/management/resource_management/Memory_management.md • administration/management/resource_management/resource_group.md

RonJay

06/30/2026, 4:50 AM

@Rocky what is load_mem_limit

Rocky

06/30/2026, 4:50 AM

load_mem_limit

is a configuration used to control the memory consumption of data loading (import) operations on each Backend (BE) node. It acts as a safeguard to prevent a single large load job from consuming too much memory and impacting the stability of the BE. 1. How it works * Scope: It limits memory on a per-job, per-BE basis. If a load job runs across three BEs and

load_mem_limit

is set to 2GB, the job can use up to 2GB on each of those BEs. * Default Value: Usually

(which typically falls back to

exec_mem_limit

query_mem_limit

) or

2GB

depending on the context. 2. Usage in Different Scenarios The behavior of

load_mem_limit

depends on the loading method you are using: * INSERT INTO ... SELECT
: * This operation has two parts: the query (selecting data) and the load (writing data). * If

load_mem_limit

is set to

, StarRocks uses

exec_mem_limit

(or

query_mem_limit

) for the entire operation. * If you set a specific value for

load_mem_limit

, the query part is limited by

exec_mem_limit

, while the import (writing) part is limited by

load_mem_limit

. * Broker Load: * You can specify this limit within the

PROPERTIES

of the load command:

Copy code

sql
        LOAD LABEL my_label ...
        PROPERTIES ("load_mem_limit" = "2147483648"); -- 2GB

* Stream Load / Routine Load: * These generally follow the session variable

load_mem_limit

or the BE configuration

default_load_mem_limit

. 3. Difference from other "Load" limits It is important to distinguish

load_mem_limit

from the system-wide load limits: * load_mem_limit
: Limits one specific load job. * load_process_max_memory_limit_percent
: A BE configuration (default 30%) that limits the total memory consumed by all concurrent load jobs on that BE node. If this total limit is hit, StarRocks will trigger backpressure or flush data to disk to free up memory. Summary of Differences Variable | Target | Common Use Case load_mem_limit
| Single load job (per BE) | Preventing a single massive

INSERT

Broker Load

from crashing a node. query_mem_limit
| Single query (per BE) | Limiting memory for

SELECT

queries. exec_mem_limit
| Per-instance/Fallback | The legacy/baseline memory limit for both queries and loads. Tip: If you encounter "Memory Limit Exceeded" errors during a large

INSERT INTO ... SELECT

operation, try increasing both

query_mem_limit

(for the read phase) and

load_mem_limit

(for the write phase). References • sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md • sql-reference/System_variable.md • loading/loading_introduction/loading_considerations.md • administration/management/resource_management/Memory_management.md • administration/management/BE_configuration.md

RonJay

06/30/2026, 5:00 AM

@Rocky so, number of fagments and pipeline is always equal?

Rocky

06/30/2026, 5:00 AM

No, the number of Fragments and Pipelines is not always equal. They represent different layers of the StarRocks execution hierarchy. Think of it this way: a Fragment is a "logical slice" of the query plan, while a Pipeline is a "physical execution chain" inside that fragment. 1. The Relationship * Fragment: A query is split into fragments based on data distribution (e.g., scanning a table, joining tables, or aggregating). Each fragment runs on one or more Backend (BE) nodes as "Fragment Instances." * Pipeline: Inside each fragment instance, StarRocks further breaks down the work into one or more pipelines. A fragment is split into multiple pipelines whenever it encounters a "pipeline breaker" (a blocking operator). * Pipeline Driver: This is where

pipeline_dop

comes in. For every Pipeline, StarRocks creates

drivers (where

pipeline_dop

) to run that specific pipeline in parallel across CPU cores. 2. Why a Fragment might have multiple Pipelines A single fragment will be split into multiple pipelines if one operation must wait for another to complete. Example: A Hash Join Fragment If you have a fragment performing a Hash Join: 1. Pipeline A (Build Phase): Reads data from the right table and builds a Hash Table in memory. 2. Pipeline B (Probe Phase): Reads data from the left table and "probes" the Hash Table created by Pipeline A. In this case, you have 1 Fragment containing 2 Pipelines. If your

pipeline_dop

is 8, StarRocks will run 8 drivers for Pipeline A and 8 drivers for Pipeline B. 3. Summary of Hierarchy * Query $\rightarrow$ split into multiple Fragments. * Fragment $\rightarrow$ split into one or more Pipelines (due to blocking operators). * Pipeline $\rightarrow$ run as multiple Drivers (the number of drivers =

pipeline_dop

). How to see this in your query? If you look at a Query Profile, you will see this hierarchy clearly:

Copy code

text
Fragment 0
  Pipeline 0
     DegreeOfParallelism: 16
  Pipeline 1
     DegreeOfParallelism: 16
Fragment 1
  Pipeline 0
     DegreeOfParallelism: 16

In this example, the query has 2 fragments, and Fragment 0 actually contains 2 different pipelines. Both are running with a DOP of 16. References • best_practices/query_tuning/query_planning.md • introduction/Features.md • faq/resource_isolation_faq.md • administration/management/resource_management/resource_group.md • sql-reference/System_variable.md • best_practices/query_tuning/query_profile_overview.md • best_practices/query_tuning/query_profile_operator_metrics.md • faq/Sql_faq.md • best_practices/query_tuning/query_planning.md • introduction/Features.md • faq/resource_isolation_faq.md • administration/management/resource_management/resource_group.md • sql-reference/System_variable.md • best_practices/query_tuning/query_profile_overview.md

Rocky

06/30/2026, 5:00 AM

• best_practices/query_tuning/query_profile_operator_metrics.md • faq/Sql_faq.md References • best_practices/query_tuning/query_planning.md • best_practices/partitioning.md • introduction/Features.md • knowledge/usage/best-practice.md • release_notes/release-3.2.md • faq/resource_isolation_faq.md • unloading/Spark_connector.md

RonJay

06/30/2026, 6:01 AM

@Rocky is there any option for handle disk size for cache or spill size of cn (shared data) using system variable or fe conf or cn conf?

Rocky

06/30/2026, 6:02 AM

Yes, you can manage both the Data Cache (for shared-data/data lake queries) and Spill to Disk (for intermediate results during memory-intensive queries) on CN nodes using CN/BE configurations and system variables. 1. Handling Data Cache Disk Size (Shared-Data) In shared-data mode, CN nodes cache data locally to speed up access to remote storage (S3/HDFS). * Cache Directory: Defined in

cn.conf

storage_root_path

. The cache is stored in

<storage_root_path>/starlet_cache

. * Cache Size Limit: Controlled by two parameters in

cn.conf

. StarRocks takes the larger of the two values: * datacache_disk_size
: Specifies an absolute size (e.g.,

100GB

). * starlet_star_cache_disk_size_percent
: Specifies the percentage of total disk capacity (Default:

). * Table-level Control: You can disable or enable cache for specific tables using the table property

"datacache.enable" = "true/false"

. 2. Handling Spill Size (Intermediate Results) When a query exceeds its memory limit, StarRocks can "spill" intermediate data (sorts, joins, aggregates) to disk. * Spill Directory: Defined in

cn.conf

(or

be.conf

) using: * spill_local_storage_dir
: The primary path for local spill files (e.g.,

/data1/spill;/data2/spill

). * query_scratch_dirs
: (Introduced in v3.2) A comma-separated list of writable scratch directories for spilling. * Enabling Spilling: * enable_spill
: A system/session variable. Set

SET enable_spill = true;

to allow the query to use the disk when memory is tight. * spill_mode
: Can be set to

auto

(default) or

force

. * Remote Spilling (v3.3+): If local disk space is insufficient, you can spill to object storage (like S3) by setting: *

SET enable_spill_to_remote_storage = true;

SET spill_storage_volume = 'your_volume_name';

storage_root_path

| Root directory for local cache. Cache | CN Conf |

starlet_star_cache_disk_size_percent

| % of disk allowed for cache (Default 80%). Cache | System Var |

populate_datacache_mode

| Controls how/when the cache is populated. Spill | CN Conf |

spill_local_storage_dir

| Local disk paths for spilling data. Spill | System Var |

enable_spill

| Must be

true

for any query to spill to disk. Spill | System Var |

spill_mem_limit_threshold

| Memory threshold (0 to 1) to trigger spilling. Important Note: Currently, StarRocks does not support a hard "per-query" disk size limit for local spilling. The

spill_local_storage_dir

is shared by all concurrent queries on that CN. Forcing multiple large spills simultaneously could exhaust the physical disk space. References • administration/management/resource_management/spill_to_disk.md • sql-reference/System_variable.md • administration/management/BE_configuration.md • knowledge/usage/best-practice.md

RonJay

06/30/2026, 6:10 AM

@Rocky how to setup datacache_disk_size without any restart cluster

Rocky

06/30/2026, 6:10 AM

You can modify

datacache_disk_size

dynamically without restarting the cluster by using the

UPDATE be_configs

SQL command. 1. Dynamic Update (Immediate Effect) To adjust the cache disk size for all nodes or a specific node while the cluster is running, execute the following SQL in your MySQL client: For all BE/CN nodes:

Copy code

sql
UPDATE be_configs SET VALUE = "500G" WHERE NAME = "datacache_disk_size";

For a specific node (using its BE ID):

Copy code

sql
-- You can find the BE_ID using 'SHOW BACKENDS'
UPDATE be_configs SET VALUE = "1T" WHERE NAME = "datacache_disk_size" AND BE_ID = 10005;

2. Make it Permanent (Persist after Restart) Changes made via

UPDATE be_configs

are not persistent. If a node restarts, it will revert to the value defined in its configuration file. After running the SQL command above, you must manually update the

cn.conf

(for Compute Nodes) or

be.conf

(for Backend nodes) on each server:

Copy code

properties
# Add or update this line in be.conf / cn.conf
datacache_disk_size = 500G

Important Considerations * Shared-Data Clusters: In shared-data mode, the system also uses

starlet_star_cache_disk_size_percent

(default 80%). The effective cache limit is typically the larger of

datacache_disk_size

and the calculated value from the percentage. * Verification: You can verify the change was successful by running:

Copy code

sql
    ADMIN SHOW FRONTEND CONFIG LIKE '%datacache_disk_size%'; -- (If applicable)
    -- Or check specifically on BEs:
    SHOW BACKENDS; -- Check the output or use the http interface for detailed config

* Auto-Scaling: If you are on v3.3+, StarRocks supports automatic scaling (

enable_datacache_disk_auto_adjust = true

). If enabled, the system will automatically manage disk usage based on

disk_high_level

(default 90%) and

disk_low_level

(default 60%). References • data_source/data_cache.md • administration/management/BE_configuration.md • data_source/data_cache_troubleshooting.md • using_starrocks/caching/block_cache.md References • administration/management/BE_configuration.md • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md

RonJay

06/30/2026, 6:26 AM

@Rocky how to drain data cache file manually?

Rocky

06/30/2026, 6:26 AM

To manually drain or clear the Data Cache (Block Cache) in StarRocks, you can use one of the two methods below depending on whether you can afford to restart the nodes. Method 1: The "No-Restart" Way (Recommended) You can force the system to evict all cached data by temporarily scaling the disk quota to zero. This triggers an internal cleanup process without needing to stop the service. 1. Set the disk quota to 0:

Copy code

sql
    -- For all nodes
    UPDATE be_configs SET VALUE = "0" WHERE NAME = "datacache_disk_size";

2. Wait a few minutes: The system will begin removing the cached block files to meet the new 0-byte limit. 3. Restore the original quota:

Copy code

sql
    -- For example, restore to 500GB
    UPDATE be_configs SET VALUE = "500G" WHERE NAME = "datacache_disk_size";

Method 2: Manual File Deletion (Requires Restart) If you want a "hard" reset or need to reclaim space immediately, you can manually delete the files from the operating system. 1. Stop the CN or BE node. 2. Locate the cache directory: The path is typically

<storage_root_path>/datacache

<storage_root_path>/starlet_cache

(depending on your version and configuration). 3. Delete the contents:

Copy code

bash
    # Replace with your actual path
    rm -rf /your/storage/path/datacache/*

4. Restart the node. Which directory should I clear? * For Shared-Data clusters (v3.0+): The cache is usually in the

starlet_cache

folder inside your

storage_root_path

. * For Data Lake queries (External Tables): The cache is usually in the

datacache

folder. Note: If you find that memory usage is high and not being released even after clearing the disk, you may also need to clear the metadata directory located at

${storage_root_path}/starlet_cache/star_cache/meta

. References • data_source/data_cache_troubleshooting.md • using_starrocks/caching/block_cache.md • data_source/data_cache.md • data_source/data_cache_observe.md References • data_source/data_cache_troubleshooting.md • using_starrocks/caching/block_cache.md • data_source/data_cache.md • data_source/data_cache_observe.md

RonJay

06/30/2026, 6:30 AM

@Rocky then, any options for restrict disk spill size

Rocky

06/30/2026, 6:31 AM

Unlike the Data Cache (which has

datacache_disk_size

), StarRocks currently does not have a single configuration or system variable to set a hard numerical limit (e.g., "50GB") on the total disk space used for spilling on a CN or BE node. However, you can manage and restrict spilling behavior using the following options: 1. Physical Isolation (Recommended) Because StarRocks uses all available space in the directories specified, the best way to restrict spill size is to mount a dedicated disk or partition for spilling. * Configuration: Set

spill_local_storage_dir

(or

query_scratch_dirs

in v3.2+) to a dedicated path. * Effect: This ensures that even if a large query triggers a massive spill, it will only consume the space on that specific partition and won't affect your OS or data directories. 2. Spilling to Remote Storage (v3.3+) If you want to avoid local disk exhaustion entirely, you can configure StarRocks to spill to object storage (S3/HDFS). * Variable:

SET enable_spill_to_remote_storage = true;

* Variable:

SET disable_spill_to_local_disk = true;

* Effect: By disabling local-disk spill, you force intermediate results to go directly to remote storage, effectively bypassing local disk limits. 3. Controlling "When" Spilling Occurs (Memory-based) Instead of limiting the disk size, you can control the memory thresholds that trigger spilling to prevent the disk from being hit too often: * query_pool_spill_mem_limit_threshold
(CN/BE Conf): Triggers spilling when the total memory used by all queries reaches a certain percentage of the query pool (Default:

1.0

). Lowering this (e.g.,

0.8

) triggers spilling earlier. * spill_revocable_max_bytes
(System Variable): A per-operator threshold. If an operator's memory exceeds this value, it will start spilling. 4. Known Limitations * Shared Resource: The

spill_local_storage_dir

is shared by all concurrent queries on a node. * No Per-Query Limit: StarRocks does not currently support restricting the amount of disk space a single query can use for spilling. If one query is very large, it can theoretically fill the entire spill directory. Summary of Differences Feature | Size Restriction Method Data Cache | Explicitly limited via

datacache_disk_size

starlet_star_cache_disk_size_percent

. Spill Size | Limited only by the physical capacity of the

spill_local_storage_dir

paths. References • administration/management/resource_management/spill_to_disk.md • administration/management/BE_configuration.md • sql-reference/System_variable.md • administration/management/resource_management/spill_to_disk.md • sql-reference/System_variable.md References • administration/management/resource_management/spill_to_disk.md • knowledge/usage/best-practice.md • sql-reference/System_variable.md

RonJay

06/30/2026, 10:19 AM

@Rocky why cluster snapshot is not working on builtin volume for s3

Rocky

06/30/2026, 10:19 AM

The "Cluster Snapshot" feature (introduced in v3.4.2) is designed specifically for shared-data (compute-separated) clusters. If it is not working on your built-in S3 volume, it is likely due to one of the following reasons: 1. "BACKUP/RESTORE" vs. "Cluster Snapshot" It is common to confuse the two. Traditional
BACKUP
and
RESTORE
SQL commands are NOT supported on shared-data clusters. * If you are trying to run

CREATE REPOSITORY

BACKUP

pointing to your S3 volume, it will fail. * For shared-data clusters, you must use the Cluster Snapshot mechanism instead:

Copy code

sql
    -- Correct way to enable snapshots on shared-data
    ADMIN SET AUTOMATED CLUSTER SNAPSHOT ON;

2. Version Requirement Cluster Snapshots were introduced in v3.4.2. If your cluster is on an older version (e.g., v3.1, v3.2, or early v3.3), the

ADMIN

command to enable snapshots will not exist, and the feature is not available. 3. Permissions and Config The built-in volume (

builtin_storage_volume

) is created automatically based on your

fe.conf

S3 settings. For snapshots to work, the FE requires List, Put, and Get permissions on the specific S3 path because the FE must write metadata images to:

s3://<your_bucket>/<cluster_id>/meta/image/automated_cluster_snapshot_...

* Check FE Logs: Look for

StorageVolumeException

AccessDenied

fe.log

. * Verify Credentials: Ensure

aws_s3_use_instance_profile = true

or valid `access_key`/`secret_key` are provided in

fe.conf

. 4. Storage Volume Accessibility In shared-data mode, StarRocks performs an accessibility check. If the credentials or endpoint provided in the config are invalid, the built-in volume may fail to initialize properly. * Verify your volume status:

Copy code

sql
    SHOW STORAGE VOLUMES;

Ensure your

builtin_storage_volume

is listed and marked as

IS_DEFAULT = true

. 5. Shared-Nothing Mode If your cluster is running in shared-nothing mode (standard BEs with local disks), the

builtin_storage_volume

and Cluster Snapshot features are not supported. For shared-nothing clusters, you must use the standard

BACKUP

and

RESTORE

commands with a Broker or S3 repository. Summary Checklist: 1. Version: Are you on v3.4.2 or higher? 2. Mode: Is

run_mode = shared_data

in your

fe.conf

? 3. Command: Are you using

ADMIN SET AUTOMATED CLUSTER SNAPSHOT ON

(Correct) or

BACKUP

(Incorrect for shared-data)? 4. View Status: Check progress in

information_schema.cluster_snapshot_jobs

. References • administration/cluster_snapshot.md • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • administration/management/Backup_and_restore.md References • administration/cluster_snapshot.md • administration/management/Backup_and_restore.md • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • administration/management/FE_configuration.md • sql-reference/sql-statements/cluster-management/storage_volume/SET_DEFAULT_STORAGE_VOLUME.md • administration/management/BE_configuration.md References

Rocky

06/30/2026, 10:19 AM

• administration/cluster_snapshot.md • administration/management/FE_configuration.md • sql-reference/sql-statements/cluster-management/storage_volume/SET_DEFAULT_STORAGE_VOLUME.md • administration/management/BE_configuration.md

RonJay

07/01/2026, 9:53 AM

@Rocky give me some options for handling query count run at same time

Rocky

07/01/2026, 9:53 AM

To manage the number of queries running at the same time in StarRocks, you have three primary layers of control: Query Queuing, Resource Groups, and Connection Limits. 1. Global Query Queuing (Protecting the Cluster) Query queuing allows the system to hold incoming queries in a "waiting" state rather than failing them immediately when the system is busy. * Enable for SELECT queries:

Copy code

sql
    SET GLOBAL enable_query_queue_select = true;

* Set the concurrency limit: This defines the maximum number of queries allowed to run simultaneously per BE node.

Copy code

sql
    SET GLOBAL query_queue_concurrency_limit = 100;

* Configure the queue behavior: * `query_queue_max_queued_queries`: Max number of queries allowed to wait in the queue (Default: 1024). * `query_queue_pending_timeout_second`: How long a query can wait before being canceled (Default: 300s). 2. Resource Group Isolation (Workload Multi-tenancy) If you have different types of workloads (e.g., "Reporting" vs. "Ad-hoc"), you can set concurrency limits per group. This ensures one heavy user doesn't block everyone else. * Create a resource group with a limit:

Copy code

sql
    CREATE RESOURCE GROUP 'reporting_group'
    PROPERTIES (
        "cpu_core_limit" = "10",
        "mem_limit" = "20%",
        "concurrency_limit" = "20" -- Only 20 queries can run at once for this group
    );

* Assign users to the group:

Copy code

sql
    SET PROPERTY FOR 'report_user' 'resource_group' = 'reporting_group';

3. Connection Limits (Front-end Level) This restricts the number of active MySQL protocol connections to the FE. This is a "hard" limit at the networking layer. * qe_max_connection
(FE Config): * Default: 4096 (in newer versions). * This is the total number of connections across all users. If reached, new connection attempts will be rejected. * max_user_connections
(User Property): * You can restrict a specific user to a maximum number of connections:

Copy code

sql
    SET PROPERTY FOR 'some_user' 'max_user_connections' = '50';

4. Dynamic Concurrency Adjustment (v3.1.4+) StarRocks can automatically adjust the internal parallelism (

pipeline_dop

) based on the system load. If many queries are running, it reduces the resources allocated to each new query to maintain stability. * Variables:

query_queue_driver_low_water

and

query_queue_driver_high_water

. * Effect: When the number of active "drivers" (execution units) exceeds the high water mark, StarRocks forces new queries to use a lower

pipeline_dop

. Summary Checklist Level | Best For | Behavior when limit reached Connection Limit | Preventing connection leaks | Connection rejected Query Queue | Global cluster stability | Query waits in queue Resource Group | Fair-share between teams | Query waits or fails (depending on queue config) References • administration/management/resource_management/query_queues.md • administration/management/resource_management/resource_group.md • administration/management/monitor_manage_big_queries.md • administration/management/FE_configuration.md • sql-reference/System_variable.md References • administration/management/resource_management/query_queues.md • administration/management/resource_management/resource_group.md

Rocky

07/01/2026, 9:53 AM

• administration/management/monitor_manage_big_queries.md • administration/management/FE_configuration.md • sql-reference/System_variable.md References • administration/management/FE_configuration.md

RonJay

07/01/2026, 11:23 AM

@Rocky iceberg table 의 대소문자 구분없이 사용할 수 있게 설정하는 방법

Rocky

07/01/2026, 11:24 AM

StarRocks에서 Iceberg 테이블을 사용할 때 대소문자 구분(Case-sensitivity) 설정은 *컬럼명*과 *테이블/데이터베이스/카탈로그명*에 따라 처리 방식이 다릅니다. 1. 컬럼명 (Column Names) StarRocks에서 컬럼명은 기본적으로 대소문자를 구분하지 않습니다. * Iceberg 테이블의 컬럼이 `UserName`으로 되어 있더라도 SQL 쿼리에서는

username

USERNAME

UserName

중 어떤 것을 사용해도 동일하게 인식됩니다. 별도의 추가 설정이 필요하지 않습니다. 2. 테이블, 데이터베이스, 카탈로그명 StarRocks는 기본적으로 테이블, 데이터베이스, 카탈로그 이름을 *대소문자를 구분(Case-sensitive)*하여 처리합니다. 이를 대소문자 구분 없이 사용하려면 다음과 같은 설정이 필요합니다. StarRocks v4.0 이상: FE 설정 활용 v4.0부터는 FE(Front-End) 설정값인 `enable_table_name_case_insensitive`를 통해 대소문자 구분을 제어할 수 있습니다. * 설정값:

enable_table_name_case_insensitive = true

* 주의사항: 이 설정은 *클러스터를 처음 생성(Initialization)할 때만 설정 가능*하며, 이미 실행 중인 클러스터에서는 도중에 변경할 수 없습니다. * 이 옵션을 활성화하면 모든 카탈로그, DB, 테이블 이름이 내부적으로 소문자로 저장되고 처리됩니다. v4.0 미만 버전 또는 기존 클러스터 이전 버전이나 이미 운영 중인 클러스터의 경우, 테이블 명에 대해서는 대소문자를 엄격히 구분해야 합니다. * 작업 방법: Iceberg의 Metastore(Hive Metastore, AWS Glue 등)에 저장된 실제 테이블 이름의 대소문자와 동일하게 SQL을 작성해야 합니다. * 대안: 만약 특정 테이블을 자주 조회하는데 대소문자가 섞여 있어 불편하다면, StarRocks 내부에 *소문자 이름으로 View를 생성*하여 사용하는 방법이 권장됩니다.

Copy code

sql
    CREATE VIEW iceberg_catalog.db_name.my_table_lowercase AS
    SELECT * FROM iceberg_catalog.DB_NAME.My_Table_Name;

enable_table_name_case_insensitive=true

설정 참고 문헌 • administration/management/FE_configuration.md • sql-reference/System_limit.md • data_source/catalog/iceberg/iceberg_catalog.md References • administration/management/FE_configuration.md • data_source/catalog/iceberg/iceberg_catalog.md • data_source/feature-support-data-lake-analytics.md

RonJay

07/03/2026, 1:42 AM

@Rocky if i set pipeline_dop = 0 it is working as auto. how can i check pipeline dop usage when run some query?

Rocky

07/03/2026, 1:43 AM

When you set

pipeline_dop = 0

(the default), StarRocks uses an Adaptive Parallelism strategy. It automatically calculates the optimal Degree of Parallelism (DOP) based on query complexity and available system resources, typically capping it at half the number of physical CPU cores on your BE nodes. To check the actual DOP used by a query, you can use the following methods: 1. For a Running Query You can view the real-time status of queries, including their parallelism, using the following command:

Copy code

sql
SHOW RUNNING QUERIES;

* DOP Column: This column shows the degree of parallelism currently assigned to the query. Note that if it shows

here, it refers to the session variable setting; for the actual execution value, the Query Profile is more reliable. 2. For a Finished Query (Query Profile) The most detailed way to see the actual DOP is by inspecting the Query Profile. Option A: Using
EXPLAIN ANALYZE
If you are running the query manually to test, prepend `EXPLAIN ANALYZE`:

Copy code

sql
EXPLAIN ANALYZE SELECT ... FROM table;

In the output, look for the Pipeline Metrics section. You will see: * DegreeOfParallelism
: The actual number of parallel drivers used for that specific pipeline fragment. Option B: Using
SHOW QUERY PROFILE
If the query has already finished: 1. Get the Query ID (usually returned by the client or found in

information_schema.active_queries

). 2. Run:

Copy code

sql
    -- Replace with your actual Query ID
    SHOW QUERY PROFILE "/" "10db481c-fab7-11ef-8063-461f20abc3f0";

3. Search for the string DegreeOfParallelism
. 3. Using the FE Web UI If you have access to the StarRocks Front-End Web UI (usually at

http://<FE_IP>:8030

): 1. Navigate to the Queries tab. 2. Click on the Profile link for your query. 3. Expand the Pipeline or Fragment details to see the parallelism metrics visually. Pro-Tips: * max_pipeline_dop
: This variable (introduced in v3.2.0) acts as a safety ceiling for adaptive DOP. Even if

pipeline_dop

is 0, the actual DOP will not exceed the value of

max_pipeline_dop

(default is 64). * Profile Detail Level: If you cannot see detailed pipeline metrics, ensure your profile level is sufficient:

Copy code

sql
    SET pipeline_profile_level = 1; -- Default, usually enough to see DOP

References • best_practices/query_tuning/query_profile_operator_metrics.md • sql-reference/System_variable.md • using_starrocks/running_queries.md • administration/management/monitoring/metrics.md References • best_practices/query_tuning/query_profile_operator_metrics.md • sql-reference/System_variable.md • using_starrocks/running_queries.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_RUNNING_QUERIES.md References • sql-reference/information_schema/warehouse_queries.md • administration/http_interface/query_detail.md • using_starrocks/running_queries.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_RUNNING_QUERIES.md

RonJay

07/03/2026, 5:12 AM

@Rocky how to Reduce fe pod creating stdout log

Rocky

07/03/2026, 5:13 AM

To reduce the amount of log data sent to

stdout

(and thus your pod logs) for the StarRocks FE, you can adjust the logging level or redirect the logs back to files. In containerized environments, StarRocks FEs are often configured to send all system logs to the console for easier collection by log drivers. Here are the primary ways to reduce that volume: 1. Increase the Log Level The most effective way to reduce log volume is to change the logging level from

INFO

(default) to

WARN

ERROR

. This filters out routine operational messages. * Via Environment Variable (Recommended for Pods): Set the following in your FE container specification:

Copy code

yaml
    env:
      • name: SYS_LOG_LEVEL
        value: "WARN"

* Via `fe.conf`:

Copy code

conf
    sys_log_level = WARN

2. Disable Console Logging By default, in many Kubernetes deployments (or if the environment variable

SYS_LOG_TO_CONSOLE

is set to

), StarRocks sends the entire

fe.log

content to

stdout

. If you prefer to keep logs inside the pod's persistent volume and only see startup/critical errors in

kubectl logs

, you can disable this: * Set Environment Variable:

SYS_LOG_TO_CONSOLE=0

* Effect: Only

fe.out

content (JVM startup, critical crashes, and explicit

System.out

calls) will appear in the pod logs. The main system logs will stay in

${STARROCKS_HOME}/log/fe.log

. 3. Reduce Berkeley DB (BDB) Log Verbosity BDB JE is the metadata store, and it can be quite chatty. You can set its level separately: * `fe.conf`:

Copy code

conf
    bdbje_log_level = WARN

4. Limit Audit Logs Audit logs record every SQL command. If these are being piped to the console (v3.2.0+ via

sys_log_to_console

), they can grow very fast. You can adjust which modules are logged: * audit_log_modules
: By default, this includes

slow_query

and

query

. Removing

query

will significantly reduce volume by only logging queries that exceed the

slow_query_time_threshold

Copy code

conf
    audit_log_modules = slow_query

5. Summary of Key Variables Variable | Default | Recommended for Less Log

sys_log_level

INFO

WARN

ERROR

SYS_LOG_TO_CONSOLE

(often

in K8s) |

(to stop system logs on stdout)

bdbje_log_level

INFO

WARN

audit_log_modules

slow_query, query

slow_query

Note: If you are using the StarRocks Operator, these settings should be applied in the

fe.config

section of your

StarRocksCluster

YAML or StarRocksFeSpec` YAML. References • administration/management/logs.md • administration/management/FE_configuration.md • sql-reference/System_variable.md References • administration/management/FE_configuration.md • administration/management/logs.md

RonJay

07/06/2026, 12:56 AM

@Rocky how to delete files which is loaded as insert into files with sql

Rocky

07/06/2026, 12:56 AM

INSERT INTO ... FROM FILES()

구문을 통해 데이터를 로드한 후, StarRocks SQL 명령만으로 원본 파일(S3, HDFS 등)을 직접 삭제하는 방법은 없습니다. StarRocks는 외부 스토리지의 파일을 읽기 전용(Read-only) 데이터 소스로 취급하며, 보안 및 데이터 무결성을 위해 엔진 내부에서 외부 파일 시스템의 객체를 삭제하는 기능을 제공하지 않습니다. 로드 완료 후 원본 파일을 삭제하려면 다음과 같은 외부적인 방법을 사용해야 합니다. 1. 워크플로우 도구 활용 (권장) Airflow, Dagster 또는 사용자 정의 스크립트(Python, Shell 등)를 사용하여 로드 작업을 자동화하고, SQL 실행이 성공적으로 완료된 후 파일을 삭제하는 로직을 추가합니다. * 단계:

INSERT INTO table SELECT ... FROM FILES(...)

실행 → 성공 반환 확인 → 클라우드 CLI(예:

aws s3 rm

) 또는 SDK로 파일 삭제. 2. 클라우드 스토리지 수명 주기 정책 (Lifecycle Policy) 데이터가 특정 경로에 저장되고 로드 후 더 이상 필요하지 않다면, 클라우드 서비스 제공업체의 기능을 활용하는 것이 가장 효율적입니다. * S3 예시: 특정 접두사(Prefix) 아래의 객체에 대해 "생성 후 1일 뒤 삭제"와 같은 *Lifecycle Rule*을 설정하여 자동으로 정리되도록 합니다. 3. 파일 목록 확인을 통한 수동 삭제 어떤 파일이 로드되었는지 확인하고 싶다면

FILES()

함수의

list_files_only

옵션을 사용하여 SQL로 목록을 조회한 뒤, 해당 경로를 기반으로 삭제 스크립트를 생성할 수 있습니다.

Copy code

sql
SELECT * FROM FILES(
    "path" = "<s3://my-bucket/load-data/*.parquet>",
    "format" = "parquet",
    "aws.s3.access_key" = "...",
    "aws.s3.secret_key" = "...",
    "list_files_only" = "true"
);

요약 * StarRocks SQL 내부 기능: 없음 (외부 파일 삭제 권한을 직접 가지지 않음) * 해결책: Airflow 같은 오케스트레이션 도구를 사용하거나, S3/GCS의 수명 주기 정책을 사용하여 자동 삭제를 구성해야 합니다. References • sql-reference/sql-functions/table-functions/files.md • unloading/unload_using_insert_into_files.md • sql-reference/sql-statements/loading_unloading/INSERT.md _ References • sql-reference/sql-functions/table-functions/files.md • sql-reference/sql-statements/table_bucket_part_index/TRUNCATE_TABLE.md

RonJay

07/06/2026, 1:18 AM

@Rocky what happed if i increase fe pod size 1 -> 3 which is using a lot of metadata previously. is that possible scale out fe pod?

Rocky

07/06/2026, 1:19 AM

FE pod의 수를 1개에서 3개로 늘리는 것(Scale-out)은 *가능하며, 고가용성(High Availability)을 위해 매우 권장되는 작업*입니다. 하지만 말씀하신 것처럼 *메타데이터가 많은 경우*에는 다음과 같은 현상과 주의사항이 발생합니다. 1. 메타데이터 동기화 (Image + Edit Logs) 새로운 2개의 FE pod가 생성되면, 현재 Leader 상태인 기존 FE로부터 메타데이터를 복제받아야 합니다. * 프로세스: 새로운 FE는 Leader로부터

image

파일(메타데이터 스냅샷)을 다운로드한 후, 이후에 쌓인 `edit log`를 재생(Replay)하여 최신 상태를 맞춥니다. * 시간 소요: 메타데이터 크기가 클수록 초기 동기화 시간이 오래 걸립니다. 이 과정 동안 새로운 FE pod는 'Ready' 상태가 되지 않을 수 있습니다. 2. 리소스 요구 사항 (Memory & Disk) StarRocks FE는 모든 메타데이터를 *메모리(JVM Heap)*에 올려서 관리합니다. * Memory: 새로운 FE pod들도 기존 Leader와 동일한 크기의 `-Xmx`(JVM Max Heap) 설정을 가져야 합니다. 메타데이터가 많다면 최소 16GB~64GB 이상의 메모리가 필요할 수 있습니다. * Disk: 메타데이터가 저장되는 디스크 공간이 충분해야 합니다. (

meta

디렉토리 크기 확인 필요) 3. 주요 설정 변경 제안 메타데이터가 매우 클 경우, 동기화 과정에서 타임아웃이 발생하여 새로운 FE가 클러스터 조인에 실패할 수 있습니다. `fe.conf`에서 다음 설정을 검토하세요. * bdbje_replica_ack_timeout_second
: 기본값은 10초입니다. 메타데이터 쓰기나 동기화가 많을 경우 이 값을 30~60초 정도로 늘리는 것이 안전합니다. * replica_ack_policy
: 3대의 FE가 되면 'SIMPLE_MAJORITY'(2대 이상의 승인) 원칙에 따라 쿼리가 처리됩니다. 4. 스케일 아웃 방법 * StarRocks Operator 사용 시:

StarRocksCluster

YAML 파일에서 FE의 `replicas`를 `1`에서 `3`으로 수정하기만 하면 됩니다. Operator가 자동으로

ALTER SYSTEM ADD FOLLOWER

명령을 실행합니다. * 수동 설치 시: 1. MySQL 클라이언트로 기존 FE에 접속하여 새로운 FE의 IP:Port를 추가합니다.

ALTER SYSTEM ADD FOLLOWER "FE_IP:9010";

2. 새로운 FE를

--helper 기존_FE_IP:9010

옵션과 함께 실행합니다. 요약 * 가능 여부: 가능하며, 3대 구성 시 1대가 죽어도 서비스가 유지되는 HA가 구성됩니다. * 주의점: 메타데이터가 크면 *초기 기동 시간*이 길어지고 *메모리 사용량*이 높으므로, Pod의 리소스 제한(Limit)을 충분히 확보해야 합니다. References • administration/management/FE_configuration.md • faq/operation_maintenance_faq.md • administration/Meta_recovery.md • faq/Others.md References • administration/management/FE_configuration.md • faq/operation_maintenance_faq.md • administration/Meta_recovery.md • faq/Others.md References • faq/operation_maintenance_faq.md • faq/Deploy_faq.md • administration/Meta_recovery.md • administration/management/FE_configuration.md

RonJay

07/06/2026, 5:56 AM

@Rocky give me metric example for check datacach disk hit rate for starrocks (shared_data with pvc)

Rocky

07/06/2026, 5:56 AM

StarRocks의 Shared-data 아키텍처(Cloud-native)에서 PVC를 활용한 Data Cache(StarCache)의 디스크 적중률(Hit Rate)을 확인하기 위한 주요 메트릭과 PromQL 예시는 다음과 같습니다. 1. 주요 프로메테우스(Prometheus) 메트릭 Data Cache는 크게 *Block Cache*(주로 디스크/PVC)와 *Page Cache*(주로 메모리)로 나뉩니다. 디스크 적중률을 확인하려면

block_cache

관련 메트릭을 사용해야 합니다. * `starrocks_be_block_cache_hit_bytes`: 캐시(디스크)에서 읽어온 데이터 크기 (Bytes) * `starrocks_be_block_cache_miss_bytes`: 캐시 미스가 발생하여 원격 저장소(S3 등)에서 직접 읽어온 데이터 크기 (Bytes) 2. PromQL 예시 (Disk Hit Rate) 디스크 캐시 적중률을 백분율(%)로 계산하는 쿼리입니다.

Copy code

promql
# 최근 5분간의 평균 디스크 캐시 적중률 (%)
(
  sum(rate(starrocks_be_block_cache_hit_bytes[5m])) 
  / 
  (sum(rate(starrocks_be_block_cache_hit_bytes[5m])) + sum(rate(starrocks_be_block_cache_miss_bytes[5m])))
) * 100

3. 추가 모니터링 메트릭 (용량 및 상태) PVC의 할당량과 현재 사용량을 확인하여 캐시 교체(Eviction)가 빈번한지 판단할 수 있습니다. * 캐시 디스크 사용량:

starrocks_be_block_cache_disk_used_bytes

* 캐시 디스크 할당량:

starrocks_be_block_cache_disk_quota_bytes

* 캐시 상태 확인 (API): BE 노드에 직접 쿼리하여 실시간 상태를 JSON으로 볼 수 있습니다 (v3.3.2 이상).

Copy code

bash
    curl http://<BE_IP>:<BE_HTTP_PORT>/api/datacache/app_stat

4. 주의사항 * 초기 로딩: 클러스터 재시작 직후나 새로운 데이터를 처음 읽을 때는 `miss_bytes`가 높아 적중률이 낮게 나타나는 것이 정상입니다. * 메트릭 접두어: 사용 중인 모니터링 환경(Exporter 설정)에 따라

starrocks_be_

접두어가 생략되거나 다를 수 있으므로,

/metrics

엔드포인트에서 실제 이름을 확인하시기 바랍니다. References • administration/management/monitoring/metrics.md • data_source/data_cache_observe.md • administration/management/monitoring/Monitor_and_Alert.md References • administration/management/monitoring/metrics.md • data_source/data_cache_observe.md

RonJay

07/06/2026, 6:09 AM

@Rocky is fslib_read_io_size_sum represent read data from any object storage or not?

Rocky

07/06/2026, 6:09 AM

네,

fslib_read_io_size_sum

메트릭은 *StarRocks의 Shared-data(Cloud-native) 아키텍처에서 오브젝트 스토리지(S3, GCS, Azure Blob 등)로부터 읽어온 데이터 크기의 총합*을 나타냅니다. 상세 내용은 다음과 같습니다. 1. 의미 * FSLIB (File System Library): StarRocks의 공유 스토리지 엔진(Starlet)이 외부 저장소와 통신하기 위해 사용하는 추상화 레이어입니다. * 용도: 캐시(Data Cache)에 없는 데이터를 원격 저장소(Object Storage)에서 직접 읽어올 때 발생하는 I/O 크기를 기록합니다. * 데이터 소스: 문서상에는 주로 "S3 reads"로 설명되어 있으나, 실제로는 Shared-data 클러스터에 설정된 *모든 원격 스토리지(S3, GCS, Azure Blob, HDFS 등)*를 포함합니다. 2. 특징 * Cumulative Sum: 이 메트릭은 프로메테우스(Prometheus)의 Histogram 또는 Summary 타입의 일부로, 특정 시점까지 읽은 *누적 바이트(Byte) 수*를 의미합니다. * Data Cache와의 관계: 만약 데이터가 로컬 PVC(Data Cache)에서 히트(Hit)된다면 이 수치는 증가하지 않습니다. 즉, *캐시 미스(Cache Miss)가 발생하여 원격지에서 실제로 가져온 트래픽*을 측정할 때 유용합니다. 3. 함께 확인하면 좋은 메트릭 * `fslib_read_io_size_count`: 원격 저장소에 요청한 읽기 작업의 총 횟수 (IOPS 계산에 활용). * `fslib_read_io_latency_sum / fslib_read_io_latency_count`: 원격 저장소 읽기 시 발생하는 평균 지연 시간(Latency). 요약하자면: 이 메트릭은 클라우드 환경에서 StarRocks가 오브젝트 스토리지로부터 얼마나 많은 데이터를 읽고 있는지(네트워크 인바운드 트래픽/비용과 직결) 모니터링하는 핵심 지표입니다. References • administration/management/monitoring/metrics-shared-data.md • administration/management/monitoring/metrics.md • data_source/data_cache_observe.md References • administration/management/monitoring/metrics-shared-data.md • administration/management/monitoring/metrics.md

RonJay

07/06/2026, 6:48 AM

@Rocky datacache limit을 안걸고 그냥 쓰다가 디스크가 꽉차면 어떻게되나

Rocky

07/06/2026, 6:48 AM

StarRocks의 Data Cache(StarCache)는 기본적으로 디스크가 꽉 차지 않도록 *자동 관리 메타니즘*을 가지고 있습니다. 별도의 Limit(Quota)을 설정하지 않았을 때의 동작과 발생 가능한 상황은 다음과 같습니다. 1. 자동 관리 모드 (Automatic Scaling) StarRocks v3.3 이상 버전부터는 별도의 설정을 하지 않으면 `datacache_auto_adjust_enable=true`가 기본값으로 작동합니다. 이 경우 시스템은 디스크 전체 용량을 기준으로 다음 임계치에 따라 캐시를 관리합니다. * 90% (
disk_high_level
): 디스크 사용량이 90%에 도달하면 LRU(Least Recently Used) 알고리즘에 따라 오래된 캐시 데이터를 *삭제(Eviction)*하여 공간을 확보합니다. * 80% (
disk_safe_level
): 캐시 삭제를 통해 유지하려고 하는 목표 사용량입니다. * 동작 방식: 캐시는 계속 쌓이다가 90%를 찍으면 80% 수준까지 예전 데이터를 밀어내면서 순환 구조로 작동합니다. 즉, *디스크가 물리적으로 100%가 되어 서비스가 멈추는 상황을 스스로 방지*하려고 노력합니다. 2. 디스크가 실제로 꽉 찼을 때 (External Factors) 만약 StarRocks 캐시 외에 *로그 파일, Core Dump, 혹은 다른 애플리케이션 파일*이 디스크를 점유하여 실제 물리 디스크가 100%에 도달하면 다음과 같은 문제가 발생할 수 있습니다. * 캐시 쓰기 실패: 새로운 데이터를 캐싱하지 못하고 바로 원격 저장소(S3 등)에서 읽어오게 되어 *쿼리 성능이 저하*됩니다. * BE 노드 불안정: StarRocks BE는 캐시 외에도 임시 파일(SSTables, Index, Log 등)을 기록해야 하는데, 공간이 없으면 프로세스가 비정상 종료(Panic/Crash)되거나 읽기 전용 상태가 될 수 있습니다. 3. 주의사항:
du
명령어로 확인 시 디스크가 줄어들지 않음 Data Cache는 한 번 점유한 디스크 공간을 운영체제에 반환(Delete)하지 않고, 기존 파일을 덮어쓰는(Overwrite) 방식으로 관리합니다. * 따라서

du -sh

명령어로 확인하면 캐시 삭제(Eviction)가 일어나고 있음에도 불구하고 디스크 사용량은 항상 최대치(예: 80~90%)에 머물러 있는 것처럼 보입니다. 이는 정상적인 동작이며 내부적으로는 오래된 데이터가 계속 교체되고 있는 것입니다. 권장 설정 디스크 꽉 참으로 인한 BE 노드 장애를 방지하려면, 전체 디스크 용량의 일부를 명시적으로 제한하는 것이 안전합니다.

Copy code

bash
# be.conf 예시 (전체 디스크 중 100GB만 캐시로 사용)
storage_path = /data/starrocks/cache,capacity:100

또는 전체 디스크 비중으로 설정:

Copy code

sql
-- 모든 BE에 대해 디스크의 70%까지만 캐시 사용하도록 동적 변경
UPDATE be_configs SET VALUE="70%" WHERE NAME="datacache_disk_size";

요약: 별도의 설정을 안 해도 StarRocks가 90% 선에서 오래된 데이터를 밀어내며 관리하므로 당장 서비스가 죽지는 않지만, 안전을 위해 전체 디스크의 70~80% 정도로 명시적인 Quota를 주는 것이 운영상 가장 안전합니다. References • data_source/data_cache.md • using_starrocks/caching/block_cache.md • data_source/data_cache_troubleshooting.md • data_source/data_cache_troubleshooting.md • data_source/data_cache_troubleshooting.md References • using_starrocks/caching/block_cache.md • data_source/data_cache_troubleshooting.md • data_source/data_cache.md

RonJay

07/06/2026, 8:13 AM

@Rocky how to catch failure of creating checkpoint for journallog and image for metadata (fe pods)

Rocky

07/06/2026, 8:13 AM

StarRocks FE의 메타데이터 체크포인트(Image 생성) 및 Journal Log(Edit Log) 생성 실패를 감지하는 방법은 크게 세 가지(메트릭, 로그, SQL)가 있습니다. 1. 프로메테우스 메트릭을 통한 감지 (가장 권장) FE는 일정 수 이상의 Edit Log가 쌓이면 체크포인트를 수행하여 이를

image

파일로 병합합니다. 이 과정이 실패하면 로그 개수가 줄어들지 않고 계속 증가합니다. * 메트릭:

starrocks_fe_meta_log_count

* 의미: 체크포인트 되지 않은 BDBJE(Berkeley DB Java Edition) 로그 항목의 수입니다. * 임계치: * 기본적으로 50,000개가 쌓이면 체크포인트가 실행됩니다. * *100,000개 이상*으로 유지된다면 체크포인트가 실패하고 있는 것입니다. * PromQL 예시 (Alert rule):

Copy code

promql
    starrocks_fe_meta_log_count > 100000

2. FE 로그(
fe.log
) 감시 체크포인트 생성 과정에서 오류가 발생하면 `fe.log`에 특정 키워드가 기록됩니다. 로그 시스템(ELK, Grafana Loki 등)에서 다음 패턴을 감시하세요. * 정상 흐름: * 시작:

begin to generate new image: image.xxxx

* 완료:

checkpoint finished save image.xxxx

* 실패 시 키워드: *

Exception when generate new image file

failed to push image

(Leader와 Follower 간의 이미지 전송 실패) *

catch exception when replaying

(로그 재생성 중 오류) *

INSUFFICIENT_LOG

(로그 유실 또는 불일치) 3. SQL을 통한 수동 확인 Admin 권한으로 접속하여 메타데이터 상태를 직접 확인할 수 있습니다. * 프론트엔드 상태 확인:

Copy code

sql
    SHOW PROC '/frontends';

출력 결과에서 `CurrentJournalId`를 확인합니다. 이 숫자가 비상식적으로 높거나(수백만 단위), 시간이 지나도

image

버전이 갱신되지 않는다면 문제가 있는 것입니다. * 수동 체크포인트 시도: 만약 자동 체크포인트가 실패한다면 아래 명령어로 수동 생성을 시도하여 에러 메시지를 즉시 확인할 수 있습니다.

Copy code

sql
    ALTER SYSTEM CREATE IMAGE;

주요 실패 원인 및 조치 1. JVM Heap Memory 부족: 메타데이터가 너무 크면 체크포인트 중 `OutOfMemoryError`가 발생할 수 있습니다. `fe.conf`의 `-Xmx`를 늘려야 합니다. 2. 디스크 공간 부족:

meta_dir

경로의 디스크가 꽉 차면 신규

image

파일을 저장할 수 없습니다. 3. 네트워크 문제: Leader FE가 아닌 Helper FE가 체크포인트를 수행한 후 Leader에게 전송하는데, FE 간의 HTTP 포트(기본 8030) 통신이 막혀있으면 실패합니다. 요약:

starrocks_fe_meta_log_count > 100000

RonJay

07/06/2026, 9:17 AM

@Rocky

Copy code

sql
    SHOW PROC '/frontends';

의 결과로 currentjournalid는 없고 replayedjournalid만 있음

Rocky

07/06/2026, 9:18 AM

SHOW PROC '/frontends';

결과에 `CurrentJournalId`가 없는 것은 정상입니다. 최신 StarRocks 버전의 해당 명령어 출력 항목에는 `CurrentJournalId`라는 이름 대신 *`ReplayedJournalId`*가 그 역할을 대신하거나, 혹은 메트릭을 통해 확인해야 합니다. 질문하신 *체크포인트 실패 및 메타데이터 상태*를 판단하는 방법은 다음과 같습니다. 1. `ReplayedJournalId`의 의미와 활용 `SHOW PROC '/frontends';`에서 각 노드의 상태를 비교하여 판단합니다. * LEADER 노드: LEADER 노드의 `ReplayedJournalId`는 현재 해당 클러스터에서 가장 마지막으로 생성된(쓰여진) Journal ID를 의미합니다. (이것이 사실상 'Current' Journal ID입니다.) * FOLLOWER 노드: FOLLOWER의 `ReplayedJournalId`는 LEADER로부터 전달받아 자신의 메모리에 반영한 ID입니다. * 판단 방법: LEADER와 FOLLOWER들 간의

ReplayedJournalId

차이가 거의 없어야 정상입니다. 만약 특정 노드의 숫자가 멈춰있거나 차이가 계속 벌어진다면 Journal Log 복제나 재생(Replay)에 문제가 생긴 것입니다. 2. 체크포인트(Image 생성) 실패 여부 확인 방법 체크포인트는 Journal Log를

image

파일로 합치는 작업입니다. 이 작업의 성공 여부는 SQL 결과보다는 *메트릭*과 *디스크의 실제 파일*을 보는 것이 가장 정확합니다. A. 메트릭 확인 (가장 확실함) * starrocks_fe_meta_log_count
: 현재 체크포인트가 되지 않고 쌓여 있는 Journal Log의 개수입니다. * 정상: 보통 50,000개(기본값)가 쌓이면 체크포인트가 돌면서 숫자가 확 줄어듭니다. * 위험: 이 숫자가 100,000개, 200,000개 등으로 계속 증가만 하고 줄어들지 않는다면 체크포인트가 실패하고 있는 것입니다. B. 실제 파일 확인 (FE 서버 접속) FE의 메타데이터 경로(`meta_dir`/image)로 이동하여 파일을 확인합니다. *

image.[ID]

파일의 생성 시간을 봅니다. * 가장 최근의

image

파일 생성 시간이 몇 시간 또는 며칠 전이라면 체크포인트 프로세스가 죽었거나 에러가 발생한 상태입니다. C. 로그 확인 `fe.log`에서 체크포인트 관련 에러를 검색합니다. * 키워드:

checkpoint

save image

Exception when generate new image

요약

SHOW PROC '/frontends';

결과에서 *LEADER 노드의 `ReplayedJournalId`가 현재 가장 높은(최신) ID*이며, 이 값이 계속 커지고 있다면 Journal Log 생성 자체는 잘 되고 있는 것입니다. 하지만 *체크포인트(이미지 생성) 실패*를 잡으려면 `ReplayedJournalId`보다는 위에서 언급한 *`starrocks_fe_meta_log_count` 메트릭이 줄어드는지*를 모니터링해야 합니다. References • administration/management/monitoring/metrics.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • administration/Meta_recovery.md Meta_recovery) • administration/management/monitoring/Monitor_and_Alert.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md References • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md

RonJay

07/07/2026, 9:18 AM

@Rocky Starrocks mview 나 기타 ddl 을 internal catalog에 쓰지않으면 bdb edit log 누적 현상은 발생하지 않는거야?

Rocky

07/07/2026, 9:19 AM

아니요, 그렇지 않습니다. Internal Catalog에 DDL(테이블 생성 등)을 수행하지 않더라도, StarRocks가 운영 중이라면 BDB Edit Log(Journal Log)는 계속해서 발생하고 누적됩니다. 그 이유는 Edit Log가 단순한 DDL 기록뿐만 아니라, *클러스터의 상태를 변화시키는 모든 트랜잭션*을 기록하기 때문입니다. 주요 원인은 다음과 같습니다. 1. 데이터 적재 (가장 큰 원인) Internal Catalog에 테이블을 만들지 않더라도, 기존 테이블에 데이터를 넣는 모든 행위가 로그를 생성합니다. * Stream Load, Routine Load, Insert Into: 데이터가 적재될 때마다 트랜잭션의 시작과 끝(Commit) 정보가 Edit Log에 기록됩니다. * 고빈도(High-frequency) 적재가 발생하는 환경에서는 DDL이 전혀 없어도 초당 수백 개의 Edit Log가 생성될 수 있습니다. 2. Routine Load 및 파이프라인 상태 * Kafka 등에서 데이터를 가져오는 *Routine Load*의 경우, 어디까지 읽었는지에 대한 *Offset 정보*를 주기적으로 메타데이터에 업데이트합니다. 이 업데이트 과정이 모두 Edit Log에 기록됩니다. 3. Materialized View(MV) 관련 동작 * MV를 External Catalog(예: Iceberg, Hive) 기반으로 만들었더라도, 그 MV의 정의와 새로고침 상태(Refresh Status), 마지막 새로고침 시간 등은 모두 FE의 메타데이터(BDB JE)에 저장됩니다. * MV가 주기적으로 새로고침될 때마다 그 이력이 로그로 남습니다. 4. 권한 및 계정 관리 *

GRANT

REVOKE

, 유저 생성, 비밀번호 변경 등 보안 관련 설정 변경도 모두 Edit Log 대상입니다. 5. 클러스터 관리 및 동적 설정 * BE 노드의 추가/삭제(Decommission), 태그 변경. *

ADMIN SET FRONTEND CONFIG

등을 통한 동적 설정 변경. 6. 외부 카탈로그(External Catalog) 정보 캐싱 * 외부 카탈로그 자체는 외부에 있지만, StarRocks FE가 해당 카탈로그를 *등록(

CREATE EXTERNAL CATALOG

)*하거나, 메타데이터 캐시를 갱신하는 과정에서 일부 정보가 로그에 포함될 수 있습니다. 요약 Edit Log 누적 현상은 *"무언가 변경되거나 기록되어야 할 상태값"*이 생기면 무조건 발생합니다. 따라서 "DDL을 안 쓰면 로그가 안 쌓이겠지"라고 방치하시면 안 되며, 앞서 말씀드린 *체크포인트(Image 생성)가 정상적으로 동작하여 누적된 로그를 정리하고 있는지*를 주기적으로 확인하는 것이 운영상 필수적입니다. * 확인 지표:

starrocks_fe_meta_log_count

(이 수치가 계속 올라가고 내려오지 않는다면 체크포인트 프로세스 장애입니다.)

RonJay

07/08/2026, 1:26 AM

@Rocky starrocks fe 가 종료될때 checkpoint를 생성하나?

Rocky

07/08/2026, 1:26 AM

StarRocks FE는 종료 시 자동으로 체크포인트(Image 생성)를 수행하지 않습니다. FE가 종료될 때 발생하는 동작과 주의사항은 다음과 같습니다. 1. 종료 시 발생하는 동작 * BDB JE 로그 플러시: FE가 정상 종료(

stop_fe.sh

)될 때, 메타데이터 저장소인 BDB JE(Berkeley DB Java Edition) 환경을 닫으면서 메모리에 있는 Journal Log(Edit Log)를 디스크에 안전하게 기록(Flush)합니다. 이는 데이터의 영속성을 보장하기 위함입니다. * 서비스 중단: 쿼리 수락을 중단하고 진행 중인 작업을 정리합니다. v3.3 이상의 *Graceful Exit*(

-g

옵션)를 사용하면 진행 중인 쿼리가 끝날 때까지 대기하거나 로드 밸런서에 상태를 알리는 과정이 추가되지만, 이 과정에도 Image 생성 단계는 포함되어 있지 않습니다. 2. 체크포인트가 생성되지 않을 때의 영향 체크포인트는 누적된 Journal Log를

image

파일로 병합하는 작업입니다. 종료 시 이 작업을 하지 않으면 다음과 같은 현상이 발생합니다. * 재시작 시간 증가: 마지막 체크포인트 이후 발생한 로그가 많을수록, FE가 다시 뜰 때 재플레이(Replay)해야 하는 로그 양이 많아져서 Startup 시간이 길어집니다. * 메타데이터 크기 유지: 체크포인트가 수행되어야만 오래된 Journal Log 파일들이 삭제되는데, 종료 시에는 이 정리가 일어나지 않습니다. 3. 권장 조치: 수동 체크포인트 생성 점검이나 업데이트를 위해 FE를 내리기 전, 재시작 시간을 단축하고 싶다면 *수동으로 체크포인트를 생성*하는 것이 좋습니다. 1. 수동 체크포인트 명령 실행 (Leader FE에서):

Copy code

sql
    ALTER SYSTEM CREATE IMAGE;

2. 로그 확인: `fe.log`에서

checkpoint finished save image.xxxx

메시지가 출력되는지 확인합니다. 3. FE 종료: 이미지 생성이 완료된 후 FE를 종료하면 다음 부팅 시 매우 빠르게 시작됩니다. 요약 StarRocks FE는 종료 시점에 자동으로 이미지를 합치지 않으므로, *"종료 전

ALTER SYSTEM CREATE IMAGE

수행"*이 관리 측면에서 권장되는 운영 패턴입니다. References • administration/management/graceful_exit.md • sql-reference/sql-statements/cluster-management/nodes_processes/ALTER_SYSTEM.md • administration/Meta_recovery.md • administration/management/monitoring/alert.md -rules) -rules) • administration/management/FE_configuration.md -configuration) References • administration/management/graceful_exit.md • sql-reference/sql-statements/cluster-management/nodes_processes/ALTER_SYSTEM.md • administration/Meta_recovery.md References • administration/management/FE_configuration.md

RonJay

07/09/2026, 4:03 AM

@Rocky starrocks iceberg catalog 만들때 파라미터로 CATALOG.access.control 이거 있떤데, 혹시 이거 어떻게 필드 채워야해

Rocky

07/09/2026, 4:04 AM

StarRocks에서 Iceberg Catalog를 생성할 때 사용하는

catalog.access.control

파라미터는 *해당 카탈로그 내의 데이터(데이터베이스, 테이블 등)에 대한 접근 권한을 어디서 관리할지*를 결정하는 설정입니다. 사용 가능한 값은 크게 3가지이며, 환경에 맞춰 하나를 선택해 입력하시면 됩니다. 1.
native
(기본값) StarRocks의 *자체 권한 시스템(RBAC)*을 사용합니다. * 어떨 때 쓰나요? StarRocks 내부에서

GRANT

REVOKE

명령어를 통해 유저나 역할(Role)에게 직접 권한을 주고 싶을 때 사용합니다. * 설정 예시:

Copy code

sql
    "catalog.access.control" = "native"

2.
allowall
StarRocks 내부의 권한 체크를 모두 건너뜁니다. * 어떨 때 쓰나요? 주로 *Iceberg REST Catalog*를 사용하면서, 권한 제어를 StarRocks가 아닌 외부 카탈로그 서버나 스토리지 계층(S3 IAM 등)에서 전적으로 관리할 때 사용합니다. StarRocks는 "모두 허용" 상태가 되며, 실제 접근 가능 여부는 외부 서비스가 판단합니다. * 설정 예시:

Copy code

sql
    "catalog.access.control" = "allowall"

3.
ranger
*Apache Ranger*를 통해 권한을 관리합니다. * 어떨 때 쓰나요? 이미 사내에서 Apache Ranger를 사용해 데이터 거버넌스를 통합 관리하고 있을 때 사용합니다. * 주의사항: 이 값을 쓰려면 Ranger 플러그인 설정이 FE에 미리 되어 있어야 하며, 보통

ranger.plugin.hive.service.name

(또는 해당 카탈로그 서비스 이름) 같은 추가 파라미터가 필요할 수 있습니다. * 설정 예시:

Copy code

sql
    "catalog.access.control" = "ranger"

────────── 작성 예시 (Iceberg Catalog 생성 시) 가장 일반적인

native

방식을 사용한다면 아래와 같이 작성합니다.

Copy code

sql
CREATE EXTERNAL CATALOG iceberg_catalog
PROPERTIES (
    "type" = "iceberg",
    "iceberg.catalog.type" = "hive", -- 또는 rest, glue 등
    "hive.metastore.uris" = "<thrift://xx.xx.xx.xx:9083>",
    "catalog.access.control" = "native"  -- 이 부분을 채우시면 됩니다.
);

팁: 만약 별도로 설정하지 않으면 기본적으로 `native`가 적용되므로, StarRocks 내부에서 권한 관리를 하실 계획이라면 이 필드를 생략하셔도 무방합니다. References • data_source/catalog/iceberg/iceberg_catalog.md • data_source/catalog/iceberg/iceberg_rest_security.md • administration/user_privs/authorization/privilege_item.md References • administration/user_privs/authorization/ranger_plugin.md • data_source/catalog/iceberg/iceberg_catalog.md • data_source/catalog/iceberg/iceberg_rest_security.md

RonJay

07/09/2026, 4:18 AM

@Rocky property에 넣는게 아니고 comment 로 넣는거아니야?

Rocky

07/09/2026, 4:18 AM

아니요, `catalog.access.control`은 `COMMENT`가 아니라 반드시
PROPERTIES
내에 설정해야 하는 파라미터입니다. StarRocks의 SQL 문법에서 두 항목의 역할은 명확히 구분됩니다. 1. COMMENT vs PROPERTIES 차이 * COMMENT: 카탈로그에 대한 단순한 *설명(주석)*입니다. "이 카탈로그는 재무팀용 Iceberg입니다"와 같은 사람이 읽는 메모 용도이며, 시스템 동작에는 영향을 주지 않습니다. * PROPERTIES: 카탈로그의 *기능적 동작*을 정의하는 설정값입니다. 접속 주소, 인증 방식, 그리고 문의하신 접근 제어 방식(
catalog.access.control
) 등이 여기에 포함됩니다. 2. 올바른 작성 예시 만약 `COMMENT`와 `PROPERTIES`를 모두 사용한다면 아래와 같은 구조가 됩니다.

Copy code

sql
CREATE EXTERNAL CATALOG my_iceberg
COMMENT "Iceberg 접근 제어 테스트용 카탈로그" -- 여기는 설명만 들어갑니다.
PROPERTIES (
    "type" = "iceberg",
    "iceberg.catalog.type" = "hive",
    "hive.metastore.uris" = "<thrift://1.2.3.4:9083>",
    -- 반드시 PROPERTIES 안에 위치해야 합니다.
    "catalog.access.control" = "allowall" 
);

3. 왜 PROPERTIES에 넣어야 하나요? `catalog.access.control`은 StarRocks가 쿼리를 실행할 때 "이 유저가 이 테이블을 볼 권한이 있는가?"를 판단하는 로직을 결정하는 *설정(Configuration)*이기 때문입니다. `COMMENT`에 넣으면 StarRocks는 이를 단순 텍스트로 인식하여 무시하고, 기본값인

native

방식으로 동작하게 됩니다. 요약: * 동작을 제어하는 모든 설정값은 *`PROPERTIES`*에 넣으셔야 합니다. * `COMMENT`는 선택 사항이며, 카탈로그 관리용 메모장으로만 사용하세요. References • data_source/catalog/iceberg/iceberg_catalog.md • sql-reference/sql-statements/Catalog/CREATE_EXTERNAL_CATALOG.md • data_source/catalog/iceberg/iceberg_rest_security.md • data_source/catalog/hive_catalog.md • data_source/catalog/jdbc_catalog.md References • data_source/catalog/iceberg/iceberg_catalog.md • administration/user_privs/authorization/privilege_item.md • data_source/catalog/iceberg/iceberg_rest_security.md • administration/user_privs/authorization/privilege_faq.md • table_design/table_design.md • administration/user_privs/authorization/ranger_plugin.md

RonJay

07/09/2026, 5:10 AM

@Rocky 수동으로 cluster snapshot 찍는방법

Rocky

07/09/2026, 5:10 AM

StarRocks에서 "Snapshot"은 사용 중인 아키텍처(Shared-data vs Shared-nothing)와 용도에 따라 두 가지 의미로 나뉩니다. 1. 전역 클러스터 스냅샷 (Shared-data 모드, v3.4.2 이상) *Shared-data 아키텍처*에서 클러스터 전체의 상태(메타데이터 + 데이터)를 객체 스토리지(S3, HDFS 등)에 한 번에 백업하는 기능입니다. 재해 복구(DR) 용도로 사용됩니다. * 자동 생성 활성화: 현재 이 기능은 자동화를 기본으로 하며, 특정 주기에 따라 생성됩니다.

Copy code

sql
    ADMIN SET AUTOMATED CLUSTER SNAPSHOT ON [STORAGE VOLUME <storage_volume_name>];

* 수동으로 생성하는 방법: 공식 문서에 따르면, 시스템은 FE가 메타데이터 이미지(Checkpoint)를 생성할 때마다 자동으로 클러스터 스냅샷을 생성합니다. 따라서 수동으로 즉시 찍고 싶다면 아래 명령어로 메타데이터 이미지를 먼저 생성하면 됩니다.

Copy code

sql
    ALTER SYSTEM CREATE IMAGE;

_생성된 스냅샷은

information_schema.cluster_snapshots

뷰에서 확인할 수 있습니다._ ────────── 2. 데이터 백업 및 복구 (Shared-nothing / 일반 모드) 특정 데이터베이스나 테이블의 스냅샷을 찍어 원격 저장소에 보관하는 전통적인 방법입니다. * 수동 스냅샷 생성 (BACKUP): 먼저 백업용 저장소(Repository)가 생성되어 있어야 합니다.

Copy code

sql
    -- 1. 저장소 생성 (예: S3)
    CREATE REPOSITORY `s3_repo`
    WITH S3 (
        "aws.s3.endpoint" = "<http://s3.us-west-2.amazonaws.com|s3.us-west-2.amazonaws.com>",
        "aws.s3.region" = "us-west-2",
        "aws.s3.bucket" = "my-bucket",
        "path" = "/backups"
    );

    -- 2. 수동 백업(스냅샷) 실행
    BACKUP SNAPSHOT my_db.snapshot_name_20240101
    TO `s3_repo`
    ON (my_table); -- 특정 테이블만 지정하거나, 생략 시 DB 전체 백업

요약: 어떤 것을 찾으시나요? 1. 클러스터 전체(설정, 유저 권한 포함)를 DR 용도로 백업: v3.4.2+ Shared-data 환경에서

ADMIN SET AUTOMATED CLUSTER SNAPSHOT ON

설정 후 `ALTER SYSTEM CREATE IMAGE`로 유도. 2. 특정 테이블/DB 데이터만 백업:

BACKUP SNAPSHOT

명령어 사용. 3. FE 메타데이터 파일만 디스크에 기록:

ALTER SYSTEM CREATE IMAGE

사용. References • administration/cluster_snapshot.md • sql-reference/sql-statements/backup_restore/BACKUP.md • administration/management/Backup_and_restore.md • sql-reference/sql-statements/cluster_management/nodes_processes/ALTER_SYSTEM.md References • administration/cluster_snapshot.md • sql-reference/sql-statements/backup_restore/BACKUP.md • administration/management/Backup_and_restore.md • sql-reference/sql-statements/cluster_management/nodes_processes/ALTER_SYSTEM.md References • administration/cluster_snapshot.md • sql-reference/sql-statements/backup_restore/BACKUP.md • administration/management/Backup_and_restore.md

RonJay

07/09/2026, 5:30 AM

@Rocky repository에서 복구하려는데 이미 생성되어있거나 연결된 레포지터리 어떻게봐

Rocky

07/09/2026, 5:33 AM

이미 생성된 레포지토리(Repository) 목록과 설정 정보를 확인하려면 다음 명령어를 사용하시면 됩니다. 1. 연결된 레포지토리 목록 확인 현재 StarRocks 클러스터에 등록된 모든 레포지토리의 이름, 저장소 위치(S3/HDFS 경로), 생성 시간 등을 볼 수 있습니다.

Copy code

sql
SHOW REPOSITORIES;

* RepoName: 레포지토리 이름 * Location: 데이터가 실제 저장된 외부 스토리지 경로 (예: `s3a://my-bucket/backup`) * ReadOnly: 해당 레포지토리가 읽기 전용인지 여부 (복구 전용으로 만들었을 경우

Yes

) ────────── 2. 레포지토리 내부의 스냅샷 확인 (복구할 대상 찾기) 레포지토리가 연결되었다면, 그 안에 어떤 백업 파일(스냅샷)들이 들어있는지 확인해야 복구 명령을 내릴 수 있습니다.

Copy code

sql
-- 특정 레포지토리에 들어있는 스냅샷 목록 확인
SHOW SNAPSHOT ON <레포지토리_이름>;

* 이 명령어를 통해 복구 가능한 Snapshot 이름, Timestamp, 상태 등을 확인할 수 있습니다. ────────── 참고: 만약 레포지토리가 없다면? 다른 클러스터에서 백업한 데이터를 가져오려는 경우, *새 클러스터에서도 동일한 이름과 경로로 레포지토리를 생성*해줘야 합니다.

Copy code

sql
-- 예: S3 레포지토리 다시 연결하기
CREATE REPOSITORY `my_repo`
WITH S3 (
    "aws.s3.endpoint" = "<http://s3.us-west-2.amazonaws.com|s3.us-west-2.amazonaws.com>",
    "aws.s3.region" = "us-west-2",
    "aws.s3.bucket" = "my-bucket",
    "path" = "/backups"
);

복구 진행 시 팁: 스냅샷 목록을 확인한 후, 아래 명령어로 복구를 시작합니다.

Copy code

sql
RESTORE SNAPSHOT <데이터베이스명>.<스냅샷명>
FROM `레포지토리명`
ON (<복구할_테이블명>);

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

Rocky

07/09/2026, 5:33 AM

RonJay

07/09/2026, 6:03 AM

@Rocky AUTOMATED CLUSTER SNAPSHoT 을 builtin storage volume에 만들어서 s3에 저장된 거 까진 확인했는데 restore할때 REPOSITORY도 있어야해?

Rocky

07/09/2026, 6:03 AM

결론부터 말씀드리면, AUTOMATED CLUSTER SNAPSHOT
기능을 통해 생성된 스냅샷을 복구할 때는 별도의 `REPOSITORY`를 생성할 필요가 없습니다. 그 이유는 `AUTOMATED CLUSTER SNAPSHOT`과 기존의

BACKUP/RESTORE

방식이 사용하는 메커니즘이 다르기 때문입니다. 1. 왜 REPOSITORY가 필요 없나요? * 기존 방식 (Shared-nothing):

BACKUP

명령어를 통해 테이블 데이터를 수동으로 백업할 때는 StarRocks가 외부 저장소와 통신하기 위한 매개체로 `REPOSITORY`를 정의해야 합니다. * 클러스터 스냅샷 방식 (Shared-data): 이 방식은 이미 클러스터가 데이터 저장소로 사용하고 있는 *`STORAGE VOLUME`*을 직접 활용합니다. 시스템이 이미 해당 볼륨에 대한 권한과 경로를 알고 있기 때문에, 백업 전용 객체인 `REPOSITORY`를 추가로 만들지 않아도 됩니다. 2. 그럼 어떻게 복구하나요? (RESTORE CLUSTER SNAPSHOT) 클러스터 스냅샷을 복구할 때는

RESTORE

문법이 아닌, 클러스터 전체 상태를 되돌리는 전용 명령어를 사용합니다. (주로 신규 클러스터를 띄울 때 해당 스냅샷 지점부터 시작하도록 설정합니다.) 현재 클러스터 내에서 특정 시점의 스냅샷 목록 확인:

Copy code

sql
SELECT * FROM information_schema.cluster_snapshots;

복구 시나리오: 보통 클러스터 스냅샷은 재해 복구(DR)용입니다. 전체 클러스터를 해당 시점으로 복구하려면 서비스 중단이 필요하거나 신규 클러스터 구축이 권장됩니다. 수동 복구 명령어는 다음과 같은 구조를 가집니다.

Copy code

sql
-- 예시: 특정 스냅샷 ID로 클러스터 복구 (Shared-data 전용)
RESTORE CLUSTER SNAPSHOT <snapshot_id>;

(참고: 이 명령어는 클러스터의 모든 데이터를 해당 시점으로 덮어쓰므로 매우 주의해서 사용해야 합니다.) 요약 * BACKUP SNAPSHOT
명령어 사용 시:

REPOSITORY

필요 (테이블/DB 단위) * AUTOMATED CLUSTER SNAPSHOT
사용 시: `STORAGE VOLUME`만 있으면 됨 (클러스터 전체 단위) 따라서 이미 S3(Storage Volume)에 저장이 된 것을 확인하셨다면, 복구 시에도 해당 볼륨 설정을 그대로 이용하면 됩니다. References • administration/cluster_snapshot.md • sql-reference/sql-statements/backup_restore/RESTORE.md • administration/management/Backup_and_restore.md • sql-reference/sql-statements/backup_restore/BACKUP.md • administration/management/Data_recovery.md

RonJay

07/09/2026, 6:35 AM

@Rocky 레포지터리를 만들고 거기에 스냅샷찍고 리스토어 하는 하나의 전체 사이클 알려줘

Rocky

07/09/2026, 6:35 AM

StarRocks에서 레포지토리를 생성하고, 데이터를 백업(Snapshot)한 후 복구(Restore)하는 전체 과정을 S3 기준으로 정리해 드립니다. 1단계: 레포지토리 생성 (Create Repository) 데이터를 저장할 원격 저장소와의 연결 고리를 만듭니다. AWS S3를 사용할 경우 URI의 접두사를 *`s3a://`*로 작성해야 합니다.

Copy code

sql
CREATE REPOSITORY `my_s3_repo`
WITH BROKER -- (또는 BROKER 없이 설정 가능)
ON LOCATION "<s3a://my-bucket/starrocks_backups>"
PROPERTIES (
    "aws.s3.endpoint" = "<http://s3.us-west-2.amazonaws.com|s3.us-west-2.amazonaws.com>",
    "aws.s3.region" = "us-west-2",
    "aws.s3.access_key" = "YOUR_ACCESS_KEY",
    "aws.s3.secret_key" = "YOUR_SECRET_KEY"
);

-- 연결 확인
SHOW REPOSITORIES;

────────── 2단계: 수동 스냅샷 생성 (Backup) 특정 데이터베이스나 테이블의 스냅샷을 찍어 레포지토리에 저장합니다.

Copy code

sql
-- 예: my_db 전체를 'backup_v1'이라는 이름으로 백업
BACKUP SNAPSHOT my_db.backup_v1
TO `my_s3_repo`;

-- 특정 테이블만 백업할 경우
BACKUP SNAPSHOT my_db.backup_v1
TO `my_s3_repo`
ON (table1, table2);

* 상태 확인: 백업은 비동기로 진행됩니다. 아래 명령어로 `State`가 `FINISHED`가 될 때까지 확인하세요.

Copy code

sql
    SHOW BACKUP FROM my_db;

────────── 3단계: 복구할 스냅샷 정보 확인 복구(Restore) 명령 시에는 정확한 *`backup_timestamp`*가 필요합니다. 레포지토리에 저장된 스냅샷 목록을 조회합니다.

Copy code

sql
SHOW SNAPSHOT ON `my_s3_repo`;

* 조회 결과에서 복구하려는 스냅샷의 Timestamp
값(예:

2024-05-20-10-00-00-000

)을 복사해 둡니다. ────────── 4단계: 데이터 복구 (Restore) 저장된 스냅샷을 사용하여 데이터를 클러스터로 불러옵니다.

Copy code

sql
-- 기존 DB에 덮어쓰거나 새로운 DB로 복구할 수 있습니다.
RESTORE SNAPSHOT my_db.backup_v1
FROM `my_s3_repo`
PROPERTIES (
    "backup_timestamp" = "2024-05-20-10-00-00-000" -- 3단계에서 확인한 타임스탬프
);

* 상태 확인: 복구 역시 비동기입니다. `State`가 `FINISHED`가 되면 완료된 것입니다.

Copy code

sql
    SHOW RESTORE FROM my_db;

────────── 💡 주요 팁 1. 다른 클러스터로 복구할 때: 새 클러스터에서 동일한 이름과 경로(

ON LOCATION

)를 가진 레포지토리를 먼저 생성한 후 3단계부터 진행하면 됩니다. 2. 테이블 이름 변경: 복구 시

ON (table1 AS table1_new)

문법을 사용하여 다른 이름의 테이블로 복구할 수 있습니다. 3. 권한: 백업 및 복구 작업은

ADMIN

권한이 필요합니다. References • administration/management/Backup_and_restore.md • sql-reference/sql-statements/backup_restore/BACKUP.md • sql-reference/sql-statements/backup_restore/RESTORE.md • sql-reference/sql-statements/backup_restore/SHOW_SNAPSHOT.md References • administration/management/Backup_and_restore.md

RonJay

07/09/2026, 6:36 AM

그냥 하나씩 말고 전체로 스냅샷찍는과정으로 설명해줘 @Rocky

Rocky

07/09/2026, 6:36 AM

StarRocks에서 개별 테이블이 아닌 *데이터베이스 전체*를 한 번에 백업(Snapshot)하고 복구하는 전체 사이클입니다. 1. 레포지토리 생성 (저장소 연결) 먼저 백업 파일이 저장될 S3 위치를 정의합니다.

Copy code

sql
CREATE REPOSITORY `full_backup_repo`
WITH S3 (
    "aws.s3.endpoint" = "<http://s3.us-west-2.amazonaws.com|s3.us-west-2.amazonaws.com>",
    "aws.s3.region" = "us-west-2",
    "aws.s3.bucket" = "my-starrocks-backup",
    "path" = "/all_databases",
    "aws.s3.access_key" = "AKIA...",
    "aws.s3.secret_key" = "SECRET..."
);

2. 데이터베이스 전체 백업 (Full Backup)

ON

절을 생략하면 해당 데이터베이스 내의 *모든 테이블*이 백업됩니다.

Copy code

sql
-- 'demo_db' 데이터베이스 전체를 'ss_20240520'이라는 이름의 스냅샷으로 백업
BACKUP SNAPSHOT demo_db.ss_20240520
TO `full_backup_repo`;

* 상태 확인: `State`가 `FINISHED`가 될 때까지 기다립니다.

Copy code

sql
    SHOW BACKUP FROM demo_db;

3. 레포지토리에서 스냅샷 정보 확인 (복구 준비) 복구할 때 필요한 정확한 *타임스탬프*를 확인합니다.

Copy code

sql
SHOW SNAPSHOT ON `full_backup_repo`;

* 결과 화면의

Timestamp

컬럼 값을 복사합니다 (예:

2024-05-20-10-00-00-000

). 4. 데이터베이스 전체 복구 (Full Restore) 스냅샷에 포함된 모든 데이터를 복구합니다.

Copy code

sql
-- 'demo_db'에 스냅샷 전체를 복구
RESTORE SNAPSHOT demo_db.ss_20240520
FROM `full_backup_repo`
PROPERTIES (
    "backup_timestamp" = "2024-05-20-10-00-00-000" -- 위에서 확인한 값
);

* 상태 확인: `State`가 `FINISHED`가 되면 복구가 완료된 것입니다.

Copy code

sql
    SHOW RESTORE FROM demo_db;

────────── ⚠️ 주의 및 팁 * 클러스터 전체 백업: StarRocks의

BACKUP

명령어는 데이터베이스 단위로 작동합니다. 클러스터에 DB가 여러 개라면 각 DB마다 위 과정을 수행해야 합니다. * 기존 테이블 처리: 복구하려는 DB에 동일한 이름의 테이블이 이미 있다면, 복구가 거절될 수 있습니다. 이 경우 기존 테이블을 삭제(

DROP

)하거나,

AS

문법을 사용하여 다른 이름의 DB로 복구해야 합니다. * Shared-data 모드(Cloud Native): 만약 이전에 언급하신

AUTOMATED CLUSTER SNAPSHOT

기능을 사용 중이라면, 위와 같은

REPOSITORY

방식보다는 볼륨 자체의 스냅샷 기능을 사용하는 것이 더 효율적입니다. 하지만 수동으로 특정 시점을 관리하고 싶을 때는 이

BACKUP/RESTORE

방식이 가장 확실합니다. References • administration/management/Backup_and_restore.md • sql-reference/sql-statements/backup_restore/BACKUP.md • sql-reference/sql-statements/backup_restore/RESTORE.md • sql-reference/sql-statements/backup_restore/SHOW_SNAPSHOT.md

RonJay

07/09/2026, 6:42 AM

@Rocky Cluster SNapshot 을 만들면 그때 edit log에 있는것도 반영해서 스냅샷찍나?

Rocky

07/09/2026, 6:42 AM

네, Cluster Snapshot은 Edit Log의 내용이 반영된 상태(Checkpoint 완료 후의 상태)를 스냅샷으로 찍습니다. 작동 원리를 구체적으로 설명드리면 다음과 같습니다. 1. 작동 방식: Checkpoint와 연동 StarRocks의 `AUTOMATED CLUSTER SNAPSHOT`은 FE(Frontend)의 Metadata Checkpoint 작업과 밀접하게 연결되어 있습니다. * FE는 주기적으로 현재까지 쌓인 *Edit Log*(메타데이터 변경 이력)를 메모리의 상태와 합쳐서 새로운 *Image 파일*로 만듭니다. 이 과정을 'Checkpoint'라고 합니다. * 자동 클러스터 스냅샷 기능이 켜져 있으면, *FE가 새로운 Image 파일을 생성한 직후*에 해당 시점의 데이터와 메타데이터를 묶어서 스냅샷을 생성합니다. 2. Edit Log 반영 여부 * 포함됨: 스냅샷이 찍히는 시점까지 쌓였던 모든 Edit Log는 이미 Image 파일에 병합(Replay)된 상태로 저장됩니다. 즉, 스냅샷 시점 이전의 모든 변경 사항은 스냅샷에 안전하게 포함됩니다. * Journal ID:

information_schema.cluster_snapshots

뷰를 조회해 보면 `fe_journal_id`라는 컬럼이 있는데, 이는 해당 스냅샷이 *어느 시점의 Edit Log까지 포함하고 있는지*를 나타내는 번호입니다. 3. 한계점 (실시간성) * 스냅샷은 실시간으로 모든 Edit Log를 추적하는 기능은 아닙니다. * 설정된 주기(

automated_cluster_snapshot_interval_seconds

, 기본 10분)에 따라 Checkpoint가 발생할 때만 스냅샷이 업데이트됩니다. * 따라서 마지막 스냅샷이 생성된 이후에 발생한 '따끈따끈한' Edit Log들은 다음 스냅샷 주기가 돌아와서 새로운 Image가 만들어질 때까지는 해당 스냅샷에 포함되지 않습니다. 요약 클러스터 스냅샷은 *"Edit Log를 Image 파일로 굳히는 시점(Checkpoint)"*의 결과물을 저장하는 것이므로, 그 시점까지의 모든 변경 사항은 확실히 반영됩니다. 복구 시에도 해당

fe_journal_id

시점의 완벽하게 일관된(Consistent) 상태로 돌아가게 됩니다. References • administration/cluster_snapshot.md • administration/management/FE_configuration.md References • administration/cluster_snapshot.md • deployment/shared_data/feature-support-shared-data.md • faq/shared_data_faq.md • deployment/shared_data/gcs.md • introduction/Architecture.md

5 Views

Open in Slack

Previous Next